amg4psblas/docs/src/gettingstarted.tex

\section{Getting Started\label{sec:started}}
\markboth{\textsc{MLD2P4 User's and Reference Guide}}
         {\textsc{\ref{sec:started} Getting Started}}

We describe the basics for building and applying MLD2P4 one-level and multilevel
(i.e., AMG) preconditioners with the Krylov solvers included in PSBLAS \cite{PSBLASGUIDE}.
The following steps are required:
\begin{enumerate} 
\item \emph{Declare the preconditioner data structure}. It is a derived data type,
  \verb|mld_|\-\emph{x}\verb|prec_| \verb|type|, where \emph{x} may be \verb|s|, \verb|d|, \verb|c|
	or \verb|z|, according to the basic data type of the sparse matrix
	(\verb|s| = real single precision; \verb|d| = real double precision;
	\verb|c| = complex single precision; \verb|z| = complex double precision).
	This data structure is accessed by the user only through the MLD2P4 routines,
	following an object-oriented approach.
\item \emph{Allocate and initialize the preconditioner data structure, according to
	a preconditioner type chosen by the user}. This is performed by the routine
	\verb|init|, which also sets defaults for each preconditioner
	type selected by the user. The preconditioner types and the defaults associated
	with them are given in Table~\ref{tab:precinit}, where the strings used by
	\verb|init| to identify the preconditioner types are also given.
	Note that these strings are valid also if uppercase letters are substituted by
	corresponding lowercase ones.
%\item \emph{Modify the aggregation  parameters (for multilevel preconditioners only).}
%  This is performed by the routine \verb|mld_precset|. 
%  This routine must be called only if the user wants to modify the default values
%  of the parameters associated with the aggregation hierarchy construction.
%  Examples of use of \verb|mld_precset| are given in
%  Section~\ref{sec:examples}; a complete list of all the
%  preconditioner parameters and their allowed and default values is provided in 
%  Section~\ref{sec:userinterface}, Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}. 
\item \emph{Modify the selected preconditioner type, by properly setting
  preconditioner parameters.} This is performed by the routine \verb|set|.
  This routine must be called only if the user wants to modify the default values
  of the parameters associated with the selected preconditioner type, to obtain a variant
  of that preconditioner. Examples of use of \verb|set| are given in
  Section~\ref{sec:examples}; a complete list of all the
  preconditioner parameters and their allowed and default values is provided in 
  Section~\ref{sec:userinterface}, Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}.
\item \emph{Build the preconditioner for a given matrix}. If the selected preconditioner
 is multilevel, then two steps must be performed, as specified next.
\begin{enumerate}
\item[4.1] \emph{Build the aggregation hierarchy for a given matrix.} This is
performed by the routine \verb|hierarchy_build|.
\item[4.2] \emph{Build the preconditioner for a given matrix.} This is performed
by the routine \verb|smoothers_build|.
\end{enumerate}
 If the selected preconditioner is one-level, it is built in a single step,
performed by the routine \verb|bld|.
\item \emph{Apply the preconditioner at each iteration of a Krylov solver.}
  This is performed by the method \verb|apply|. When using the PSBLAS Krylov solvers,
  this step is completely transparent to the user, since \verb|apply| is called
  by the PSBLAS routine implementing the Krylov solver (\verb|psb_krylov|).
\item \emph{Free the preconditioner data structure}. This is performed by
  the routine \verb|free|. This step is complementary to step 1 and should
  be performed when the preconditioner is no more used.
\end{enumerate}

All the previous routines are available as methods of the preconditioner object.
A detailed description of them is given in Section~\ref{sec:userinterface}.
Examples showing the basic use of MLD2P4 are reported in Section~\ref{sec:examples}.

\begin{table}[h!]
\begin{center}
%{\small
\begin{tabular}{|l|p{1.8cm}|p{8.2cm}|}
\hline
\textsc{type}       & \textsc{string} & \textsc{default preconditioner} \\ \hline
No preconditioner &\verb|'NONE'|& Considered  to use the PSBLAS
                                    Krylov solvers with no preconditioner. \\ \hline
Diagonal          & \verb|'DIAG'| or \verb|'JACOBI'| & Diagonal preconditioner.
                         For any zero diagonal entry of the matrix to be preconditioned,
                         the corresponding entry of the preconditioner is set to~1.\\ \hline
Gauss-Seidel      & \verb|'GS'|     & Hybrid Gauss-Seidel (forward), that is,
                                      global block Jacobi with
                                      Gauss-Seidel as local solver.\\ \hline
Symmetrized Gauss-Seidel      & \verb|'FBGS'|     & Symmetrized hybrid Gauss-Seidel,that is,
                                      forward Gauss-Seidel followed by
                                                    backward Gauss-Seidel.\\ \hline
Block Jacobi      & \verb|'BJAC'| & Block-Jacobi with ILU(0) on the local blocks.\\ \hline
Additive Schwarz  & \verb|'AS'|   & Additive Schwarz (AS),
                                    with overlap~1 and ILU(0) on the local blocks. \\ \hline
Multilevel        &\verb|'ML'|    & V-cycle with one hybrid forward Gauss-Seidel
                                    (GS) sweep as pre-smoother and one hybrid backward 
                                    GS sweep as post-smoother, basic smoothed aggregation
                                   as coarsening algorithm, and LU (plus triangular solve)
                                   as coarsest-level solver. See the default values in
                                   Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}
                                   for further details of the preconditioner. \\
