amg4psblas/docs/pdf/gettingstarted.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 five steps are required:
\begin{enumerate}
\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. The preconditioner data structure is
	the derived data type \verb|mld_prec_type|, which is accessed to the user only
	through the MLD2P4 routines.
\item \emph{Choose a specific variant of 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 
  Sections~\ref{sec:example1} and \ref{sec:example1}; 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.

Two simple example programs 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 &'NOPREC'& (Considered only to use the PSBLAS
                             Krylov solvers with no preconditioner.) \\
Diagonal          & 'DIAG' & --- \\
Block Jacobi      & 'BJAC' & ILU(0) on the local blocks.\\ 
Additive Schwarz  & 'AS'   & Restricted Additive Schwarz (RAS),
                             with overlap 1 and ILU(0) on the local blocks. \\ 
Multilevel        &'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 simple 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_prec_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: