  is an Adaptive multi-Level finite element toolbox using 
         Bisectioning refinement and Error control by Residual
         Techniques for scientific Applications.

-------------------------------------------------------------------------------

Contents
========

I.   Introduction

II.  External Packages (both required and optional packages)
   1.) Required Packages
         OpenGL
         BLAS (with examples)
   2.) Optional Packages
         gltools
         GRAPE
         Silo
         Open DX 
         alternate compilers

III. Configure Options
   1.) Non-standard behaviour of ALBERTA
   2.) Options affecting which versions of ALBERTA are built
   3.) Options controlling the search-path for external libraries

IV.  Compiler flags (with examples)

V.   Some platform dependent notes and examples

-------------------------------------------------------------------------------


I) Introduction
===============

This is ALBERTA Version 2.0. Generic installation instructions can be
found in the file `INSTALL' in this directory.  ALBERTA has a web-page
at

        http://www.alberta-fem.de/

Please see the file `COPYING' for information about the availability of
ALBERTA.

The directory layout 
Contained in the package are the following sub-packages:

                  __________ alberta/ __________ src/ _______|--- 1d/
                 /                          \                |--- 2d/ 
                /                            -- doc/         |--- 3d/
               /                                             |--- Common/
              /_____________ demo/ __ src/ _______|--- 1d/   |--- alberta*/
alberta-2.0 /                                    |--- 2d/  
             \                                    |--- 3d/
              \                                   |--- Common/
               \                           
                \__________ alberta_util/ ___ src/
                 \
                  \
                   \_______ add_ons/ ---- grape/ __ mesh/ ____|--- 2d/
                    \               \                         |--- 3d/
                     \               \                        |--- Common/
                      \               \
	               \___            - meshtv/ ___|--- 1d/
		        \                           |--- 2d/ 
		         \                          |--- 3d/
		          \                         |--- Common/
                           \
                            \_ 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 apropriate 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 standalone 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.

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

		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.

	You should have a look at
	
	http://www.netlib.org/blas/faq.html

	which lists some URLs to optimized BLAS-implementations for
	some architectures. For an optimized 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".

	Compiler dependence
	-------------------
	In general, you need a version of the BLAS which was compiled
	by the Fortran compiler you are using to compile (parts of)
	the ALBERTA package. Sometimes it is possible to get around
	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).

gltools -- OpenGL toolkit
	We strongly recommend that you install the gltools package;
	you can fetch it from

	http://www.wias-berlin.de/software/gltools/

	gltools provides a more flexible graphical output than would
	be otherwise available with ALBERTA. 

	NOTE: you need at least gltools-2-4. Version 2-3 will _not_
	work. "configure" does not check for right version, it's up to
	yourself.

dxtools -- Open DX toolkit
	The dxtools are an interface to the Open DX visualization software.
	It may be downloaded from

	http://www.opendx.org/

	The visualization features are far more advanced than gltools, 
	however Open DX is a huge project that takes time getting used to.
	The dxtools interface was designed to keep things simple and 
	intuitive.
	
GRAPE -- Graphics Programming Environment
	If GRAPE is present, the four programs alberta_grape22,
	alberta_grape33, alberta_movi22 and alberta_movi33 are
	compiled and installed in PREFIX/bin/. 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/

Silo -- 
	Silo is a library developed at the Lawrence Livermore National
	Laboratory to handle portable storage of mesh and function data. It
	serves as an interface to MeshTV, an open source visualization 
	project also based at the LLNL.
	If the Silo library is present, the programs alberta_meshtv? are
	compiled and installed. They can be used to convert ALBERTA meshes 
	and DOF_REAL[_D]_VECS to Silo data files, which can then be 
	visualized using the MeshTV binary.

	MeshTV and Silo are available from

	http://www.llnl.gov/bdiv/meshtv/


alternate compilers
	Many CPU-vendors distribute highly optimizing compilers for
	their specific CPU architecture. Often those compilers
	generate much faster code than even a modern gcc. Sometimes
	they are available at no costs, at least for private and
	academical use.


III) Configure Options
======================

"configure --help" will give you a summary of available options. The file
"INSTALL" contains generic configuration instructions and a description of
generic command line options for configure.

