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.
amg4psblas/docs/pdf/gettingstarted.tex

232 lines
10 KiB
TeX

\section{Getting Started\label{sec: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{}.
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_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|s| = 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 a default preconditioner for each preconditioner
type selected by the user. The default preconditioner associated to each preconditioner
type is listed in Table~\ref{tab:precinit}; the string used by \verb|mld_precinit|
to identify each preconditioner type is also given.
\item \emph{Choose a specific preconditioner within the selected preconditioner type, by setting
the preconditioner parameters.} This is performed by the routine \verb|mld_precset|.
A few examples concerning the use of \verb|mld_precset| are given in
Section~\ref{sec:examples}; a complete list of all the
preconditioner parameters and their allowed values is provided in
Section~\ref{sec:highlevel}.
\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{Deallocate the preconditioner data structure}. This is performed by
the routine \verb|mld_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:highlevel}.
Note that the Fortran 95 module \verb|mld_prec_mod| must be used in the program
calling the MLD2P4 routines. Furthermore, to apply MLD2P4 with the Krylov solvers
from PSBLAS, the module \verb|psb_krylov_mod| must be used too.
Examples showing the basic use of MLD2P4 are reported in Section~\ref{sec:examples}.
\begin{table}[th]
{
\begin{center}
\begin{tabular}{|l|l|p{6.7cm}|}
\hline
Type & String & Default preconditioner \\ \hline
No preconditioner &\verb|'NOPREC'|& (Considered only to use the PSBLAS
Krylov solvers with no preconditioner.) \\
Diagonal & \verb|'DIAG'| & --- \\
Block Jacobi & \verb|'BJAC'| & Block Jacobi with ILU(0) on the local blocks.\\
Additive Schwarz & \verb|'AS'| & Restricted Additive Schwarz (RAS),
with overlap 1 and ILU(0) on the local blocks. \\
Multilevel &\verb|'ML'| & Multi-level hybrid preconditioner (additive on the
same level and multiplicative through the levels),
with post-smoothing only. Number of levels: 2;
post-smoother: block-Jacobi preconditioner with ILU(0)
on the local blocks; coarsest matrix: distributed among the
processors; corase-level solver: 4 sweeps of the
block-Jacobi solver, with ILU(0) on the blocks. \\
\hline
\end{tabular}
\end{center}
}
\caption{Preconditioner types and default choices.\label{tab:precinit}}
\end{table}
\subsection{Examples\label{sec:examples}}
The code reported below shows how to set and apply the MLD2P4 default multi-level
preconditioned, i.e.\ the two-level hybrid post-smoothed Schwarz preconditioner,
using block-Jacobi with ILU(0) on the blocks as basic preconditioner,
a coarse matrix distributed among the processors, and four block-Jacobi
sweeps with ILU(0) on the blocks as approximate coarse-level solver.
The choice of this preconditioner is made
by simply specifying \verb|'ML'| as second argument of \verb|mld_precinit|
(a call to \verb|mld_precset| is not needed).
The preconditioner is applied within the BiCGSTAB solver provided by PSBLAS.
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. Other statements concerning the use of PSBLAS are neglected too.
The complete code can be found in the example program file \verb|example_2lev_default.f90|
in the directory \textbf{XXXXXX (SPECIFICARE).} Note that the modules \verb|psb_base_mod|
and \verb|psb_util_mod| at the beginning of the code are required by PSBLAS.
For details on the use of the PSBLAS routines, see the PSBLAS User's Guide \cite{}.
\begin{verbatim}
use psb_base_mod
use psb_util_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) :: PRE
... ...
!
! 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
! (two-level hybrid post-smoothed Schwarz)
call mld_precinit(PRE,'ML',info)
!
! build the preconditioner
call psb_precbld(A,PRE,DESC_A,info)
!
! set the solver parameters and the initial guess
... ...
!
! solve Ax=b with preconditioned BiCGSTAB
call psb_krylov('BICGSTAB',A,PRE,b,x,tol,DESC_A,info)
... ...
!
! cleanup the preconditioner
call mld_precfree(PRE,info)
!
! cleanup other data structures
... ...
!
! exit the parallel environment
call psb_exit(ictxt)
stop
\end{verbatim}
\textbf{MODIFICARE TUTTA LA PARTE CHE SEGUE:\\
- solo istruzioni diverse dall'esempio precedente (essenzialmente il setting del precondizionatore, magari con piu' chiamate a precset;\\
- lasciare l'osservazione sulla specifica esplicita del numero di livelli;\\
- rimandare al paragrafo successivo per una decrizione accurata di tutti i parametri;\\
- lasciare l'osservazione sui vecchi utenti di PSBLAS.}\\
In the following we describe the general procedure for setting and building one of the MLD2P4 preconditioners.
The user has first to prepare the preconditioner data structure by using the routine \verb|mld_precinit|. Input parameters
for this routine include a string parameter, needed to define the preconditioner type, and an optional integer parameter
specifying the number of the levels in the case of a multi-level preconditioner.
Note that if the optional parameter is not present and a multi-level preconditioner has been chosen,
a two-level preconditioner is set. On the other hand, the integer parameter is ignored if the type of the preconditioner is not multilevel.
In Table \ref{tab:precinit} we report both the possible choices for the preconditioner type
and the related default preconditioners.
The user of MLD2P4 may set a lot of parameters for one-level and multi-level Schwarz, in order
to define a different preconditioner than that of default choices. The parameters
can be set through the routine \verb|mld_precset|. The APIs of \verb|mld_precinit| and \verb|mld_precset| as well as the complete
list of the parameters that can be set with the corresponding allowed values are reported in Section \ref{sec:highlevel}. In the following a simple code
for a three-level hybrid post-smoothed Schwarz preconditioner, using RAS with overlap 1 as local preconditioner,
with ILU(0) on the local blocks, a distributed coarse matrix, four block-Jacobi sweeps with the UMFPACK LU
factorization on the blocks as coarse-matrix solver, is reported. Note that for the multi-level preconditioners, the levels are numbered in increasing
order starting from the finest one, i.e. level 1 is the finest level.
For more details, see the test program \verb|example2.f90| in xxxx(directory dei test).\\[0.5cm]
\begin{verbatim}
use psb_base_mod
use psb_util_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 data
type(mld_dprec_type) :: PRE
... ...
!
! initialization of the parallel environment
call psb_init(ictxt)
call psb_info(ictxt,iam,np)
... ...
! read and assemble the matrix A and the right-hand
! side vector b using PSBLAS routines for sparse
! matrix/vector management
... ...
! prepare the three-level hybrid post-smoothed Schwarz
! using RAS with overlap 1 as local preconditioner
!
call mld_precinit(PRE,'ML',info,nlev=3)
call mld_precset(PRE,mld_n_ovr_,novr=1,info,ilev=1)
call mld_precset(PRE,mld_sub_restr_,psb_halo_,info,ilev=1)
NOTA: e' PROPRIO BRUTTO "PSB_HALO_", BISOGNEREBBE AVERE COSTANTI CHE HANNO IL PREFISSO MLD!
!
! build preconditioner
call psb_precbld(A,PRE,DESC_A,info)
!
! set solver parameters and initial guess
... ...
! solve Ax=b with preconditioned BiCGSTAB
call psb_krylov('BICGSTAB',A,PRE,b,x,tol,DESC_A,info)
... ...
!
! cleanup storage and exit
!
call mld_precfree(PRE,info)
!
call psb_gefree(b,DESC_A,info)
call psb_gefree(x,DESC_A,info)
call psb_spfree(A,DESC_A,info)
call psb_cdfree(DESC_A,info)
!
call psb_exit(ictxt)
stop
\end{verbatim}
{\bf Remark for users with PSBLAS-based legacy codes:} when MLD2P4 is installed, a PSBLAS user, with a PSBLAS-based legacy code
calling base preconditioners included in PSBLAS (NOPREC, DIAG and BJAC), is able to use the same preconditioners without changes to the code, if she/he
includes in her/his program the file \verb|psb_prec_mod|.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: