Updated descriptions

docs/src/bibliography.tex

@@ -76,7 +76,7 @@ for Scientific and Engineering Applications}, Appl. Algebra Engrg. Comm. Comput.
 %
 \bibitem{DDF2020}
 P.~D'Ambra, F~Durastante, S.~Filippone, 
-\emph{AMG preconditioners for Linear Solvers towards Extreme Scale}, 2020, arXiv:2006.16147v2.
+\emph{AMG preconditioners for Linear Solvers towards Extreme Scale}, 2020, \href{https://arxiv.org/abs/2006.16147v3arXiv:2006.16147v2}{arXiv:2006.16147v3}.
 %
 \bibitem{UMFPACK}
 T.~A.~Davis,

docs/src/building.tex

@@ -32,9 +32,9 @@ The following base libraries are needed:
 \item[BLAS] \cite{blas3,blas2,blas1} Many vendors provide optimized versions
   of BLAS; if no vendor version is
   available for a given platform, the ATLAS software
-  (\url{math-atlas.sourceforge.net})
+  (\href{http://math-atlas.sourceforge.net}{math-atlas.sourceforge.net})
   may be employed.  The reference BLAS from Netlib
-  (\url{www.netlib.org/blas}) are meant to define the standard
+  (\href{http://www.netlib.org/blas}{www.netlib.org/blas}) are meant to define the standard
   behaviour of the BLAS interface, so they are not optimized for any
   particular platform, and should only be used as a last
   resort. Note that BLAS computations form a relatively small part of
@@ -43,14 +43,14 @@ The following base libraries are needed:
   libraries. Note that UMFPACK requires a full LAPACK library; our
 experience is that configuring ATLAS for building full LAPACK does not
 work in the correct way. Our advice is first to download the LAPACK tarfile from
-\url{www.netlib.org/lapack} and install it independently of ATLAS. In this case,
+\href{http://www.netlib.org/lapack}{www.netlib.org/lapack} and install it independently of ATLAS. In this case,
 you need to modify the OPTS and NOOPT definitions for including -fPIC compilation option
 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{github.com/sfilippone/psblas3} ?? {\bf Mettere tutto sotto psctoolkit}; version
+  available from \href{https://psctoolkit.github.io/products/psblas/}{psctoolkit.github.io/products/psblas/}; version
-  3.5.0  (or later) is required. Indeed, all the prerequisites
+  3.7.0  (or later) is required. Indeed, all the prerequisites
   listed so far are also prerequisites of PSBLAS.
 \end{description}
 Please note that the four previous libraries must have Fortran
@@ -102,7 +102,7 @@ in the main directory to generate the necessary makefile.
 %\textbf{Sono necessarie le parentesi intorno a s?}
 
 
-\bf{DA RISCRIVERE}
+\textbf{DA RISCRIVERE}
 
 As a minimal example consider the following:
 \begin{verbatim}
@@ -280,7 +280,7 @@ it to find libraries and programs with nonstandard names/locations.
 Report bugs to <https://github.com/sfilippone/mld2p4-2/issues>.
 \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.7 under the
 \verb|/opt| directory and is
 using the SuiteSparse package (which includes UMFPACK), then MLD2P4
 might be configured with:

docs/src/distribution.tex

@@ -5,7 +5,7 @@
 \noindent
 AMG4PSBLAS is available from the web site
 \begin{quotation}
-\texttt{https://github.com/psctoolkit/amg4psblas}
+\href{https://psctoolkit.github.io/products/amg4psblas/}{https://psctoolkit.github.io/products/amg4psblas/}
 \end{quotation}
 where contact points for further information can be also found.
 

docs/src/gettingstarted.tex

@@ -33,7 +33,7 @@ The following steps are required:
 \item \emph{Build the preconditioner for a given matrix}. If the selected preconditioner
  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
+\item[4.1] \emph{Build the AMG hierarchy for a given matrix.} This is
 performed by the routine \verb|hierarchy_build|.
 \item[4.2] \emph{Build the preconditioner for a given matrix.} This is performed
 by the routine \verb|smoothers_build|.
@@ -56,26 +56,26 @@ Examples showing the basic use of AMG4PSBLAS are reported in Section~\ref{sec:ex
 \begin{table}[h!]
 \begin{center}
 %{\small
-\begin{tabular}{|l|p{1.8cm}|p{8.2cm}|}
+\begin{tabular}{|l|p{2cm}|p{8cm}|}
 \hline
 \textsc{type}       & \textsc{string} & \textsc{default preconditioner} \\ \hline
 No preconditioner &\verb|'NONE'|& Considered  to use the PSBLAS
                                     Krylov solvers with no preconditioner. \\ \hline
-Diagonal          & \verb|'DIAG'| or \verb|'JACOBI'| & Diagonal preconditioner.
+Diagonal          & \verb|'DIAG'|, \verb|'JACOBI'|, \verb|'L1-JACOBI'| & Diagonal preconditioner.
                          For any zero diagonal entry of the matrix to be preconditioned,
                          the corresponding entry of the preconditioner is set to~1.\\ \hline
-Gauss-Seidel      & \verb|'GS'|     & Hybrid Gauss-Seidel (forward), that is,
+Gauss-Seidel      & \verb|'GS'|, \verb|'L1-GS'|     & Hybrid Gauss-Seidel (forward), that is,
                                       global block Jacobi with
                                       Gauss-Seidel as local solver.\\ \hline
-Symmetrized Gauss-Seidel      & \verb|'FBGS'|     & Symmetrized hybrid Gauss-Seidel,that is,
+Symmetrized Gauss-Seidel      & \verb|'FBGS'|, \verb|'L1-FBGS'|     & Symmetrized hybrid Gauss-Seidel, that is,
                                       forward Gauss-Seidel followed by
                                                     backward Gauss-Seidel.\\ \hline
-Block Jacobi      & \verb|'BJAC'| & Block-Jacobi with ILU(0) on the local blocks.\\ \hline
+Block Jacobi      & \verb|'BJAC'|, \verb|'L1-BJAC'| & Block-Jacobi with ILU(0) on the local blocks.\\ \hline
 Additive Schwarz  & \verb|'AS'|   & Additive Schwarz (AS),
                                     with overlap~1 and ILU(0) on the local blocks. \\ \hline
 Multilevel        &\verb|'ML'|    & V-cycle with one hybrid forward Gauss-Seidel
                                     (GS) sweep as pre-smoother and one hybrid backward
-                                    GS sweep as post-smoother, basic smoothed aggregation
+                                    GS sweep as post-smoother, decoupled smoothed aggregation
                                    as coarsening algorithm, and LU (plus triangular solve)
                                    as coarsest-level solver. See the default values in
                                    Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}
@@ -100,7 +100,7 @@ such as those implemented in UMFPACK, MUMPS, SuperLU, and SuperLU\_Dist,
 usually lead to smaller numbers of preconditioned Krylov
 iterations than inexact solvers, when the linear system comes from
 a standard discretization of basic scalar elliptic PDE problems. However,
-this does not necessarily correspond to the smallest execution time
+this does not necessarily correspond to the shortest execution time
 on parallel computers.
 
 

docs/src/overview.tex

@@ -29,8 +29,7 @@ two different coarsening strategies, based on aggregation, are available:
 \end{itemize}
 
 Either exact or approximate solvers can be used on the coarsest-level system. Specifically, different sparse LU factorizations from external
-packages, native incomplete LU factorizations, weighted Jacobi, hybrid Gauss-Seidel,
+packages, native incomplete LU and approximate inverse factorizations, weighted Jacobi, hybrid Gauss-Seidel, block-Jacobi solvers and recursive call to preconditioned Krylov methods are available. All the smoothers can be also exploited as one-level
-and block-Jacobi solvers are available. All the smoothers can be also exploited as one-level
 preconditioners.
 
 AMG4PSBLAS is written in Fortran~2003, following an

docs/src/userinterface.tex

@@ -65,13 +65,7 @@ This method allocates and initializes the preconditioner
 
 \end{tabular}
 
-\vskip1.5\baselineskip
-For compatibility with the previous versions of MLD2P4, this method can be also invoked
-as follows:
 
-\begin{center}
-\verb|call amg_precinit(p,ptype,info)|
-\end{center}
 
 
 \clearpage
@@ -132,13 +126,6 @@ contained in \verb|val|.
                 underlying objects.
 \end{tabular}
 
-\vskip1.5\baselineskip
-For compatibility with the previous versions of MLD2P4, this method can be also invoked
-as follows:
-
-\begin{center}
-\verb|call amg_precset(p,what,val,info)|
-\end{center}
 
 \noindent
 However, in this case the optional arguments \verb|ilev|,
@@ -238,13 +225,9 @@ See also Sec.~\ref{sec:adding}.
 \verb|what|              & \textsc{data type}        &  \verb|val|      &  \textsc{default}  &
 \textsc{comments} \\ \hline
 \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{'ADD'}
-                             \texttt{'MULT'} \par \texttt{'ADD'}
                          & \texttt{'VCYCLE'}
-                         &Multilevel cycle: V-cycle, W-cycle, K-cycle, hybrid Multiplicative Schwarz,
+                         &Multilevel cycle: V-cycle, W-cycle, K-cycle, and additive composition. \\ \hline
-                           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|'OUTER_SWEEPS'| & \texttt{integer} &
                            Any integer \par number $\ge 1$  & 1 &
                            Number of multilevel cycles. \\ \hline
@@ -290,7 +273,7 @@ be applied.
                            if the number of levels reaches this value (see Note). \\ \hline
 
 \verb|'PAR_AGGR_ALG'|  & \verb|character(len=*)| \hspace*{-3mm}
-                         & \texttt{'DEC'}, \texttt{'SYMDEC'}
+                         & \texttt{'DEC'}, \texttt{'SYMDEC'}, \texttt{'COUPLED'}
                          & \texttt{'DEC'}
                          & Parallel aggregation algorithm. \par Currently, only the
                          decoupled aggregation (\verb|DEC|) is available; the
@@ -301,7 +284,8 @@ be applied.
 \verb|'AGGR_TYPE'|  & \verb|character(len=*)| \hspace*{-3mm}
                          & \textbf{\texttt{'SOC1'}} &
                                                       \textbf{\texttt{'SOC1'}},
-                                                      \textbf{\texttt{'SOC2'}}
+                                                      \textbf{\texttt{'SOC2'}},
+                                                      \textbf{\texttt{'MATCHBOXP'}}
                          & Type of aggregation algorithm: currently,
                            we implement to measures of strength of
                            connection, the one by Van\v{e}k, Mandel
@@ -582,7 +566,7 @@ made by the user through the methods \verb|init| and \verb|set|.
               & The sparse matrix structure containing the local part of the
                 matrix to be preconditioned. Note that \emph{x} must be chosen according
                 to the real/complex,
-single/double precision version of MLD2P4 under use.
+single/double precision version of AMG4PSBLAS under use.
                 See the PSBLAS User's Guide for details \cite{PSBLASGUIDE}.\\
 \verb|desc_a| & \verb|type(psb_desc_type), intent(in)|. \\
               & The communication descriptor of \verb|a|. See the PSBLAS User's Guide for
@@ -615,7 +599,7 @@ hierarchy produced by a previous call to \verb|hierarchy_build|
 \verb|a|      & \verb|type(psb_|\emph{x}\verb|spmat_type), intent(in)|. \\
               & The sparse matrix structure containing the local part of the
                 matrix to be preconditioned. Note that \emph{x} must be chosen according
-                to the real/complex, single/double precision version of MLD2P4 under use.
+                to the real/complex, single/double precision version of AMG4PSBLAS under use.
                 See the PSBLAS User's Guide for details \cite{PSBLASGUIDE}.\\
 \verb|desc_a| & \verb|type(psb_desc_type), intent(in)|. \\
               & The communication descriptor of \verb|a|. See the PSBLAS User's Guide for
@@ -659,7 +643,7 @@ unnatural when dealing with simple one-level preconditioners.
 \verb|a|  & \verb|type(psb_|\emph{x}\verb|spmat_type), intent(in)|. \\
               & The sparse matrix structure containing the local part of the
                 matrix to be preconditioned. Note that \emph{x} must be chosen according
-                to the real/complex, single/double precision version of MLD2P4 under use.
+                to the real/complex, single/double precision version of AMG4PSBLAS under use.
                 See the PSBLAS User's Guide for details \cite{PSBLASGUIDE}.\\
 \verb|desc_a| & \verb|type(psb_desc_type), intent(in)|. \\
               & The communication descriptor of \verb|a|. See the PSBLAS User's Guide for
@@ -679,13 +663,6 @@ unnatural when dealing with simple one-level preconditioners.
   components; this allows e.g. running on GPUs. \\
 \end{tabular}
 
-\vskip1.5\baselineskip
-For compatibility with the previous versions of MLD2P4, this method can be also invoked
-as follows:
-
-\begin{center}
-\verb|call amg_precbld(p,what,val,info[,amold,vmold,imold])|
-\end{center}
 
 \noindent
 The method can be used to build multilevel preconditioners too.
@@ -703,7 +680,7 @@ This method computes $y = op(B^{-1})\, x$, where $B$ is a previously built
 preconditioner, stored into \verb|p|, and $op$
 denotes the preconditioner itself or its transpose, according to
 the value of \verb|trans|.
-Note that, when MLD2P4 is used with a Krylov solver from PSBLAS,
+Note that, when AMG4PSBLAS is used with a Krylov solver from PSBLAS,
 \verb|p%apply| is called within the PSBLAS method \verb|psb_krylov|
 and hence it is completely transparent to the user.
 
@@ -713,11 +690,11 @@ and hence it is completely transparent to the user.
 \verb|x|      & \emph{type}\verb|(|\emph{kind\_parameter}\verb|), dimension(:), intent(in)|.\\
               & The local part of the vector $x$. Note that \emph{type} and
                 \emph{kind\_parameter} must be chosen according
-                to the real/complex, single/double precision version of MLD2P4 under use.\\
+                to the real/complex, single/double precision version of AMG4PSBLAS under use.\\
 \verb|y|      & \emph{type}\verb|(|\emph{kind\_parameter}\verb|), dimension(:), intent(out)|.\\
               & The local part of the vector $y$. Note that \emph{type} and
                 \emph{kind\_parameter} must be chosen according
-                to the real/complex, single/double precision version of MLD2P4 under use.\\
+                to the real/complex, single/double precision version of AMG4PSBLAS under use.\\
 \verb|desc_a| & \verb|type(psb_desc_type), intent(in)|. \\
               & The communication descriptor associated to the matrix to be
                 preconditioned.\\
@@ -732,16 +709,9 @@ and hence it is completely transparent to the user.
              & Workspace. Its size should be at
                least \verb|4 * psb_cd_get_local_| \verb|cols(desc_a)| (see the PSBLAS User's Guide).
                Note that \emph{type} and \emph{kind\_parameter} must be chosen according
-               to the real/complex, single/double precision version of MLD2P4 under use.\\
+               to the real/complex, single/double precision version of AMG4PSBLAS under use.\\
 \end{tabular}
 
-\vskip1.5\baselineskip
-For compatibility with the previous versions of MLD2P4, this method can be also invoked
-as follows:
-
-\begin{center}
-\verb|call amg_precaply(p,what,val,info)|
-\end{center}
 
 \clearpage
 
@@ -761,14 +731,6 @@ This method deallocates the preconditioner data structure \verb|p|.
               & Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
 \end{tabular}
 
-\vskip1.5\baselineskip
-For compatibility with the previous versions of MLD2P4, this method can be also invoked
-as follows:
-
-\begin{center}
-\verb|call amg_precfree(p,info)|
-\end{center}
-
 
 \clearpage
 
@@ -793,14 +755,6 @@ or \verb|build|, have been called.
                 will be printed; the default is the standard output.\\
 \end{tabular}
 
-\vskip1.5\baselineskip
-For compatibility with the previous versions of MLD2P4, this method can be also invoked
-as follows:
-
-\begin{center}
-\verb|call amg_precdescr(p,info [,iout])|
-\end{center}
-
 
 \subsection{Auxiliary Methods\label{sec:auxil}}
 Various functionalities are implemented as additional methods of the
@@ -843,7 +797,7 @@ Create a (deep) copy of the preconditioner object.
 \verb|pout|  & \verb|type(amg_|\emph{x}\verb|prec_type), intent(out)|.\\
               & The copy of the preconditioner data structure. Note
                 that \emph{x} must be chosen according
-                to the real/complex, single/double precision version of MLD2P4 under use.\\
+                to the real/complex, single/double precision version of AMG4PSBLAS under use.\\
 \verb|info|   & \verb|integer, intent(out)|.\\
               & Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
 \end{tabular}