diff --git a/docs/src/abstract.tex b/docs/src/abstract.tex index 21c59e93..ac02a732 100644 --- a/docs/src/abstract.tex +++ b/docs/src/abstract.tex @@ -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. diff --git a/docs/src/background.tex b/docs/src/background.tex index f86b0348..677f8720 100644 --- a/docs/src/background.tex +++ b/docs/src/background.tex @@ -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: \[ diff --git a/docs/src/bibliography.tex b/docs/src/bibliography.tex index 98305063..e935635a 100644 --- a/docs/src/bibliography.tex +++ b/docs/src/bibliography.tex @@ -1,171 +1,171 @@ -%\section{Bibliography\label{sec:bib}} -\begin{thebibliography}{99} -\addcontentsline{toc}{section}{\refname} -\markboth{\textsc{MLD2P4 User's and Reference Guide}} - {\textsc{References}} - -%\let\refname\relax -% -\bibitem{MUMPS} -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}, -SIAM Journal on Scientific Computing, volume 37 (3), 2015, A1452--A1474. -See also {\tt http://mumps.enseeiht.fr}. -% -\bibitem{BREZINA_VANEK} -M.~Brezina, P.~Van\v{e}k, -{\em A Black-Box Iterative Solver Based on a Two-Level Schwarz Method}, -Computing, 63, 1999, 233--263. -% -\bibitem{Briggs2000} -W.~L.~Briggs, V.~E.~Henson, S.~F.~McCormick, -{\em A Multigrid Tutorial, Second Edition}, -SIAM, 2000. -% -\bibitem{para_04} -A.~Buttari, P.~D'Ambra, D.~di Serafino, S.~Filippone, -{\em Extending PSBLAS to Build Parallel Schwarz Preconditioners}, -in J.~Dongarra, K.~Madsen, J.~Wasniewski, editors, -Proceedings of PARA~04 Workshop on State of the Art -in Scientific Computing, Lecture Notes in Computer Science, -Springer, 2005, 593--602. -% -\bibitem{aaecc_07} -A.~Buttari, P.~D'Ambra, D.~di~Serafino, S.~Filippone, -{\em 2LEV-D2P4: a package of high-performance preconditioners -for scientific and engineering applications}, -Applicable Algebra in Engineering, Communications and Computing, -18 (3) 2007, 223--239. -%Published online: 13 February 2007, {\tt http://dx.doi.org/10.1007/s00200-007-0035-z} -% -\bibitem{CAI_SARKIS} -X.~C.~Cai, M.~Sarkis, -{\em A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems}, -SIAM Journal on Scientific Computing, 21 (2), 1999, 792--797. -% -%\bibitem{Cai_Widlund_92} -%X.~C.~Cai, O.~B.~Widlund, -%{\em Domain Decomposition Algorithms for Indefinite Elliptic Problems}, -%SIAM Journal on Scientific and Statistical Computing, 13 (1), 1992, 243--258. -% -%\bibitem{dd1_94} -%T.~Chan and T.~Mathew, -%{\em Domain Decomposition Algorithms}, -%in A.~Iserles, editor, Acta Numerica 1994, 61--143. -%Cambridge University Press. -% -\bibitem{apnum_07} -P.~D'Ambra, S.~Filippone, D.~di~Serafino, -{\em On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners}, -Applied Numerical Mathematics, Elsevier Science, -57 (11-12), 2007, 1181-1196. -%published online 3 February 2007, {\tt -% http://dx.doi.org/10.1016/j.apnum.2007.01.006} -% -\bibitem{MLD2P4_TOMS} -P.~D'Ambra, D.~di~Serafino, S.~Filippone, -\emph{MLD2P4: a Package of Parallel Multilevel -Algebraic Domain Decomposition Preconditioners -in Fortran 95}, ACM Trans. Math. Softw., 37(3), 2010, art. 30. -% -\bibitem{UMFPACK} -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/}) -% -\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, -SIAM Journal on Matrix Analysis and Applications, 20 (3), 1999, 720--755. -% -\bibitem{blas3} -J.~J.~Dongarra, J.~Du Croz, I.~S.~Duff, S.~Hammarling, -\emph{A set of Level 3 Basic Linear Algebra Subprograms}, -ACM Transactions on Mathematical Software, 16 (1) 1990, 1--17. -% -\bibitem{blas2} -J.~J.~Dongarra, J.~Du Croz, S.~Hammarling, R.~J.~Hanson, -\emph{An extended set of FORTRAN Basic Linear Algebra Subprograms}, -ACM Transactions on Mathematical Software, 14 (1) 1988, 1--17. -% -%\bibitem{BLACS} -%J.~J.~Dongarra, R.~C.~Whaley, -%{\em A User's Guide to the BLACS v.~1.1}, -%Lapack Working Note 94, Tech.\ Rep.\ UT-CS-95-281, University of -%Tennessee, March 1995 (updated May 1997). -% -%\bibitem{EFSTATHIOU} -%E.~Efstathiou, J.~G.~Gander, -%{\em Why Restricted Additive Schwarz Converges Faster than Additive Schwarz}, -%BIT Numerical Mathematics, 43 (5), 2003, 945--959. -% -\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/}. -% -\bibitem{PSBLAS3} -S.~Filippone, A.~Buttari, -{\em Object-Oriented Techniques for Sparse Matrix Computations in Fortran 2003}. -ACM Transactions on on Mathematical Software, 38 (4), 2012, art.~23. -% -\bibitem{psblas_00} -S.~Filippone, M.~Colajanni, -{\em PSBLAS: A Library for Parallel Linear Algebra -Computation on Sparse Matrices}, -ACM Transactions on Mathematical Software, 26 (4), 2000, 527--550. -% -\bibitem{MPI2} -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}, -MIT Press, 1998. -% -\bibitem{blas1} -C.~L.~Lawson, R.~J.~Hanson, D.~Kincaid, F.~T.~Krogh, -\emph{Basic Linear Algebra Subprograms for FORTRAN usage}, -ACM Transactions on Mathematical Software, 5 (3), 1979, 308--323. -% -\bibitem{SUPERLUDIST} -X.~S.~Li, J.~W.~Demmel, -{\em SuperLU\_DIST: A Scalable Distributed-memory -Sparse Direct Solver for Unsymmetric Linear Systems}, -ACM Transactions on Mathematical Software, 29 (2), 2003, 110--140. -% -\bibitem{Notay2008} -Y.~Notay, P.~S.~Vassilevski, -{\em Recursive Krylov-based multigrid cycles}, -Numerical Linear Algebra with Applications, 15 (5), 2008, 473--487. -% -\bibitem{Saad_book} -Y.~Saad, -{\em Iterative methods for sparse linear systems}, 2nd edition, SIAM, 2003. -% -\bibitem{dd2_96} -B.~Smith, P.~Bjorstad, W.~Gropp, -{\em Domain Decomposition: Parallel Multilevel Methods for Elliptic -Partial Differential Equations}, -Cambridge University Press, 1996. -% -\bibitem{MPI1} -M.~Snir, S.~Otto, S.~Huss-Lederman, D.~Walker, J.~Dongarra, -{\em MPI: The Complete Reference. Volume 1 - The MPI Core}, second edition, -MIT Press, 1998. -% -\bibitem{Stuben_01} -K.~St\"{u}ben, -{\em An Introduction to Algebraic Multigrid}, -in A.~Sch\"{u}ller, U.~Trottenberg, C.~Oosterlee, Multigrid, -Academic Press, 2001. -% -\bibitem{TUMINARO_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. -% -\bibitem{VANEK_MANDEL_BREZINA} -P.~Van\v{e}k, J.~Mandel, M.~Brezina, -{\em Algebraic Multigrid by Smoothed Aggregation for Second and Fourth Order Elliptic Problems}, -Computing, 56 (3) 1996, 179--196. - -\end{thebibliography} +%\section{Bibliography\label{sec:bib}} +\begin{thebibliography}{99} +\addcontentsline{toc}{section}{\refname} +\markboth{\textsc{MLD2P4 User's and Reference Guide}} + {\textsc{References}} + +%\let\refname\relax +% +\bibitem{MUMPS} +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}, +SIAM Journal on Scientific Computing, volume 37 (3), 2015, A1452--A1474. +See also {\tt http://mumps.enseeiht.fr}. +% +\bibitem{BREZINA_VANEK} +M.~Brezina, P.~Van\v{e}k, +{\em A Black-Box Iterative Solver Based on a Two-Level Schwarz Method}, +Computing, 63, 1999, 233--263. +% +\bibitem{Briggs2000} +W.~L.~Briggs, V.~E.~Henson, S.~F.~McCormick, +{\em A Multigrid Tutorial, Second Edition}, +SIAM, 2000. +% +\bibitem{para_04} +A.~Buttari, P.~D'Ambra, D.~di Serafino, S.~Filippone, +{\em Extending PSBLAS to Build Parallel Schwarz Preconditioners}, +in J.~Dongarra, K.~Madsen, J.~Wasniewski, editors, +Proceedings of PARA~04 Workshop on State of the Art +in Scientific Computing, Lecture Notes in Computer Science, +Springer, 2005, 593--602. +% +\bibitem{aaecc_07} +A.~Buttari, P.~D'Ambra, D.~di~Serafino, S.~Filippone, +{\em 2LEV-D2P4: a package of high-performance preconditioners +for scientific and engineering applications}, +Applicable Algebra in Engineering, Communications and Computing, +18 (3) 2007, 223--239. +%Published online: 13 February 2007, {\tt http://dx.doi.org/10.1007/s00200-007-0035-z} +% +\bibitem{CAI_SARKIS} +X.~C.~Cai, M.~Sarkis, +{\em A Restricted Additive Schwarz Preconditioner for General Sparse Linear Systems}, +SIAM Journal on Scientific Computing, 21 (2), 1999, 792--797. +% +%\bibitem{Cai_Widlund_92} +%X.~C.~Cai, O.~B.~Widlund, +%{\em Domain Decomposition Algorithms for Indefinite Elliptic Problems}, +%SIAM Journal on Scientific and Statistical Computing, 13 (1), 1992, 243--258. +% +%\bibitem{dd1_94} +%T.~Chan and T.~Mathew, +%{\em Domain Decomposition Algorithms}, +%in A.~Iserles, editor, Acta Numerica 1994, 61--143. +%Cambridge University Press. +% +\bibitem{apnum_07} +P.~D'Ambra, S.~Filippone, D.~di~Serafino, +{\em On the Development of PSBLAS-based Parallel Two-level Schwarz Preconditioners}, +Applied Numerical Mathematics, Elsevier Science, +57 (11-12), 2007, 1181-1196. +%published online 3 February 2007, {\tt +% http://dx.doi.org/10.1016/j.apnum.2007.01.006} +% +\bibitem{MLD2P4_TOMS} +P.~D'Ambra, D.~di~Serafino, S.~Filippone, +\emph{MLD2P4: a Package of Parallel Multilevel +Algebraic Domain Decomposition Preconditioners +in Fortran 95}, ACM Trans. Math. Softw., 37(3), 2010, art. 30. +% +\bibitem{UMFPACK} +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 \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, +{\em A supernodal approach to sparse partial pivoting}, +SIAM Journal on Matrix Analysis and Applications, 20 (3), 1999, 720--755. +% +\bibitem{blas3} +J.~J.~Dongarra, J.~Du Croz, I.~S.~Duff, S.~Hammarling, +\emph{A set of Level 3 Basic Linear Algebra Subprograms}, +ACM Transactions on Mathematical Software, 16 (1) 1990, 1--17. +% +\bibitem{blas2} +J.~J.~Dongarra, J.~Du Croz, S.~Hammarling, R.~J.~Hanson, +\emph{An extended set of FORTRAN Basic Linear Algebra Subprograms}, +ACM Transactions on Mathematical Software, 14 (1) 1988, 1--17. +% +%\bibitem{BLACS} +%J.~J.~Dongarra, R.~C.~Whaley, +%{\em A User's Guide to the BLACS v.~1.1}, +%Lapack Working Note 94, Tech.\ Rep.\ UT-CS-95-281, University of +%Tennessee, March 1995 (updated May 1997). +% +%\bibitem{EFSTATHIOU} +%E.~Efstathiou, J.~G.~Gander, +%{\em Why Restricted Additive Schwarz Converges Faster than Additive Schwarz}, +%BIT Numerical Mathematics, 43 (5), 2003, 945--959. +% +\bibitem{PSBLASGUIDE} +S.~Filippone, A.~Buttari, +{\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, +{\em Object-Oriented Techniques for Sparse Matrix Computations in Fortran 2003}. +ACM Transactions on on Mathematical Software, 38 (4), 2012, art.~23. +% +\bibitem{psblas_00} +S.~Filippone, M.~Colajanni, +{\em PSBLAS: A Library for Parallel Linear Algebra +Computation on Sparse Matrices}, +ACM Transactions on Mathematical Software, 26 (4), 2000, 527--550. +% +\bibitem{MPI2} +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}, +MIT Press, 1998. +% +\bibitem{blas1} +C.~L.~Lawson, R.~J.~Hanson, D.~Kincaid, F.~T.~Krogh, +\emph{Basic Linear Algebra Subprograms for FORTRAN usage}, +ACM Transactions on Mathematical Software, 5 (3), 1979, 308--323. +% +\bibitem{SUPERLUDIST} +X.~S.~Li, J.~W.~Demmel, +{\em SuperLU\_DIST: A Scalable Distributed-memory +Sparse Direct Solver for Unsymmetric Linear Systems}, +ACM Transactions on Mathematical Software, 29 (2), 2003, 110--140. +% +\bibitem{Notay2008} +Y.~Notay, P.~S.~Vassilevski, +{\em Recursive Krylov-based multigrid cycles}, +Numerical Linear Algebra with Applications, 15 (5), 2008, 473--487. +% +\bibitem{Saad_book} +Y.~Saad, +{\em Iterative methods for sparse linear systems}, 2nd edition, SIAM, 2003. +% +\bibitem{dd2_96} +B.~Smith, P.~Bjorstad, W.~Gropp, +{\em Domain Decomposition: Parallel Multilevel Methods for Elliptic +Partial Differential Equations}, +Cambridge University Press, 1996. +% +\bibitem{MPI1} +M.~Snir, S.~Otto, S.~Huss-Lederman, D.~Walker, J.~Dongarra, +{\em MPI: The Complete Reference. Volume 1 - The MPI Core}, second edition, +MIT Press, 1998. +% +\bibitem{Stuben_01} +K.~St\"{u}ben, +{\em An Introduction to Algebraic Multigrid}, +in A.~Sch\"{u}ller, U.~Trottenberg, C.~Oosterlee, Multigrid, +Academic Press, 2001. +% +\bibitem{TUMINARO_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. +% +\bibitem{VANEK_MANDEL_BREZINA} +P.~Van\v{e}k, J.~Mandel, M.~Brezina, +{\em Algebraic Multigrid by Smoothed Aggregation for Second and Fourth Order Elliptic Problems}, +Computing, 56 (3) 1996, 179--196. + +\end{thebibliography} diff --git a/docs/src/building.tex b/docs/src/building.tex index f1fb3b57..c909d512 100644 --- a/docs/src/building.tex +++ b/docs/src/building.tex @@ -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 . +Report bugs to . \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 diff --git a/docs/src/distribution.tex b/docs/src/distribution.tex index d6ef8187..5682acfe 100644 --- a/docs/src/distribution.tex +++ b/docs/src/distribution.tex @@ -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. diff --git a/docs/src/gettingstarted.tex b/docs/src/gettingstarted.tex index 6644ae1a..ce1d6d72 100644 --- a/docs/src/gettingstarted.tex +++ b/docs/src/gettingstarted.tex @@ -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} diff --git a/docs/src/license.tex b/docs/src/license.tex index 8f76d67c..f298af02 100644 --- a/docs/src/license.tex +++ b/docs/src/license.tex @@ -5,13 +5,12 @@ 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 diff --git a/docs/src/overview.tex b/docs/src/overview.tex index 6c88056f..1c142973 100644 --- a/docs/src/overview.tex +++ b/docs/src/overview.tex @@ -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. diff --git a/docs/src/userguide.tex b/docs/src/userguide.tex index afb6f49e..7584dd9e 100644 --- a/docs/src/userguide.tex +++ b/docs/src/userguide.tex @@ -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}} diff --git a/docs/src/userhtml.tex b/docs/src/userhtml.tex index cf125309..5a979980 100644 --- a/docs/src/userhtml.tex +++ b/docs/src/userhtml.tex @@ -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}\\ diff --git a/docs/src/userinterface.tex b/docs/src/userinterface.tex index fad93c0a..deea81f1 100644 --- a/docs/src/userinterface.tex +++ b/docs/src/userinterface.tex @@ -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 + solvers is specified, the matrix layout is set to a default + 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}).