\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 multi-level
Schwarz 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 |mld_ precinit|, which also sets defaults for each preconditioner
type selected by the user. The defaults associated to each preconditioner
type are given in Table~\ref { tab:precinit} , where the strings used by
\verb |mld_ precinit| 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 selected preconditioner type, by properly setting
preconditioner parameters.} 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 to the selected preconditioner type, to obtain a variant
of the preconditioner. 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_ type} -\ref { tab:p_ coarse} .
\item \emph { Build the preconditioner for a given matrix.} This is performed by
the routine \verb |mld_ precbld|.
\item \emph { Apply the preconditioner at each iteration of a Krylov solver.}
This is performed by the routine \verb |mld_ precaply|. When using the PSBLAS Krylov solvers,
this step is completely transparent to the user, since \verb |mld_ precaply| 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 |mld_ | \verb |precfree|. This step is complementary to step 1 and should
be performed when the preconditioner is no more used.
\end { enumerate}
A detailed description of the above routines is given in Section~\ref { sec:userinterface} .
Examples showing the basic use of MLD2P4 are reported in Section~\ref { sec:examples} .
Note that the Fortran 95 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.} The coarsest-level solver used by the default two-level
preconditioner has been chosen by taking into account that, on parallel
machines, it often leads to the smallest execution time when applied to
linear systems coming from finite-difference discretizations of basic
elliptic PDE problems, considered as standard tests for multi-level Schwarz
preconditioners \cite { aaecc_ 07,apnum_ 07} . However, this solver does
not necessarily correspond to the smallest number of iterations of the
preconditioned Krylov method, which is usually obtained by applying
a direct solver to the coarsest-level system, e.g.\ based on the LU
factorization (see Section~\ref { sec:userinterface}
for the coarsest-level solvers available in MLD2P4).
% \ \\
% \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.
\begin { table} [th]
\begin { center}
%{\small
\begin { tabular} { |l|l|p{ 7.8cm} |}
\hline
\textsc { type} & \textsc { string} & \textsc { default preconditioner} \\ \hline
No preconditioner & \verb |'NOPREC'|& Considered only to use the PSBLAS
Krylov solvers with no preconditioner. \\ \hline
Diagonal & \verb |'DIAG'| & --- \\ \hline
Block Jacobi & \verb |'BJAC'| & Block Jacobi with ILU(0) on the local blocks.\\ \hline
Additive Schwarz & \verb |'AS'| & Restricted Additive Schwarz (RAS),
with overlap 1 and ILU(0) on the local blocks. \\ \hline
Multilevel & \verb |'ML'| & Multi-level hybrid preconditioner (additive on the
same level and multiplicative through the levels),
with pre- and post-smoothing.
Number of levels: 2.
Smoother: RAS with overlap 1 and ILU(0)
on the local blocks.
Aggregation: decoupled smoothed aggregation with
threshold $ \theta = 0 $ .
Coarsest matrix: distributed among the processors.
Coarsest-level solver:
4 sweeps of the block-Jacobi solver,
with LU or ILU factorization of the blocks
(UMFPACK for the double precision versions and
SuperLU for the single precision ones, if the packages
have been installed; ILU(0), otherwise). \\
\hline
\end { tabular}
%}
\end { center}
\caption { Preconditioner types, corresponding strings and default choices.
\label { tab:precinit} }
\end { table}
\subsection { Examples\label { sec:examples} }
The code reported in Figure~\ref { fig:ex_ default} shows how to set and apply the default
multi-level 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 second argument of \verb |mld_ precinit|
(a call to \verb |mld_ precset| is not needed) and is applied with the BiCGSTAB
solver provided by PSBLAS. 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 tree (see
Section~\ref { sec:ex_ and_ test} ).
For details on the use of the PSBLAS routines, see the PSBLAS User's
Guide \cite { PSBLASGUIDE} .
The setup and application of the default multi-level
preconditioners 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 Fortran 95 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 matrix A and the right-hand side b
! using PSBLAS routines for sparse matrix / vector management
... ...
!
! initialize the default multi-level preconditioner, i.e. hybrid
! Schwarz, using RAS (with overlap 1 and ILU(0) on the blocks)
! as pre- and post-smoother and 4 block-Jacobi sweeps
! (with UMFPACK LU on the blocks) as distributed coarse-level
! solver.
call mld_ precinit(P,'ML',info)
!
! build the preconditioner
call mld_ precbld(A,desc_ A,P,info)
!
! set the solver parameters and the initial guess
... ...
!
! solve Ax=b with preconditioned BiCGSTAB
call psb_ krylov('BICGSTAB',A,P,b,x,tol,desc_ A,info)
... ...
!
! deallocate the preconditioner
call mld_ precfree(P,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 multi-level Schwarz preconditioner.
\label { fig:ex_ default} }
\end { center}
\end { figure}
Different versions of multi-level preconditioners can be obtained by changing
the default values of the preconditioner parameters. The code reported in
Figure~\ref { fig:ex_ 3lh} shows how to set a three-level hybrid Schwarz
preconditioner, which uses block Jacobi with ILU(0) on the
local blocks as post-smoother, has a coarsest matrix replicated on the processors,
and solves the coarsest-level system with the LU factorization from UMFPACK~\cite { UMFPACK} .
Figure~\ref { fig:ex_ 3lhm} shows how to set a three-level preconditioner similar to the one of ~\ref { fig:ex_ 3lh} , but the coarsest-level systems is solved with the multifrontal factorization from MUMPS~\cite { UMFPACK} .
Note that MUMPS can be used on both replicated and distributed coarsest level matrices,
as a global and local solver respectively.
The number of levels is specified by using \verb |mld_ precinit|; the other
preconditioner parameters are set by calling \verb |mld_ precset|. Note that
the type of multilevel framework (i.e.\ multiplicative among the levels
with post-smoothing only) is not specified since it is the default
set by \verb |mld_ precinit|.
Figure~\ref { fig:ex_ 3la} shows how to
set a three-level additive Schwarz preconditioner,
which uses RAS, with overlap 1 and ILU(0) on the blocks,
as pre- and post-smoother, and applies five block-Jacobi sweeps, with
the UMFPACK LU factorization on the blocks, as distributed coarsest-level
solver. Again, \verb |mld_ precset| is used only to set
non-default values of the parameters (see Tables~\ref { tab:p_ type} -\ref { tab:p_ coarse} ).
In both cases, the construction and the application of the preconditioner
are carried out as for the default multi-level preconditioner.
The code fragments shown in in Figures~\ref { fig:ex_ 3lh} ~\ref { fig:ex_ 3lhm} -\ref { fig:ex_ 3la} are
included in the example program file \verb |mld_ dexample_ ml.f90| too.
Finally, Figure~\ref { fig:ex_ 1l} shows the setup of a one-level
additive Schwarz preconditioner, i.e.\ RAS with overlap 2. The corresponding
example program is available in \verb |mld_ dexample_ | \verb |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}
... ...
! set a three-level hybrid Schwarz preconditioner, which uses
! block Jacobi (with ILU(0) on the blocks) as post-smoother,
! a coarsest matrix replicated on the processors, and the
! LU factorization from UMFPACK as coarse-level solver
call mld_ precinit(P,'ML',info,nlev=3)
call_ mld_ precset(P,'SMOOTHER_ TYPE','BJAC',info)
call_ mld_ precset(P,'SMOOTHER_ POS,'POST'w,info)
call mld_ precset(P,'COARSE_ MAT','REPL',info)
call mld_ precset(P,'COARSE_ SOLVE','UMF',info)
... ...
\end { verbatim}
}
\end { minipage}
\caption { Setup of a hybrid three-level Schwarz preconditioner.\label { fig:ex_ 3lh} }
\end { center}
\end { figure}
\begin { figure} [tbh]
\begin { center}
\begin { minipage} { .90\textwidth }
{ \small
\begin { verbatim}
... ...
! set a three-level hybrid Schwarz preconditioner, which uses
! block Jacobi (with ILU(0) on the blocks) as post-smoother,
! a coarsest matrix replicated on the processors, and the
! multifrontal solver in MUMPS as coarse-level solver
call mld_ precinit(P,'ML',info,nlev=3)
call mld_ precset(P,mld_ smoother_ type_ ,'BJAC',info)
call mld_ precset(P,mld_ coarse_ mat_ ,'REPL',info)
call mld_ precset(P,mld_ coarse_ solve_ ,'MUMPS',info)
... ...
\end { verbatim}
}
\end { minipage}
\caption { Setup of a hybrid three-level Schwarz preconditioner.\label { fig:ex_ 3lhm} }
\end { center}
\end { figure}
\begin { figure} [tbh]
\begin { center}
\begin { minipage} { .90\textwidth }
{ \small
\begin { verbatim}
... ...
! set a three-level additive Schwarz preconditioner, which uses
! RAS (with overlap 1 and ILU(0) on the blocks) as pre- and
! post-smoother, and 5 block-Jacobi sweeps (with UMFPACK LU
! on the blocks) as distributed coarsest-level solver
call mld_ precinit(P,'ML',info,nlev=3)
call mld_ precset(P,'ML_ TYPE','ADD',info)
call_ mld_ precset(P,'SMOOTHER_ POS','TWOSIDE',info)
call mld_ precset(P,'COARSE_ SWEEPS',5,info)
... ...
\end { verbatim}
}
\end { minipage}
\caption { Setup of an additive three-level Schwarz preconditioner.\label { fig:ex_ 3la} }
\end { center}
\end { figure}
\begin { figure} [tbh]
\begin { center}
\begin { minipage} { .90\textwidth }
{ \small
\begin { verbatim}
... ...
! set RAS with overlap 2 and ILU(0) on the local blocks
call mld_ precinit(P,'AS',info)
call mld_ precset(P,'SUB_ OVR',2,info)
... ...
\end { verbatim}
}
\end { minipage}
\caption { Setup of a one-level Schwarz preconditioner.\label { fig:ex_ 1l} }
\end { center}
\end { figure}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
