Add files via upload

docs/src/Makefile

@@ -86,7 +86,7 @@
 TOPFILE   = userguide.tex
 HTMLFILE  = userhtml.tex
 SECFILE   = abstract.tex overview.tex distribution.tex newobjects.tex\
-		building.tex background.tex gettingstarted.tex userinterface.tex \
+		building.tex gettingstarted.tex userinterface.tex \
             errors.tex bibliography.tex license.tex 
 FIGDIR    = figures
 
@@ -258,8 +258,7 @@ define header
   @echo
   @echo "#---------------------------------------------------------------------"
   @echo "MAKEFILE = LaTeX PDF Makefile"
-  @echo "AUTHOR   = Alfredo Buttari"
+  @echo 'ID       = $$Id: Makefile AMG4PSBLAS 1.0 March 2021$ ' 
-  @echo 'ID       = $$Id: Makefile 1524 2007-01-17 17:06:06Z sfilippo $ ' 
   @echo "#---------------------------------------------------------------------"
   @echo
   @echo "ACRO     = $(ACRO) $(ACROFLAGS) $(PDF)"

docs/src/abstract.tex

@@ -3,11 +3,15 @@
 
 \textsc{AMG4PSBLAS (Algebraic MultiGrid Preconditioners Package
 based on PSBLAS}) is a package of parallel algebraic multilevel preconditioners included in the PSCToolkit (Parallel Sparse Computation Toolkit) software framework.
-It is a progress of a software development project started in 2007, named MLD2P4, which implemented a multilevel version of some domain decomposition preconditioners of additive-Schwarz type and was based on a parallel decoupled version of the well known smoothed
+It is a progress of a software development project started in 2007, named MLD2P4, which originally implemented a 
-aggregation method to generate the multilevel hierarchy of coarser matrices. In the last years, within the context of the EU-H2020 EoCoE project (Energy Oriented Center of Excellence), the package was extended including new algorithms and functionalities for setup and application of new AMG preconditioners with the final aims of improving efficiency and scalability when tens of thousands cores are
+multilevel version of some domain decomposition preconditioners of additive-Schwarz type and was based on a parallel decoupled version of the well known smoothed
-used and of boosting reliability in dealing with general symmetric positive definite linear systems. Due to the significant number of changes and the increase in scope, we decided to rename the package as AMG4PSBLAS.
+aggregation method to generate the multilevel hierarchy of coarser matrices. 
+In the last years, within the context of the EU-H2020 EoCoE project (Energy Oriented Center of Excellence), the package is being extended for including new algorithms and 
+functionalities to setup and apply new AMG preconditioners with the final aims of improving efficiency and scalability when tens of thousands cores are
+used and of boosting reliability in dealing with general symmetric positive definite linear systems. 
+Due to the significant number of changes and the increase in scope, we decided to rename the package as AMG4PSBLAS.
 
-AMG4PSBLAS has been designed to provide scalable and easy-to-use preconditioners
+AMG4PSBLAS is 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.

docs/src/gettingstarted.tex

@@ -104,8 +104,6 @@ this does not necessarily correspond to the shortest execution time
 on parallel computers.
 
 
-{\em DA MODIFICARE PER INSERIRE TIPO DI AGGREGAZIONE}
-
 \subsection{Examples\label{sec:examples}}
 
 The code reported in Figure~\ref{fig:ex1} shows how to set and apply the default
@@ -211,8 +209,7 @@ with block-Jacobi and set by~\verb|P%init|.
 Furthermore, specifying block-Jacobi as coarsest-level
 solver implies that the coarsest-level matrix is distributed
 among the processes.
-Figure~\ref{fig:ex3} shows how to set a W-cycle preconditioner using
+Figure~\ref{fig:ex3} shows how to set a W-cycle preconditioner using the Coarsening based on Compatible Weighted Matching. It applies
-the Coarsening based on Compatible Weighted Matching. It applies 
 2 hybrid Gauss-Seidel sweeps as pre- and post-smoother,
 and solves the coarsest-level system with the multifrontal LU factorization
 implemented in MUMPS. It is specified that the coarsest-level

