Minor changes in the user's and reference guide.

stopcriterion
Daniela di Serafino 7 years ago
parent 6dde52f6df
commit bbdf862a22

@ -1,11 +1,11 @@
\section*{Abstract} \section*{Abstract}
\addcontentsline{toc}{section}{Abstract} \addcontentsline{toc}{section}{Abstract}
\textsc{MLD2P4 (Multi-Level Domain Decomposition Parallel Preconditioners Package \textsc{MLD2P4 (MultiLevel Domain Decomposition Parallel Preconditioners Package
based on PSBLAS}) is a package of parallel algebraic multi-level preconditioners. based on PSBLAS}) is a package of parallel algebraic multilevel preconditioners.
The first release of MLD2P4 made available multi-level additive and hybrid Schwarz The first release of MLD2P4 made available multilevel additive and hybrid Schwarz
preconditioners, as well as one-level additive Schwarz preconditioners. The package 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 has been extended to include further multilevel cycles and smoothers widely used in
multigrid methods. In the multi-level case, a purely algebraic approach is applied to multigrid methods. In the multilevel case, a purely algebraic approach is applied to
generate coarse-level corrections, so that no geometric background is needed generate coarse-level corrections, so that no geometric background is needed
concerning the matrix to be preconditioned. The matrix is assumed to be square, concerning the matrix to be preconditioned. The matrix is assumed to be square,
real or complex. 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) in the context of the PSBLAS (Parallel Sparse Basic Linear Algebra Subprograms)
computational framework and can be used in conjuction with the Krylov solvers computational framework and can be used in conjuction with the Krylov solvers
available in this framework. MLD2P4 enables the user to easily specify different 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. for the ``best'' preconditioner for the problem at hand.
The package employs object-oriented design techniques in The package employs object-oriented design techniques in
Fortran~2003, with interfaces to additional third party libraries Fortran~2003, with interfaces to additional third party libraries
such as MUMPS, UMFPACK, SuperLU, and SuperLU\_Dist, which 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) implementation is based on a Single Program Multiple Data (SPMD)
paradigm; the inter-process communication is based on MPI and paradigm; the inter-process communication is based on MPI and
is managed mainly through PSBLAS. is managed mainly through PSBLAS.

