\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_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: