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

Minor changes in the user's and reference guide.

Browse Source
This commit is contained in:
Daniela di Serafino
2017-09-15 11:13:50 +02:00
parent 6dde52f6df
commit bbdf862a22
11 changed files with 228 additions and 229 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/abstract.tex
+7 -7
View File
@@ -1,11 +1,11 @@
\section*{Abstract}
\addcontentsline{toc}{section}{Abstract}
\textsc{MLD2P4 (Multi-Level Domain Decomposition Parallel Preconditioners Package
based on PSBLAS}) is a package of parallel algebraic multi-level preconditioners.
The first release of MLD2P4 made available multi-level additive and hybrid Schwarz
\textsc{MLD2P4 (MultiLevel Domain Decomposition Parallel Preconditioners Package
based on PSBLAS}) is a package of parallel algebraic multilevel preconditioners.
The first release of MLD2P4 made available multilevel additive and hybrid Schwarz
preconditioners, as well as one-level additive Schwarz preconditioners. The package
has been extended to include further multi-level cycles and smoothers widely used in
multigrid methods. In the multi-level case, a purely algebraic approach is applied to
has been extended to include further multilevel cycles and smoothers widely used in
multigrid methods. In the multilevel 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 assumed to be square,
real or complex.
@@ -14,13 +14,13 @@ MLD2P4 has been designed to provide scalable and easy-to-use preconditioners
in the context of the PSBLAS (Parallel Sparse Basic Linear Algebra Subprograms)
computational framework and can be used in conjuction with the Krylov solvers
available in this framework. MLD2P4 enables the user to easily specify different
features of an algebraic multi-level preconditioner, thus allowing to search
features of an algebraic multilevel preconditioner, thus allowing to search
for the ``best'' preconditioner for the problem at hand.
The package employs object-oriented design techniques in
Fortran~2003, with interfaces to additional third party libraries
such as MUMPS, UMFPACK, SuperLU, and SuperLU\_Dist, which
can be exploited in building multi-level preconditioners. The parallel
can be exploited in building multilevel preconditioners. The parallel
implementation is based on a Single Program Multiple Data (SPMD)
paradigm; the inter-process communication is based on MPI and
is managed mainly through PSBLAS.
docs/src/background.tex
+1 -1
View File
@@ -187,7 +187,7 @@ $$
P^k = S^k \bar{P}^k,
$$
in order to remove nonsmooth components from the range of the prolongator,
and hence to improve the convergence properties of the multi-level
and hence to improve the convergence properties of the multilevel
method~\cite{BREZINA_VANEK,Stuben_01}.
A simple choice for $S^k$ is the damped Jacobi smoother:
\[
docs/src/bibliography.tex
+4 -4
View File
@@ -73,11 +73,11 @@ T.~A.~Davis,
{\em Algorithm 832: UMFPACK - an Unsymmetric-pattern Multifrontal
Method with a Column Pre-ordering Strategy},
ACM Transactions on Mathematical Software, 30, 2004, 196--199.
(See also {\tt http://www.cise.ufl.edu/~davis/})
(See also \texttt{http://www.cise.ufl.edu/{\textasciitilde}davis/})
%
\bibitem{SUPERLU}
J.~W.~Demmel, S.~C.~Eisenstat, J.~R.~Gilbert, X.~S.~Li, J.~W.~H.~Liu,
A supernodal approach to sparse partial pivoting,
{\em A supernodal approach to sparse partial pivoting},
SIAM Journal on Matrix Analysis and Applications, 20 (3), 1999, 720--755.
%
\bibitem{blas3}
@@ -103,8 +103,8 @@ ACM Transactions on Mathematical Software, 14 (1) 1988, 1--17.
%
\bibitem{PSBLASGUIDE}
S.~Filippone, A.~Buttari,
{\em PSBLAS-3.0 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library}, 2012,
available from \texttt{http://www.ce.uniroma2.it/psblas/}.
{\em PSBLAS 3.5.0 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library}, 2012,
available from \texttt{https://github.com/sfilippone/psblas3/tree/master/docs}.
%
\bibitem{PSBLAS3}
S.~Filippone, A.~Buttari,
docs/src/building.tex
+5 -4
View File
@@ -49,7 +49,7 @@ in the make.inc file of the LAPACK library.
\item[MPI] \cite{MPI2,MPI1} A version of MPI is available on most
high-performance computing systems.
\item[PSBLAS] \cite{PSBLASGUIDE,psblas_00} Parallel Sparse BLAS (PSBLAS) is
available from \url{www.ce.uniroma2.it/psblas}; version
available from \url{github.com/sfilippone/psblas3}; version
3.5.0 (or later) is required. Indeed, all the prerequisites
listed so far are also prerequisites of PSBLAS.
\end{description}
@@ -62,7 +62,7 @@ compiler as MLD2P4.
We provide interfaces to the following third-party software libraries;
note that these are optional, but if you enable them some defaults
for multi-level preconditioners may change to reflect their presence.
for multilevel preconditioners may change to reflect their presence.
\begin{description}
\item[UMFPACK] \cite{UMFPACK}
@@ -267,7 +267,8 @@ Some influential environment variables:
Use these variables to override the choices made by `configure' or to help
it to find libraries and programs with nonstandard names/locations.
Report bugs to <bugreport@mld2p4.it>.
Report bugs to <pasqua.dambra@cnr.it; daniela.diserafino@unicampania.it;
salvatore.filippone@cranfield.ac.uk>.
\end{verbatim}
For instance, if a user has built and installed PSBLAS 3.5 under the
@@ -324,7 +325,7 @@ both of them are further divided into \verb|fileread| and
\item[\tt examples] contains a set of simple example programs with a
predefined choice of preconditioners, selectable via integer
values. These are intended to get an acquaintance with the
multi-level preconditioners available in MLD2P4.
multilevel preconditioners available in MLD2P4.
\item[\tt tests] contains a set of more sophisticated examples that
will allow the user, via the input files in the \verb|runs|
subdirectories, to experiment with the full range of preconditioners
docs/src/distribution.tex
+1 -1
View File
@@ -5,7 +5,7 @@
\noindent
MLD2P4 is available from the web site
\begin{quotation}
\texttt{http://www.mld2p4.it}
\texttt{https://github.com/sfilippone/mld2p4-2}
\end{quotation}
where contact points for further information can be also found.
docs/src/gettingstarted.tex
+10 -10
View File
@@ -2,7 +2,7 @@
\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
We describe the basics for building and applying MLD2P4 one-level and multilevel
(i.e., AMG) preconditioners with the Krylov solvers included in PSBLAS \cite{PSBLASGUIDE}.
The following steps are required:
\begin{enumerate}
@@ -21,7 +21,7 @@ The following steps are required:
\verb|init| 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 aggregation parameters (for multi-level preconditioners only).}
%\item \emph{Modify the aggregation parameters (for multilevel preconditioners only).}
% 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 with the aggregation hierarchy construction.
@@ -38,7 +38,7 @@ The following steps are required:
preconditioner parameters and their allowed and default values is provided in
Section~\ref{sec:userinterface}, Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}.
\item \emph{Build the preconditioner for a given matrix}. If the selected preconditioner
is multi-level, then two steps must be performed, as specified next.
is multilevel, then two steps must be performed, as specified next.
\begin{enumerate}
\item[4.1] \emph{Build the aggregation hierarchy for a given matrix.} This is
performed by the routine \verb|hierarchy_build|.
@@ -116,7 +116,7 @@ on parallel computers.
\subsection{Examples\label{sec:examples}}
The code reported in Figure~\ref{fig:ex1} shows how to set and apply the default
multi-level preconditioner available in the real double precision version
multilevel 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 the second argument of \verb|P%init|
(a call to \verb|P%set| is not needed) and is applied with the CG
@@ -137,7 +137,7 @@ input data is available in \verb|examples/fileread/runs|.
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 preconditioner
The setup and application of the default multilevel preconditioner
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,
@@ -172,7 +172,7 @@ the corresponding codes are available in \verb|examples/fileread/|.
! using PSBLAS routines for sparse matrix / vector management
... ...
!
! initialize the default multi-level preconditioner, i.e. V-cycle
! initialize the default multilevel preconditioner, i.e. V-cycle
! with basic smoothed aggregation, 1 hybrid forward/backward
! GS sweep as pre/post-smoother and UMFPACK as coarsest-level
! solver
@@ -202,12 +202,12 @@ the corresponding codes are available in \verb|examples/fileread/|.
\end{verbatim}
}
\end{minipage}
\caption{setup and application of the default multi-level preconditioner (example 1).
\caption{setup and application of the default multilevel preconditioner (example 1).
\label{fig:ex1}}
\end{center}
\end{figure}
Different versions of the multi-level preconditioner can be obtained by changing
Different versions of the multilevel preconditioner can be obtained by changing
the default values of the preconditioner parameters. The code reported in
Figure~\ref{fig:ex2} shows how to set a V-cycle preconditioner
which applies 1 block-Jacobi sweep as pre- and post-smoother,
@@ -272,7 +272,7 @@ boundary conditions are also available in the directory \verb|examples/pdegen|.
}
\end{minipage}
\caption{setup of a multi-level preconditioner\label{fig:ex2}}
\caption{setup of a multilevel preconditioner\label{fig:ex2}}
\end{center}
\end{figure}
@@ -297,7 +297,7 @@ boundary conditions are also available in the directory \verb|examples/pdegen|.
\end{verbatim}
}
\end{minipage}
\caption{setup of a multi-level preconditioner\label{fig:ex3}}
\caption{setup of a multilevel preconditioner\label{fig:ex3}}
\end{center}
\end{figure}
docs/src/license.tex
+2 -3
View File
@@ -6,12 +6,11 @@ The MLD2P4 is freely distributable under the following copyright
terms: {\small
\begin{verbatim}
MLD2P4 version 2.1
MultiLevel Domain Decomposition Parallel Preconditioners Package
based on PSBLAS (Parallel Sparse BLAS version 3.4)
based on PSBLAS (Parallel Sparse BLAS version 3.5)
(C) Copyright 2008, 2010, 2012, 2017
(C) Copyright 2008, 2010, 2012, 2015, 2017
Salvatore Filippone Cranfield University, Cranfield, UK
Pasqua D'Ambra IAC-CNR, Naples, IT
docs/src/overview.tex
+7 -7
View File
@@ -2,7 +2,7 @@
\markboth{\textsc{MLD2P4 User's and Reference Guide}}
{\textsc{\ref{sec:overview} General Overview}}
The \textsc{Multi-Level Domain Decomposition Parallel Preconditioners Package based on
The \textsc{MultiLevel Domain Decomposition Parallel Preconditioners Package based on
PSBLAS (MLD2P4}) provides parallel Algebraic MultiGrid (AMG) and Domain
Decomposition preconditioners (see, e.g., \cite{Briggs2000,Stuben_01,dd2_96}),
to be used in the iterative solution of linear systems,
@@ -17,15 +17,15 @@ where $A$ is a square, real or complex, sparse matrix.
%adeguato e fare qualcosa di consistente anche con 1-lev Schwarz.}
%
The name of the package comes from its original implementation, containing
multi-level additive and hybrid Schwarz preconditioners, as well as one-level additive
multilevel additive and hybrid Schwarz preconditioners, as well as one-level additive
Schwarz preconditioners. The current version extends the original plan by including
multi-level cycles and smoothers widely used in multigrid methods.
multilevel cycles and smoothers widely used in multigrid methods.
The multi-level preconditioners implemented in MLD2P4 are obtained by combining
The multilevel preconditioners implemented in MLD2P4 are obtained by combining
AMG cycles with smoothers and coarsest-level solvers. The V-, W-, and
K-cycles~\cite{Briggs2000,Notay2008} are available, which allow to define
almost all the preconditioners in the package, including the multi-level hybrid
Schwarz ones; a specific cycle is implemented to obtain multi-level additive
almost all the preconditioners in the package, including the multilevel hybrid
Schwarz ones; a specific cycle is implemented to obtain multilevel additive
Schwarz preconditioners. The Jacobi, hybrid
%\footnote{see Note 2 in Table~\ref{tab:p_coarse}, p.~28.}
forward/backward Gauss-Seidel, block-Jacobi, and additive Schwarz methods
@@ -79,7 +79,7 @@ and solvers for building new versions of the preconditioners (see
Section~\ref{sec:adding}).
We note that the user interface of MLD2P4 2.1 has been extended with respect to the
previous versions in order to separate the construction of the multi-level hierarchy from
previous versions in order to separate the construction of the multilevel hierarchy from
the construction of the smoothers and solvers, and to allow for more flexibility
at each level. The software architecture described in~\cite{MLD2P4_TOMS} has significantly
evolved too, in order to fully exploit the Fortran~2003 features implemented in PSBLAS 3.
docs/src/userguide.tex
+1 -1
View File
@@ -104,7 +104,7 @@
{\Huge\bfseries MLD2P4\\[.8ex] User's and Reference Guide
}
\noindent\rule[-1ex]{\textwidth}{5pt}\\[2.5ex]
\hfill\emph{\Large A guide for the Multi-Level Domain Decomposition \\[.6ex]
\hfill\emph{\Large A guide for the MultiLevel Domain Decomposition \\[.6ex]
Parallel Preconditioners Package
based on PSBLAS}
\end{minipage}}
docs/src/userhtml.tex
+1 -1
View File
@@ -91,7 +91,7 @@
\begin{document}
{\LARGE\bfseries MLD2P4\\[.8ex] User's and Reference Guide}\\[\baselineskip]
\emph{\large A guide for the Multi-Level Domain Decomposition
\emph{\large A guide for the MultiLevel Domain Decomposition
Parallel Preconditioners Package
based on PSBLAS}\\[3ex]
{\large\bfseries Pasqua D'Ambra}\\
docs/src/userinterface.tex
+21 -22
View File
@@ -6,7 +6,7 @@ The basic user interface of MLD2P4 consists of eight routines. The six
routines \verb|init|, \verb|set|,
\verb|hierarchy_build|, \verb|smoothers_build|,
\verb|bld|, and \verb|apply| encapsulate all the
functionalities for the setup and the application of any multi-level and one-level
functionalities for the setup and the application of any multilevel and one-level
preconditioner implemented in the package.
The routine \verb|free| deallocates the preconditioner data structure, while
\verb|descr| prints a description of the preconditioner setup by the user.
@@ -63,7 +63,7 @@ This routine allocates and initializes the preconditioner
\verb|info| & \verb|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
%\verb|nlev| & \verb|integer, optional, intent(in)|.\\
% & The number of levels of the multi-level
% & The number of levels of the multilevel
% preconditioner. This optional argument is deprecated,
% new codes should set the number of levels with \verb|mld_precset|.\\
% If \verb|nlev| is not present and \verb|ptype|=\verb|'ML'|, \verb|'ml'|,
@@ -115,7 +115,7 @@ contained in \verb|val|.
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors}
for details.\\
\verb|ilev| & \verb|integer, optional, intent(in)|.\\
& For the multi-level preconditioner, the level at which the
& 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.
@@ -123,7 +123,7 @@ contained in \verb|val|.
is set at all the appropriate levels (see
Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}).\\
\verb|ilmax| & \verb|integer, optional, intent(in)|.\\
& For the multi-level preconditioner, when both
& For the multilevel preconditioner, when both
\verb|ilev| and \verb|ilmax| are present, the settings
are applied at all levels \verb|ilev:ilmax|. When
\verb|ilev| is present but \verb|ilmax| is not, then
@@ -154,11 +154,11 @@ A variety of preconditioners 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 type of multi-level cycle and how many cycles must be applied;
\item the type of multilevel cycle and how many cycles must be applied;
\item the aggregation algorithm;
\item the coarse-space correction at the coarsest level (for multi-level
\item the coarse-space correction at the coarsest level (for multilevel
preconditioners only);
\item the smoother of the multi-level preconditioners, or the one-level
\item the smoother of the multilevel preconditioners, or the one-level
preconditioner.
\end{enumerate}
@@ -237,20 +237,20 @@ solver is changed to the default sequential solver.
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\textsc{comments} \\ \hline
%\multicolumn{5}{|c|}{\emph{type of the multi-level preconditioner}}\\ \hline
%\multicolumn{5}{|c|}{\emph{type of the multilevel preconditioner}}\\ \hline
%\verb|mld_ml_cycle_| \par
\verb|'ML_CYCLE'| & \verb|character(len=*)|
& \texttt{'VCYCLE'} \par \texttt{'WCYCLE'} \par \texttt{'KCYCLE'} \par
\texttt{'MULT'} \par \texttt{'ADD'}
& \texttt{'VCYCLE'}
&Multi-level cycle: V-cycle, W-cycle, K-cycle, hybrid Multiplicative Schwarz,
&Multilevel cycle: V-cycle, W-cycle, K-cycle, hybrid Multiplicative Schwarz,
and Additive Schwarz. \par
Note that hybrid Multiplicative Schwarz is equivalent to V-cycle and
is included for compatibility with previous versions of MLD2P4. \\ \hline
%\verb|mld_outer_sweeps_| \par
\verb|'OUTER_SWEEPS'| & \texttt{integer} &
Any integer \par number $\ge 1$ & 1 &
Number of multi-level cycles. \\ \hline
Number of multilevel cycles. \\ \hline
%\verb|mld_smoother_type_| \par \verb|SMOOTHER_TYPE| & \verb|character(len=*)|
% & \texttt{'JACOBI'} \ \ \ \texttt{'BJAC'} \ \ \ \texttt{'AS'}
% & \texttt{'AS'}
@@ -264,7 +264,7 @@ solver is changed to the default sequential solver.
%\hline
\end{tabular}
\end{center}
\caption{Parameters defining the multi-level cycle and the number of cycles to
\caption{Parameters defining the multilevel cycle and the number of cycles to
be applied.
\label{tab:p_cycle}}
\esideways
@@ -448,12 +448,11 @@ the parameter \texttt{ilev}.} \\
Note that \texttt{UMF} and \texttt{SLU} require the coarsest
matrix to be replicated, \texttt{SLUDIST}, \texttt{JACOBI},
\texttt{GS} and \texttt{BJAC} require it to be
distributed, \texttt{MUMPS} can be used with either
distributed, and \texttt{MUMPS} can be used with either
a replicated or a distributed matrix. When any of the previous
solvers is specified, the matrix layout is set to a default
value
which allows the use
value UMFPACK and SuperLU\_Dist
value which allows the use of the solver (see Remark 3, p.~24).
Note also that UMFPACK and SuperLU\_Dist
are available only in double precision. \\ \hline
%\verb|mld_coarse_subsolve_| \par
\verb|'COARSE_SUBSOLVE'| & \verb|character(len=*)|
@@ -527,7 +526,7 @@ level (continued).\label{tab:p_coarse_1}}
& \verb|'JACOBI'| \par \verb|'GS'| \par \verb|'BGS'| \par \verb|'BJAC'|
\par \verb|'AS'|
& \verb|'FBGS'|
& Type of smoother used in the multi-level preconditioner:
& Type of smoother used in the multilevel preconditioner:
point-Jacobi, hybrid (forward) Gauss-Seidel,
hybrid backward Gauss-Seidel, block-Jacobi, and
Additive Schwarz. \par
@@ -539,7 +538,7 @@ level (continued).\label{tab:p_coarse_1}}
\texttt{'ILUT'} \par \texttt{'MILU'} \par
\par \texttt{'MUMPS'} \par \texttt{'SLU'} \par \texttt{'UMF'}
& \texttt{GS} and \texttt{BGS} for pre- and post-smoothers
of multi-level preconditioners, respectively \par
of multilevel preconditioners, respectively \par
\texttt{ILU} for block-Jacobi and Additive Schwarz
one-level preconditioners
& The local solver to be used with the smoother or one-level
@@ -554,7 +553,7 @@ level (continued).\label{tab:p_coarse_1}}
& Any integer \par number~$\ge 0$
& 1
& Number of sweeps of the smoother or one-level preconditioner.
In the multi-level case, no pre-smother or
In the multilevel case, no pre-smother or
post-smoother is used if this parameter is set to 0
together with \verb|pos='PRE'| or \verb|pos='POST|,
respectively. \\ \hline
@@ -635,7 +634,7 @@ level (continued).\label{tab:p_coarse_1}}
\noindent
This routine builds the one-level preconditioner \verb|p| according to the requirements
made by the user through the routines \verb|init| and \verb|set|
(see Sections~\ref{sec:hier_bld} and~\ref{sec:smooth_bld} for multi-level preconditioners).
(see Sections~\ref{sec:hier_bld} and~\ref{sec:smooth_bld} for multilevel preconditioners).
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
@@ -664,7 +663,7 @@ as follows:
\end{center}
\noindent
In this case, the routine can be used to build multi-level preconditioners too.
In this case, the routine can be used to build multilevel preconditioners too.
\clearpage
@@ -676,7 +675,7 @@ In this case, the routine can be used to build multi-level preconditioners too.
\noindent
This routine builds the hierarchy of matrices and restriction/prolongation
operators for the multi-level preconditioner \verb|p|, according to the requirements
operators for the multilevel preconditioner \verb|p|, according to the requirements
made by the user through the routines \verb|init| and \verb|set|.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
@@ -710,7 +709,7 @@ single/double precision version of MLD2P4 under use.
\noindent
This routine builds the smoothers and the coarsest-level solvers for the
multi-level preconditioner \verb|p|, according to the requirements made by
multilevel preconditioner \verb|p|, according to the requirements made by
the user through the routines \verb|init| and \verb|set|, and based on the aggregation
hierarchy produced by a previous call to \verb|hierarchy_build|
(see Section~\ref{sec:hier_bld}).