@ -187,7 +187,7 @@ $$
P^k = S^k \bar{P}^k, P^k = S^k \bar{P}^k,
$$ $$
in order to remove nonsmooth components from the range of the prolongator, 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}. method~\cite{BREZINA_VANEK,Stuben_01}.
A simple choice for $S^k$ is the damped Jacobi smoother: A simple choice for $S^k$ is the damped Jacobi smoother:
\[ \[

@ -1,171 +1,171 @@
%\section{Bibliography\label{sec:bib}} %\section{Bibliography\label{sec:bib}}
\begin{thebibliography}{99} \begin{thebibliography}{99}
\addcontentsline{toc}{section}{\refname} \addcontentsline{toc}{section}{\refname}
\markboth{\textsc{MLD2P4 User's and Reference Guide}} \markboth{\textsc{MLD2P4 User's and Reference Guide}}
{\textsc{References}} {\textsc{References}}
%\let\refname\relax %\let\refname\relax
% %
\bibitem{MUMPS} \bibitem{MUMPS}
P.~R.~Amestoy, C.~Ashcraft, O.~Boiteau, A.~Buttari, J.~L'Excellent, C.~Weisbecker, P.~R.~Amestoy, C.~Ashcraft, O.~Boiteau, A.~Buttari, J.~L'Excellent, C.~Weisbecker,
{\em Improving multifrontal methods by means of block low-rank representations}, {\em Improving multifrontal methods by means of block low-rank representations},
SIAM Journal on Scientific Computing, volume 37 (3), 2015, A1452--A1474. SIAM Journal on Scientific Computing, volume 37 (3), 2015, A1452--A1474.
See also {\tt http://mumps.enseeiht.fr}. See also {\tt http://mumps.enseeiht.fr}.
% %
\bibitem{BREZINA_VANEK} \bibitem{BREZINA_VANEK}
M.~Brezina, P.~Van\v{e}k, M.~Brezina, P.~Van\v{e}k,
{\em A Black-Box Iterative Solver Based on a Two-Level Schwarz Method}, {\em A Black-Box Iterative Solver Based on a Two-Level Schwarz Method},
Computing, 63, 1999, 233--263. Computing, 63, 1999, 233--263.
% %
\bibitem{Briggs2000} \bibitem{Briggs2000}
W.~L.~Briggs, V.~E.~Henson, S.~F.~McCormick, W.~L.~Briggs, V.~E.~Henson, S.~F.~McCormick,
{\em A Multigrid Tutorial, Second Edition}, {\em A Multigrid Tutorial, Second Edition},
SIAM, 2000. SIAM, 2000.
% %
\bibitem{para_04} \bibitem{para_04}
A.~Buttari, P.~D'Ambra, D.~di Serafino, S.~Filippone, A.~Buttari, P.~D'Ambra, D.~di Serafino, S.~Filippone,
{\em Extending PSBLAS to Build Parallel Schwarz Preconditioners}, {\em Extending PSBLAS to Build Parallel Schwarz Preconditioners},
in J.~Dongarra, K.~Madsen, J.~Wasniewski, editors, in J.~Dongarra, K.~Madsen, J.~Wasniewski, editors,
Proceedings of PARA~04 Workshop on State of the Art Proceedings of PARA~04 Workshop on State of the Art
in Scientific Computing, Lecture Notes in Computer Science, in Scientific Computing, Lecture Notes in Computer Science,
Springer, 2005, 593--602. Springer, 2005, 593--602.
% %
\bibitem{aaecc_07} \bibitem{aaecc_07}
A.~Buttari, P.~D'Ambra, D.~di~Serafino, S.~Filippone, A.~Buttari, P.~D'Ambra, D.~di~Serafino, S.~Filippone,
{\em 2LEV-D2P4: a package of high-performance preconditioners {\em 2LEV-D2P4: a package of high-performance preconditioners
for scientific and engineering applications}, for scientific and engineering applications},
Applicable Algebra in Engineering, Communications and Computing, Applicable Algebra in Engineering, Communications and Computing,
18 (3) 2007, 223--239. 18 (3) 2007, 223--239.
%Published online: 13 February 2007, {\tt http://dx.doi.org/10.1007/s00200-007-0035-z} %Published online: 13 February 2007, {\tt http://dx.doi.org/10.1007/s00200-007-0035-z}
% %
\bibitem{CAI_SARKIS} \bibitem{CAI_SARKIS}
X.~C.~Cai, M.~Sarkis, X.~C.~Cai, M.~Sarkis,
{\em A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems}, {\em A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems},
SIAM Journal on Scientific Computing, 21 (2), 1999, 792--797. SIAM Journal on Scientific Computing, 21 (2), 1999, 792--797.
% %
%\bibitem{Cai_Widlund_92} %\bibitem{Cai_Widlund_92}
%X.~C.~Cai, O.~B.~Widlund, %X.~C.~Cai, O.~B.~Widlund,
%{\em Domain Decomposition Algorithms for Indefinite Elliptic Problems}, %{\em Domain Decomposition Algorithms for Indefinite Elliptic Problems},
%SIAM Journal on Scientific and Statistical Computing, 13 (1), 1992, 243--258. %SIAM Journal on Scientific and Statistical Computing, 13 (1), 1992, 243--258.
% %
%\bibitem{dd1_94} %\bibitem{dd1_94}
%T.~Chan and T.~Mathew, %T.~Chan and T.~Mathew,
%{\em Domain Decomposition Algorithms}, %{\em Domain Decomposition Algorithms},
%in A.~Iserles, editor, Acta Numerica 1994, 61--143. %in A.~Iserles, editor, Acta Numerica 1994, 61--143.
%Cambridge University Press. %Cambridge University Press.
% %
\bibitem{apnum_07} \bibitem{apnum_07}
P.~D'Ambra, S.~Filippone, D.~di~Serafino, P.~D'Ambra, S.~Filippone, D.~di~Serafino,
{\em On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners}, {\em On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners},
Applied Numerical Mathematics, Elsevier Science, Applied Numerical Mathematics, Elsevier Science,
57 (11-12), 2007, 1181-1196. 57 (11-12), 2007, 1181-1196.
%published online 3 February 2007, {\tt %published online 3 February 2007, {\tt
% http://dx.doi.org/10.1016/j.apnum.2007.01.006} % http://dx.doi.org/10.1016/j.apnum.2007.01.006}
% %
\bibitem{MLD2P4_TOMS} \bibitem{MLD2P4_TOMS}
P.~D'Ambra, D.~di~Serafino, S.~Filippone, P.~D'Ambra, D.~di~Serafino, S.~Filippone,
\emph{MLD2P4: a Package of Parallel Multilevel \emph{MLD2P4: a Package of Parallel Multilevel
Algebraic Domain Decomposition Preconditioners Algebraic Domain Decomposition Preconditioners
in Fortran 95}, ACM Trans. Math. Softw., 37(3), 2010, art. 30. in Fortran 95}, ACM Trans. Math. Softw., 37(3), 2010, art. 30.
% %
\bibitem{UMFPACK} \bibitem{UMFPACK}
T.~A.~Davis, T.~A.~Davis,
{\em Algorithm 832: UMFPACK - an Unsymmetric-pattern Multifrontal {\em Algorithm 832: UMFPACK - an Unsymmetric-pattern Multifrontal
Method with a Column Pre-ordering Strategy}, Method with a Column Pre-ordering Strategy},
ACM Transactions on Mathematical Software, 30, 2004, 196--199. 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} \bibitem{SUPERLU}
J.~W.~Demmel, S.~C.~Eisenstat, J.~R.~Gilbert, X.~S.~Li, J.~W.~H.~Liu, 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. SIAM Journal on Matrix Analysis and Applications, 20 (3), 1999, 720--755.
% %
\bibitem{blas3} \bibitem{blas3}
J.~J.~Dongarra, J.~Du Croz, I.~S.~Duff, S.~Hammarling, J.~J.~Dongarra, J.~Du Croz, I.~S.~Duff, S.~Hammarling,
\emph{A set of Level 3 Basic Linear Algebra Subprograms}, \emph{A set of Level 3 Basic Linear Algebra Subprograms},
ACM Transactions on Mathematical Software, 16 (1) 1990, 1--17. ACM Transactions on Mathematical Software, 16 (1) 1990, 1--17.
% %
\bibitem{blas2} \bibitem{blas2}
J.~J.~Dongarra, J.~Du Croz, S.~Hammarling, R.~J.~Hanson, J.~J.~Dongarra, J.~Du Croz, S.~Hammarling, R.~J.~Hanson,
\emph{An extended set of FORTRAN Basic Linear Algebra Subprograms}, \emph{An extended set of FORTRAN Basic Linear Algebra Subprograms},
ACM Transactions on Mathematical Software, 14 (1) 1988, 1--17. ACM Transactions on Mathematical Software, 14 (1) 1988, 1--17.
% %
%\bibitem{BLACS} %\bibitem{BLACS}
%J.~J.~Dongarra, R.~C.~Whaley, %J.~J.~Dongarra, R.~C.~Whaley,
%{\em A User's Guide to the BLACS v.~1.1}, %{\em A User's Guide to the BLACS v.~1.1},
%Lapack Working Note 94, Tech.\ Rep.\ UT-CS-95-281, University of %Lapack Working Note 94, Tech.\ Rep.\ UT-CS-95-281, University of
%Tennessee, March 1995 (updated May 1997). %Tennessee, March 1995 (updated May 1997).
% %
%\bibitem{EFSTATHIOU} %\bibitem{EFSTATHIOU}
%E.~Efstathiou, J.~G.~Gander, %E.~Efstathiou, J.~G.~Gander,
%{\em Why Restricted Additive Schwarz Converges Faster than Additive Schwarz}, %{\em Why Restricted Additive Schwarz Converges Faster than Additive Schwarz},
%BIT Numerical Mathematics, 43 (5), 2003, 945--959. %BIT Numerical Mathematics, 43 (5), 2003, 945--959.
% %
\bibitem{PSBLASGUIDE} \bibitem{PSBLASGUIDE}
S.~Filippone, A.~Buttari, S.~Filippone, A.~Buttari,
{\em PSBLAS-3.0 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library}, 2012, {\em PSBLAS 3.5.0 User's Guide. A Reference Guide for the Parallel Sparse BLAS Library}, 2012,
available from \texttt{http://www.ce.uniroma2.it/psblas/}. available from \texttt{https://github.com/sfilippone/psblas3/tree/master/docs}.
% %
\bibitem{PSBLAS3} \bibitem{PSBLAS3}
S.~Filippone, A.~Buttari, S.~Filippone, A.~Buttari,
{\em Object-Oriented Techniques for Sparse Matrix Computations in Fortran 2003}. {\em Object-Oriented Techniques for Sparse Matrix Computations in Fortran 2003}.
ACM Transactions on on Mathematical Software, 38 (4), 2012, art.~23. ACM Transactions on on Mathematical Software, 38 (4), 2012, art.~23.
% %
\bibitem{psblas_00} \bibitem{psblas_00}
S.~Filippone, M.~Colajanni, S.~Filippone, M.~Colajanni,
{\em PSBLAS: A Library for Parallel Linear Algebra {\em PSBLAS: A Library for Parallel Linear Algebra
Computation on Sparse Matrices}, Computation on Sparse Matrices},
ACM Transactions on Mathematical Software, 26 (4), 2000, 527--550. ACM Transactions on Mathematical Software, 26 (4), 2000, 527--550.
% %
\bibitem{MPI2} \bibitem{MPI2}
W.~Gropp, S.~Huss-Lederman, A.~Lumsdaine, E.~Lusk, B.~Nitzberg, W.~Saphir, M.~Snir, W.~Gropp, S.~Huss-Lederman, A.~Lumsdaine, E.~Lusk, B.~Nitzberg, W.~Saphir, M.~Snir,
{\em MPI: The Complete Reference. Volume 2 - The MPI-2 Extensions}, {\em MPI: The Complete Reference. Volume 2 - The MPI-2 Extensions},
MIT Press, 1998. MIT Press, 1998.
% %
\bibitem{blas1} \bibitem{blas1}
C.~L.~Lawson, R.~J.~Hanson, D.~Kincaid, F.~T.~Krogh, C.~L.~Lawson, R.~J.~Hanson, D.~Kincaid, F.~T.~Krogh,
\emph{Basic Linear Algebra Subprograms for FORTRAN usage}, \emph{Basic Linear Algebra Subprograms for FORTRAN usage},
ACM Transactions on Mathematical Software, 5 (3), 1979, 308--323. ACM Transactions on Mathematical Software, 5 (3), 1979, 308--323.
% %
\bibitem{SUPERLUDIST} \bibitem{SUPERLUDIST}
X.~S.~Li, J.~W.~Demmel, X.~S.~Li, J.~W.~Demmel,
{\em SuperLU\_DIST: A Scalable Distributed-memory {\em SuperLU\_DIST: A Scalable Distributed-memory
Sparse Direct Solver for Unsymmetric Linear Systems}, Sparse Direct Solver for Unsymmetric Linear Systems},
ACM Transactions on Mathematical Software, 29 (2), 2003, 110--140. ACM Transactions on Mathematical Software, 29 (2), 2003, 110--140.
% %
\bibitem{Notay2008} \bibitem{Notay2008}
Y.~Notay, P.~S.~Vassilevski, Y.~Notay, P.~S.~Vassilevski,
{\em Recursive Krylov-based multigrid cycles}, {\em Recursive Krylov-based multigrid cycles},
Numerical Linear Algebra with Applications, 15 (5), 2008, 473--487. Numerical Linear Algebra with Applications, 15 (5), 2008, 473--487.
% %
\bibitem{Saad_book} \bibitem{Saad_book}
Y.~Saad, Y.~Saad,
{\em Iterative methods for sparse linear systems}, 2nd edition, SIAM, 2003. {\em Iterative methods for sparse linear systems}, 2nd edition, SIAM, 2003.
% %
\bibitem{dd2_96} \bibitem{dd2_96}
B.~Smith, P.~Bjorstad, W.~Gropp, B.~Smith, P.~Bjorstad, W.~Gropp,
{\em Domain Decomposition: Parallel Multilevel Methods for Elliptic {\em Domain Decomposition: Parallel Multilevel Methods for Elliptic
Partial Differential Equations}, Partial Differential Equations},
Cambridge University Press, 1996. Cambridge University Press, 1996.
% %
\bibitem{MPI1} \bibitem{MPI1}
M.~Snir, S.~Otto, S.~Huss-Lederman, D.~Walker, J.~Dongarra, M.~Snir, S.~Otto, S.~Huss-Lederman, D.~Walker, J.~Dongarra,
{\em MPI: The Complete Reference. Volume 1 - The MPI Core}, second edition, {\em MPI: The Complete Reference. Volume 1 - The MPI Core}, second edition,
MIT Press, 1998. MIT Press, 1998.
% %
\bibitem{Stuben_01} \bibitem{Stuben_01}
K.~St\"{u}ben, K.~St\"{u}ben,
{\em An Introduction to Algebraic Multigrid}, {\em An Introduction to Algebraic Multigrid},
in A.~Sch\"{u}ller, U.~Trottenberg, C.~Oosterlee, Multigrid, in A.~Sch\"{u}ller, U.~Trottenberg, C.~Oosterlee, Multigrid,
Academic Press, 2001. Academic Press, 2001.
% %
\bibitem{TUMINARO_TONG} \bibitem{TUMINARO_TONG}
R.~S.~Tuminaro, C.~Tong, R.~S.~Tuminaro, C.~Tong,
{\em Parallel Smoothed Aggregation Multigrid: Aggregation Strategies on Massively Parallel Machines}, in J. Donnelley, editor, Proceedings of SuperComputing 2000, Dallas, 2000. {\em Parallel Smoothed Aggregation Multigrid: Aggregation Strategies on Massively Parallel Machines}, in J. Donnelley, editor, Proceedings of SuperComputing 2000, Dallas, 2000.
% %
\bibitem{VANEK_MANDEL_BREZINA} \bibitem{VANEK_MANDEL_BREZINA}
P.~Van\v{e}k, J.~Mandel, M.~Brezina, P.~Van\v{e}k, J.~Mandel, M.~Brezina,
{\em Algebraic Multigrid by Smoothed Aggregation for Second and Fourth Order Elliptic Problems}, {\em Algebraic Multigrid by Smoothed Aggregation for Second and Fourth Order Elliptic Problems},
Computing, 56 (3) 1996, 179--196. Computing, 56 (3) 1996, 179--196.
\end{thebibliography} \end{thebibliography}

@ -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 \item[MPI] \cite{MPI2,MPI1} A version of MPI is available on most
high-performance computing systems. high-performance computing systems.
\item[PSBLAS] \cite{PSBLASGUIDE,psblas_00} Parallel Sparse BLAS (PSBLAS) is \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 3.5.0 (or later) is required. Indeed, all the prerequisites
listed so far are also prerequisites of PSBLAS. listed so far are also prerequisites of PSBLAS.
\end{description} \end{description}
@ -62,7 +62,7 @@ compiler as MLD2P4.
We provide interfaces to the following third-party software libraries; We provide interfaces to the following third-party software libraries;
note that these are optional, but if you enable them some defaults 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} \begin{description}
\item[UMFPACK] \cite{UMFPACK} \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 Use these variables to override the choices made by `configure' or to help
it to find libraries and programs with nonstandard names/locations. 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} \end{verbatim}
For instance, if a user has built and installed PSBLAS 3.5 under the 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 \item[\tt examples] contains a set of simple example programs with a
predefined choice of preconditioners, selectable via integer predefined choice of preconditioners, selectable via integer
values. These are intended to get an acquaintance with the 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 \item[\tt tests] contains a set of more sophisticated examples that
will allow the user, via the input files in the \verb|runs| will allow the user, via the input files in the \verb|runs|
subdirectories, to experiment with the full range of preconditioners subdirectories, to experiment with the full range of preconditioners

@ -5,7 +5,7 @@
\noindent \noindent
MLD2P4 is available from the web site MLD2P4 is available from the web site
\begin{quotation} \begin{quotation}
\texttt{http://www.mld2p4.it} \texttt{https://github.com/sfilippone/mld2p4-2}
\end{quotation} \end{quotation}
where contact points for further information can be also found. where contact points for further information can be also found.

@ -2,7 +2,7 @@
\markboth{\textsc{MLD2P4 User's and Reference Guide}} \markboth{\textsc{MLD2P4 User's and Reference Guide}}
{\textsc{\ref{sec:started} Getting Started}} {\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}. (i.e., AMG) preconditioners with the Krylov solvers included in PSBLAS \cite{PSBLASGUIDE}.
The following steps are required: The following steps are required:
\begin{enumerate} \begin{enumerate}
@ -21,7 +21,7 @@ The following steps are required:
\verb|init| to identify the preconditioner types are also given. \verb|init| to identify the preconditioner types are also given.
Note that these strings are valid also if uppercase letters are substituted by Note that these strings are valid also if uppercase letters are substituted by
corresponding lowercase ones. 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 is performed by the routine \verb|mld_precset|.
% This routine must be called only if the user wants to modify the default values % This routine must be called only if the user wants to modify the default values
% of the parameters associated with the aggregation hierarchy construction. % 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 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}. 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 \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} \begin{enumerate}
\item[4.1] \emph{Build the aggregation hierarchy for a given matrix.} This is \item[4.1] \emph{Build the aggregation hierarchy for a given matrix.} This is
performed by the routine \verb|hierarchy_build|. performed by the routine \verb|hierarchy_build|.
@ -116,7 +116,7 @@ on parallel computers.
\subsection{Examples\label{sec:examples}} \subsection{Examples\label{sec:examples}}
The code reported in Figure~\ref{fig:ex1} shows how to set and apply the default 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 of MLD2P4 (see Table~\ref{tab:precinit}). This preconditioner is chosen
by simply specifying \verb|'ML'| as the second argument of \verb|P%init| 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 (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 For details on the use of the PSBLAS routines, see the PSBLAS User's
Guide~\cite{PSBLASGUIDE}. 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 for the real single precision and the complex, single and double
precision, versions are obtained with straightforward modifications of the previous precision, versions are obtained with straightforward modifications of the previous
example (see Section~\ref{sec:userinterface} for details). If these versions are installed, 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 ! 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 ! with basic smoothed aggregation, 1 hybrid forward/backward
! GS sweep as pre/post-smoother and UMFPACK as coarsest-level ! GS sweep as pre/post-smoother and UMFPACK as coarsest-level
! solver ! solver
@ -202,12 +202,12 @@ the corresponding codes are available in \verb|examples/fileread/|.
\end{verbatim} \end{verbatim}
} }
\end{minipage} \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}} \label{fig:ex1}}
\end{center} \end{center}
\end{figure} \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 the default values of the preconditioner parameters. The code reported in
Figure~\ref{fig:ex2} shows how to set a V-cycle preconditioner Figure~\ref{fig:ex2} shows how to set a V-cycle preconditioner
which applies 1 block-Jacobi sweep as pre- and post-smoother, 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} \end{minipage}
\caption{setup of a multi-level preconditioner\label{fig:ex2}} \caption{setup of a multilevel preconditioner\label{fig:ex2}}
\end{center} \end{center}
\end{figure} \end{figure}
@ -297,7 +297,7 @@ boundary conditions are also available in the directory \verb|examples/pdegen|.
\end{verbatim} \end{verbatim}
} }
\end{minipage} \end{minipage}
\caption{setup of a multi-level preconditioner\label{fig:ex3}} \caption{setup of a multilevel preconditioner\label{fig:ex3}}
\end{center} \end{center}
\end{figure} \end{figure}

@ -5,13 +5,12 @@
The MLD2P4 is freely distributable under the following copyright The MLD2P4 is freely distributable under the following copyright
terms: {\small terms: {\small
\begin{verbatim} \begin{verbatim}
MLD2P4 version 2.1 MLD2P4 version 2.1
MultiLevel Domain Decomposition Parallel Preconditioners Package 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 Salvatore Filippone Cranfield University, Cranfield, UK
Pasqua D'Ambra IAC-CNR, Naples, IT Pasqua D'Ambra IAC-CNR, Naples, IT

@ -2,7 +2,7 @@
\markboth{\textsc{MLD2P4 User's and Reference Guide}} \markboth{\textsc{MLD2P4 User's and Reference Guide}}
{\textsc{\ref{sec:overview} General Overview}} {\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 PSBLAS (MLD2P4}) provides parallel Algebraic MultiGrid (AMG) and Domain
Decomposition preconditioners (see, e.g., \cite{Briggs2000,Stuben_01,dd2_96}), Decomposition preconditioners (see, e.g., \cite{Briggs2000,Stuben_01,dd2_96}),
to be used in the iterative solution of linear systems, 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.} %adeguato e fare qualcosa di consistente anche con 1-lev Schwarz.}
% %
The name of the package comes from its original implementation, containing 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 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 AMG cycles with smoothers and coarsest-level solvers. The V-, W-, and
K-cycles~\cite{Briggs2000,Notay2008} are available, which allow to define K-cycles~\cite{Briggs2000,Notay2008} are available, which allow to define
almost all the preconditioners in the package, including the multi-level hybrid almost all the preconditioners in the package, including the multilevel hybrid
Schwarz ones; a specific cycle is implemented to obtain multi-level additive Schwarz ones; a specific cycle is implemented to obtain multilevel additive
Schwarz preconditioners. The Jacobi, hybrid Schwarz preconditioners. The Jacobi, hybrid
%\footnote{see Note 2 in Table~\ref{tab:p_coarse}, p.~28.} %\footnote{see Note 2 in Table~\ref{tab:p_coarse}, p.~28.}
forward/backward Gauss-Seidel, block-Jacobi, and additive Schwarz methods 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}). Section~\ref{sec:adding}).
We note that the user interface of MLD2P4 2.1 has been extended with respect to the 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 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 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. evolved too, in order to fully exploit the Fortran~2003 features implemented in PSBLAS 3.

@ -104,7 +104,7 @@
{\Huge\bfseries MLD2P4\\[.8ex] User's and Reference Guide {\Huge\bfseries MLD2P4\\[.8ex] User's and Reference Guide
} }
\noindent\rule[-1ex]{\textwidth}{5pt}\\[2.5ex] \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 Parallel Preconditioners Package
based on PSBLAS} based on PSBLAS}
\end{minipage}} \end{minipage}}

@ -91,7 +91,7 @@
\begin{document} \begin{document}
{\LARGE\bfseries MLD2P4\\[.8ex] User's and Reference Guide}\\[\baselineskip] {\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 Parallel Preconditioners Package
based on PSBLAS}\\[3ex] based on PSBLAS}\\[3ex]
{\large\bfseries Pasqua D'Ambra}\\ {\large\bfseries Pasqua D'Ambra}\\

@ -6,7 +6,7 @@ The basic user interface of MLD2P4 consists of eight routines. The six
routines \verb|init|, \verb|set|, routines \verb|init|, \verb|set|,
\verb|hierarchy_build|, \verb|smoothers_build|, \verb|hierarchy_build|, \verb|smoothers_build|,
\verb|bld|, and \verb|apply| encapsulate all the \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. preconditioner implemented in the package.
The routine \verb|free| deallocates the preconditioner data structure, while The routine \verb|free| deallocates the preconditioner data structure, while
\verb|descr| prints a description of the preconditioner setup by the user. \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)|.\\ \verb|info| & \verb|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\ & Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
%\verb|nlev| & \verb|integer, optional, intent(in)|.\\ %\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, % preconditioner. This optional argument is deprecated,
% new codes should set the number of levels with \verb|mld_precset|.\\ % 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'|, % 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} & Error code. If no error, 0 is returned. See Section~\ref{sec:errors}
for details.\\ for details.\\
\verb|ilev| & \verb|integer, optional, intent(in)|.\\ \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. preconditioner parameter has to be set.
The levels are numbered in increasing The levels are numbered in increasing
order starting from the finest one, i.e., level 1 is the finest level. 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 is set at all the appropriate levels (see
Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}).\\ Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}).\\
\verb|ilmax| & \verb|integer, optional, intent(in)|.\\ \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 \verb|ilev| and \verb|ilmax| are present, the settings
are applied at all levels \verb|ilev:ilmax|. When are applied at all levels \verb|ilev:ilmax|. When
\verb|ilev| is present but \verb|ilmax| is not, then \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 by a suitable setting of the preconditioner parameters. These parameters
can be logically divided into four groups, i.e., parameters defining can be logically divided into four groups, i.e., parameters defining
\begin{enumerate} \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 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); 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. preconditioner.
\end{enumerate} \end{enumerate}
@ -237,20 +237,20 @@ solver is changed to the default sequential solver.
\hline \hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} & \verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\textsc{comments} \\ \hline \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|mld_ml_cycle_| \par
\verb|'ML_CYCLE'| & \verb|character(len=*)| \verb|'ML_CYCLE'| & \verb|character(len=*)|
& \texttt{'VCYCLE'} \par \texttt{'WCYCLE'} \par \texttt{'KCYCLE'} \par & \texttt{'VCYCLE'} \par \texttt{'WCYCLE'} \par \texttt{'KCYCLE'} \par
\texttt{'MULT'} \par \texttt{'ADD'} \texttt{'MULT'} \par \texttt{'ADD'}
& \texttt{'VCYCLE'} & \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 and Additive Schwarz. \par
Note that hybrid Multiplicative Schwarz is equivalent to V-cycle and Note that hybrid Multiplicative Schwarz is equivalent to V-cycle and
is included for compatibility with previous versions of MLD2P4. \\ \hline is included for compatibility with previous versions of MLD2P4. \\ \hline
%\verb|mld_outer_sweeps_| \par %\verb|mld_outer_sweeps_| \par
\verb|'OUTER_SWEEPS'| & \texttt{integer} & \verb|'OUTER_SWEEPS'| & \texttt{integer} &
Any integer \par number $\ge 1$ & 1 & 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=*)| %\verb|mld_smoother_type_| \par \verb|SMOOTHER_TYPE| & \verb|character(len=*)|
% & \texttt{'JACOBI'} \ \ \ \texttt{'BJAC'} \ \ \ \texttt{'AS'} % & \texttt{'JACOBI'} \ \ \ \texttt{'BJAC'} \ \ \ \texttt{'AS'}
% & \texttt{'AS'} % & \texttt{'AS'}
@ -264,7 +264,7 @@ solver is changed to the default sequential solver.
%\hline %\hline
\end{tabular} \end{tabular}
\end{center} \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. be applied.
\label{tab:p_cycle}} \label{tab:p_cycle}}
\esideways \esideways
@ -448,12 +448,11 @@ the parameter \texttt{ilev}.} \\
Note that \texttt{UMF} and \texttt{SLU} require the coarsest Note that \texttt{UMF} and \texttt{SLU} require the coarsest
matrix to be replicated, \texttt{SLUDIST}, \texttt{JACOBI}, matrix to be replicated, \texttt{SLUDIST}, \texttt{JACOBI},
\texttt{GS} and \texttt{BJAC} require it to be \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 a replicated or a distributed matrix. When any of the previous
solvers is specified, the matrix layout is set to a default solvers is specified, the matrix layout is set to a default
value value which allows the use of the solver (see Remark 3, p.~24).
which allows the use Note also that UMFPACK and SuperLU\_Dist
value UMFPACK and SuperLU\_Dist
are available only in double precision. \\ \hline are available only in double precision. \\ \hline
%\verb|mld_coarse_subsolve_| \par %\verb|mld_coarse_subsolve_| \par
\verb|'COARSE_SUBSOLVE'| & \verb|character(len=*)| \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'| & \verb|'JACOBI'| \par \verb|'GS'| \par \verb|'BGS'| \par \verb|'BJAC'|
\par \verb|'AS'| \par \verb|'AS'|
& \verb|'FBGS'| & \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, point-Jacobi, hybrid (forward) Gauss-Seidel,
hybrid backward Gauss-Seidel, block-Jacobi, and hybrid backward Gauss-Seidel, block-Jacobi, and
Additive Schwarz. \par Additive Schwarz. \par
@ -539,7 +538,7 @@ level (continued).\label{tab:p_coarse_1}}
\texttt{'ILUT'} \par \texttt{'MILU'} \par \texttt{'ILUT'} \par \texttt{'MILU'} \par
\par \texttt{'MUMPS'} \par \texttt{'SLU'} \par \texttt{'UMF'} \par \texttt{'MUMPS'} \par \texttt{'SLU'} \par \texttt{'UMF'}
& \texttt{GS} and \texttt{BGS} for pre- and post-smoothers & \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 \texttt{ILU} for block-Jacobi and Additive Schwarz
one-level preconditioners one-level preconditioners
& The local solver to be used with the smoother or one-level & 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$ & Any integer \par number~$\ge 0$
& 1 & 1
& Number of sweeps of the smoother or one-level preconditioner. & 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 post-smoother is used if this parameter is set to 0
together with \verb|pos='PRE'| or \verb|pos='POST|, together with \verb|pos='PRE'| or \verb|pos='POST|,
respectively. \\ \hline respectively. \\ \hline
@ -635,7 +634,7 @@ level (continued).\label{tab:p_coarse_1}}
\noindent \noindent
This routine builds the one-level preconditioner \verb|p| according to the requirements 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| 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 {\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
@ -664,7 +663,7 @@ as follows:
\end{center} \end{center}
\noindent \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 \clearpage
@ -676,7 +675,7 @@ In this case, the routine can be used to build multi-level preconditioners too.
\noindent \noindent
This routine builds the hierarchy of matrices and restriction/prolongation 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|. made by the user through the routines \verb|init| and \verb|set|.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip {\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
@ -710,7 +709,7 @@ single/double precision version of MLD2P4 under use.
\noindent \noindent
This routine builds the smoothers and the coarsest-level solvers for the 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 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| hierarchy produced by a previous call to \verb|hierarchy_build|
(see Section~\ref{sec:hier_bld}). (see Section~\ref{sec:hier_bld}).

Loading…
Cancel
Save