The remaining (i.e. ALBERTA specific) options are explained here:


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. Of course,
you can change the default behavior by using the "--prefix=PREFIX"
switch when running configure (see ./INSTALL). However, the default
layout is like follows:

When compiling ALBERTA below

	/usr/people/claus/alberta-2.0/

then the libraries will go to

	/usr/people/claus/alberta-2.0/lib/

the header-files and Makefile.alberta will end up in

	/usr/people/claus/alberta-2.0/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-2.0/share/alberta

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_OF_WORLD>d[_debug]

The options below control which of them are actually created.

  --disable-alberta-1
	Disable building of an ALBERTA library for Finite Elements of
	dimension 1. (default: enabled)

  --disable-alberta-2
	Disable building of an ALBERTA library for Finite Elements of
	dimension 2. (default: enabled)

  --disable-alberta-3
	Disable building of an ALBERTA library for Finite Elements of
	dimension 3. (default: enabled)

  --disable-debug 
	Disable building of ALBERTA libraries with debugging
	information. On some systems (or better: with some compilers)
	optimization and debugging are mutual exclusive, therefore
	there are separate ALBERTA libraries which are compiled with
	optimization, but without debugging information, and other
	versions which are compiled without optimization, 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.

  --with-PKG-name=NAME
        Alter the default name of the package,
        e.g. "--with-opengl-name=MesaGL" or "--with-blas-name=cxml".
	NOTE: it is possible to specify more than one library. For
	example on (some versions of?) Solaris the BLAS-library is
	called "libsunperf.so". If you want to link with this library
	using gcc and g77, then you need to specify

	"--with-blas-name=sunperf -lfui -lfsu -lsunmath"

	Note the "-l" in front of the additional libraries.
	(of course, in addition to --with-blas-name you also need
	--with-blas-lib=WHATEVER)

  --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/".

  --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/".

The following quotes the relevant fragment of the online-help obtained
by running "configure --help". Please see the file ./INSTALL for the
notation (e.g. PREFIX, EPREFIX etc.).

  --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-dx       	  disable use of package dx (default: autodetect)
  --with-dx-name=NAME
                          use NAME as the name of the dx library (without
                          leading "lib" prefix and trailing suffix). Default:
                          "dx"
  --with-dx-dir=DIR       use dx library (and headers) below directory
                          DIR (no default)
  --with-dx-lib=DIR       use dx library below directory DIR (default:
                          EPREFIX/lib/)
  --with-dx-headers=DIR
                          use dx 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:
                          PREFIX/lib/)
  --with-grape-headers=DIR
                          use grape include files below directory DIR
                          (default: PREFIX/include/)

  --with-silo-dir=DIR	  use Silo library (and headers) below directory DIR
                          (no default)
  --with-silo-lib=DIR     use Silo library below directory DIR (default:
                          PREFIX/lib/)
  --with-silo-headers=DIR
                          use Silo include files below directory DIR
                          (default: PREFIX/include/)


IV. Compiler flags
==================

The default flags for the optimized 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.

The relevant environment- respectively make-variables are

CFLAGS
  C-compiler flags used for _both_, optimized and debug enabled libraries

ALBERTA_OPTIMIZE_CFLAGS
  C-compiler flags used fo the optimized library. They are prepended
  to the CFLAGS variable.

ALBERTA_DEBUG_CFLAGS
  C-compiler flags used fo the debug enabled library. They are
  prepended to the CFLAGS variable.

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
  Fortran compiler are different from the flags understood by the
  C-compiler.

You have to consult the documentation for the compiler(s) you are using
to determine the appropriate switches for your setup.

There are three ways to set those flags:

a.) arguments to configure
b.) environment variables (have to be defined _before_ running configure)
c.) arguments to make

We recommend using a.).

Examples:
---------

1.) gcc with a Pentium 4

  ./configure [OTHER OPTIONS] \
     CFLAGS="-march=pentium4 -mfpmath=sse" \
     FFLAGS="-march=pentium4 -mfpmath=sse" 
  make
  make install

or (assuming a Bourne-shell)

  CFLAGS="-march=pentium4 -mfpmath=sse"
  FFLAGS="-march=pentium4 -mfpmath=sse" 
  export CFLAGS FFLAGS

  ./configure [OTHER OPTIONS]
  make
  make install

