\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 usually this is not needed to build the software. MLD2P4 is implemented almost entirely in Fortran~95, with some interfaces to external libraries in C; the Fortran compiler must 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). 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] \cite{blas3,blas2,blas1} Many vendors provide optimized versions of the Basic Linear Algebra Subprograms; if no vendor version is available for a given platform, the ATLAS software (\verb!http://math-atlas.sourceforge.net/!) 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 are not optimized for any particular plaftorm, and should only be used as a last resort. Note that BLAS computations 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] \cite{MPI2,MPI1} A version of MPI is available on most high-performance computing systems; only version 1.1 is required. \item[BLACS] \cite{BLACS} The Basic Linear Algebra Communication Subprograms are available in source form from \verb|http://www.netlib.org/blacs|; some vendors include them in their parallel computing support libraries. \item[PSBLAS] \cite{PSBLASGUIDE,psblas_00} Parallel Sparse BLAS is available from \\ \verb|http://www.ce.uniroma2.it/psblas|; version 2.3 (or later) is required. Indeed, all the prerequisites listed so far are also prerequisites of PSBLAS. To build the MLD2P4 library it is necessary to get access to the source PSBLAS directory employed to build the version under use; after the MLD2P4 build process completes, only the compiled form of the PSBLAS library is necessary to build user applications. \end{description} Please note that the four previous libraries must have Fortran interfaces compatible with MLD2P4; usually this means that they should all be built with the same compiler as MLD2P4. \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] \cite{UMFPACK} A sparse direct factorization package available from \\ \verb|http://www.cise.ufl.edu/research/sparse/umfpack/|; provides serial factorization and triangular system solution for double precision real and complex data. We have tested versions 4.4 and 5.1. \item[SuperLU] \cite{SUPERLU} A sparse direct factorization package available from \\ \verb|http://crd.lbl.gov/~xiaoye/SuperLU/|; provides serial factorization and triangular system solution for single and double precision, real and complex data. We have tested versions 3.0 and 3.1. \item[SuperLU\_Dist] \cite{SUPERLUDIST} A sparse direct factorization package available from the same site as SuperLU; provides parallel factorization and triangular system solution for double precision real and complex 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} which assumes that the various MPI compilers and support libraries are available in the standard directories on the system, and specifies only the PSBLAS build directory (note that the latter 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.3 --with-libs List additional link flags here. For example, --with-libs=-lspecial_system_lib or --with-libs=-L/path/to/libs --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 if you have libraries in a nonstandard directory LIBS libraries to pass to the linker, e.g. -l CC C compiler command CFLAGS C compiler flags CPPFLAGS C/C++/Objective C preprocessor flags, e.g. -I if you have headers in a nonstandard directory 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 . \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\label{sec:ex_and_test}} The package contains the \verb|examples| and \verb|tests| directories; both of them are further divided into \verb|fileread| and \verb|pdegen| 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 tests] 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 or the Harwell-Boeing storage format; the \verb|pdegen| instead generate matrices in full parallel mode from the discretization of a sample PDE.