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.
PSBLAS}) is a package of parallel algebraic multi-level preconditioners.
It implements various versions of one-level additive and of multi-level additive
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
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
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
concerning the matrix to be preconditioned. The matrix is required to be square, real
con $(A+A^T)/2$?}.
or complex, with a symmetric sparsity pattern
MLD2P4 has been designed to provide scalable and easy-to-use preconditioners in the
MLD2P4 has been designed to provide scalable and easy-to-use preconditioners in the
context of the PSBLAS (Parallel Sparse Basic Linear Algebra Subprograms)
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
employing object-oriented techniques, using Fortran 95 and MPI, with interfaces to
additional external libraries such as UMFPACK, SuperLU and SuperLU\_Dist, that
additional external libraries such as UMFPACK, SuperLU and SuperLU\_Dist, that
can be exploited in building multi-level preconditioners.
can be exploited in building multi-level preconditioners.
This guide provides a brief description of the functionalities and
\caption{Setup and application of the default multilevel Schwarz preconditioner.
\textbf{MODIFICARE TUTTA LA PARTE CHE SEGUE:\\
\label{fig:example1}}
- solo istruzioni diverse dall'esempio precedente (essenzialmente il setting del precondizionatore, magari con piu' chiamate a precset;\\
\end{center}
- lasciare l'osservazione sulla specifica esplicita del numero di livelli;\\
\end{figure}
- rimandare al paragrafo successivo per una decrizione accurata di tutti i parametri;\\
- lasciare l'osservazione sui vecchi utenti di PSBLAS.}\\
Different versions of multilevel preconditioner can be obtained by changing
the default values of the preconditioner parameters. The code reported in
In the following we describe the general procedure for setting and building one of the MLD2P4 preconditioners.
Figure~\ref{fig:example2} shows how to set a three-level hybrid Schwarz preconditioner
The user has first to prepare the preconditioner data structure by using the routine \verb|mld_precinit|. Input parameters
using RAS with overlap 1 as post-smoother, a coarsest matrix replicated
for this routine include a string parameter, needed to define the preconditioner type, and an optional integer parameter
on the processors and the LU factorization from UMFPACK as coarse-level solver.
specifying the number of the levels in the case of a multi-level preconditioner.
The number of levels is specified by using \verb|mld_precinit|; the other
Note that if the optional parameter is not present and a multi-level preconditioner has been chosen,
preconditioner parameters are set by calling \verb|mld_precset|. Note that
a two-level preconditioner is set. On the other hand, the integer parameter is ignored if the type of the preconditioner is not multilevel.
the type of multilevel framework (i.e.\ multiplicative among the levels,
In Table \ref{tab:precinit} we report both the possible choices for the preconditioner type
which corresponds to the hybrid multilevel preconditioner); the type
and the related default preconditioners.
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 user of MLD2P4 may set a lot of parameters for one-level and multi-level Schwarz, in order
The construction and the application of the preconditioner
to define a different preconditioner than that of default choices. The parameters
are carried out as for the default multi-level preconditioner.
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
As a further example, we report in Figure~\ref{fig:example3} the code
for a three-level hybrid post-smoothed Schwarz preconditioner, using RAS with overlap 1 as local preconditioner,
concerning the setup of a three-level additive multi-level preconditioner,
with ILU(0) on the local blocks, a distributed coarse matrix, four block-Jacobi sweeps with the UMFPACK LU
using ILU(0) as pre- and post-smoother, a distributed coarsest matrix and
factorization on the blocks as coarse-matrix solver, is reported. Note that for the multi-level preconditioners, the levels are numbered in increasing
five block-Jacobi sweeps as coarsest-level solver, with
order starting from the finest one, i.e. level 1 is the finest level.
ILU(0) on the local blocks. Again, \verb|mld_precset| is used only to set
For more details, see the test program \verb|example2.f90| in xxxx(directory dei test).\\[0.5cm]
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}
\begin{verbatim}
use psb_base_mod
use psb_util_mod
use mld_prec_mod
use psb_krylov_mod
... ...
... ...
!
! setup a three-level hybrid Schwarz preconditioner,
! sparse matrix
! using RAS with overlap 1 as post-smoother, a coarsest
type(psb_dspmat_type) :: A
! matrix replicated on the processors, and the LU
! sparse matrix descriptor
! factorization from UMFPACK as coarse-level solver
type(psb_desc_type) :: DESC_A
call mld_precinit(P,'ML',info,nlev=3)
! preconditioner data
call_mld_precset(P,mld_smooth_type_,'AS',info)
type(mld_dprec_type) :: PRE
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}
! initialization of the parallel environment
}
\caption{Setup of a hybrid three-level Schwarz preconditioner.\label{fig:example2}}
\end{center}
\end{figure}
call psb_init(ictxt)
\begin{figure}[tbp]
call psb_info(ictxt,iam,np)
\begin{center}
{\small
\begin{verbatim}
... ...
... ...
! read and assemble the matrix A and the right-hand
! setup a three-level additive Schwarz preconditioner,
! side vector b using PSBLAS routines for sparse
! using ILU(0) as pre- and post-smoother, five block-Jacobi
! matrix/vector management
! 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
\textbf{Note.} Any PSBLAS-based program using the basic preconditioners implemented in PSBLAS 2.0,
includes in her/his program the file \verb|psb_prec_mod|.
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
The basic user interface of MLD2P4 consists of six routines. The four routines \verb|mld_precinit|,
and the application of any of the multi-level preconditioners.
\verb|mld_precset|, \verb|mld_precbld| and \verb|mld_precaply| encapsulate all the functionalities
In the following we give the details of the above routines. Note that for each routine are available four
for the setup and application of any one-level and multi-level preconditioner implemented in the package.
different versions depending on involved data types: Real-Single/Double Precision, Complex-Single/Double Precision.
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.
lavoriamo su $(A+A^T)/2$? Ma questo vale solo per l'aggregazione? Dovremmo fare
to be used in the iterative solutions of sparse linear systems:
qualcosa di consistente anche con 1-lev Schwarz.}
\begin{equation}
Both additive and hybrid preconditioners, i.e.\ multiplicative among the levels
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
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
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
explicitly using any information on the geometry of the original problem (e.g.\ the
discretization of a PDE). The smoothed aggregation technique is applied
discretization of a PDE). The \emph{smoothed aggregation} technique is applied
as algebraic coarsening strategy~\cite{}.
as algebraic coarsening strategy~\cite{Vanek_Mandel_Brezina,Brezina_Vanek}.
\end{itemize}
The package is written in Fortran~95, using object-oriented techniques,
The package is written in \emph{Fortran~95}, following an \emph{object-oriented approach}
and is based on a distributed-memory parallel programming paradigm. \textbf{SALVATORE,
through the exploitation of features such as abstract data type creation, functional overloading and
potresti aggiungere due righe sulla scelta del Fortran 95 e sul semplice interfacciamento
dynamic memory management, while providing a smooth path towards the integration in
con i legacy codes, senza ripetere quello che e' detto sotto sulla scelta di PSBLAS?}
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
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.
real and the complex case, that can be used through a single interface.
\textbf{SALVATORE, funziona tutto?}
\textbf{SALVATORE, funziona tutto?}
MLD2P4 has been designed to implement scalable and easy-to-use multilevel preconditioners
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
PSBLAS is a library originally developed to address the parallel implementation of
iterative solvers for sparse linear system, by providing basic linear algebra
iterative solvers for sparse linear system, by providing basic linear algebra
operators and data management facilities for distributed sparse matrices; it
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
portability, modularity ed extensibility in the development of the preconditioner
package. On the other hand, the implementation of MLD2P4 has led to some
package. On the other hand, the implementation of MLD2P4 has led to some
revisions and extentions of the PSBLAS kernels, leading to the
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
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.
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
the construction and application phases of the preconditioners, and the upper one
provides a uniform and easy-to-use interface to all the preconditioners.
provides a uniform and easy-to-use interface to all the preconditioners.
This architecture allows for different levels of use of the package:
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.
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
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.\\
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
\textbf{Organizzazione della guida:\\
medium-layer ones.
dire che per il momento non
forniamo anche la documentazione del middle layer, ma lo faremo in seguito\\}
\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