diff --git a/README b/README
index 0417322c9319ac901f7dcb8b03c306dc5aa3fcd7..c32593255fd83a25b30513b8dbe2ec75f883ce4a 100644
--- a/README
+++ b/README
@@ -1,20 +1,28 @@
-ALBERTA: an Adaptive multi Level finite element toolbox using
+ALBERTA: an Adaptive multi Level finite element toolbox using
Bisectioning refinement and Error control by Residual
Techniques
+Contents
+========
+
+I. Introduction
+II. External Packages (both required and optional packages)
+III. Configure Options
+
+
I) Introduction
===============
This is ALBERTA Version 1.2. For the installation process refer to INSTALL.
-Contained in the package are the following subpackages:
+Contained in the package are the following sub-packages:
- __________ ALBERTA/ __________ src/ _______|--- 1d/
+ __________ ALBERTA/ __________ src/ ______|--- 1d/
/ \ |--- 2d/
- /___________ BLAS/ -- doc/ |--- 3d/
+ / -- doc/ |--- 3d/
/ |--- Common/
/_____________ DEMO/ __ src/ _______|--- 1d/ |--- ALBERTA??_?/
-alberta-1.2/ * |--- 2d/
- \_____________ ALBERTA_UTIL/ |--- 3d/
+alberta-1.2/| |--- 2d/
+ \_____________ ALBERTA_UTIL/ |--- 3d/
\ |--- Common/
\___________ PLOT_ANSI/ __ src/
\
@@ -24,46 +32,106 @@ alberta-1.2/ * |--- 2d/
\ |--- 3d/
\ |--- Common/
\
- \___ [gltools-2-4/] optional
- \
- \_ configure.ac and other distribution
- files
+ \
+ \_ configure.ac and other distribution
+ files
1) ALBERTA
The main package.
-2) BLAS
-Basic Linear Algebra Subroutines, these are compiled if the system on which ALBERTA will run does not supply them.
-
-3) DEMO
-A few demonstration programs. This subpackage includes several small Makefile.in's in which configure substitutes values like installation paths for libraries and headers. This directory can be copied elsewhere by the user after installation. The Makefiles include "Makefile.alberta" which resides in $installdir/include together with the C-header files. They are meant to faciliate the first steps with ALBERTA.
+2) DEMO
+A few demonstration programs. This sub-package includes several small Makefile.in's in which configure substitutes values like installation paths for libraries and headers. This directory can be copied elsewhere by the user after installation. The Makefiles include "Makefile.alberta" which resides in $installdir/include together with the C-header files. They are meant to facilitate the first steps with ALBERTA.
-4) ALBERTA_UTIL
+3) ALBERTA_UTIL
This package contains the old ALBERTA util.c file, now split into several smaller source files. It is compiled to form a separate utility library (message macros, ALBERTA memory allocation routines, etc.) and should linked to any program using the ALBERTA package.
It can also be used as a standalone utility library.
-5) PLOT_ANSI
+4) PLOT_ANSI
PLOT_ANSI provides tools for displaying X11 graphics, if gltools is not used.
-6) SOLVER
+5) SOLVER
Linear and nonlinear solver routines for ALBERTA.
-7) GRAPE
+6) GRAPE
GRAPE interface for ALBERTA. Only for non-parametric FE of dimension 2 and 3.
"make" will create "alberta_grapeXX" and alberta_moviXX" where XX is in {22, 33}.
"make install" will install those programs below PREFIX/bin.
The GRAPE interface is only installed when the GRAPE library and header file
are available on your system (determined at configure time, use
-"configure --help" for apropriate command line switches for "configure").
+"configure --help" for appropriate command line switches for "configure").
II) External packages
=====================
-The gltools package is not part of ALBERTA. If it is detected during installation, the file ALBERTA/src/Common/gltools.c is included in the ALBERTA libraries. The user can specify the path of an already installed gltools-package as a configure option, see below.
+1) Required Packages
+--------------------
+
+The software-packages mentioned here are _required_. You will not be
+able to compile and use ALBERTA without them. The configure-script
+will attempt to detect them at build-time (see "Configure Options"
+below).
+
+OpenGL -- you need some implementation of SGI's 3D-API. If your system
+ does not have OpenGL you can fetch the free OpenGL
+ implementation "MesaGL" from
+
+ http://www.mesa3d.org/
+
+ If you don't have a clue what this is all about then ask your
+ system-administrator.
+
+BLAS -- "Basic Linear Algebra Subprograms"
+ You definitely need some version of the BLAS. Often the BLAS
+ can be found at "/usr/lib/libblas.a", but this need not be the
+ case. Also, you definitely want to use a version which is
+ optimised for your computer-architecture.
+
+ You should have a look at
+
+ http://www.netlib.org/blas/faq.html
+
+ which lists some URLs to optimised BLAS-implementations for
+ some architectures. For an optimised version for AMD's Athlon
+ and Opteron CPUs you should have a look at AMD's web-site
+ (www.amd.com) and search for "acml".
+
+2) Optional Packages
+--------------------
+
+The software-packages mentioned here are not required to compile and
+use ALBERTA. They are detected by the configure-script at build-time
+and are used when available (see "Configure Options" below).
+gltools -- OpenGL toolkit
+ We strongly recommend that you install the gltools package;
+ you can fetch it from
-III) Configure options
+ http://www.wias-berlin.de/software/gltools/
+
+ gltools provides a more flexible graphical output than would
+ be otherwise available with ALBERTA.
+
+GRAPE -- Graphics Programming Environment
+ If GRAPE is present the four programs alberta_grape22,
+ alberta_grape33, alberta_movi22 and alberta_movi33 are
+ compiled during the build-process. They can be used to display
+ data-files created by ALBERTA during your numerical
+ simulations.
+
+ GRAPE is available from
+
+ http://www.mathematik.uni-freiburg.de/IAM/Research/grape/GENERAL/
+
+alternate compilers
+ Many CPU-vendors distribute highly optimising compilers for
+ their specific CPU architecture. Often those compilers
+ generate much faster code than even a modern gcc. Sometimes
+ they are available at no cost, at least for private and
+ research use.
+
+
+III) Configure Options
======================
"configure --help" will give you a summary of available options. The file
@@ -72,43 +140,187 @@ generic command line options for configure.
The remaining (i.e. ALBERTA specific) options are explained here:
- --with-gltools=PATH
- PATH is the path of a gltools-2-4 directory possible installed
- on the system. The default value where gltools-2-4 is searched
- is the build directory. The default installation path is also
- the build directory. This can be changed via
- --prefix=PREFIX install architecture-independent files in PREFIX.
- NOTE: this is different from the default GNU installation prefix,
- which would be "/usr/local/".
+1.) Non-standard behaviour of ALBERTA
+-------------------------------------
+
+BIG FAT NOTE: the default installation prefix of the ALBERTA-package
+is _NOT_ the default GNU installation prefix which would be
+/usr/local/ on Un*x systems, but it is the build-directory. I.e. when
+compiling ALBERTA below
+
+ /usr/people/claus/alberta-1.2/
+
+then the libraries will go to
+
+ /usr/people/claus/alberta-1.2/lib/
+
+the header-files and Makefile.alberta will end up in
+
+ /usr/people/claus/alberta-1.2/include/
+
+libtool.alberta will reside in
+
+ /usr/people/claus/alberta-1.2/libexec/
+
+and finally the demo package (under the name alberta-1.2.demo.tar.gz)
+will be copied to
+
+ /usr/people/claus/alberta-1.2/libexec/share/
+
+This will be the layout after running "make install".
+
+
+2.) Options affecting which versions of ALBERTA are built
+---------------------------------------------------------
+
+Compiling all flavours of the ALBERTA libraries takes a long time. The
+ALBERTA libraries are all named
+
+ libALBERTA$(DIM)$(DIM_OF_WORLD)_$(DEBUG)$(EL_INDEX)
+
+The options below control which of them are actually created.
+
+ --disable-alberta-11
+ Disable building of an ALBERTA library for Finite Elements of
+ dimension 1. (default: enabled)
+
+ --disable-alberta-22
+ Disable building of an ALBERTA library for Finite Elements of
+ dimension 2. (default: enabled)
+
+ --disable-alberta-33
+ Disable building of an ALBERTA library for Finite Elements of
+ dimension 3. (default: enabled)
+
+ --enable-alberta-12
+ Enable building of an ALBERTA library for parametric
+ Finite Elements of dimension 1 where the
+ surrounding space has dimension 2. (default: disabled)
+
+ --enable-alberta-13
+ Enable building of an ALBERTA library for parametric
+ Finite Elements of dimension 1 where the
+ surrounding space has dimension 3. (default: disabled)
+
+ --enable-alberta-23
+ Enable building of an ALBERTA library for parametric
+ Finite Elements of dimension 2 where the
+ surrounding space has dimension 3. (default: disabled)
+
+ --enable-el-index
+ Additionally build ALBERTA libraries which assigns unique
+ index to each element. Normally, this is not needed but it can
+ be handy for debugging purposes. (default: disabled)
+
+ --disable-debug
+ Disable building of ALBERTA libraries with debugging
+ information. On some systems (or better: with some compilers)
+ optimisation and debugging are mutual exclusive, therefore
+ there are separate ALBERTA libraries which are compiled with
+ optimisation, but without debugging information, and another
+ versions which is compiled without optimisation, but with
+ debugging. (default: enabled)
+
+
+3.) Options controlling the search-path for external libraries
+--------------------------------------------------------------
+
+See also "External Packages" above.
+
+For each external package PKG the configure script provides the
+following options:
+
+ --without-PKG
+ Prohibit the use of this package, even if it is installed on
+ your system. Obviously, this affects only the two optional
+ packages "gltools" and "GRAPE" .
+
+ --with-PKG-name=NAME
+ The library is not called PKG, but NAME, e.g. "MesaGL" instead
+ of "GL", or "cxml" instead of "blas". Configure will then
+ search for "libNAME" instead of "libPKG".
+
+ --with-PKG-dir=DIR
+ Search for header-files and for the library itself below DIR,
+ e.g. "--with-gltools-dir=/foo/bar/gltools-2.4".
+
+ --with-PKG-lib=DIR
+ Search for the library below DIR,
+ e.g. "--with-blas-lib=/usr/people/claus/software/lib/".
- --enable-shared=?? and/or --enable-static=??
- Default library mode is to install static and shared libraries.
- This can be changed using these switches,
- where ?? is "yes" or "no".
+ --with-PKG-headers=DIR
+ Use DIR as search-path for the include-files for PKG,
+ e.g. "--with-opengl-include=/usr/people/claus/software/include/".
- --enable-el_index
- builds versions of the ALBERTA libraries with C Preprocessor
- macro "EL_INDEX" set to 1. See the ALBERTA documentation for
- details.
+The following quotes the online-help obtained by running "configure
+--help"
- --without-GRAPE
- do not even attempt to detect GRAPE. As a result, the GRAPE
- interface will not be compiled.
+ --with-blas-name=NAME use NAME as the name of the blas library (without
+ leading "lib" prefix and trailing suffix). Default:
+ "blas"
+ --with-blas-lib=DIR use blas library below directory DIR (default:
+ EPREFIX/lib/)
+ --with-opengl-name=NAME use NAME as the name of the opengl library (without
+ leading "lib" prefix and trailing suffix). Default:
+ "GL"
+ --with-opengl-dir=DIR use opengl library (and headers) below directory DIR
+ (no default)
+ --with-opengl-lib=DIR use opengl library below directory DIR (default:
+ EPREFIX/lib/)
+ --with-opengl-headers=DIR
+ use opengl include files below directory DIR
+ (default: PREFIX/include/)
+ --without-gltools disable use of package gltools (default: autodetect)
+ --with-gltools-name=NAME
+ use NAME as the name of the gltools library (without
+ leading "lib" prefix and trailing suffix). Default:
+ "gltools"
+ --with-gltools-dir=DIR use gltools library (and headers) below directory
+ DIR (no default)
+ --with-gltools-lib=DIR use gltools library below directory DIR (default:
+ EPREFIX/lib/)
+ --with-gltools-headers=DIR
+ use gltools include files below directory DIR
+ (default: PREFIX/include/)
+ --without-grape disable use of package grape (default: autodetect)
+ --with-grape-name=NAME use NAME as the name of the grape library (without
+ leading "lib" prefix and trailing suffix). Default:
+ "gr"
+ --with-grape-dir=DIR use grape library (and headers) below directory DIR
+ (no default)
+ --with-grape-lib=DIR use grape library below directory DIR (default:
+ EPREFIX/lib/)
+ --with-grape-headers=DIR
+ use grape include files below directory DIR
+ (default: PREFIX/include/)
- --with-GRAPE-lib=DIR
- Location of "libgr.a" or "libgr.so" on your system. If
- "libgr.so" is installed at "/foo/bar/lib/libgr.so", then DIR
- should be set to "/foo/bar/lib/".
- --with-GRAPE-headers=DIR
- Location of the GRAPE header file "grape.h". If "grape.h" is
- installed at "/foo/bar/include/grape.h", then DIR should be
- set to "/foo/bar/include/".
+4.) CFLAGS and FFLAGS settings
+------------------------------
-We recommend setting the environment variables "CFLAGS" and "FFLAGS" to "", so that "configure" does NOT automatically substitute a "-g" debugging option while compiling, as well as using the highest possible optimization flag "-O???" during a build of (non-debug) libraries.
+The default flags for the optimised libraries are "-O3" when using gcc
+and "-O" otherwise.
+The default flags for the debugging-enabled libraries are
+"-O0 -ggdb -fno-inline -fno-builtin" with gcc and "-g" otherwise.
+You are strongly encouraged to change this. To do so, you can set the
+environment variables CFLAGS, FFLAGS and ALBERTA_DEBUG_CFLAGS before
+you run configure. You can also set these variables on the
+command-line of the make program, e.g. with a recent gcc on a Pentium
+4 you could use
+make CFLAGS="-O3 -march=pentium4 -mfpmath=sse"
+You have to consult the documentation for the compiler(s) you are using
+to determine the appropriate switches for your setup.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+PLEASE LEAVE HERE FOR ISPELL:
+ LocalWords: src alberta UTIL ac in's installdir util gltools FE grapeXX SGI's
+ LocalWords: moviXX OpenGL API MesaGL BLAS AMD's Athlon Opteron acml movi gcc
+ LocalWords: libtool libALBERTA PKG GL cxml blas libNAME libPKG dir DIR opengl
+ LocalWords: EPREFIX gr CFLAGS FFLAGS ggdb fno inline pentium sse
+ LocalWords: mfpmath