\hline
\end{tabular}
%}
\caption{Preconditioner types, corresponding strings and default choices.
\label{tab:precinit}}
\end{center}
\end{table}

Note that the module \verb|mld_prec_mod|, containing the definition of the 
preconditioner data type and the interfaces to the routines of MLD2P4,
must be used in any program calling such routines.
The modules \verb|psb_base_mod|, for the sparse matrix and communication descriptor
data types, and \verb|psb_krylov_mod|, for interfacing with the
Krylov solvers, must be also used (see Section~\ref{sec:examples}). \\

\textbf{Remark 1.} Coarsest-level solvers based on the LU factorization,
such as those implemented in UMFPACK, MUMPS, SuperLU, and SuperLU\_Dist,
usually lead to smaller numbers of preconditioned Krylov
iterations than inexact solvers, when the linear system comes from
a standard discretization of basic scalar elliptic PDE problems. However,
this does not necessarily correspond to the smallest execution time
on parallel computers. 
% \ \\
% \textbf{Remark 2.} The include path for MLD2P4 must override
% those for PSBLAS, i.e.\ the former must come first in the sequence
% passed to the compiler, as the MLD2P4 version of the Krylov solver
% interfaces must override that of PSBLAS. This will change in the future
% when the support for the \verb|class| statement becomes widespread in Fortran
% compilers. 



\subsection{Examples\label{sec:examples}}

The code reported in Figure~\ref{fig:ex1} shows how to set and apply the default
multilevel preconditioner available in the real double precision version
of MLD2P4 (see Table~\ref{tab:precinit}). This preconditioner is chosen
by simply specifying \verb|'ML'| as the second argument of \verb|P%init|
(a call to \verb|P%set| is not needed) and is applied with the CG
solver provided by PSBLAS (the matrix of the system to be solved is
assumed to be positive definite). As previously observed, the modules
\verb|psb_base_mod|, \verb|mld_prec_mod| and \verb|psb_krylov_mod|
must be used by the example program.
 
The part of the code concerning the
reading and assembling of the sparse matrix and the right-hand side vector, performed
through the PSBLAS routines for sparse matrix and vector management, is not reported
here for brevity; the statements concerning the deallocation of the PSBLAS
data structure are neglected too.
The complete code can be found in the example program file \verb|mld_dexample_ml.f90|,
in the directory \verb|examples/fileread| of the MLD2P4 implementation (see
Section~\ref{sec:ex_and_test}). A sample test problem along with the relevant
input data is available in \verb|examples/fileread/runs|.
For details on the use of the PSBLAS routines, see the PSBLAS User's
Guide~\cite{PSBLASGUIDE}.

The setup and application of the default multilevel preconditioner
for the real single precision and the complex, single and double
precision, versions are obtained with straightforward modifications of the previous
example (see Section~\ref{sec:userinterface} for details). If these versions are installed,
the corresponding codes are available in \verb|examples/fileread/|.

\begin{figure}[tbp]
\begin{center}
\begin{minipage}{.90\textwidth} 
{\small
\begin{verbatim}
  use psb_base_mod
  use mld_prec_mod
  use psb_krylov_mod
... ...
!
! sparse matrix
  type(psb_dspmat_type) :: A
! sparse matrix descriptor
  type(psb_desc_type)   :: desc_A
! preconditioner
  type(mld_dprec_type)  :: P
! right-hand side and solution vectors
  type(psb_d_vect_type) :: b, x
... ...
!
! initialize the parallel environment
  call psb_init(ictxt)
  call psb_info(ictxt,iam,np)
... ...
!
! read and assemble the spd matrix A and the right-hand side b 
! using PSBLAS routines for sparse matrix / vector management
... ...
!
! initialize the default multilevel preconditioner, i.e. V-cycle
! with basic smoothed aggregation, 1 hybrid forward/backward
! GS sweep as pre/post-smoother and UMFPACK as coarsest-level
! solver
  call P%init('ML',info)
!
! build the preconditioner
  call P%hierarchy_build(A,desc_A,info)
  call P%smoothers_build(A,desc_A,info)

!
! set the solver parameters and the initial guess
  ... ...
!
! solve Ax=b with preconditioned CG
  call psb_krylov('CG',A,P,b,x,tol,desc_A,info)
  ... ...
!
! deallocate the preconditioner
  call P%free(info)
!
! deallocate other data structures
  ... ...
!
! exit the parallel environment
  call psb_exit(ictxt)
  stop
\end{verbatim}
}
\end{minipage}
\caption{setup and application of the default multilevel preconditioner (example 1).
\label{fig:ex1}}
\end{center}
\end{figure}

