fdurastante/amg4psblas
1
0
Fork 0
mirror of https://github.com/sfilippone/amg4psblas.git synced 2026-10-06 22:55:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

mld2p4:

Browse Source 
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.
This commit is contained in:
Salvatore Filippone
2008-06-18 11:28:57 +00:00
parent 7fb23b6468
commit 593cc629ae
6 changed files with 5109 additions and 2033 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pdf/abstract.tex
+6 -3
View File
@@ -1,11 +1,11 @@
\begin{abstract} \begin{abstract}
\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
the user interface of MLD2P4.
\end{abstract} \end{abstract}
docs/pdf/background.tex
+11 -12
View File
@@ -16,9 +16,7 @@ solution of the original problem from the local solutions
submatrices, i.e.\ with some common rows, to couple the local information submatrices, i.e.\ with some common rows, to couple the local information
related to the submatrices (see, e.g., \cite{dd2_96}). related to the submatrices (see, e.g., \cite{dd2_96}).
The main motivations for choosing Additive Schwarz preconditioners are their The main motivations for choosing Additive Schwarz preconditioners are their
intrinsic parallelism and good \textbf{(dire good e' un po' "`forte"', dato che intrinsic parallelism. A drawback of these
subito dopo diciamo che la convergenza dipende dal numero di sottomatrici)}
convergence properties. A drawback of these
preconditioners is that the number of iterations of the preconditioned solvers preconditioners is that the number of iterations of the preconditioned solvers
generally grows with the number of submatrices. This may be a serious limitation generally grows with the number of submatrices. This may be a serious limitation
on parallel computers, since the number of submatrices usually matches the number on parallel computers, since the number of submatrices usually matches the number
@@ -72,8 +70,7 @@ The Multilevel preconditioners implemented in MLD2P4 are obtained by combining
Additive Schwarz preconditioners with coarse-space corrections; therefore Additive Schwarz preconditioners with coarse-space corrections; therefore
we first provide a sketch of the Additive Schwarz preconditioners. we first provide a sketch of the Additive Schwarz preconditioners.
Given a linear system Given the linear system \Ref{system1},
\[ Ax=b, \]
where $A=(a_{ij}) \in \Re^{n \times n}$ is a where $A=(a_{ij}) \in \Re^{n \times n}$ is a
nonsingular sparse matrix with a symmetric non-zero pattern, nonsingular sparse matrix with a symmetric non-zero pattern,
let $G=(W,E)$ be the adjacency graph of $A$, where $W=\{1, 2, \ldots, n\}$ let $G=(W,E)$ be the adjacency graph of $A$, where $W=\{1, 2, \ldots, n\}$
@@ -118,9 +115,9 @@ time on parallel distributed-memory computers is the so-called \emph{Restricted
(RAS)} preconditioner~\cite{Cai_Sarkis,Efstathiou_Gander}. It (RAS)} preconditioner~\cite{Cai_Sarkis,Efstathiou_Gander}. It
is obtained by zeroing the components of $w_i$ corresponding to the is obtained by zeroing the components of $w_i$ corresponding to the
overlapping vertices when applying the prolongation. Therefore, overlapping vertices when applying the prolongation. Therefore,
RAS differs from classical AS by the prolongation operator $(R_i^{\delta})^T$, RAS differs from classical AS by the prolongation operators,
which is substituted by $(\tilde{R}_i^0)^T \in \Re^{n_i^\delta \times n}$, which are substituted by $(\tilde{R}_i^0)^T \in \Re^{n_i^\delta \times n}$,
where $\tilde{R}_i^0$ obtained by zeroing the rows of $R_i^\delta$ where $\tilde{R}_i^0$ is obtained by zeroing the rows of $R_i^\delta$
corresponding to the vertices in $W_i^\delta \backslash W_i^0$: corresponding to the vertices in $W_i^\delta \backslash W_i^0$:
\[ \[
M_{RAS}^{-1}= \sum_{i=1}^m (\tilde{R}_i^0)^T M_{RAS}^{-1}= \sum_{i=1}^m (\tilde{R}_i^0)^T
@@ -233,11 +230,12 @@ applying a suitable smoother to a simple piecewise constant
prolongation operator, to improve the quality of the coarse-space correction. prolongation operator, to improve the quality of the coarse-space correction.
Three main steps can be identified in the smoothed aggregation procedure: Three main steps can be identified in the smoothed aggregation procedure:
\begin{itemize} \begin{enumerate}
\item coarsening of the vertex set $W$, to obtain $W_C$; \item coarsening of the vertex set $W$, to obtain $W_C$;
\item construction of the prolongator $R_C^T$; \item construction of the prolongator $R_C^T$;
\item application of $R_C$ and $R_C^T$ to build $A_C$. \item application of $R_C$ and $R_C^T$ to build $A_C$.
\end{itemize} \end{enumerate}
%\textbf{NOTA: Controllare cosa fa trilinos dopo il primo passo.}
To perform the coarsening step, we have implemented the aggregation algorithm sketched To perform the coarsening step, we have implemented the aggregation algorithm sketched
in \cite{apnum_07}. According to \cite{brezina_vanek}, a modification of this algorithm in \cite{apnum_07}. According to \cite{brezina_vanek}, a modification of this algorithm
@@ -282,8 +280,9 @@ S = I - \omega D^{-1} A ,
\end{equation} \end{equation}
where the value of $\omega$ can be chosen where the value of $\omega$ can be chosen
using some estimate of the spectral radius of $D^{-1}A$ \cite{Brezina_Vanek}. using some estimate of the spectral radius of $D^{-1}A$ \cite{Brezina_Vanek}.
\textbf{Cenno al filtering di $A$ nello smoothing, dicendo che pero' non e' stato %
implementato?} %\textbf{NOTA: filtering di $A$ nello smoothing, da implementare?}
%
%%% Local Variables: %%% Local Variables:
%%% mode: latex %%% mode: latex
docs/pdf/gettingstarted.tex
+109 -100
View File
@@ -7,7 +7,7 @@ The following steps are required:
\item \emph{Declare the preconditioner data structure}. It is a derived data type, \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| \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 or \verb|z|, according to the basic data type of the sparse matrix
(\verb|s| = real single precision; \verb|s| = real double precision; (\verb|s| = real single precision; \verb|d| = real double precision;
\verb|c| = complex single precision; \verb|z| = complex 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, This data structure is accessed by the user only through the MLD2P4 routines,
following an object-oriented approach. following an object-oriented approach.
@@ -19,9 +19,12 @@ The following steps are required:
to identify each preconditioner type is also given. to identify each preconditioner type is also given.
\item \emph{Choose a specific preconditioner within the selected preconditioner type, by setting \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|. 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 This routine must be called only if the user wants to modify the default values
Section~\ref{sec:examples}; a complete list of all the of the parameters associated to the selected preconditioner type, to obtain a variant
preconditioner parameters and their allowed values is provided in 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}. Section~\ref{sec:highlevel}.
\item \emph{Build the preconditioner for a given matrix.} This is performed by \item \emph{Build the preconditioner for a given matrix.} This is performed by
the routine \verb|mld_precbld|. the routine \verb|mld_precbld|.
@@ -58,8 +61,8 @@ Multilevel &\verb|'ML'| & Multi-level hybrid preconditioner (additive
with post-smoothing only. Number of levels: 2; with post-smoothing only. Number of levels: 2;
post-smoother: block-Jacobi preconditioner with ILU(0) post-smoother: block-Jacobi preconditioner with ILU(0)
on the local blocks; coarsest matrix: distributed among the on the local blocks; coarsest matrix: distributed among the
processors; corase-level solver: 4 sweeps of the processors; corase-level solver: 4 sweeps of the block-Jacobi
block-Jacobi solver, with ILU(0) on the blocks. \\ solver, with the UMFPACK LU factorization on the blocks. \\
\hline \hline
\end{tabular} \end{tabular}
\end{center} \end{center}
@@ -69,25 +72,29 @@ Multilevel &\verb|'ML'| & Multi-level hybrid preconditioner (additive
\subsection{Examples\label{sec:examples}} \subsection{Examples\label{sec:examples}}
The code reported below shows how to set and apply the MLD2P4 default multi-level The code reported in Figure~\ref{fig:example1} shows how to set and apply the MLD2P4 default
preconditioned, i.e.\ the two-level hybrid post-smoothed Schwarz preconditioner, multi-level preconditioner, i.e.\ the two-level hybrid post-smoothed Schwarz preconditioner,
using block-Jacobi with ILU(0) on the blocks as basic preconditioner, having block-Jacobi with ILU(0) on the blocks as basic preconditioner,
a coarse matrix distributed among the processors, and four block-Jacobi a coarse matrix distributed among the processors, and four block-Jacobi
sweeps with ILU(0) on the blocks as approximate coarse-level solver. sweeps, with the UMFPACK sparse LU factorization on the blocks, as approximate coarse-level solver.
The choice of this preconditioner is made The choice of this preconditioner is made
by simply specifying \verb|'ML'| as second argument of \verb|mld_precinit| by simply specifying \verb|'ML'| as second argument of \verb|mld_precinit|
(a call to \verb|mld_precset| is not needed). (a call to \verb|mld_precset| is not needed).
The preconditioner is applied within the BiCGSTAB solver provided by PSBLAS. The preconditioner is applied with the BiCGSTAB solver provided by PSBLAS.
The part of the code concerning the The part of the code concerning the
reading and assembling of the sparse matrix and the right-hand side vector, performed 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 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. here for brevity; the statements concerning the deallocation of the PSBLAS data structure
The complete code can be found in the example program file \verb|example_2lev_default.f90| 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| 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. 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{}. For details on the use of the PSBLAS routines, see the PSBLAS User's Guide \cite{}.
\begin{figure}[tbp]
\begin{center}
{\small
\begin{verbatim} \begin{verbatim}
use psb_base_mod use psb_base_mod
use psb_util_mod use psb_util_mod
@@ -98,9 +105,9 @@ For details on the use of the PSBLAS routines, see the PSBLAS User's Guide \cite
! sparse matrix ! sparse matrix
type(psb_dspmat_type) :: A type(psb_dspmat_type) :: A
! sparse matrix descriptor ! sparse matrix descriptor
type(psb_desc_type) :: DESC_A type(psb_desc_type) :: desc_A
! preconditioner ! preconditioner
type(mld_dprec_type) :: PRE type(mld_dprec_type) :: P
... ... ... ...
! !
! initialize the parallel environment ! initialize the parallel environment
@@ -114,116 +121,118 @@ For details on the use of the PSBLAS routines, see the PSBLAS User's Guide \cite
... ... ... ...
! !
! initialize the default multi-level preconditioner ! initialize the default multi-level preconditioner
! (two-level hybrid post-smoothed Schwarz) ! (two-level hybrid Schwarz, with ILU(0) as post-smoother
call mld_precinit(PRE,'ML',info) ! 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 ! build the preconditioner
call psb_precbld(A,PRE,DESC_A,info) call psb_precbld(A,P,DESC_A,info)
! !
! set the solver parameters and the initial guess ! set the solver parameters and the initial guess
... ... ... ...
! !
! solve Ax=b with preconditioned BiCGSTAB ! solve Ax=b with preconditioned BiCGSTAB
call psb_krylov('BICGSTAB',A,PRE,b,x,tol,DESC_A,info) call psb_krylov('BICGSTAB',A,P,b,x,tol,desc_A,info)
... ... ... ...
! !
! cleanup the preconditioner ! deallocate the preconditioner
call mld_precfree(PRE,info) call mld_precfree(P,info)
! !
! cleanup other data structures ! deallocate other data structures
... ... ... ...
! !
! exit the parallel environment ! exit the parallel environment
call psb_exit(ictxt) call psb_exit(ictxt)
stop stop
\end{verbatim} \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.
\textbf{MODIFICARE TUTTA LA PARTE CHE SEGUE:\\ As a further example, we report in Figure~\ref{fig:example3} the code
- solo istruzioni diverse dall'esempio precedente (essenzialmente il setting del precondizionatore, magari con piu' chiamate a precset;\\ concerning the setup of a three-level additive multi-level preconditioner,
- lasciare l'osservazione sulla specifica esplicita del numero di livelli;\\ using ILU(0) as pre- and post-smoother, a distributed coarsest matrix and
- rimandare al paragrafo successivo per una decrizione accurata di tutti i parametri;\\ five block-Jacobi sweeps as coarsest-level solver, with
- lasciare l'osservazione sui vecchi utenti di PSBLAS.}\\ 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.}
In the following we describe the general procedure for setting and building one of the MLD2P4 preconditioners. An example program including the code fragments
The user has first to prepare the preconditioner data structure by using the routine \verb|mld_precinit|. Input parameters shown in in Figures~\ref{fig:example2} and \ref{fig:example3} is in
for this routine include a string parameter, needed to define the preconditioner type, and an optional integer parameter \verb|XXX/.../example_3lev.f90|. \textbf{COMPLETARE. Fare un programma solo
specifying the number of the levels in the case of a multi-level preconditioner. per i due esempi, in cui uno e' commentato e l'altro no.}
Note that if the optional parameter is not present and a multi-level preconditioner has been chosen, One more example program, showing the setup and application of a one-level
a two-level preconditioner is set. On the other hand, the integer parameter is ignored if the type of the preconditioner is not multilevel. additive Schwarz preconditioner can be found in \verb|XXX/.../example_1lev.f90|.
In Table \ref{tab:precinit} we report both the possible choices for the preconditioner type \textbf{COMPLETARE}.
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{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')
... ... ... ...
!
! 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} \end{verbatim}
}
\caption{Setup of a hybrid three-level Schwarz preconditioner.\label{fig:example2}}
\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 \begin{figure}[tbp]
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 \begin{center}
includes in her/his program the file \verb|psb_prec_mod|. {\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: %%% Local Variables:
%%% mode: latex %%% mode: latex
docs/pdf/highlevelview.tex
+210 -46
View File
@@ -1,40 +1,217 @@
\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.
\subsection{Subroutine mld\_precinit\label{sec:precinit}}
The setup of a MLD2P4 preconditioner is obtained by using the \verb|mld_precinit| routine, which
allocates and initializes the preconditioner data structure.
The API of this routine as well as the description of the arguments is reported in Fig.~\ref{fig:prcinit}.
Note that the allowed values for the \verb|ptype| argument are reported in Table~\ref{tab:precinit} (Sec. \ref{sec:started}).
%
\begin{figure}[h]
\begin{center} \begin{center}
{\small \verb|mld_precinit(p,ptype,info)|\\
\begin{verbatim} \verb|mld_precinit(p,ptype,info,nlev)|
mld_precinit(p,ptype,info,nlev)
Arguments:
p type(mld_dprec_type), input/output.
The preconditioner data structure.
ptype character, input. The type of preconditioner.
info integer, output. Error code.
nlev integer, optional, input.
The number of levels of the multilevel preconditioner.
If nlev is not present and ptype=`ML'/`ml',
then nlev=2 is assumed.
Otherwise, nlev is ignored.
\end{verbatim}
}
\end{center} \end{center}
\caption{API of the routine for preconditioner allocation and inizialization.\label{fig:prcinit}}
\end{figure} \noindent
% This routine allocates and initializes the preconditioner data structure,
% according to the preconditioner type chosen by the user.
\subsubsection*{Arguments}
\begin{tabular}{p{1.2cm}p{10.6cm}}
\verb|p| & \verb|type(mld_|\emph{x}\verb|prec_type), intent(inout)|.\\
& The preconditioner data structure. Note that \emph{x} must be chosen according
to the real/complex, single/double precision version of MLD2P4 under use.\\
\verb|ptype| & \verb|character(len=*), intent(in)|.\\
& The type of preconditioner. Its values are specified in Table~\ref{tab:precinit}.\\
\verb|info| & \verb|integer, intent(out)|.\\
& Error code. See Section~\ref{sec:errors} for details.\\
\verb|nlev| & \verb|integer, optional, intent(in)|.\\
& The number of levels of the multilevel preconditioner.
If \verb|nlev| is not present and \verb|ptype|='ML'/'ml',
then \verb|nlev|=2 is assumed. Otherwise, \verb|nlev| is ignored.
\end{tabular}
\subsection{Subroutine mld\_precset\label{sec:precset}}
\begin{center}
\verb|mld_precset(p,what,val,info)|\\
\verb|mld_precset(p,what,val,info,ilev)|
\end{center}
\noindent
This routine sets the parameters defining the preconditioner. More
precisely, the parameter identified by \verb|what| is assigned the value
contained in \verb|val|.
\subsubsection*{Arguments}
\begin{tabular}{p{1.2cm}p{10.6cm}}
\verb|p| & \verb|type(mld_|\emph{x}\verb|prec_type), intent(inout)|.\\
& The preconditioner data structure. Note that \emph{x} must be chosen according
to the real/complex, single/double precision version of MLD2P4 under use.\\
\verb|what| & \verb|integer, intent(in)|. \\
& The number identifying the parameter to be set.
A mnemonic constant has been associated to each of these
numbers, as reported in Table~\ref{tab:params}.\\
\verb|val | & \verb|integer| \emph{or} \verb|character(len=*)| \emph{or} \verb|real(1.0)|
\emph{or} \verb|real(1.0d0)|,\\
& \verb|intent(in)|.\\
& The value of the parameter to be set. The list of allowed
values and the corresponding data types is given in Table~\ref{tab:params}.\\
\verb|info| & \verb|integer, intent(out)|.\\
& Error code. See Section~\ref{sec:errors} for details.\\
\verb|ilev| & \verb|integer, optional, intent(in)|.\\
& For the multilevel preconditioner, the level at which the
preconditioner parameter has to be set. The levels are numbered in increasing
order starting from the finest one, i.e.\ level 1 is the finest level.
If \verb|ilev| is not present, the parameter identified by \verb|what|
is set at all the appropriate levels (see Table~\ref{tab:params}).
\end{tabular}
\ \\
A variety of (one-level and multi-level) preconditioner can be obtained by a suitable
setting of the preconditioner parameters. These parameters can be logically divided into
four groups, i.e.\ parameters defining
\begin{enumerate}
\item the basic structure of the multi-level preconditioner;
\item the one-level preconditioner to be used as smoother;
\item the aggregation algorithm;
\item the coarse-space correction at the coarsest level.
\end{enumerate}
A list of the parameters that can be set, along with their allowed and default values, and the levels
at which their are appropriate is given in Table~\ref{tab:params}. Note that the routines allows
to set different features of the preconditioner at each level through the use of \verb|ilev|.
This should be done by users with experience in the field of multi-level preconditioners.
Non-expert users are recommended to call \verb| mld_precset| without specifying \verb|ilev|.
\begin{table}[p]
{\small
\begin{center}
\textbf{QUESTA TABELLA VA RUOTATA DI 90 GRADI E SUDDIVISA IN DUE TABELLE, TOGLIENDO SMALL}
\hspace*{-3cm}
\begin{tabular}{|l|l|p{1.5cm}|l|p{6cm}|}
\hline
\verb|what| & \emph{data type} & \verb|val| & \verb|ilev| & \emph{comments} \\ \hline
\multicolumn{5}{|c|}{\emph{basic structure of the multi-level preconditioner}} \\ \hline
\verb|mld_ml_type_| & \verb|character(len=*)|
& 'ADD', 'MULT'
& 2,...,\verb|nlev|
& basic multi-level framework: additive or multiplicative among the levels
(always additive inside a level); when \verb|ilev| is present, it refers
only to the combination of levels \verb|ilev|-1 and \verb|ilev|. \\
\verb|mld_baseprec_type_|& \verb|character(len=*)|
& 'DIAG', 'BJAC', 'AS'
& 1,...,\verb|nlev|-1
& basic one-level preconditioner (i.e.\ smoother) of the multi-level
preconditioner \textbf{CAMBIARE NOME COSTANTE; ora e' mld\_prec\_type,
ma questo puo' generare confusione!} \\
\verb|mld_smooth_pos_| & \verb|character(len=*)|
& 'PRE', 'POST', 'BOTH'
& 2,...,\verb|nlev|
& ``position'' of the smoother: pre-smoother, post-smoother, pre-/post-smoother
\textbf{per l'utente NON HA SENSO settarlo ai livelli 2,..., nlev; l'utente
deve specificare un livello tra 1 e nlev-1 e la precset deve shiftare il livello
tenendo conto della struttura del tipo di dato precondizionatore} \\ \hline
\multicolumn{5}{|c|}{\emph{basic one-level preconditioner (smoother)}} \\ \hline
\verb|mld_n_ovr| &
&
&
& \\
\verb|mld_sub_restr_| &
&
&
& \\
\verb|mld_sub_prol_| &
&
&
& \\
\verb|mld_sub_solve_| &
&
&
& \\
\verb|mld_sub_fillin_| &
&
&
& \textbf{MODIFICA: fill\_in $-->$ fillin} \\
\verb|mld_sub_thresh_| &
&
&
& \textbf{AGGIUNGERE THRESHOLD ILU(t)} \\
\verb|mld_sub_ren_| &
&
&
& \textbf{MANCA COSTANTE STRINGA ASSOCIATA} \\ \hline
\multicolumn{5}{|c|}{\emph{aggregation algorithm}} \\ \hline
\verb|mld_aggr_alg_| &
&
&
& \\
\verb|mld_aggr_kind_| &
&
&
& \\
\verb|mld_aggr_thresh_| &
&
&
& \\
\verb|mld_aggr_eig_| &
&
&
& \textbf{NON E' DEFINITA LA STRINGA CORRISPONDENTE a mld\_max\_norm} \\ \hline
\multicolumn{5}{|c|}{\emph{coarse-space correction at the coarsest level}} \\ \hline
\verb|mld_coarse_mat_| &
&
&
& \\
\verb|mld_coarse_solve_| &
&
&
& \textbf{VEDI OSSERVAZIONI EMAIL 15-16/06/08}\\
\verb|mld_coarse_subsolve_| &
&
&
& \textbf{VEDI OSSERVAZIONI EMAIL 15-16/06/08}\\
\verb|mld_coarse_sweeps_|&
&
&
& \\
\verb|mld_coarse_fillin_| &
&
&
& \textbf{MODIFICA: fill\_in $-->$ fillin} \\
\verb|mld_coarse_thresh_| &
&
&
& \textbf{AGGIUNGERE THRESHOLD ILU(t)} \\ \hline
\end{tabular}
\end{center}
}
\caption{Parameters defining the preconditioner.\label{tab:precinit}}
\end{table}
\clearpage
\noindent
=========================================\\
\begin{figure}[h] \begin{figure}[h]
\begin{center} \begin{center}
{\small {\small
@@ -125,20 +302,7 @@ mld_precbld(a,desc_a,prec,info)
In the following we report the list of possible parameters to be set through the \verb|mld_precset| routine, In the following we report the list of possible parameters to be set through the \verb|mld_precset| routine,
in order to choose the type of multi-level preconditioner. The parameters are classified depending on their scope. in order to choose the type of multi-level preconditioner. The parameters are classified depending on their scope.
Note that for character data both uppercase and lowercase strings are allowed. Note that for character data both uppercase and lowercase strings are allowed.
\begin{table}[h]
{\small \label{tab:prec_type}
\begin{tabular}{ll}
Parameter (\verb|what|) & Allowed values ( \verb|val|)\\
\verb|mld_ml_type_| & 'ADD', 'MULT'\\
& Define the type of multi-level preconditioner.\\
\verb|mld_prec_type_| & 'DIAG', 'BJAC', 'AS' \\
& Define the smoother at a certain level.\\
\verb|mld_smooth_pos_| & 'PRE', 'POST', 'BOTH'\\
& Define the way to apply the smoother.\\
\end{tabular}
\caption{Parameters for preconditioner type.}
}
\end{table}
In order to build a coarse matrix from a fine one, this version of MLD2P4 implements the In order to build a coarse matrix from a fine one, this version of MLD2P4 implements the
smoothed aggregation algorithm described in Section~\ref{sec:aggregation}. However, since for nonsymmetric problems the smoothed aggregation algorithm described in Section~\ref{sec:aggregation}. However, since for nonsymmetric problems the
docs/pdf/overview.tex
+39 -26
View File
@@ -1,30 +1,44 @@
\section{General Overview\label{sec:overview}} \section{General Overview\label{sec:overview}}
The \emph{Multi-Level Domain Decomposition Parallel Preconditioners Package based on \markboth{\underline{MLD2P4 User's and Reference Guide}}
PSBLAS (MLD2P4}) provides various versions of multi-level Schwarz preconditioners~\cite{DD2}, {\underline{\ref{sec:overview} General Overview}}
to be used in the iterative solutions of sparse linear systems $Ax=b$, where
$A$ is a square, real or complex, sparse matrix with a symmetric sparsity pattern. The \textsc{Multi-Level Domain Decomposition Parallel Preconditioners Package based on
\textbf{Ma non abbiamo detto che, se il pattern di sparista' non e' simmetrico, PSBLAS (MLD2P4}) provides \emph{multi-level Schwarz preconditioners}~\cite{DD2},
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
medium-layer ones.
\textbf{Organizzazione della guida:\\ This guide is organized as follows:\textbf{organizzazione della guida}
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}
%%% Local Variables: %%% Local Variables:
%%% mode: latex %%% mode: latex
docs/userguide.pdf
+4733 -1845
View File
File diff suppressed because one or more lines are too long