docs/src/license.tex

@@ -2,65 +2,21 @@
 \markboth{\textsc{AMG4PSBLAS User's and Reference Guide}}
          {\textsc{\ref{sec:license} License}}
 
+{\bf DA CONTROLLARE E MODIFICARE INCLUDENDO I CREDITS A MLD2P4}
 
-AMG4PSBLAS is freely distributable under the following copyright
+The AMG4PSBLAS is freely distributable under the following copyright
 terms: {\small
 \begin{verbatim}
 
+                           AMG4PSBLAS  version 1.0
+              Algebraic MultiGrid Preconditioners Package
+             based on PSBLAS (Parallel Sparse BLAS version 3.7)
 
-                             AMG4PSBLAS version 1.0
+  (C) Copyright 2021
-    Algebraic Multigrid Package
-               based on PSBLAS (Parallel Sparse BLAS version 3.7)
-    
-    (C) Copyright 2021
-  
-        Salvatore Filippone  
-        Pasqua D'Ambra   
-        Fabio Durastante        
-   
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
-      1. Redistributions of source code must retain the above copyright
-         notice, this list of conditions and the following disclaimer.
-      2. Redistributions in binary form must reproduce the above copyright
-         notice, this list of conditions, and the following disclaimer in the
-         documentation and/or other materials provided with the distribution.
-      3. The name of the AMG4PSBLAS group or the names of its contributors may
-         not be used to endorse or promote products derived from this
-         software without specific written permission.
-   
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-    TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AMG4PSBLAS GROUP OR ITS CONTRIBUTORS
-    BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-    POSSIBILITY OF SUCH DAMAGE.
-
-\end{verbatim}
-}
-\newpage
-AMG4PSBLAS is an evolution (a rather substantial one) of MLD2P4, whose
-license we reproduce here to abide by its terms:
-{\small
-\begin{verbatim}
-
- 
-                           MLD2P4  version 2.2
-  MultiLevel Domain Decomposition Parallel Preconditioners Package
-             based on PSBLAS (Parallel Sparse BLAS version 3.5)
-  
-  (C) Copyright 2008-2018
-
-      Salvatore Filippone  
-      Pasqua D'Ambra   
-      Daniela di Serafino   
 
+  Pasqua D'Ambra         IAC-CNR, IT
+  Fabio Durastante       University of Pisa and IAC-CNR, IT
+  Salvatore Filippone    University of Rome Tor-Vergata and IAC-CNR, IT
 
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
@@ -87,4 +43,4 @@ license we reproduce here to abide by its terms:
   POSSIBILITY OF SUCH DAMAGE.
 
 \end{verbatim}
-  }
+}

docs/src/overview.tex

@@ -17,7 +17,7 @@ where $A$ is a square, real or complex, sparse symmetric positive definite (s.p.
 %
 
 The preconditioners implemented in AMG4PSBLAS are obtained by combining
-3 different types of AMG cycles with smoothers and coarsest-level solvers. The V-, W-, and a version of a Krylov-type cycle (K-cycle)~\cite{Briggs2000,Notay2008} are available, which can be combined with weighted versions of Jacobi, hybrid
+3 different types of AMG cycles with smoothers and coarsest-level solvers. The V-, W-, and a version of a Krylov-type cycle (K-cycle)~\cite{Briggs2000,Notay2008} are available, which can be combined with Jacobi hybrid
 %\footnote{see Note 2 in Table~\ref{tab:p_coarse}, p.~28.}
 forward/backward Gauss-Seidel, block-Jacobi, and additive Schwarz smoothers. Also $\ell_1$ versions of Jacobi, block-Jacobi and Gauss-Seidel smoothers are available.
 An algebraic approach is used to generate a hierarchy of

docs/src/userguide.tex

@@ -89,7 +89,7 @@
 \newcommand{\precdata}{\hyperlink{precdata}{{\tt mld\_prec\_type}}}
 \newcommand{\descdata}{\hyperlink{descdata}{{\tt psb\_desc\_type}}}
 \newcommand{\spdata}{\hyperlink{spdata}{{\tt psb\_spmat\_type}}}
-%\newcommand{\Ref}[1]{\mbox{(\ref{#1})}}
+\newcommand{\Ref}[1]{\mbox{(\ref{#1})}}
 
 \begin{document}
 \pdfbookmark{AMG4PSBLAS User's and Reference Guide}{title}
@@ -172,7 +172,6 @@ Preconditioners Package based on PSBLAS}
 \include{overview}
 \include{distribution}
 \include{building}
-%\include{background}
 \include{gettingstarted}
 \include{userinterface}
 \include{newobjects}

docs/src/userhtml.tex

@@ -87,7 +87,7 @@
 \newcommand{\precdata}{\hyperlink{precdata}{{\tt mld\_prec\_type}}}
 \newcommand{\descdata}{\hyperlink{descdata}{{\tt psb\_desc\_type}}}
 \newcommand{\spdata}{\hyperlink{spdata}{{\tt psb\_spmat\_type}}}
-%\newcommand{\Ref}[1]{\mbox{(\ref{#1})}}
+\newcommand{\Ref}[1]{\mbox{(\ref{#1})}}
 
 \begin{document}
 {\LARGE\bfseries MLD2P4\\[.8ex] User's and Reference Guide}\\[\baselineskip]

docs/src/userinterface.tex

@@ -240,30 +240,28 @@ be applied.
 \bsideways
 \begin{center}
 %\begin{tabular}{|p{5cm}|l|p{2.4cm}|p{2.5cm}|p{5cm}|}
-\begin{tabular}{|p{5.7cm}|l|p{2.3cm}|p{2.5cm}|p{6.9cm}|}
+\begin{tabular}{|p{3.9cm}|l|p{2.3cm}|p{2.9cm}|p{6.9cm}|}
 \hline
 \verb|what|              & \textsc{data type}        &  \verb|val|      &  \textsc{default}  &
 \textsc{comments} \\ \hline
-\verb|'MIN_COARSE_SIZE_PER_PROCESS'| & \verb|integer|
+\verb|'MIN_COARSE_SIZE'| & \verb|integer|
+                         & Any number \par $> 0$
+                         & $\lfloor 40 \sqrt[3]{n} \rfloor$, where $n$ is the dimension
+                            of the matrix at the finest level
+                         & Coarse size threshold. The aggregation stops
+                            if the global number of variables of the
+                            computed coarsest matrix
+                            is lower than or equal to this threshold
+                           (see Note).
+                           \\ \hline
+\verb|'MIN_COARSE_SIZE_PROCESS'| & \verb|integer|
                          & Any number \par $> 0$
                          & $200$
                          & Coarse size threshold per process. The aggregation stops
-                            if  the global number of variables of the
+                            if the number of variables of the
-                            computed coarsest matrix
+                            computed coarsest matrix on the local process
                             is lower than or equal to this threshold
-                           multiplied by the number of processes.
+                           (see Note).
-
-                           \\ \hline
-\verb|'MIN_COARSE_SIZE'| & \verb|integer|
-                         & Any number \par $> 0$
-                         & -1
-                         & Coarse size threshold. The aggregation stops
-                            if  the global number of variables of the
-                            computed coarsest matrix
-                            is lower than or equal to this threshold
-                           (see Note). If negative, it is ignored in
-                           favour of the default for
-                           \verb|'MIN_COARSE_SIZE_PER_PROCESS'|. 
                            \\ \hline
 
 \verb|'MIN_CR_RATIO'| & \verb|real|