\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
  (\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 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
\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 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?}


\textbf{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:
\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 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.