diff --git a/README b/README
index 40da14186ecc8c6a160b0af90db40f0451387ce8..19b75edbfdc27d0560f087100244a5d7bb6d853c 100644
--- a/README
+++ b/README
@@ -1,5 +1,3 @@
-TODO: this file needs to be overhauled
-
ALBERTA is an Adaptive multi-Level finite element toolbox using
Bisectioning refinement and Error control by Residual
Techniques for scientific Applications.
@@ -11,21 +9,21 @@ Contents
I. Introduction
-II. External Packages (both required and optional packages)
- 1.) Required Packages
+II. External Packages (all optional)
OpenGL
BLAS (with examples)
- 2.) Optional Packages
gltools
GRAPE
Silo
- OpenDX
+ OpenDX
+ Paraview
alternate compilers
III. Configure Options
- 1.) Non-standard behavior of ALBERTA
+ 1.) ALBERTA's installation paths
2.) Options affecting which versions of ALBERTA are built
- 3.) Options controlling the search-path for external libraries
+ 3.) Options controlling specific features
+ 4.) Options controlling the search-path for external libraries
IV. Compiler flags (with examples)
@@ -37,8 +35,7 @@ V. Some platform dependent notes and examples
I) Introduction
===============
-This is ALBERTA Version 3.0. ALBERTA has a web-page
-at
+This is ALBERTA Version 3.0. ALBERTA has a web-page at
http://www.alberta-fem.de/
@@ -57,87 +54,127 @@ beast in a directory hierarchy below the path-prefix PREFIX, where
PREFIX defaults to `/usr/local/' if the `--prefix' switch is omitted.
0) The directory layout
-Contained in the package are the following sub-packages:
-
- __________ alberta/ __________ src/ ______|--- 1d/
- / \ |--- 2d/
- / -- doc/ |--- 3d/
- / |--- Common/
- / |--- alberta*/
- /_____________ demo/ __ src/ _______|--- 1d/
-alberta-3.0 / |--- 2d/
- \ |--- 3d/
- \ |--- 4d/
- \ |--- 5d/
- \ |--- Common/
- \
- \
- \__________ alberta_util/ ___ src/
- \
- \
- \_______ add_ons/ ---- grape/ __ mesh/ ____|--- 2d/
- \ \ |--- 3d/
- \ \ |--- Common/
- \ \
- \ - meshtv/ ___|--- 1d/
- \ \ |--- 2d/
- \ \ |--- 3d/
- \ \ |--- Common/
- \ \
- \ \- geomview/
- \
- \_ configure.ac and other distribution
- files
-
-1) alberta
-The main package.
-
-2) demo
-The sub-directory `demo/' contains a few demonstration programs. After
-running "make install" (see file `./INSTALL') a tar-ball containing
-all demo programs will be installed in `PREFIX/share/alberta/'. The
-tar-ball can be extracted elsewhere; the make-files contained in the
-tar-ball have appropriate defaults for the location of the (installed)
-ALBERTA libraries and header files.
-
-3) alberta_util
-This package contains the old ALBERTA util.c file, now split into
-several smaller source files. As of version 2.0 it also contains the former
-SOLVER library. It is compiled to form a separate utility library
-(message macros, ALBERTA memory allocation routines, BLAS routines and
-wrappers, etc.) and should linked to any program using the ALBERTA package. It
-can also be used as a stand-alone utility library.
-
-4) grape
-GRAPE interface for ALBERTA. Only for non-parametric FE of dimension 2
-and 3. The GRAPE-interface consists of "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 appropriate command line switches for
-"configure").
-
-5) meshtv
-MeshTV interface for ALBERTA. Only for non-parametric FE. The MeshTV
-interface consists of the programs "alberta_meshtvX" with X in
-{1,2,3}. These are installed in `PREFIX/bin/' as well.
-
-The interface is only installed if the Silo library and header files are
-available on your system. See "configure --help" for details.
+~~~~~~~~~~~~~~~~~~~~~~~
+Contained in the package-tree are the following sub-directories
+(ommitting 3rd-level sub-directories below add_ons/):
+
+ ___ 0d/
+ ____________ alberta/ ___ src/ ______|___ 1d/
+ / \ |___ 2d/
+ / \__ doc/ |___ 3d/
+ / ___ 1d/ |___ Common/
+ / |___ 2d/ |___ alberta*/
+ /_ demo/ __ src/ _______|___ 3d/
+ / |___ 4d/
+ / |___ 5d/
+ / |___ Common/
+ /
+ /
+ /
+alberta-3.0 /
+ \___ alberta_util/ ___ src/
+ \
+ \ ____ bamg2alberta/
+ \__ add_ons/___/
+ \ \____ block_solve/
+ \ \
+ \ \___ geomview/
+ \ \
+ \ \___ gmv/
+ \ \
+ \ \___ grape/
+ \ \
+ \ \___ libalbas/
+ \ \
+ \ \
+ \ \___ meshtv/
+ \ \
+ \ \___ paraview/
+ \ \
+ \ \___ static_condensation/
+ \ \
+ \ \___ triangle2alberta/
+ \ \
+ \ \___ write_mesh_fig/
+ \
+ \_ configure and other distribution
+ files
+
+Short description of the sub-directories:
+
+* alberta
+ The main package.
+
+* demo
+ The sub-directory `demo/' contains a few demonstration
+ programs. After running "make install" (see file `./INSTALL') a
+ tar-ball containing all demo programs will be installed in
+ `PREFIX/share/alberta/'. The tar-ball can be extracted elsewhere;
+ the make-files contained in the tar-ball have appropriate defaults
+ for the location of the (installed) ALBERTA libraries and header
+ files.
+
+* alberta_util
+ This package contains the old ALBERTA util.c file, now split into
+ several smaller source files. As of version 2.0 it also contains the
+ former SOLVER library. It is compiled to form a separate utility
+ library (message macros, ALBERTA memory allocation routines, BLAS
+ routines and wrappers, etc.) and should linked to any program using
+ the ALBERTA package. It can also be used as a stand-alone utility
+ library.
+
+* bamg2alberta
+ A converter from the FreeFem++ grid-generatar `bamd' to ALBERTA
+ macro file format.
+
+* block_solve
+ Block-matrix support.
+
+* geomview
+ Simple ALBERTA-OOGL converter.
+
+* gmv
+ Stand-alone converter ALBERTA-gmv.
+
+* grape
+ GRAPE interface for ALBERTA. Only for non-parametric FE of dimension
+ 2 and 3. The GRAPE-interface consists of "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 appropriate command line switches
+ for "configure").
+
+* libalbas
+ Implementation of some more fancy basis functions (bubbles, direct
+ sums).
+
+* meshtv
+ MeshTV interface for ALBERTA. Only for non-parametric FE. The MeshTV
+ interface consists of the programs "alberta_meshtvX" with X in
+ {1,2,3}. These are installed in `PREFIX/bin/' as well.
+
+ The interface is only installed if the Silo library and header files
+ are available on your system. See "configure --help" for details.
+
+* paraview
+ Stand-alone converte ALBERTA-Paraview
+
+* static_condensation
+ Condensation of element bubbles, resulting in a drastical reduction
+ of the dimension.
+
+* triangle2alberta
+ Converter from the Triangle grid generator to the ALBERTA macro-file format.
+
+* write_mesh_fig
+ Dump a mesh to disk in a format suitable for xfig(1).
II) External packages
=====================
-1) Required Packages
---------------------
-
-The software-packages mentioned here are mandatory. 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
@@ -145,7 +182,9 @@ OpenGL -- you need some implementation of SGI's 3D-API. If your system
http://www.mesa3d.org/
If you don't have a clue what this is all about then ask your
- system-administrator.
+ system-administrator. In former version OpenGL was required to
+ compile ALBERTA, starting with this release graphical output
+ is an optional feature.
BLAS -- "Basic Linear Algebra Subprograms"
You definitely need some version of the BLAS. Often the BLAS
@@ -169,13 +208,8 @@ BLAS -- "Basic Linear Algebra Subprograms"
this restriction by linking in additional libraries, as shown
in some of the platform dependent examples listed below.
-
-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).
+ ALBERTA can be compiled without BLAS, in which case
+ C-replacements are used instead of the BLAS-functions.
gltools -- OpenGL toolkit
We strongly recommend that you install the gltools package;
@@ -248,6 +282,10 @@ Geomview -- An ancient program, originally from the Geometry Center,
meshes -- the `gvemod-ndview' add-on. Both are available from
SourceForge.
+Paraview -- For viewing the output from the alberta2paraviewXd converters.
+
+ http://www.paraview.org
+
alternate compilers
Many CPU-vendors distribute highly optimizing compilers for
their specific CPU architecture. Often those compilers
@@ -266,8 +304,8 @@ generic command line options for configure.
The remaining (i.e. ALBERTA specific) options are explained here:
-1.) Non-standard behavior of ALBERTA
--------------------------------------
+1.) ALBERTA's installation paths
+--------------------------------
The default installation prefix of the ALBERTA-package is the default
GNU installation prefix, i.e. `/usr/local/' Of course, you can change
@@ -283,9 +321,10 @@ the header-files and Makefile.alberta will end up in
/usr/local/include/alberta/
-The configured libtool-script will reside in
+The configured libtool-script and the Makefile-fragment for the
+demo-suite will reside in
- /usr/local/libexec/alberta-2.0/
+ /usr/local/libexec/alberta-VERSION/
and finally the demo package (under the name alberta-VERSION.demo.tar.gz,
where VERSION denotes the actual version of the alberta package) will
@@ -323,12 +362,45 @@ The options below control which of them are actually created.
information. (default: enabled)
--disable-graphics disable support for visualization, including all
add-ons which need graphics. (default: enabled)
+
+3.) Options controlling specific features
+-----------------------------------------
+
--enable-efence use the malloc debugger "Electric Fence" for all
allocations for the DEBUG libraries, the optimized
libraries will still use the default allocators.
(default: disabled)
-
-3.) Options controlling the search-path for external libraries
+ --enable-fortran-blas Use BLAS routines for some basic linear algebra
+ stuff. (default: disabled)
+ --disable-vector-basis-functions
+ Disable support for vector-valued basis functions.
+ If you leave this enabled ALBERTA supports
+ DIM_OF_WORLD-valued basis functions and scalar basis
+ functions. If you disable this feature ALBERTA only
+ supports scalar valued basis functions.
+ DIM_OF_WORLD-valued basis functions play an
+ important role, e.g. for the discretisation of
+ problems involving H(div) (Maxwell equations ...)
+ and, e.g., for stable mixed discretisations for the
+ Stokes-problem. Building ALBERTA with support for
+ vector valued basis functions increases the
+ compile-time, otherwise it should not have any
+ measureable performance impact, therefore this
+ feature is normally ENABLED. Disable it to reduce
+ the compile time if you do not need this feature.
+ (default: enabled)
+ --disable-chained-basis-functions
+ Disable support for chains of basis-functions.
+ ALBERTA has support for forming direct sums of
+ FE-spaces. This is useful, e.g., to implement
+ certain stable mixed discretisations for the
+ Stokes-problem (P1+Bubble = Mini, P1+FaceBubble =
+ Bernardi-Raugel, weak slip b.c.). Keeping this
+ feature enabled will have a slight performance
+ impact, you may disable it if you do not need this
+ feature. (default: enabled)
+
+4.) Options controlling the search-path for external libraries
--------------------------------------------------------------
See also "External Packages" above.
@@ -451,7 +523,9 @@ and "-O" otherwise.
The default flags for the debugging-enabled libraries are
"-O0 -ggdb -fno-inline -fno-builtin" with gcc and "-g" otherwise.
-The relevant environment- respectively make-variables are
+The relevant environment- respectively make-variables are listed at
+the end of the online-help provided by running `configure --help'.
+They include:
CFLAGS
C-compiler flags used for _both_, optimized and debug enabled libraries
@@ -464,7 +538,7 @@ ALBERTA_DEBUG_CFLAGS
C-compiler flags used for the debug enabled library. They are
prepended to the CFLAGS variable.
-FFLAGS
+ALBERTA_FFLAGS
Fortran-compiler flags. They are separated from the CFLAGS because
in general the Fortran compiler can come from a different vendor
than the C-compiler in which case the flags understood by the