docs/pdf/abstract.tex
docs/pdf/background.tex
docs/pdf/gettingstarted.tex
docs/pdf/highlevelview.tex
docs/pdf/overview.tex
docs/userguide.pdf
merged doc fixes from Daniela/Pasqua. Still a long way to go.
\emph{MLD2P4 (Multi-Level Domain Decomposition Parallel Preconditioners Package based on
\textsc{MLD2P4 (Multi-Level Domain Decomposition Parallel Preconditioners Package based on
PSBLAS}) is a package of parallel algebraic multi-level preconditioners.
It implements various versions of one-level additive and of multi-level additive
and hybrid Schwarz algorithms. In the multi-level case, a purely algebraic approach
is applied to generate coarse-level corrections, so that no geometric background is needed
concerning the matrix to be preconditioned. The matrix is required to be square, real or complex, with a symmetric sparsity pattern \textbf{Non consideriamo anche il caso non simmetrico
con $(A+A^T)/2$?}.
concerning the matrix to be preconditioned. The matrix is required to be square, real
or complex, with a symmetric sparsity pattern
MLD2P4 has been designed to provide scalable and easy-to-use preconditioners in the
context of the PSBLAS (Parallel Sparse Basic Linear Algebra Subprograms)
@ -16,4 +16,7 @@ for the ``best'' preconditioner for the problem at hand. The package has been de
employing object-oriented techniques, using Fortran 95 and MPI, with interfaces to
additional external libraries such as UMFPACK, SuperLU and SuperLU\_Dist, that
can be exploited in building multi-level preconditioners.
\end{abstract}
This guide provides a brief description of the functionalities and
- 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]
}
\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}
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
! 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')
... ...
!
! initialization of the parallel environment
\end{verbatim}
}
\caption{Setup of a hybrid three-level Schwarz preconditioner.\label{fig:example2}}
\end{center}
\end{figure}
call psb_init(ictxt)
call psb_info(ictxt,iam,np)
\begin{figure}[tbp]
\begin{center}
{\small
\begin{verbatim}
... ...
! read and assemble the matrix A and the right-hand
! side vector b using PSBLAS routines for sparse
! matrix/vector management
! 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)
\caption{Setup of an additive three-level Schwarz preconditioner.\label{fig:example3}}
\end{center}
\end{figure}
{\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|.
\ \\
\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
\section{High-Level User Interface\label{sec:highlevel}}
\section{User Interface\label{sec:highlevel}}
At the upper layer of MLD2P4, five black-box routines encapsulate all the functionalities for the construction
and the application of any of the multi-level preconditioners.
In the following we give the details of the above routines. Note that for each routine are available four
different versions depending on involved data types: Real-Single/Double Precision, Complex-Single/Double Precision.
The basic user interface of MLD2P4 consists of six routines. The four routines \verb|mld_precinit|,
\verb|mld_precset|, \verb|mld_precbld| and \verb|mld_precaply| encapsulate all the functionalities
for the setup and application of any one-level and multi-level preconditioner implemented in the package.
The routine \verb|mld_precfree| deallocates the preconditioner data structure, while \verb|mld_precdescr|
prints a description of the preconditioner setup by the user.
\subsection{Preconditioner Setup and Building}\label{sec:setup}
For each routine, the same user interface is available independently of the real or complex case
and of the single or double precision. However, the appropriate preconditioner data type to be used with
each version of the package must be explicitly chosen by the user, i.e.\ a preconditioner data structure of type \verb|mld_|\emph{x}\verb|prec_type| must be declared, where \emph{x} = \verb|s| for real single precision,
\emph{x} = \verb|d| for real double precision, \emph{x} = \verb|c| for complex single precision,
\emph{x} = \verb|z| for complex double precision. A few parameters defining the preconditioner may be
real single or double precision, depending on the package version (see Section~\ref{sec:precset}).
A description of each routine is given in the remainder of this section.
to be used in the iterative solutions of sparse linear systems:
\begin{equation}
Ax=b,
\label{system1}
\end{equation}
where $A$ is a square, real or complex, sparse matrix with a symmetric sparsity pattern.
%
%\textbf{NOTA: Caso non simmetrico, aggregazione con $(A+A^T)$ fatta!
%Dovremmo implementare uno smoothed prolongator
%adeguato e fare qualcosa di consistente anche con 1-lev Schwarz.}
%
These preconditioners have the following general features:
\begin{itemize}
\item both \emph{additive and hybrid multilevel} variants, i.e.\ multiplicative among the levels
and additive inside a level, are implemented; the basic additive Schwarz preconditioners
are obtained by considering only one level. A purely algebraic approach is used to
are obtained by considering only one level;
\item a \emph{purely algebraic} approach is used to
generate a sequence of coarse-level corrections to a basic preconditioner, without
explicitly using any information on the geometry of the original problem (e.g.\ the
discretization of a PDE). The smoothed aggregation technique is applied
as algebraic coarsening strategy~\cite{}.
discretization of a PDE). The \emph{smoothed aggregation} technique is applied
as algebraic coarsening strategy~\cite{Vanek_Mandel_Brezina,Brezina_Vanek}.
\end{itemize}
The package is written in Fortran~95, using object-oriented techniques,
and is based on a distributed-memory parallel programming paradigm. \textbf{SALVATORE,
potresti aggiungere due righe sulla scelta del Fortran 95 e sul semplice interfacciamento
con i legacy codes, senza ripetere quello che e' detto sotto sulla scelta di PSBLAS?}
The package is written in \emph{Fortran~95}, following an \emph{object-oriented approach}
through the exploitation of features such as abstract data type creation, functional overloading and
dynamic memory management, while providing a smooth path towards the integration in
legacy application codes. The parallel implementation is based on a Single Program Multiple Data
(SPMD) paradigm for distributed-memory architectures.
Single and double precision implementations of MLD2P4 are available for both the
real and the complex case, that can be used through a single interface.
\textbf{SALVATORE, funziona tutto?}
MLD2P4 has been designed to implement scalable and easy-to-use multilevel preconditioners
in the context of the PSBLAS (Parallel Sparse BLAS) computational framework~\cite{}.
in the context of the \emph{PSBLAS (Parallel Sparse BLAS) computational framework}~\cite{psblas_00}.
PSBLAS is a library originally developed to address the parallel implementation of
iterative solvers for sparse linear system, by providing basic linear algebra
operators and data management facilities for distributed sparse matrices; it
@ -36,25 +50,24 @@ parallel sparse linear algebra kernels, to pursue goals such as performance,
portability, modularity ed extensibility in the development of the preconditioner
package. On the other hand, the implementation of MLD2P4 has led to some
revisions and extentions of the PSBLAS kernels, leading to the
recent PSBLAS 2.0 version~\cite{}. The inter-process comunication required
recent PSBLAS 2.0 version~\cite{PSBLASGUIDE}. The inter-process comunication required
by MLD2P4 is encapsulated into the PSBLAS routines, except few cases where
MPI~\cite{} is explicitly called. Therefore, MLD2P4 can be run on any parallel
MPI~\cite{MPI1} is explicitly called. Therefore, MLD2P4 can be run on any parallel
machine where PSBLAS and MPI implementations are available.
MLD2P4 has a layered and modular software architecture where three main layers can be identified. The lower layer consists of the PSBLAS kernels, the middle one implements
MLD2P4 has a layered and modular software architecture where three main layers can be identified.
The lower layer consists of the PSBLAS kernels, the middle one implements
the construction and application phases of the preconditioners, and the upper one
provides a uniform and easy-to-use interface to all the preconditioners.
This architecture allows for different levels of use of the package:
few black-box routines at the upper level allow non-expert users to easily
few black-box routines at the upper layer allow non-expert users to easily
build any preconditioner available in MLD2P4 and to apply it within a PSBLAS Krylov solver.
On the other hand, the routines of the middle and lower layer can be used and extended
by expert users to build new versions of multi-level Schwarz preconditioners.\\
\textbf{Organizzazione della guida:\\
dire che per il momento non
forniamo anche la documentazione del middle layer, ma lo faremo in seguito\\}
by expert users to build new versions of multi-level Schwarz preconditioners.
We provide here a description of the upper-layer routines, but not of the
medium-layer ones.
\textbf{Evidenziare le parole chiave che caratterizzano il nostro package}
This guide is organized as follows:\textbf{organizzazione della guida}
Salvatore Filippone
17 years ago