|
|
|
|
\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<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 <bugreport@mld2p4.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{Bug reporting}
|
|
|
|
|
If you find any bugs in our codes, please let us know at
|
|
|
|
|
\begin{rawhtml}
|
|
|
|
|
<a href="mailto:bugreport@mld2p4.it">
|
|
|
|
|
\end{rawhtml}
|
|
|
|
|
\texttt{bugreport@mld2p4.it}
|
|
|
|
|
\begin{rawhtml}
|
|
|
|
|
</a>
|
|
|
|
|
\end{rawhtml}
|
|
|
|
|
; be aware that
|
|
|
|
|
the amount of information needed to reproduce a problem in a parallel
|
|
|
|
|
program may vary quite a lot.
|
|
|
|
|
\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.
|
