ALU-Grid library
===================

License
-------

The ALU-Grid library and headers are licensed under the GNU Lesser GPL
version 2.1. The full license text can be found in the file COPYING
and via http://www.gnu.org/licenses/lgpl.html .


Compiler 
--------

The ALU-Grid code in known to compile with the GNU Compiler version 3.4.x or higher. 
Also with the INTEL C++ Compiler version 8.1 or higher the code compiles.
Furthermore the code compiles with the IBM xlC compiler version 6 or higher. 

The compiler can be chosen by editing the fields COMP and CXXCOMP in the
*.opts files. For parallel computations the MPI compiler, like mpiCC should
be used or the include path and lib path adapted. 


Getting started
---------------

To compile the library ALU-Grid has to check several components of
your system. Run

  ./configure

to commence those tests. See ./configure --help for detail help on options. 
If you intend to use the parallel version of the
grid, make sure that you have a version of MPI, and METIS (--with-metis=PATH), and 
PARTY (--with-party=PATH) and supply the respective flags to the 
configure script. Dynamic load balancing can only be used if either METIS
or PARTY Lib or both are linked to the ALU-Grid Library.

For parallel computation MPI is needed, common packages are 
MPICH (version 1.2.5 or higher) or LAM MPI (version 7.x).
To compile the parallel version of the library use the MPI compiler script
(i.e. mpiCC) by passing this as CXX variable to the configure script 
(i.e. ./configure CXX=mpiCC). If not using the MPI compiler scripts just
make sure that all include path and library paths are set the right way.

For example to compile the parallel version of ALU-Grid the configure
command can look as follows: 

./configure CXX=mpiCC --with-metis="metis_path" --with-party="partylib_path"

For METIS (version 4.0 or higher) see http://www-users.cs.umn.edu/~karypis/metis/metis/ ,
see also the section Known bugs, when you using METIS. 
For PARTY Lib (version 1.1 or higher) see http://wwwcs.upb.de/fachbereich/AG/monien/RESEARCH/PART/party.html .

You can use

  ./configure --prefix=PATH

if you don't want ALU-Grid to be installed into the default directory
(i.e. the path were ALU-Grid was unpacked).

After configuration

  make
  make install

build and install ALU-Grid.  


Dynamic Load Balancing Options
------------------------------

If the compiled code is used for parallel computations including dynamic
load balancing, then a parameter file named "lastverteilung.cfg" should be
available in the dicrectory the program is launched. See
"misc/lastverteilung.cfg" for an example file. 

The file must contain three values: 
first row: ldb_under (value < 1.0), for example 0.0
second row: ldb_over (value > 1.0), for example 1.2 
third row: Graph partitioning method, for example 11 

Available methods are: 

NONE = 0
COLLECT = 1

PARTY_helpfulSet = 3
PARTY_kernighanLin = 4
PARTY_linear = 7
PARTY_gain = 8
PARTY_farhat = 9

METIS_PartGraphKway = 11
METIS_PartGraphRecursive = 12

See the documentation of the corresponding package for detail on the
methods. 


Debug Options
--------------

There are serveral debug options that can be set an shell environment
variable and that forces the code to produce debug output. To use this
feature, the code must be compiled without the CPP variable NDEBUG set. 
The following shell environment variables can be set to a level of 
verbosity (higher is better).

VERBOSE      general verbose output  
VERBOSE_MGB  output produced by the macro grid builder 
VERBOSE_LDB  output produced while partitioning. 
VERBOSE_PLL  output produced by parallel grid methods


Optimization 
-------------

The ALU-Grid code is highly riddled with assert statements. 
Therefore it is recommened to compile the library and the application code
with the CPP variable NDEBUG set (i.e. -DNDEBUG) to avoid all asserts
statement tests. 

Known bugs: On Intel ia64 architectures the optimisation option -O3 dosen't
work with the INTEL C++ Compiler. 


Debug
-----

For debugging the code the preprocessor variable NDEBUG must not be defined
and additionally the preprocessor variable DEBUG_ALUGRID can be defined
for object reference counting.


Knowns Bugs 
-----------

Intel ia64 architectures: On Intel ia64 architectures the 
optimisation option -O3 dosen't work with the INTEL C++ Compiler. 

METIS bug: 

If you want to use the METIS library for partitioning, comment 
in the metis_dir/Lib/proto.h line 462 the function declaration 
int log2(int);

This bug has been reported and hopefully will be fixed soon.