amg4psblas/docs/src/building.tex

\section{Configuring and Building AMG4PSBLAS\label{sec:building}}
\markboth{\textsc{AMG4PSBLAS User's and Reference Guide}}
         {\textsc{\ref{sec:building} Configuring and Building AMG4PSBLAS}}
In order to build AMG4PSBLAS it is necessary to set up a Makefile with appropriate
system-dependent variables; 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.

AMG4PSBLAS is implemented almost entirely in Fortran~2003, with some
interfaces to external libraries in C; the Fortran compiler
must support the Fortran~2003 standard plus the extension \verb|MOLD=|
feature, which enhances the usability of \verb|ALLOCATE|.
Many compilers do this; in particular, this is
supported by the GNU Fortran compiler, for which we
recommend to use at least version 4.8.
The software defines data types and interfaces for
real and complex data, in both single and double precision.

Building AMG4PSBLAS requires some base libraries (see Section~\ref{sec:prerequisites});
interfaces to optional third-party libraries, which extend the functionalities of AMG4PSBLAS
(see Section~\ref{sec:third-party}), are also available.  Many Linux distributions
(e.g., Ubuntu, Fedora, CentOS) provide precompiled packages for the prerequisite and
optional software. In many cases these packages are split between a runtime part and a
``developer'' part; in order to build AMG4PSBLAS you need both. A description of the base and
optional software used by AMG4PSBLAS is given in the next sections.

\subsection{Prerequisites\label{sec:prerequisites}}

The following base libraries are needed:
\begin{description}
\item[BLAS] \cite{blas3,blas2,blas1} Many vendors provide optimized versions
  of BLAS; if no vendor version is
  available for a given platform, the ATLAS software
  (\url{math-atlas.sourceforge.net})
  may be employed.  The reference BLAS from Netlib
  (\url{www.netlib.org/blas}) are meant to define the standard
  behaviour of the BLAS interface, so they are not optimized for any
  particular platform, and should only be used as a last
  resort. Note that BLAS computations form a relatively small part of
  the AMG4PSBLAS/PSBLAS computations; they are however critical when using
  preconditioners based on MUMPS, UMFPACK or SuperLU third party
  libraries. Note that UMFPACK requires a full LAPACK library; our
experience is that configuring ATLAS for building full LAPACK does not
work in the correct way. Our advice is first to download the LAPACK tarfile from
\url{www.netlib.org/lapack} and install it independently of ATLAS. In this case,
you need to modify the OPTS and NOOPT definitions for including -fPIC compilation option
in the make.inc file of the LAPACK library.
\item[MPI] \cite{MPI2,MPI1} A version of MPI is available on most
  high-performance computing systems.
 \item[PSBLAS] \cite{PSBLASGUIDE,psblas_00} Parallel Sparse BLAS (PSBLAS) is
  available from \url{github.com/sfilippone/psblas3} ?? {\bf Mettere tutto sotto psctoolkit}; version
  3.5.0  (or later) is required. Indeed, all the prerequisites
  listed so far are also prerequisites of PSBLAS.
\end{description}
Please note that the four previous libraries must have Fortran
interfaces compatible with AMG4PSBLAS;
usually this means that they should all be built with the same
compiler as AMG4PSBLAS.

\subsection{Optional third party libraries\label{sec:third-party}}

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 LU factorization package included in the SuiteSparse library, available from
  \url{faculty.cse.tamu.edu/davis/suitesparse.html};
  it provides sequential factorization and triangular system solution for double
  precision real and complex data. We tested version 4.5.4 of SuiteSparse.
  Note that for configuring SuiteSparse you should provide the right path to the BLAS
  and LAPACK libraries in the \verb|SuiteSparse_config/SuiteSparse_config.mk| file.
\item[MUMPS] \cite{MUMPS}
  A sparse LU factorization package available from \url{mumps.enseeiht.fr};
  it provides sequential and parallel factorizations and triangular system solution
  for single and double precision, real and complex data.
  We tested versions 4.10.0 and 5.0.1.
\item[SuperLU] \cite{SUPERLU}
  A sparse LU factorization package available from
  \url{crd.lbl.gov/~xiaoye/SuperLU/}; it provides sequential
  factorization and triangular system solution for single and double precision,
  real and complex data. We tested versions 4.3 and 5.0. If you installed BLAS from
  ATLAS, remember to define the BLASLIB variable in the make.inc file.
 \item[SuperLU\_Dist] \cite{SUPERLUDIST}
   A sparse LU factorization package available
   from the same site as SuperLU; it provides parallel factorization and
   triangular system solution for double precision real and complex data.
   We tested versions 3.3 and 4.2. If you installed BLAS from
   ATLAS, remember to define the BLASLIB variable in the make.inc file and
   to add the \verb|-std=c99| option to the C compiler options.
   Note that this library requires the ParMETIS
   library for parallel graph partitioning and fill-reducing matrix ordering, available from
   \url{glaros.dtc.umn.edu/gkhome/metis/parmetis/overview}.
\end{description}

\subsection{Configuration options}

In order to build AMG4PSBLAS, the first step is to use the \verb|configure| script
in the main directory to generate the necessary makefile.
%\textbf{Sono necessarie le parentesi intorno a s?}


\bf{DA RISCRIVERE}

As a minimal example consider the following:
\begin{verbatim}
./configure --with-psblas=PSB-INSTALL-DIR
\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 install  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 2.1.1 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]

Program names:
  --program-prefix=PREFIX            prepend PREFIX to installed program names
  --program-suffix=SUFFIX            append SUFFIX to installed program names
  --program-transform-name=PROGRAM   run sed PROGRAM on installed program names

Optional Features:
  --disable-option-checking  ignore unrecognized --enable/--with options
  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
  --enable-silent-rules   less verbose build output (undo: "make V=1")
  --disable-silent-rules  verbose build output (undo: "make V=0")
  --enable-dependency-tracking
                          do not reject slow dependency extractors
  --disable-dependency-tracking
                          speeds up one-time build
  --enable-serial         Specify whether to enable a fake mpi library to run
                          in serial mode.
  --enable-long-integers  Specify usage of 64 bits integers.

Optional Packages:
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
  --with-psblas=DIR       The install directory for PSBLAS, for example,
                          --with-psblas=/opt/packages/psblas-3.5
  --with-psblas-incdir=DIR
                          Specify the directory for PSBLAS C includes.
  --with-psblas-moddir=DIR
                          Specify the directory for PSBLAS Fortran modules.
  --with-psblas-libdir=DIR
                          Specify the directory for PSBLAS library.
  --with-ccopt            additional [CCOPT] flags to be added: will prepend
                          to [CCOPT]
  --with-fcopt            additional [FCOPT] flags to be added: will prepend
                          to [FCOPT]
  --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-extra-libs       List additional link flags here. For example,
                          --with-extra-libs=-lspecial_system_lib or
                          --with-extra-libs=-L/path/to/libs
  --with-blas=<lib>       use BLAS library <lib>
  --with-blasdir=<dir>    search for BLAS library in <dir>
  --with-lapack=<lib>     use LAPACK library <lib>
  --with-mumps=LIBNAME    Specify the libname for MUMPS. Default: autodetect
                          with minimum "-lmumps_common -lpord"
  --with-mumpsdir=DIR     Specify the directory for MUMPS library and
                          includes. Note: you will need to add auxiliary
                          libraries with --extra-libs; this depends on how
                          MUMPS was configured and installed, at a minimum you
                          will need SCALAPACK and BLAS
  --with-mumpsincdir=DIR  Specify the directory for MUMPS includes.
  --with-mumpsmoddir=DIR  Specify the directory for MUMPS Fortran modules.
  --with-mumpslibdir=DIR  Specify the directory for MUMPS library.
  --with-umfpack=LIBNAME  Specify the library name for UMFPACK and its support
                          libraries. Default: "-lumfpack -lamd"
  --with-umfpackdir=DIR   Specify the directory for UMFPACK library and
                          includes.
  --with-umfpackincdir=DIR
                          Specify the directory for UMFPACK includes.
  --with-umfpacklibdir=DIR
                          Specify the directory for UMFPACK library.
  --with-superlu=LIBNAME  Specify the library name for SUPERLU library.
                          Default: "-lsuperlu"
  --with-superludir=DIR   Specify the directory for SUPERLU library and
                          includes.
  --with-superluincdir=DIR
                          Specify the directory for SUPERLU includes.
  --with-superlulibdir=DIR
                          Specify the directory for SUPERLU library.
  --with-superludist=LIBNAME
                          Specify the libname for SUPERLUDIST library.
                          Requires you also specify SuperLU. Default:
                          "-lsuperlu_dist"
  --with-superludistdir=DIR
                          Specify the directory for SUPERLUDIST library and
                          includes.
  --with-superludistincdir=DIR
                          Specify the directory for SUPERLUDIST includes.
  --with-superludistlibdir=DIR
                          Specify the directory for SUPERLUDIST library.

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    (Objective) C/C++ preprocessor flags, e.g. -I<include dir> if
              you have headers in a nonstandard directory <include dir>
  MPICC       MPI C compiler command
  MPIFC       MPI Fortran compiler command
  CPP         C preprocessor

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 <https://github.com/sfilippone/mld2p4-2/issues>.
\end{verbatim}

For instance, if a user has built and installed PSBLAS 3.5 under the
\verb|/opt| directory and is
using the SuiteSparse package (which includes UMFPACK), then MLD2P4
might be configured with:
\begin{verbatim}
 ./configure --with-psblas=/opt/psblas-3.5/ \
 --with-umfpackincdir=/usr/include/suitesparse/
\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; this file will be copied in the
install directory under the name \verb|Make.inc.MLD2P4|.

To use the MUMPS solver package,
the user has to add the appropriate options to the configure script;
by default we are looking for the libraries
\verb|-ldmumps -lsmumps| \verb| -lzmumps -lcmumps -mumps_common -lpord|.
MUMPS often uses additional packages such as ScaLAPACK, ParMETIS,
SCOTCH, as well as enabling OpenMP; in such cases it is necessary to
add linker options with the \verb|--with-extra-libs| configure option.

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 report them through our
issues page on \\[2mm]
\url{https://github.com/psctoolkit/amg4psblas/issues}\\

To enable us to track the bug, please provide a log from the failing
application, the test conditions, and ideally a self-contained test
program reproducing the issue.

\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 available in AMG4PSBLAS.
\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 package.
\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| programs generate
matrices in full parallel mode from the discretization of a sample partial
differential equation.