or

  ./configure [OTHER OPTIONS]
  make CFLAGS="-march=pentium4 -mfpmath=sse" \
    FFLAGS="-march=pentium4 -mfpmath=sse" 
  make install

2.) Pentium 4 with icc and with Intel "math kernel library" (BLAS
implementation)

  ./configure [OTHER OPTIONS] \
     CC=icc CFLAGS="-xW" ALBERTA_OPTIMIZE_CFLAGS="-O3" \
     ALBERTA_DEBUG_CFLAGS="-O0 -g" \
     F77=ifc FFLAGS="-xW -O3" \
     --with-blas-name=mkl --with-blas-lib=/opt/intel/mkl61/lib/32/
  make
  make install

or set environment variables or use arguments to "make" as shown in
example 1.)

V. Some platform dependent notes and examples
=============================================

0) Compilation under SuSE Linux:
--------------------------------

a) SuSE 9.2: We used MesaGL and a BLAS lib included in our
   distribution. If MesaGL is not found, "configure" will also try "GL". The 
   alberta_util lib needed "-lg2c" to process FORTRAN code properly.

b) SuSE 10.0: More trouble with the FORTRAN compiler. Try running
   F77=gfortran ../configure


1) Compilation under Fedora Core
--------------------------------

a) Install the following packages (and dependencies)

xorg-x11-devel
blas
gcc-gfortran

This can be done with the command (as root):

# yum -y install xorg-x11-devel blas gcc-gfortran

You will also need the packages  make, gcc
which usually come by default if you have a "workstation" installation.

b) install gltools (everything as root):
# cd /usr/local
# tar vxfz /path/to/gltools-2-4.tar.gz
# cd gltools-2-4
edit the Makefile change the line
LIBRARY_PATH=-L/usr/X11/lib
to
LIBRARY_PATH=-L/usr/X11R6/lib 

2) Compilation under Ubuntu/Xubuntu/Kubuntu
-------------------------------------------
a) Install the following packages (and dependencies)

make
gcc
g77
mesa-common-dev
libc6-dev
libx11-dev
libxext-dev
atlas3-sse2-dev

This can be done with the command:

sudo apt-get install make gcc g77 mesa-common-dev libc6-dev libx11-dev\
libxext-dev atlas3-sse2-dev

b) Install gltools
cd /usr/local
sudo tar vxfz /path/to/gltools-2-4.tar.gz
cd gltools-2-4
edit the Makefile change the line
 LIBRARY_PATH=-L/usr/X11/lib
to
 LIBRARY_PATH=-L/usr/lib
sudo make 


3) Intel's  "math core library" libmkl:
--------------------------------------
Make sure to also link with libguide, this can be achieved by the
following configure switches:

	--with-blas-lib=/opt/intel/mkl61/lib/32/ --with-blas-name="mkl -lguide"

You also need to set the LD_LIBRARY_PATH variable appropriately:

	export LD_LIBRARY_PATH=/opt/intel/mkl61/lib/32

or

	setenv LD_LIBRARY_PATH /opt/intel/mkl61/lib/32


4) g77-compiled libblas on Linux, but Intel's ifc compiler for ALBERTA
-------------------------------------------------------------------
NOTE: this probably doesn't make to much sense, but you can
try the following

	--with-blas-name="blas -lg2c"


5) SunOS (Solaris), using libsunperf:
----------------------------------
Find out about the location of libsunperf, then using Sun's f77
compiler you need the following switches:

	--with-blas-lib=LOCATION --with-blas-name=sunperf

However, with gcc the following might work:

	--with-blas-lib=LOCATION --with-blas-name="sunperf -lfui -lfsu -lsunmath"
	

6) Alpha AXP with Compaq's extended math-library libcxml:
------------------------------------------------------
The following might work (UNTESTED!!!)

	--with-blas-lib=LOCATION --with-blas-name="cxml -lcpml"


7) MAC OS X using the Accelerate library:
--------------------------------------
The following switch has been reported to work:

	--with-blas-name=Accelerate

The following location was used for the OpenGL library:

	--with-opengl-lib=/usr/X11R6/lib --with-opengl-headers=/usr/X11R6/include


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
PLEASE LEAVE HERE FOR ISPELL:
 LocalWords:  src alberta UTIL ac in's installdir util gltools FE grapeXX SGI's
 LocalWords:  moviXX OpenGL API MesaGL 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
