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 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|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 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|.
  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 default preconditioner.
  An example of use of \verb|mld_precset| is given in 
  Section~\ref{sec:examples}, Figure~\ref{fig:example2}; a complete list of all the
  preconditioner parameters and their allowed and default 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 the UMFPACK LU factorization 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 in Figure~\ref{fig:example1} shows how to set and apply the MLD2P4 default
multi-level preconditioner, i.e.\ the two-level hybrid post-smoothed Schwarz preconditioner,
having block-Jacobi with ILU(0) on the blocks as basic preconditioner,
a coarse matrix distributed among the processors, and four block-Jacobi
sweeps, with the UMFPACK sparse LU factorization 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 with 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; 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|example_ml_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{figure}[tbp]
\begin{center}
{\small
\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)  :: P
... ...
!
! 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 Schwarz, with ILU(0) as post-smoother
! and 4 Block-Jacobi sweeps, with ILU(0) on the blocks,
! as distributed coarsest-level solver)
  call mld_precinit(P,'ML',info)
!
! build the preconditioner
  call psb_precbld(A,P,DESC_A,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}
}
\caption{Setup and application of the default multilevel Schwarz preconditioner.
\label{fig:example1}}
\end{center}
\end{figure}

Different versions of multilevel preconditioner can be obtained by changing
the default values of the preconditioner parameters. The code reported in
Figure~\ref{fig:example2} shows how to set a three-level hybrid Schwarz preconditioner
using RAS with overlap 1 as post-smoother, a coarsest matrix replicated
on the processors and the LU factorization from UMFPACK as coarse-level solver.
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,
which corresponds to the hybrid multilevel preconditioner); the type
of one-level AS preconditioner used as smoother (i.e.\ RAS)
and its ``position'' (i.e.\ pre-smoother) are not specified since they
are chosen by default when \verb|mld_precinit| is called.
The construction and the application of the preconditioner
are carried out as for the default multi-level preconditioner.

As a further example, we report in Figure~\ref{fig:example3} the code
concerning the setup of a three-level additive multi-level preconditioner,
using ILU(0) as pre- and post-smoother, a distributed coarsest matrix and
five block-Jacobi sweeps as coarsest-level solver, with
ILU(0) on the local blocks. Again, \verb|mld_precset| is used only to set
the values of the parameters that are not default values.
For a detailed description of the parameters associated to a preconditioner
type, including their allowed and default values, the user is referred to
\textbf{SPECIFICARE.} 

An example program including the code fragments
shown in in Figures~\ref{fig:example2} and \ref{fig:example3} is in
\verb|XXX/.../example_3lev.f90|. \textbf{COMPLETARE. Fare un programma solo
per i due esempi, in cui uno e' commentato e l'altro no.}
One more example program, showing the setup and application of a one-level
additive Schwarz preconditioner can be found in \verb|XXX/.../example_1lev.f90|.
\textbf{COMPLETARE}.

\begin{figure}[tbp]
\begin{center}
{\small
\begin{verbatim}
... ...
! setup a three-level hybrid Schwarz preconditioner,
! using RAS with overlap 1 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,mld_smooth_type_,'AS',info)
  call mld_precset(P,mld_n_ovr_,1,info)
  call mld_precset(P,mld_coarse_mat,'REPL')
  call mld_precset(P,mld_coarse_solve,'UMF')
... ...
\end{verbatim}
}
\caption{Setup of a hybrid three-level Schwarz preconditioner.\label{fig:example2}}
\end{center}
\end{figure}

\begin{figure}[tbp]
\begin{center}
{\small
\begin{verbatim}
... ...
! setup a three-level additive Schwarz preconditioner,
! using ILU(0) as pre- and post-smoother, five block-Jacobi
! sweeps as distributed coarsest-level solver, with ILU(0)
! on the local blocks
  call mld_precinit(P,'ML',info,nlev=3)
  call mld_precset(P,mld_ml_type_,'ADD',info)
  call_mld_precset(P,mld_smooth_pos_,'TWOSIDE',info)
  call mld_precset(P,mld_n_ovr_,1,info)
  call mld_precset(P,mld_coarse_sweeps,5)
  call mld_precset(P,mld_coarse_subsolve,'UMF')
... ...
\end{verbatim}
}
\caption{Setup of an additive three-level Schwarz preconditioner.\label{fig:example3}}
\end{center}
\end{figure}

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

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