Different versions of the multilevel preconditioner can be obtained by changing
the default values of the preconditioner parameters. The code reported in
Figure~\ref{fig:ex2} shows how to set a V-cycle preconditioner
which applies 1 block-Jacobi sweep as pre- and post-smoother,
and solves the coarsest-level system with 8 block-Jacobi sweeps.
Note that the ILU(0) factorization (plus triangular solve) is used as
local solver for the block-Jacobi sweeps, since this is the default associated
with block-Jacobi and set by~\verb|P%init|.
Furthermore, specifying block-Jacobi as coarsest-level
solver implies that the coarsest-level matrix is distributed
among the processes.
Figure~\ref{fig:ex3} shows how to set a W-cycle preconditioner which
applies 2 hybrid Gauss-Seidel sweeps as pre- and post-smoother,
and solves the coarsest-level system with the multifrontal LU factorization
implemented in MUMPS. It is specified that the coarsest-level
matrix is distributed, since MUMPS can be used on both
replicated and distributed matrices, and by default
it is used on replicated ones. 
%Note the use of the parameter \verb|pos|
%to specify a property only for the pre-smoother or the post-smoother
%(see Section~\ref{sec:precset} for more details).
The code fragments shown in Figures~\ref{fig:ex2} and \ref{fig:ex3} are
included in the example program file \verb|mld_dexample_ml.f90| too.

Finally, Figure~\ref{fig:ex4} shows the setup of a one-level
additive Schwarz preconditioner, i.e., RAS with overlap 2.
Note also that a Krylov method different from CG must be used to solve
the preconditioned system, since the preconditione in nonsymmetric.
The corresponding example program is available in the file
\verb|mld_dexample_1lev.f90|. 

For all the previous preconditioners, example programs where the sparse matrix and
the right-hand side are generated by discretizing a PDE with Dirichlet
boundary conditions are also available in the directory \verb|examples/pdegen|.

% \ \\
% \textbf{Remark 2.} Any PSBLAS-based program using the basic preconditioners
% implemented in PSBLAS 3.0, i.e.\ the diagonal and block-Jacobi ones,
% can use the diagonal and block-Jacobi preconditioners
% implemented in MLD2P4 without  change in the code.
% The PSBLAS-based program must be only recompiled
% and linked to the MLD2P4 library.
% \\


\begin{figure}[tbh]
\begin{center}
\begin{minipage}{.90\textwidth} 
{\small
\begin{verbatim}
... ...
! build a V-cycle preconditioner with 1 block-Jacobi sweep (with 
! ILU(0) on the blocks) as pre- and post-smoother, and 8  block-Jacobi
! sweeps (with ILU(0) on the blocks) as coarsest-level solver
  call P%init('ML',info)
  call_P%set('SMOOTHER_TYPE','BJAC',info)
  call P%set('COARSE_SOLVE','BJAC',info)
  call P%set('COARSE_SWEEPS',8,info)
  call P%hierarchy_build(A,desc_A,info)
  call P%smoothers_build(A,desc_A,info)
... ...
\end{verbatim}
}
\end{minipage}

\caption{setup of a multilevel preconditioner\label{fig:ex2}}
\end{center}
\end{figure}

\begin{figure}[h!]
\begin{center}
\begin{minipage}{.90\textwidth} 
{\small
\begin{verbatim}
... ...
! build a W-cycle preconditioner with 2 hybrid Gauss-Seidel sweeps
! as pre- and post-smoother, a distributed coarsest
! matrix, and MUMPS as coarsest-level solver
  call P%init('ML',info)
  call P%set('ML_CYCLE','WCYCLE',info)
  call P%set('SMOOTHER_TYPE','FBGS',info)
  call P%set('SMOOTHER_SWEEPS',2,info)
  call P%set('COARSE_SOLVE','MUMPS',info)
  call P%set('COARSE_MAT','DIST',info)
  call P%hierarchy_build(A,desc_A,info)
  call P%smoothers_build(A,desc_A,info)
... ...
\end{verbatim}
}
\end{minipage}
\caption{setup of a multilevel preconditioner\label{fig:ex3}}
\end{center}
\end{figure}

\begin{figure}[h!]
\begin{center}
\begin{minipage}{.90\textwidth} 
{\small
\begin{verbatim}
... ...
! set RAS with overlap 2 and ILU(0) on the local blocks
  call P%init('AS',info)
  call P%set('SUB_OVR',2,info)
  call P%bld(A,desc_A,info)
... ...
! solve Ax=b with preconditioned BiCGSTAB
  call psb_krylov('BICGSTAB',A,P,b,x,tol,desc_A,info)
\end{verbatim}
}
\end{minipage}
\caption{setup of a one-level Schwarz preconditioner.\label{fig:ex4}}
\end{center}
\end{figure}


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: