amg4psblas/docs/pdf/building.tex

\section{Configuring and Building MLD2P4\label{sec:building}}
\markboth{\textsc{MLD2P4 User's and Reference Guide}}
         {\textsc{\ref{sec:building} Configuring and Building MLD2P4}}
To build MLD2P4 it is necessary to set up a Makefile with appropriate
values for your system; this is done by means of the \verb|configure|
script. The distribution also includes the autoconf and automake
sources employed to generate the script, but this should not normally
be needed to build the software. 

MLD2P4 is implemented almost entirely in Fortran~95, with some
interfaces to external libraries in C; we require the Fortran compiler
to support the Fortran~95 standard plus the extension TR15581, which
enhances the usability of \verb|ALLOCATABLE| variables. Most modern
Fortran compilers support this language level. In particular, this is
supported by the GNU Fortran compiler as of version 4.2.0; however we
recommend to use the latest available release (4.3.1 at the time of
this writing<6E>).
The software defines data types and interfaces for
real and complex data, in both single and double precision. 

\subsection{Prerequisites}
The following base libraries are needed: 
\begin{description}
\item[BLAS] The Basic Linear Algebra subprograms. Many vendors provide
  optimized versions; if no vendor version is available for a given 
  platform, the  ATLAS software  \verb!http://www.netlib.org/atlas!
  may be employed.  The reference BLAS from Netlib
  \verb|http://www.netlib.org/blas| are meant to define the standard
  behaviour of the BLAS interface, so they not optimized for any
  particular plaftorm, and  should only be used as a last
  resort.  Note that BLAS computation form a relatively small part of
  the MLD2P4/PSBLAS computations; they are however critical when using
  preconditioners based on the UMFPACK or SuperLU third party
  libraries.  
\item[MPI] A version of MPI is available on most high performance
  computing system; we only require version 1.1.
\item[BLACS] The Basic Linear Algebra Communication Subroutines are
  available in source form from \verb|http://www.netlib.org/blacs|;
  some vendors  include them in their parallel computing
  support libraries. 
\end{description}

The MLD2P4 software requires PSBLAS version 2.3 (at least), available
from \verb|http://www.ce.uniroma2.it/psblas|; indeed, all the
prerequisites listed so far are also prerequisites of PSBLAS. Please
note that to build the MLD2P4 library it is necessary to get access to
the source PSBLAS directory used to build the version under use; after
the build process completes, only the compiled form of the library is
necessary to build user applications.

Please note that all the libraries listed so fare (BLAS, MPI, BLACS,
PSBLAS) must have Fortran interfaces compatible with the MLD2P4;
usually this means that they should all be built with the same
compiler. 


\subsection{Optional third party libraries}

We provide interfaces to the following third-party software libraries;
note that these are optional, but if you enable them some defaults
for multilevel preconditioners may change to reflect their presence. 

\begin{description}
\item[UMFPACK] A sparse direct factorization package available from\\ 
  \verb|http://www.cise.ufl.edu/research/sparse/umfpack/|; 
  provides serial factorization and solution for double
  precision real and complex double precision data. We have tested
  versions 4.4 and 5.1; 
\item[SuperLU] A sparse direct factorization package available from \\
  \verb|http://crd.lbl.gov/~xiaoye/SuperLU/|; provides serial
  factorization and solution for single and double precision real and
  complex data. We have tested versions 3.0 and 3.1.
\item[SuperLU\_Dist] A sparse direct factorization package available
  from the same site as SuperLU; provides parallel factorization and
  solution for real and complex double precision data. We have tested
  version 2.1.
\end{description}

\subsection{Configuration options}

To build  MLD2P4 the first step is to use the \verb|configure| script
in the main directory to generate the necessary makefile(s). 

As a minimal example consider the following:
\begin{verbatim}
./configure --with-psblas=/home/user/PSBLAS/psblas-2.3
\end{verbatim}
This assumes that the various MPI compilers and support libraries are
available in the standard directories on the system. Note that the
PSBLAS build directory must be specified with an {\em absolute} path.
The full set of options may be looked at by issuing the command
\verb|./configure --help|, which produces:
\begin{verbatim}
`configure' configures MLD2P4 1.0 to adapt to many kinds of systems.

Usage: ./configure [OPTION]... [VAR=VALUE]...

To assign environment variables (e.g., CC, CFLAGS...), specify them as
VAR=VALUE.  See below for descriptions of some of the useful variables.

Defaults for the options are specified in brackets.

Configuration:
  -h, --help              display this help and exit
      --help=short        display options specific to this package
      --help=recursive    display the short help of all the included packages
  -V, --version           display version information and exit
  -q, --quiet, --silent   do not print `checking...' messages
      --cache-file=FILE   cache test results in FILE [disabled]
  -C, --config-cache      alias for `--cache-file=config.cache'
  -n, --no-create         do not create output files
      --srcdir=DIR        find the sources in DIR [configure dir or `..']

Installation directories:
  --prefix=PREFIX         install architecture-independent files in PREFIX
			  [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
			  [PREFIX]

By default, `make install' will install all the files in
`/usr/local/bin', `/usr/local/lib' etc.  You can specify
an installation prefix other than `/usr/local' using `--prefix',
for instance `--prefix=$HOME'.

For better control, use the options below.

Fine tuning of the installation directories:
  --bindir=DIR           user executables [EPREFIX/bin]
  --sbindir=DIR          system admin executables [EPREFIX/sbin]
  --libexecdir=DIR       program executables [EPREFIX/libexec]
  --sysconfdir=DIR       read-only single-machine data [PREFIX/etc]
  --sharedstatedir=DIR   modifiable architecture-independent data [PREFIX/com]
  --localstatedir=DIR    modifiable single-machine data [PREFIX/var]
  --libdir=DIR           object code libraries [EPREFIX/lib]
  --includedir=DIR       C header files [PREFIX/include]
  --oldincludedir=DIR    C header files for non-gcc [/usr/include]
  --datarootdir=DIR      read-only arch.-independent data root [PREFIX/share]
  --datadir=DIR          read-only architecture-independent data [DATAROOTDIR]
  --infodir=DIR          info documentation [DATAROOTDIR/info]
  --localedir=DIR        locale-dependent data [DATAROOTDIR/locale]
  --mandir=DIR           man documentation [DATAROOTDIR/man]
  --docdir=DIR           documentation root [DATAROOTDIR/doc/mld2p4]
  --htmldir=DIR          html documentation [DOCDIR]
  --dvidir=DIR           dvi documentation [DOCDIR]
  --pdfdir=DIR           pdf documentation [DOCDIR]
  --psdir=DIR            ps documentation [DOCDIR]

Optional Packages:
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
  --with-psblas           The source directory for PSBLAS, for example,
                          --with-psblas=/opt/packages/psblas-2.2
  --with-libs             List additional libraries here. For example,
                          --with-libs=-lsuperlu or
                          --with-libs=/path/libsuperlu.a
  --with-clibs            additional CLIBS flags to be added: will prepend
                          to CLIBS
  --with-flibs            additional FLIBS flags to be added: will prepend
                          to FLIBS
  --with-library-path     additional LIBRARYPATH flags to be added: will
                          prepend to LIBRARYPATH
  --with-include-path     additional INCLUDEPATH flags to be added: will
                          prepend to INCLUDEPATH
  --with-module-path      additional MODULE_PATH flags to be added: will
                          prepend to MODULE_PATH
  --with-umfpack=LIBNAME  Specify the library name for UMFPACK library.
                          Default: "-lumfpack -lamd"
  --with-umfpackdir=DIR   Specify the directory for UMFPACK library and
                          includes.
  --with-superlu=LIBNAME  Specify the library name for SUPERLU library.
                          Default: "-lslu"
  --with-superludir=DIR   Specify the directory for SUPERLU library and
                          includes.
  --with-superludist=LIBNAME
                          Specify the libname for SUPERLUDIST library.
                          Requires you also specify SuperLU. Default: "-lslud"
  --with-superludistdir=DIR
                          Specify the directory for SUPERLUDIST library and
                          includes.

Some influential environment variables:
  FC          Fortran compiler command
  FCFLAGS     Fortran compiler flags
  LDFLAGS     linker flags, e.g. -L<lib dir> if you have libraries in a
              nonstandard directory <lib dir>
  LIBS        libraries to pass to the linker, e.g. -l<library>
  CC          C compiler command
  CFLAGS      C compiler flags
  CPPFLAGS    C/C++/Objective C preprocessor flags, e.g. -I<include dir> if
              you have headers in a nonstandard directory <include dir>
  CPP         C preprocessor
  MPICC       MPI C compiler command

Use these variables to override the choices made by `configure' or to help
it to find libraries and programs with nonstandard names/locations.

Report bugs to <salvatore.filippone@uniroma2.it>.
\end{verbatim}
Thus, a sample build with libraries in installation
directories specifics to the GNU 4.3 compiler suite might be as
follows, specifying only the UMFPACK external package: 
\begin{verbatim}
 ./configure --with-psblas=/home/user/psblas-2.3/ \
 --with-libs="-L/usr/local/BLAS/gnu43 -L/usr/local/BLACS/gnu43" \
 --with-blacs=-lmpiblacs  --with-umfpackdir=/usr/local/UMFPACK/gnu43 
\end{verbatim}
Once the configure script has completed execution, it will have
generated the file \verb|Make.inc| which will then be used by all
Makefiles in the directory tree. 

To build the library the user will now enter 
\begin{verbatim}
make
\end{verbatim}
followed (optionally) by 
\begin{verbatim}
make install
\end{verbatim}

\subsection{Example and test programs}
The package contains the \verb|examples| and \verb|tests| directories;
both of them are further divided into \verb|fileread| and
\verb|pargen| subdirectories. Their purpose is as follows:
\begin{description}
\item[\tt examples] contains a set of simple example programs with a
  predefined choice of preconditioners, selectable via integer
  values. These are intended to get an acquaintance with the
  multilevel preconditioners.
\item[\tt test] contains a set of more sophisticated examples that
  will allow the user, via the input files in the \verb|runs|
  subdirectories, to experiment with the full range of preconditioners
  implemented in the library.
\end{description}
The \verb|fileread| directories contain sample programs that read
sparse matrices from files, according to the Matrix Market storage
format; the \verb|pargen| instead generate matrices in full parallel
mode from the discretization of a sample PDE.