You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
206 lines
9.4 KiB
TeX
206 lines
9.4 KiB
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|.
|
|
Most Fortran compilers provide this feature; 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. A number of 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
|
|
(\href{http://math-atlas.sourceforge.net}{math-atlas.sourceforge .net})
|
|
may be employed. The reference BLAS from Netlib
|
|
(\href{http://www.netlib.org/blas}{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; however they are critical when using
|
|
preconditioners based on the MUMPS, UMFPACK or SuperLU third party
|
|
libraries. UMFPACK requires a full LAPACK library; our
|
|
experience is that configuring ATLAS for building full LAPACK does not always
|
|
work in the expected way. Our advice is first to download the LAPACK tarfile from
|
|
\href{http://www.netlib.org/lapack}{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
|
|
\href{https://psctoolkit.github.io/products/psblas/}{psctoolkit.github.io/
|
|
products/psblas/}; version 3.7.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 being used for 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?}
|
|
|
|
|
|
\textbf{DA RISCRIVERE}
|
|
|
|
As a minimal example consider the following:
|
|
\ifpdf
|
|
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{console}
|
|
./configure --with-psblas=PSB-INSTALL-DIR
|
|
\end{minted}
|
|
\else
|
|
\begin{verbatim}
|
|
./configure --with-psblas=PSB-INSTALL-DIR
|
|
\end{verbatim}
|
|
\fi
|
|
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:
|
|
\ifpdf
|
|
\inputminted[breaklines=true,bgcolor=bg,fontsize=\small]{console}{../configureout.txt}
|
|
\else
|
|
\lstinputlisting{../configureout.txt}
|
|
\fi
|
|
For instance, if a user has built and installed PSBLAS 3.7 under the
|
|
\verb|/opt| directory and is
|
|
using the SuiteSparse package (which includes UMFPACK), then AMG4PSBLAS
|
|
might be configured with:
|
|
\ifpdf
|
|
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{console}
|
|
./configure --with-psblas=/opt/psblas-3.5/ --with-umfpackincdir=/usr/include/suitesparse/
|
|
\end{minted}
|
|
\else
|
|
\begin{verbatim}
|
|
./configure --with-psblas=/opt/psblas-3.5/ \
|
|
--with-umfpackincdir=/usr/include/suitesparse/
|
|
\end{verbatim}
|
|
\fi
|
|
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.AMG4PSBLAS|.
|
|
|
|
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
|
|
\ifpdf
|
|
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{console}
|
|
make
|
|
\end{minted}
|
|
\else
|
|
\begin{verbatim}
|
|
make
|
|
\end{verbatim}
|
|
\fi
|
|
followed (optionally) by
|
|
\ifpdf
|
|
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{console}
|
|
make install
|
|
\end{minted}
|
|
\else
|
|
\begin{verbatim}
|
|
make install
|
|
\end{verbatim}
|
|
\fi
|
|
\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 acquainted 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.
|