fdurastante/amg4psblas
1
0
Fork 0
mirror of https://github.com/sfilippone/amg4psblas.git synced 2026-10-06 22:55:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Full highlighting and code-of-conduct

Browse Source
This commit is contained in:
Cirdans-Home
2021-03-10 23:28:04 +01:00
parent 7af511a218
commit 8b9a6c5f9a
31 changed files with 2077 additions and 1195 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/Makefile
+1 -1
View File
@@ -87,7 +87,7 @@ TOPFILE = userguide.tex
HTMLFILE = userhtml.tex
SECFILE = abstract.tex overview.tex distribution.tex newobjects.tex\
building.tex gettingstarted.tex userinterface.tex \
errors.tex bibliography.tex license.tex
errors.tex bibliography.tex license.tex covenant.tex
FIGDIR = figures
XPDFFLAGS =
docs/src/building.tex
+7 -1
View File
@@ -38,7 +38,7 @@ The following base libraries are needed:
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
the AMG4PSBLAS/PSBLAS computations; they are however critical when using
the AMG4PSBLAS/\-PSBLAS computations; they are however critical when using
preconditioners based on MUMPS, UMFPACK or SuperLU third party
libraries. Note that UMFPACK requires a full LAPACK library; our
experience is that configuring ATLAS for building full LAPACK does not
@@ -105,9 +105,15 @@ in the main directory to generate the necessary makefile.
\textbf{DA RISCRIVERE}
As a minimal example consider the following:
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{console}
./configure --with-psblas=PSB-INSTALL-DIR
\end{minted}
\else
\begin{verbatim}
./configure --with-psblas=PSB-INSTALL-DIR
\end{verbatim}
\fi
which assumes that the various MPI compilers and support libraries are
available in the standard directories on the system, and specifies
only the PSBLAS install directory (note that the latter directory must
docs/src/covenant.tex
+113
View File
@@ -0,0 +1,113 @@
\section{Contributor Covenant Code of Conduct\label{sec:codeofconduct}}
\markboth{\textsc{AMG4PSBLAS User's and Reference Guide}}
{\textsc{\ref{sec:codeofconduct} Contributor Covenant Code of Conduct}}
\paragraph{Our Pledge}
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, caste, color, religion, or sexual identity
and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
\begin{itemize}
\item Demonstrating empathy and kindness toward other people
\item Being respectful of differing opinions, viewpoints, and experiences
\item Giving and gracefully accepting constructive feedback
\item Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
\item Focusing on what is best not just for us as individuals, but for the
overall community
\end{itemize}
Examples of unacceptable behavior include:
\begin{itemize}
\item The use of sexualized language or imagery, and sexual attention or
advances of any kind
\item Trolling, insulting or derogatory comments, and personal or political attacks
\item Public or private harassment
\item Publishing others’ private information, such as a physical or email
address, without their explicit permission
\item Other conduct which could reasonably be considered inappropriate in a
professional setting
\end{itemize}
\paragraph{Enforcement Responsibilities}
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
\href{mailto:eocoe@na.iac.cnr.it}{eocoe@na.iac.cnr.it}.
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
\paragraph{Enforcement Guidelines}
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
\begin{enumerate}
\item Correction
Community Impact: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
Consequence: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
\item Warning
Community Impact: A violation through a single incident or series
of actions.
Consequence: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.
\item Temporary Ban
Community Impact: A serious violation of community standards, including
sustained inappropriate behavior.
Consequence: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
\item Permanent Ban
Community Impact: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
Consequence: A permanent ban from any sort of public interaction within
the community.
\end{enumerate}
\paragraph{Attribution}
This Code of Conduct is adapted from the Contributor Covenant,
version 2.0, available at
\href{https://www.contributor-covenant.org/version/2/0/code_of_conduct.html}{https://www.contributor-covenant.org/version/2/0/code\_of\_conduct.html}.
Community Impact Guidelines were inspired by
Mozilla’s code of conduct enforcement ladder.
For answers to common questions about this code of conduct, see the FAQ at
\href{https://www.contributor-covenant.org/faq}{https://www.contributor-covenant.org/faq}. Translations are available
at \href{https://www.contributor-covenant.org/translations}{https://www.contributor-covenant.org/translations}.
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
docs/src/gettingstarted.tex
+138 -38
View File
@@ -15,18 +15,18 @@ The following steps are required:
following an object-oriented approach.
\item \emph{Allocate and initialize the preconditioner data structure, according to
a preconditioner type chosen by the user}. This is performed by the routine
\verb|init|, which also sets defaults for each preconditioner
\fortinline|init|, which also sets defaults for each preconditioner
type selected by the user. The preconditioner types and the defaults associated
with them are given in Table~\ref{tab:precinit}, where the strings used by
\verb|init| to identify the preconditioner types are also given.
\fortinline|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 selected preconditioner type, by properly setting
preconditioner parameters.} This is performed by the routine \verb|set|.
preconditioner parameters.} This is performed by the routine \fortinline|set|.
This routine must be called only if the user wants to modify the default values
of the parameters associated with the selected preconditioner type, to obtain a variant
of that preconditioner. Examples of use of \verb|set| are given in
of that preconditioner. Examples of use of \fortinline|set| are given in
Section~\ref{sec:examples}; a complete list of all the
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}.
@@ -34,18 +34,18 @@ The following steps are required:
is multilevel, then two steps must be performed, as specified next.
\begin{enumerate}
\item[4.1] \emph{Build the AMG hierarchy for a given matrix.} This is
performed by the routine \verb|hierarchy_build|.
performed by the routine \fortinline|hierarchy_build|.
\item[4.2] \emph{Build the preconditioner for a given matrix.} This is performed
by the routine \verb|smoothers_build|.
by the routine \fortinline|smoothers_build|.
\end{enumerate}
If the selected preconditioner is one-level, it is built in a single step,
performed by the routine \verb|bld|.
performed by the routine \fortinline|bld|.
\item \emph{Apply the preconditioner at each iteration of a Krylov solver.}
This is performed by the method \verb|apply|. When using the PSBLAS Krylov solvers,
this step is completely transparent to the user, since \verb|apply| is called
by the PSBLAS routine implementing the Krylov solver (\verb|psb_krylov|).
This is performed by the method \fortinline|apply|. When using the PSBLAS Krylov solvers,
this step is completely transparent to the user, since \fortinline|apply| is called
by the PSBLAS routine implementing the Krylov solver (\fortinline|psb_krylov|).
\item \emph{Free the preconditioner data structure}. This is performed by
the routine \verb|free|. This step is complementary to step 1 and should
the routine \fortinline|free|. This step is complementary to step 1 and should
be performed when the preconditioner is no more used.
\end{enumerate}
@@ -88,11 +88,11 @@ Multilevel &\fortinline|'ML'| & V-cycle with one hybrid forward Gauss-
\end{center}
\end{table}
Note that the module \verb|amg_prec_mod|, containing the definition of the
Note that the module \fortinline|amg_prec_mod|, containing the definition of the
preconditioner data type and the interfaces to the routines of AMG4PSBLAS,
must be used in any program calling such routines.
The modules \verb|psb_base_mod|, for the sparse matrix and communication descriptor
data types, and \verb|psb_krylov_mod|, for interfacing with the
The modules \fortinline|psb_base_mod|, for the sparse matrix and communication descriptor
data types, and \fortinline|psb_krylov_mod|, for interfacing with the
Krylov solvers, must be also used (see Section~\ref{sec:examples}). \\
\textbf{Remark 1.} Coarsest-level solvers based on the LU factorization,
@@ -109,11 +109,11 @@ on parallel computers.
The code reported in Figure~\ref{fig:ex1} shows how to set and apply the default
multilevel preconditioner available in the real double precision version
of AMG4PSBLAS (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
by simply specifying \fortinline|'ML'| as the second argument of \fortinline|P%init|
(a call to \fortinline|P%set| is not needed) and is applied with the CG
solver provided by PSBLAS (the matrix of the system to be solved is
assumed to be positive definite). As previously observed, the modules
\verb|psb_base_mod|, \verb|amg_prec_mod| and \verb|psb_krylov_mod|
\fortinline|psb_base_mod|, \fortinline|amg_prec_mod| and \fortinline|psb_krylov_mod|
must be used by the example program.
The part of the code concerning the
@@ -134,9 +134,64 @@ precision, versions are obtained with straightforward modifications of the previ
example (see Section~\ref{sec:userinterface} for details). If these versions are installed,
the corresponding codes are available in \verb|examples/fileread/|.
\begin{figure}[tbp]
\begin{listing}[tbp]
\begin{center}
\begin{minipage}{.90\textwidth}
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
use psb_base_mod
use amg_prec_mod
use psb_krylov_mod
... ...
!
! sparse matrix
type(psb_dspmat_type) :: A
! sparse matrix descriptor
type(psb_desc_type) :: desc_A
! preconditioner
type(amg_dprec_type) :: P
! right-hand side and solution vectors
type(psb_d_vect_type) :: b, x
... ...
!
! initialize the parallel environment
call psb_init(ctxt)
call psb_info(ctxt,iam,np)
... ...
!
! read and assemble the spd matrix A and the right-hand side b
! using PSBLAS routines for sparse matrix / vector management
... ...
!
! 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
call P%init('ML',info)
!
! build the preconditioner
call P%hierarchy_build(A,desc_A,info)
call P%smoothers_build(A,desc_A,info)
!
! set the solver parameters and the initial guess
... ...
!
! solve Ax=b with preconditioned CG
call psb_krylov('CG',A,P,b,x,tol,desc_A,info)
... ...
!
! deallocate the preconditioner
call P%free(info)
!
! deallocate other data structures
... ...
!
! exit the parallel environment
call psb_exit(ctxt)
stop
\end{minted}
\else
{\small
\begin{verbatim}
use psb_base_mod
@@ -155,8 +210,8 @@ the corresponding codes are available in \verb|examples/fileread/|.
... ...
!
! initialize the parallel environment
call psb_init(ictxt)
call psb_info(ictxt,iam,np)
call psb_init(ctxt)
call psb_info(ctxt,iam,np)
... ...
!
! read and assemble the spd matrix A and the right-hand side b
@@ -188,15 +243,16 @@ the corresponding codes are available in \verb|examples/fileread/|.
... ...
!
! exit the parallel environment
call psb_exit(ictxt)
call psb_exit(ctxt)
stop
\end{verbatim}
}
\fi
\end{minipage}
\caption{setup and application of the default multilevel preconditioner (example 1).
\label{fig:ex1}}
\end{center}
\end{figure}
\end{listing}
Different versions of the multilevel preconditioner can be obtained by changing
the default values of the preconditioner parameters. The code reported in
@@ -205,7 +261,7 @@ which applies 1 block-Jacobi sweep as pre- and post-smoother,
and solves the coarsest-level system with 8 block-Jacobi sweeps.
Note that the ILU(0) factorization (plus triangular solve) is used as
local solver for the block-Jacobi sweeps, since this is the default associated
with block-Jacobi and set by~\verb|P%init|.
with block-Jacobi and set by~\fortinline|P%init|.
Furthermore, specifying block-Jacobi as coarsest-level
solver implies that the coarsest-level matrix is distributed
among the processes.
@@ -216,7 +272,7 @@ implemented in MUMPS. It is specified that the coarsest-level
matrix is distributed, since MUMPS can be used on both
replicated and distributed matrices, and by default
it is used on replicated ones.
%Note the use of the parameter \verb|pos|
%Note the use of the parameter \fortinline|pos|
%to specify a property only for the pre-smoother or the post-smoother
%(see Section~\ref{sec:precset} for more details).
The code fragments shown in Figures~\ref{fig:ex2} and \ref{fig:ex3} are
@@ -232,8 +288,20 @@ The corresponding example program is available in the file
For all the previous preconditioners, example programs where the sparse matrix and
the right-hand side are generated by discretizing a PDE with Dirichlet
boundary conditions are also available in the directory \verb|examples/pdegen|.
\begin{figure}[tbh]
\vspace{-1em}\begin{listing}[tbh]
\ifpdf%
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
! build a V-cycle preconditioner with 1 block-Jacobi sweep (with
! ILU(0) on the blocks) as pre- and post-smoother, and 8 block-Jacobi
! sweeps (with ILU(0) on the blocks) as coarsest-level solver
call P%init('ML',info)
call P%set('SMOOTHER_TYPE','BJAC',info)
call P%set('COARSE_SOLVE','BJAC',info)
call P%set('COARSE_SWEEPS',8,info)
call P%hierarchy_build(A,desc_A,info)
call P%smoothers_build(A,desc_A,info)
\end{minted}
\else%
\begin{center}
\begin{minipage}{.90\textwidth}
{\small
@@ -243,7 +311,7 @@ boundary conditions are also available in the directory \verb|examples/pdegen|.
! ILU(0) on the blocks) as pre- and post-smoother, and 8 block-Jacobi
! sweeps (with ILU(0) on the blocks) as coarsest-level solver
call P%init('ML',info)
call_P%set('SMOOTHER_TYPE','BJAC',info)
call P%set('SMOOTHER_TYPE','BJAC',info)
call P%set('COARSE_SOLVE','BJAC',info)
call P%set('COARSE_SWEEPS',8,info)
call P%hierarchy_build(A,desc_A,info)
@@ -252,12 +320,27 @@ boundary conditions are also available in the directory \verb|examples/pdegen|.
\end{verbatim}
}
\end{minipage}
\caption{setup of a multilevel preconditioner based on the default decoupled coarsening\label{fig:ex2}}
\end{center}
\end{figure}
\begin{figure}[h!]
\fi\vspace{-2em}%
\caption{setup of a multilevel preconditioner based on the default decoupled coarsening\label{fig:ex2}}
\end{listing}\vspace*{-2em}
\begin{listing}[h!]
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
! build a W-cycle preconditioner with 2 hybrid Gauss-Seidel sweeps
! as pre- and post-smoother, a distributed coarsest
! matrix, and MUMPS as coarsest-level solver
call P%init('ML',info)
call P%set('PAR_AGGR_ALG','COUPLED',info)
call P%set('ML_CYCLE','WCYCLE',info)
call P%set('SMOOTHER_TYPE','FBGS',info)
call P%set('SMOOTHER_SWEEPS',2,info)
call P%set('COARSE_SOLVE','MUMPS',info)
call P%set('COARSE_MAT','DIST',info)
call P%hierarchy_build(A,desc_A,info)
call P%smoothers_build(A,desc_A,info)
\end{minted}
\else
\begin{center}
\begin{minipage}{.90\textwidth}
{\small
@@ -279,11 +362,27 @@ boundary conditions are also available in the directory \verb|examples/pdegen|.
\end{verbatim}
}
\end{minipage}
\caption{setup of a multilevel preconditioner based on the coupled coarsening based on weighted matching\label{fig:ex3}}
\end{center}
\end{figure}
\begin{figure}[h!]
\fi\vspace{-2em}%
\caption{setup of a multilevel preconditioner based on the coupled coarsening based on weighted matching\label{fig:ex3}}
\end{listing}\vspace*{-2em}
\begin{listing}[h!]
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
! build a W-cycle preconditioner with 2 hybrid Gauss-Seidel sweeps
! as pre- and post-smoother, a distributed coarsest
! matrix, and MUMPS as coarsest-level solver
call P%init('ML',info)
call P%set('PAR_AGGR_ALG','COUPLED',info)
call P%set('ML_CYCLE','WCYCLE',info)
call P%set('SMOOTHER_TYPE','FBGS',info)
call P%set('SMOOTHER_SWEEPS',2,info)
call P%set('COARSE_SOLVE','MUMPS',info)
call P%set('COARSE_MAT','DIST',info)
call P%hierarchy_build(A,desc_A,info)
call P%smoothers_build(A,desc_A,info)
\end{minted}
\else
\begin{center}
\begin{minipage}{.90\textwidth}
{\small
@@ -299,9 +398,10 @@ boundary conditions are also available in the directory \verb|examples/pdegen|.
\end{verbatim}
}
\end{minipage}
\caption{setup of a one-level Schwarz preconditioner.\label{fig:ex4}}
\end{center}
\end{figure}
\fi\vspace{-2em}%
\caption{setup of a one-level Schwarz preconditioner.\label{fig:ex4}}
\end{listing}
%%% Local Variables:
docs/src/overview.tex
+1 -1
View File
@@ -3,7 +3,7 @@
{\textsc{\ref{sec:overview} General Overview}}
The \textsc{Algebraic MultiGrid Preconditioners Package based on
PSBLAS (AMG4PSBLAS)} provides parallel Algebraic MultiGrid (AMG) preconditioners (see, e.g., \cite{Briggs2000,Stuben_01}),
PSBLAS} (\textsc{AMG\-4\-PSBLAS}) provides parallel Algebraic MultiGrid (AMG) preconditioners (see, e.g., \cite{Briggs2000,Stuben_01}),
to be used in the iterative solution of linear systems,
\begin{equation}
Ax=b,
docs/src/userguide.tex
+3
View File
@@ -24,6 +24,8 @@
\usemintedstyle{friendly}
\definecolor{bg}{rgb}{0.95,0.95,0.95}
\usepackage{breakurl}
\usepackage{mathpazo}
\usepackage[english]{babel}
\ifpdf
\newmintinline[fortinline]{fortran}{}
\else%
@@ -192,6 +194,7 @@ Preconditioners Package based on PSBLAS}
\clearpage
\appendix
\include{license}
\include{covenant}
\clearpage
\include{bibliography}
docs/src/userhtml.tex
+6 -1
View File
@@ -21,11 +21,16 @@
%\newboolean{mtc}
%\setboolean{mtc}{true}
\usepackage{microtype}
\usepackage{listings}
\ifpdf
\newmintinline[fortinline]{fortran}{}
\else%
\usepackage{listings}
\def\fortinline{\lstinline[basicstyle=\ttfamily,language=fortran]}
\usepackage{float}
\newfloat{listing}{htbp}{lop}
\floatname{listing}{Listing}
\def\lstfloatautorefname{Listing} % needed for hyperref/auroref
\fi
\pdfoutput=0
docs/src/userinterface.tex
+172 -173
View File
@@ -3,13 +3,13 @@
{\textsc{\ref{sec:userinterface} User Interface}}
The basic user interface of AMG4PBLAS consists of eight methods. The six
methods \verb|init|, \verb|set|, \verb|build|,
\verb|hierarchy_build|, \verb|smoothers_build| and \verb|apply|
methods \fortinline|init|, \fortinline|set|, \fortinline|build|,
\fortinline|hierarchy_build|, \fortinline|smoothers_build| and \fortinline|apply|
encapsulate all the functionalities for the setup and the application
of any multilevel and one-level preconditioner implemented in the
package.
The method \verb|free| deallocates the preconditioner data structure, while
\verb|descr| prints a description of the preconditioner setup by the user.
The method \fortinline|free| deallocates the preconditioner data structure, while
\fortinline|descr| prints a description of the preconditioner setup by the user.
For backward compatibility, methods are also accessible as
stand-alone subroutines.
@@ -43,24 +43,24 @@ A description of each method is given in the remainder of this section.
\subsection{Method init\label{sec:precinit}}
\begin{center}
\verb|call p%init(icontx,ptype,info)|
\fortinline|call p%init(contxt,ptype,info)|
\end{center}
\noindent
This method allocates and initializes the preconditioner
\verb|p|, according to the preconditioner type chosen by the user.
\fortinline|p|, according to the preconditioner type chosen by the user.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|icontxt| & \verb|integer, intent(in)|.\\
\fortinline|contxt| & \fortinline|type(psb_ctxt_type), intent(in)|.\\
& The communication context.\\
\verb|ptype| & \verb|character(len=*), intent(in)|.\\
\fortinline|ptype| & \fortinline|character(len=*), intent(in)|.\\
& The type of preconditioner. Its values are specified
in Table~\ref{tab:precinit}.\\
& Note that the strings are case insensitive.\\
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\end{tabular}
@@ -73,63 +73,63 @@ This method allocates and initializes the preconditioner
\subsection{Method set\label{sec:precset}}
\begin{center}
\verb|call p%set(what,val,info [,ilev, ilmax, pos, idx])|
\fortinline|call p%set(what,val,info [,ilev, ilmax, pos, idx])|
\end{center}
\noindent
This method sets the parameters defining the preconditioner \verb|p|. More
precisely, the parameter identified by \verb|what| is assigned the value
contained in \verb|val|.
This method sets the parameters defining the preconditioner \fortinline|p|. More
precisely, the parameter identified by \fortinline|what| is assigned the value
contained in \fortinline|val|.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|what| & \verb|character(len=*)|. \\
\fortinline|what| & \fortinline|character(len=*)|. \\
& The parameter to be set. It can be specified through its name;
the string is case-insensitive. See
Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}.\\
\verb|val | & \verb|integer| \emph{or} \verb|character(len=*)| \emph{or}
\verb|real(psb_spk_)| \emph{or} \verb|real(psb_dpk_)|,
\verb|intent(in)|.\\
\fortinline|val | & \fortinline|integer| \emph{or} \fortinline|character(len=*)| \emph{or}
\fortinline|real(psb_spk_)| \emph{or} \fortinline|real(psb_dpk_)|,
\fortinline|intent(in)|.\\
& The value of the parameter to be set. The list of allowed
values and the corresponding data types is given in
Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}.
When the value is of type \verb|character(len=*)|,
When the value is of type \fortinline|character(len=*)|,
it is also treated as case insensitive.\\
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors}
for details.\\
\verb|ilev| & \verb|integer, optional, intent(in)|.\\
\fortinline|ilev| & \fortinline|integer, optional, intent(in)|.\\
& 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.
If \verb|ilev| is not present, the parameter identified by \verb|what|
If \fortinline|ilev| is not present, the parameter identified by \fortinline|what|
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)|.\\
\fortinline|ilmax| & \fortinline|integer, optional, intent(in)|.\\
& 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
the default is \verb|ilmax=ilev|.
\fortinline|ilev| and \fortinline|ilmax| are present, the settings
are applied at all levels \fortinline|ilev:ilmax|. When
\fortinline|ilev| is present but \fortinline|ilmax| is not, then
the default is \fortinline|ilmax=ilev|.
The levels are numbered in increasing
order starting from the finest one, i.e., level 1 is the finest level. \\
\verb|pos| & \verb|charater(len=*), optional, intent(in)|.\\
& Whether the other arguments apply only to the pre-smoother (\verb|'PRE'|)
or to the post-smoother (\verb|'POST'|). If \verb|pos| is not present,
\fortinline|pos| & \fortinline|character(len=*), optional, intent(in)|.\\
& Whether the other arguments apply only to the pre-smoother (\fortinline|'PRE'|)
or to the post-smoother (\fortinline|'POST'|). If \fortinline|pos| is not present,
the other arguments are applied to both smoothers.
If the preconditioner is one-level or the parameter identified by \verb|what|
does not concern the smoothers, \verb|pos| is ignored.\\
\verb|idx| & \verb|integer, optional, intent(in)|.\\
If the preconditioner is one-level or the parameter identified by \fortinline|what|
does not concern the smoothers, \fortinline|pos| is ignored.\\
\fortinline|idx| & \fortinline|integer, optional, intent(in)|.\\
& An auxiliary input argument that can be passed to the
underlying objects.
\end{tabular}
\noindent
However, in this case the optional arguments \verb|ilev|,
\verb|ilmax|, \verb|pos| and \verb|idx|
However, in this case the optional arguments \fortinline|ilev|,
\fortinline|ilmax|, \fortinline|pos| and \fortinline|idx|
cannot be used. \\
A variety of preconditioners can be obtained
@@ -148,7 +148,7 @@ A list of the parameters that can be set, along with their allowed and
default values, is given in Tables~\ref{tab:p_cycle}-\ref{tab:p_smoother_1}.\\
\textbf{Remark 2.} A smoother is usually obtained by combining two objects:
a smoother (\verb|SMOOTHER_TYPE|) and a local solver (\verb|SUB_SOLVE|),
a smoother (\fortinline|'SMOOTHER_TYPE'|) and a local solver (\fortinline|'SUB_SOLVE'|),
as specified in Tables~\ref{tab:p_smoother}-\ref{tab:p_smoother_1}.
For example, the block-Jacobi smoother using
ILU(0) on the blocks is obtained by combining the block-Jacobi smoother
@@ -160,9 +160,9 @@ result of combining the block-Jacobi smoother object with a single sweep
of the point-Jacobi solver object. However, for simplicity, shortcuts are
provided to set point-Jacobi, hybrid (forward) Gauss-Seidel, and
hybrid backward Gauss-Seidel, i.e., the previous smoothers can be defined
by setting only \verb|SMOOTHER_TYPE| to appropriate values (see
by setting only \fortinline|'SMOOTHER_TYPE'| to appropriate values (see
Tables~\ref{tab:p_smoother}), i.e., without setting
\verb|SUB_SOLVE| too.
\fortinline|'SUB_SOLVE'| too.
The smoother and solver objects are arranged in a
hierarchical manner. When specifying a smoother object, its parameters,
@@ -205,9 +205,9 @@ Likewise, the replicated layout can be used with any solver but SuperLu\_Dist;
therefore, if SuperLu\_Dist has been previously set, the coarsest-level
solver is changed to the default sequential solver.
\textbf{Remark 4.} The argument \verb|idx| can be used to allow finer
\textbf{Remark 4.} The argument \fortinline|idx| can be used to allow finer
control for those solvers; for instance, by specifying the keyword
\verb|MUMPS_IPAR_ENTRY| and an appropriate value for \verb|idx|, it is
\fortinline|'MUMPS_IPAR_ENTRY'| and an appropriate value for \fortinline|idx|, it is
possible to set any entry in the MUMPS integer control array.
See also Sec.~\ref{sec:adding}.
%The \verb|what,val| pairs described here are those of the predefined
@@ -220,13 +220,13 @@ See also Sec.~\ref{sec:adding}.
%\begin{tabular}{|p{5cm}|l|p{2.4cm}|p{2.5cm}|p{5cm}|}
\begin{tabular}{|p{3.6cm}|l|p{2.4cm}|p{2.4cm}|p{7.2cm}|}
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\fortinline|what| & \textsc{data type} & \fortinline|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|'ML_CYCLE'| & \verb|character(len=*)|
\fortinline|'ML_CYCLE'| & \fortinline|character(len=*)|
& \texttt{'VCYCLE'} \par \texttt{'WCYCLE'} \par \texttt{'KCYCLE'} \par \texttt{'ADD'}
& \texttt{'VCYCLE'}
&Multilevel cycle: V-cycle, W-cycle, K-cycle, and additive composition. \\ \hline
\verb|'OUTER_SWEEPS'| & \texttt{integer} &
\fortinline|'OUTER_SWEEPS'| & \texttt{integer} &
Any integer \par number $\ge 1$ & 1 &
Number of multilevel cycles. \\ \hline
@@ -242,9 +242,9 @@ be applied.
%\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}|}
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\fortinline|what| & \textsc{data type} & \fortinline|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|'MIN_COARSE_SIZE_PER_PROCESS'| & \verb|integer|
\fortinline|'MIN_COARSE_SIZE_PER_PROCESS'| & \fortinline|integer|
& Any number \par $> 0$
& $200$
& Coarse size threshold per process. The aggregation stops
@@ -254,7 +254,7 @@ be applied.
multiplied by the number of processes.
\\ \hline
\verb|'MIN_COARSE_SIZE'| & \verb|integer|
\fortinline|'MIN_COARSE_SIZE'| & \fortinline|integer|
& Any number \par $> 0$
& -1
& Coarse size threshold. The aggregation stops
@@ -263,10 +263,10 @@ be applied.
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'|.
\fortinline|'MIN_COARSE_SIZE_PER_PROCESS'|.
\\ \hline
\verb|'MIN_CR_RATIO'| & \verb|real|
\fortinline|'MIN_CR_RATIO'| & \fortinline|real|
& Any number \par $> 1$
& 1.5
& Minimum coarsening ratio. The aggregation stops
@@ -274,21 +274,21 @@ be applied.
at two consecutive levels is lower than or equal to this
threshold (see Note).\\ \hline
\verb|'MAX_LEVS'| & \verb|integer|
\fortinline|'MAX_LEVS'| & \fortinline|integer|
& Any integer \par number $> 1$
& 20
& Maximum number of levels. The aggregation stops
if the number of levels reaches this value (see Note). \\ \hline
\verb|'PAR_AGGR_ALG'| & \verb|character(len=*)| \hspace*{-3mm}
\fortinline|'PAR_AGGR_ALG'| & \fortinline|character(len=*)| \hspace*{-3mm}
& \texttt{'DEC'}, \texttt{'SYMDEC'}, \texttt{'COUPLED'}
& \texttt{'DEC'}
& Parallel aggregation algorithm. \par the
\verb|SYMDEC| option applies decoupled
\fortinline|SYMDEC| option applies decoupled
aggregation to the sparsity pattern
of $A+A^T$.\\ \hline
\verb|'AGGR_TYPE'| & \verb|character(len=*)| \hspace*{-3mm}
\fortinline|'AGGR_TYPE'| & \fortinline|character(len=*)| \hspace*{-3mm}
& \textbf{\texttt{'SOC1'}} &
\textbf{\texttt{'SOC1'}},
\textbf{\texttt{'SOC2'}},
@@ -302,7 +302,7 @@ be applied.
matching implemented in the MatchBox-P software package
{\bf AGGIUNGERE LINK AL PACKAGE?}\\ \hline
\verb|'AGGR_SIZE'| & \verb|integer| \hspace*{-3mm}
\fortinline|'AGGR_SIZE'| & \fortinline|integer| \hspace*{-3mm}
& Any integer \par number power of $2$ and $> 2$
& 4
& Maximum size of aggregates when the coupled aggregation based on
@@ -310,7 +310,7 @@ be applied.
aggregate larger than $8$ we recommend the use of smoothed prolongators.
{\bf MODIFICARE CODICE}\\ \hline
\verb|'AGGR_PROL'| & \verb|character(len=*)| \hspace*{-3mm}
\fortinline|'AGGR_PROL'| & \fortinline|character(len=*)| \hspace*{-3mm}
& \texttt{'SMOOTHED'}, \texttt{'UNSMOOTHED'} & \texttt{'SMOOTHED'}
& Prolongator used by the aggregation algorithm: smoothed or unsmoothed
(i.e., tentative prolongator). \\
@@ -334,10 +334,10 @@ of levels. } \\
%\begin{tabular}{|p{5cm}|l|p{2.4cm}|p{2.5cm}|p{5cm}|}
\begin{tabular}{|p{3.8cm}|l|p{2.5cm}|p{2.3cm}|p{6.6cm}|}
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\fortinline|what| & \textsc{data type} & \fortinline|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|'AGGR_ORD'| & \verb|character(len=*)|
\fortinline|'AGGR_ORD'| & \fortinline|character(len=*)|
& \texttt{'NATURAL'} \par \texttt{'DEGREE'}
& \texttt{'NATURAL'}
& Initial ordering of indices for the decoupled aggregation
@@ -347,14 +347,14 @@ of levels. } \\
%Since aggregation is
%heuristic, results will be different.
\verb|'AGGR_THRESH'| & \verb|real(|\emph{kind\_parameter}\verb|)|
\fortinline|'AGGR_THRESH'| & \fortinline|real(|\emph{kind\_parameter}\fortinline|)|
& Any~real \par number~$\in [0, 1]$
& 0.01
& The threshold $\theta$ in the decoupled aggregation algorithm,
see (\ref{eq:strongly_coup}) in Section~\ref{sec:aggregation}.
See also the note at the bottom of this table. \\ \hline
\verb|'AGGR_FILTER'|
& \verb|character(len=*)|
\fortinline|'AGGR_FILTER'|
& \fortinline|character(len=*)|
& \texttt{'FILTER'} \par \texttt{'NOFILTER'}
& \texttt{'NOFILTER'} & Matrix used in computing the smoothed
prolongator: filtered or unfiltered (see~(\ref{eq:filtered}) in Section~\ref{sec:aggregation}). \\
@@ -375,14 +375,14 @@ the parameter \texttt{ilev}.} \\
\begin{center}
\begin{tabular}{|p{3.9cm}|l|p{1.7cm}|p{1.7cm}|p{8.6cm}|}
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\fortinline|what| & \textsc{data type} & \fortinline|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|'COARSE_MAT'| & \verb|character(len=*)|
\fortinline|'COARSE_MAT'| & \fortinline|character(len=*)|
& \texttt{'DIST'} \par \texttt{'REPL'}
& \texttt{'REPL'}
& Coarsest matrix layout: distributed among the processes or
replicated on each of them. \\ \hline
\verb|'COARSE_SOLVE'| & \verb|character(len=*)|
\fortinline|'COARSE_SOLVE'| & \fortinline|character(len=*)|
& \texttt{'MUMPS'} \par \texttt{'UMF'} \par
\texttt{'SLU'} \par \texttt{'SLUDIST'} \par
\texttt{'JACOBI'} \par \texttt{'GS'} \par \texttt{'BJAC'} \par \texttt{'PCG'}
@@ -404,7 +404,7 @@ the parameter \texttt{ilev}.} \\
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|'COARSE_SUBSOLVE'| & \verb|character(len=*)|
\fortinline|'COARSE_SUBSOLVE'| & \fortinline|character(len=*)|
& \texttt{'ILU'} \par \texttt{'ILUT'} \par \texttt{'MILU'} \par
\texttt{'MUMPS'} \par \texttt{'SLU'} \par \texttt{'UMF'}
& See~Note.
@@ -435,19 +435,19 @@ level.\label{tab:p_coarse}}
\begin{center}
\begin{tabular}{|p{3.9cm}|l|p{2cm}|p{1.5cm}|p{7.5cm}|}
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\fortinline|what| & \textsc{data type} & \fortinline|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|'COARSE_SWEEPS'| & \verb|integer|
\fortinline|'COARSE_SWEEPS'| & \fortinline|integer|
& Any integer \par number $> 0$
& 10
& Number of sweeps when \verb|JACOBI|, \verb|GS| or \verb|BJAC|
& Number of sweeps when \fortinline|JACOBI|, \fortinline|GS| or \fortinline|BJAC|
is chosen as coarsest-level solver. {\bf Aggiungere criterio di arresto del PCG?}\\ \hline
\verb|'COARSE_FILLIN'| & \verb|integer|
\fortinline|'COARSE_FILLIN'| & \fortinline|integer|
& Any integer \par number $\ge 0$
& 0
& Fill-in level $p$ of the ILU factorizations. \\ \hline
\verb|'COARSE_ILUTHRS'|
& \verb|real(|\emph{kind\_parameter}\verb|)|
\fortinline|'COARSE_ILUTHRS'|
& \fortinline|real(|\emph{kind\_parameter}\fortinline|)|
& Any real \par number $\ge 0$
& 0
& Drop tolerance $t$ in the ILU($p,t$) factorization. \\
@@ -463,19 +463,19 @@ level (continued).\label{tab:p_coarse_1}}
\small
\begin{tabular}{|p{3.6cm}|l|p{1.9cm}|p{3.6cm}|p{6.5cm}|}
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\fortinline|what| & \textsc{data type} & \fortinline|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|'SMOOTHER_TYPE'| & \verb|character(len=*)|
& \verb|'JACOBI'| \par \verb|'GS'| \par \verb|'BGS'| \par \verb|'BJAC'|
\par \verb|'AS'|
& \verb|'FBGS'|
\fortinline|'SMOOTHER_TYPE'| & \fortinline|character(len=*)|
& \fortinline|'JACOBI'| \par \fortinline|'GS'| \par \fortinline|'BGS'| \par \fortinline|'BJAC'|
\par \fortinline|'AS'|
& \fortinline|'FBGS'|
& Type of smoother used in the multilevel preconditioner:
point-Jacobi, hybrid (forward) Gauss-Seidel,
hybrid backward Gauss-Seidel, block-Jacobi, \textbf{$\ell_1$-versions?} and
Additive Schwarz. \par
It is ignored by one-level preconditioners. \\ \hline
\verb|'SUB_SOLVE'| & \verb|character(len=*)|
\fortinline|'SUB_SOLVE'| & \fortinline|character(len=*)|
& \texttt{'JACOBI'} \par
\texttt{'GS'} \par \texttt{'BGS'} \par \texttt{'ILU'} \par
\texttt{'ILUT'} \par \texttt{'MILU'} \par
@@ -492,15 +492,15 @@ level (continued).\label{tab:p_coarse_1}}
LU from MUMPS, SuperLU or UMFPACK
(plus triangular solve). See Note for details on hybrid
Gauss-Seidel. \\ \hline
\verb|'SMOOTHER_SWEEPS'| & \verb|integer|
\fortinline|'SMOOTHER_SWEEPS'| & \fortinline|integer|
& Any integer \par number~$\ge 0$
& 1
& Number of sweeps of the smoother or one-level preconditioner.
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|,
together with \fortinline|pos='PRE'| or \fortinline|pos='POST|,
respectively. \\ \hline
\verb|'SUB_OVR'| & \verb|integer|
\fortinline|'SUB_OVR'| & \fortinline|integer|
& Any integer \par number~$\ge 0$
& 1
& Number of overlap layers, for Additive Schwarz only. \\
@@ -514,51 +514,51 @@ level (continued).\label{tab:p_coarse_1}}
\bsideways
\begin{center}
\small
\begin{tabular}{|p{3cm}|l|p{2.5cm}|p{2.2cm}|p{7.1cm}|}
\begin{tabular}{|p{3.2cm}|l|p{2.6cm}|p{2.6cm}|p{6.7cm}|}
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\fortinline|what| & \textsc{data type} & \fortinline|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|'SUB_RESTR'| & \verb|character(len=*)|
& \texttt{'HALO'} \par \texttt{'NONE'}
& \texttt{'HALO'}
\fortinline|'SUB_RESTR'| & \fortinline|character(len=*)|
& \fortinline|'HALO'| \par \fortinline|'NONE'|
& \fortinline|'HALO'|
& Type of restriction operator, for Additive Schwarz only:
\texttt{HALO} for taking into account the overlap, \texttt{NONE}
\texttt{HALO} for taking into account the overlap, \fortinline|'NONE'|
for neglecting it. \par
Note that \texttt{HALO} must be chosen for
the classical Addditive Schwarz smoother and its RAS variant.\\ \hline
\verb|'SUB_PROL'| & \verb|character(len=*)|
& \texttt{'SUM'} \par \texttt{'NONE'}
& \texttt{'NONE'}
\fortinline|'SUB_PROL'| & \fortinline|character(len=*)|
& \fortinline|'SUM'| \par \fortinline|'NONE'|
& \fortinline|'NONE'|
& Type of prolongation operator, for Additive Schwarz only:
\texttt{SUM} for adding the contributions from the overlap, \texttt{NONE}
\fortinline|'SUM'| for adding the contributions from the overlap, \fortinline|'NONE'|
for neglecting them. \par
Note that \texttt{SUM} must be chosen for the classical Additive
Schwarz smoother, and \texttt{NONE} for its RAS variant. \\ \hline
\verb|'SUB_FILLIN'| & \verb|integer|
Note that \fortinline|'SUM'| must be chosen for the classical Additive
Schwarz smoother, and \fortinline|'NONE'| for its RAS variant. \\ \hline
\fortinline|'SUB_FILLIN'| & \fortinline|integer|
& Any integer \par number~$\ge 0$
& 0
& Fill-in level $p$ of the incomplete LU factorizations. \\ \hline
\verb|'SUB_ILUTHRS'| & \verb|real(|\emph{kind\_parameter}\verb|)|
\fortinline|'SUB_ILUTHRS'| & \fortinline|real(|\emph{kind\_parameter}\fortinline|)|
& Any real number~$\ge 0$
& 0
& Drop tolerance $t$ in the ILU($p,t$) factorization. \\ %\hline
\verb|'MUMPS_LOC_GLOB'| & \verb|character(len=*)|
& \texttt{LOCAL\_SOLVER'} \par \texttt{GLOBAL\_SOLVER'}
& \texttt{GLOBAL\_SOLVER'}
\fortinline|'MUMPS_LOC_GLOB'| & \fortinline|character(len=*)|
& \fortinline|'LOCAL_SOLVER'| \par \fortinline|'GLOBAL_SOLVER'|
& \fortinline|'GLOBAL_SOLVER'|
& Whether MUMPS should be used as a
distributed solver, or as a serial solver
acting only on the part of the matrix local
to each process. \\ %\hline
\verb|'MUMPS_IPAR_ENTRY'| & \verb|integer|
\fortinline|'MUMPS_IPAR_ENTRY'| & \fortinline|integer|
& Any integer number
& 0
& Set an entry in the MUMPS integer control array, as
chosen via the \verb|idx| optional argument. \\ %\hline
\verb|'MUMPS_RPAR_ENTRY'| & \verb|real|
chosen via the \fortinline|idx| optional argument. \\ %\hline
\fortinline|'MUMPS_RPAR_ENTRY'| & \fortinline|real|
& Any real number
& 0
& Set an entry in the MUMPS real control array, as
chosen via the \verb|idx| optional argument. \\ %\hline
chosen via the \fortinline|idx| optional argument. \\ %\hline
\hline
\end{tabular}
\end{center}
@@ -572,28 +572,27 @@ level (continued).\label{tab:p_coarse_1}}
\subsection{Method hierarchy\_build\label{sec:hier_bld}}
\begin{center}
\verb|call p%hierarchy_build(a,desc_a,info)|\\
\fortinline|call p%hierarchy_build(a,desc_a,info)|\\
\end{center}
\noindent
This method builds the hierarchy of matrices and restriction/prolongation
operators for the multilevel preconditioner \verb|p|, according to the requirements
made by the user through the methods \verb|init| and \verb|set|.
operators for the multilevel preconditioner \fortinline|p|, according to the requirements
made by the user through the methods \fortinline|init| and \fortinline|set|.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|a| & \verb|type(psb_|\emph{x}\verb|spmat_type), intent(in)|. \\
\fortinline|a| & \fortinline|type(psb_|\emph{x}\fortinline|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,
to the \fortinline|real|/\fortinline|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
\fortinline|desc_a| & \fortinline|type(psb_desc_type), intent(in)|. \\
& The communication descriptor of \fortinline|a|. See the PSBLAS User's Guide for
details \cite{PSBLASGUIDE}.\\
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\end{tabular}
@@ -604,38 +603,38 @@ single/double precision version of AMG4PSBLAS under use.
\begin{center}
\verb|call p%smoothers_build(a,desc_a,p,info[,amold,vmold,imold])|\\
\fortinline|call p%smoothers_build(a,desc_a,p,info[,amold,vmold,imold])|\\
\end{center}
\noindent
This method builds the smoothers and the coarsest-level solvers for the
multilevel preconditioner \verb|p|, according to the requirements made by
the user through the methods \verb|init| and \verb|set|, and based on the aggregation
hierarchy produced by a previous call to \verb|hierarchy_build|
multilevel preconditioner \fortinline|p|, according to the requirements made by
the user through the methods \fortinline|init| and \fortinline|set|, and based on the aggregation
hierarchy produced by a previous call to \fortinline|hierarchy_build|
(see Section~\ref{sec:hier_bld}).
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|a| & \verb|type(psb_|\emph{x}\verb|spmat_type), intent(in)|. \\
\fortinline|a| & \fortinline|type(psb_|\emph{x}\fortinline|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 AMG4PSBLAS under use.
to the \fortinline|real|/\fortinline|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
\fortinline|desc_a| & \fortinline|type(psb_desc_type), intent(in)|. \\
& The communication descriptor of \fortinline|a|. See the PSBLAS User's Guide for
details \cite{PSBLASGUIDE}.\\
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\verb|amold| & \verb|class(psb_|\emph{x}\verb|_base_sparse_mat), intent(in), optional|. \\
\fortinline|amold| & \fortinline|class(psb_|\emph{x}\fortinline|_base_sparse_mat), intent(in), optional|. \\
& The desired dynamic type for internal matrix
components; this allows e.g. running on GPUs; it needs not be the
same on all processes. See the PSBLAS User's Guide for
details \cite{PSBLASGUIDE}. \\
\verb|vmold| & \verb|class(psb_|\emph{x}\verb|_base_vect_type), intent(in), optional|. \\
\fortinline|vmold| & \fortinline|class(psb_|\emph{x}\fortinline|_base_vect_type), intent(in), optional|. \\
& The desired dynamic type for internal vector
components; this allows e.g. running on GPUs. \\
\verb|imold| & \verb|class(psb_i_base_vect_type), intent(in), optional|. \\
\fortinline|imold| & \fortinline|class(psb_i_base_vect_type), intent(in), optional|. \\
& The desired dynamic type for internal integer vector
components; this allows e.g. running on GPUs. \\
\end{tabular}
@@ -645,41 +644,41 @@ hierarchy produced by a previous call to \verb|hierarchy_build|
\subsection{Method build\label{sec:precbld}}
\begin{center}
\verb|call p%build(a,desc_a,info[,amold,vmold,imold])|\\
\fortinline|call p%build(a,desc_a,info[,amold,vmold,imold])|\\
\end{center}
\noindent
This method builds the preconditioner \verb|p| according to the requirements
made by the user through the methods \verb|init| and \verb|set|
This method builds the preconditioner \fortinline|p| according to the requirements
made by the user through the methods \fortinline|init| and \fortinline|set|
(see Sections~\ref{sec:hier_bld} and~\ref{sec:smooth_bld} for
multilevel preconditioners). It is mostly provided for backward
compatibility; indeed, it is internally implemented by invoking the
two previous methods \verb|hierarchy_build| and
\verb|smoothers_build|, whose nomenclature would however be somewhat
two previous methods \fortinline|hierarchy_build| and
\fortinline|smoothers_build|, whose nomenclature would however be somewhat
unnatural when dealing with simple one-level preconditioners.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|a| & \verb|type(psb_|\emph{x}\verb|spmat_type), intent(in)|. \\
\fortinline|a| & \fortinline|type(psb_|\emph{x}\fortinline|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 AMG4PSBLAS under use.
to the \fortinline|real|/\fortinline|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
\fortinline|desc_a| & \fortinline|type(psb_desc_type), intent(in)|. \\
& The communication descriptor of \fortinline|a|. See the PSBLAS User's Guide for
details \cite{PSBLASGUIDE}.\\
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\verb|amold| & \verb|class(psb_|\emph{x}\verb|_base_sparse_mat), intent(in), optional|. \\
\fortinline|amold| & \fortinline|class(psb_|\emph{x}\fortinline|_base_sparse_mat), intent(in), optional|. \\
& The desired dynamic type for internal matrix
components; this allows e.g. running on GPUs; it needs not be the
same on all processes. See the PSBLAS User's Guide for
details \cite{PSBLASGUIDE}. \\
\verb|vmold| & \verb|class(psb_|\emph{x}\verb|_base_vect_type), intent(in), optional|. \\
\fortinline|vmold| & \fortinline|class(psb_|\emph{x}\fortinline|_base_vect_type), intent(in), optional|. \\
& The desired dynamic type for internal vector
components; this allows e.g. running on GPUs. \\
\verb|imold| & \verb|class(psb_i_base_vect_type), intent(in), optional|. \\
\fortinline|imold| & \fortinline|class(psb_i_base_vect_type), intent(in), optional|. \\
& The desired dynamic type for internal integer vector
components; this allows e.g. running on GPUs. \\
\end{tabular}
@@ -693,44 +692,44 @@ The method can be used to build multilevel preconditioners too.
\subsection{Method apply\label{sec:precapply}}
\begin{center}
\verb|call p%apply(x,y,desc_a,info [,trans,work])|\\
\fortinline|call p%apply(x,y,desc_a,info [,trans,work])|\\
\end{center}
\noindent
This method computes $y = op(B^{-1})\, x$, where $B$ is a previously built
preconditioner, stored into \verb|p|, and $op$
preconditioner, stored into \fortinline|p|, and $op$
denotes the preconditioner itself or its transpose, according to
the value of \verb|trans|.
the value of \fortinline|trans|.
Note that, when AMG4PSBLAS is used with a Krylov solver from PSBLAS,
\verb|p%apply| is called within the PSBLAS method \verb|psb_krylov|
\fortinline|p%apply| is called within the PSBLAS method \fortinline|psb_krylov|
and hence it is completely transparent to the user.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|x| & \emph{type}\verb|(|\emph{kind\_parameter}\verb|), dimension(:), intent(in)|.\\
\fortinline|x| & \emph{type}\fortinline|(|\emph{kind\_parameter}\fortinline|), 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 AMG4PSBLAS under use.\\
\verb|y| & \emph{type}\verb|(|\emph{kind\_parameter}\verb|), dimension(:), intent(out)|.\\
to the \fortinline|real|/\fortinline|complex|, single/double precision version of AMG4PSBLAS under use.\\
\fortinline|y| & \emph{type}\fortinline|(|\emph{kind\_parameter}\fortinline|), 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 AMG4PSBLAS under use.\\
\verb|desc_a| & \verb|type(psb_desc_type), intent(in)|. \\
to the \fortinline|real|/\fortinline|complex|, single/double precision version of AMG4PSBLAS under use.\\
\fortinline|desc_a| & \fortinline|type(psb_desc_type), intent(in)|. \\
& The communication descriptor associated to the matrix to be
preconditioned.\\
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\verb|trans| & \verb|character(len=1), optional, intent(in).|\\
& If \verb|trans| = \verb|'N','n'| then $op(B^{-1}) = B^{-1}$;
if \verb|trans| = \verb|'T','t'| then $op(B^{-1}) = B^{-T}$
(transpose of $B^{-1})$; if \verb|trans| = \verb|'C','c'| then $op(B^{-1}) = B^{-C}$
\fortinline|trans| & \fortinline|character(len=1), optional, intent(in).|\\
& If \fortinline|trans| = \fortinline|'N','n'| then $op(B^{-1}) = B^{-1}$;
if \fortinline|trans| = \fortinline|'T','t'| then $op(B^{-1}) = B^{-T}$
(transpose of $B^{-1})$; if \fortinline|trans| = \fortinline|'C','c'| then $op(B^{-1}) = B^{-C}$
(conjugate transpose of $B^{-1})$.\\
\verb|work| & \emph{type}\verb|(|\emph{kind\_parameter}\verb|), dimension(:), optional, target|.\\
\fortinline|work| & \emph{type}\fortinline|(|\emph{kind\_parameter}\fortinline|), dimension(:), optional, target|.\\
& Workspace. Its size should be at
least \verb|4 * psb_cd_get_local_| \verb|cols(desc_a)| (see the PSBLAS User's Guide).
least \fortinline|4 * psb_cd_get_local_| \fortinline|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 AMG4PSBLAS under use.\\
to the \fortinline|real|/\fortinline|complex|, single/double precision version of AMG4PSBLAS under use.\\
\end{tabular}
@@ -739,16 +738,16 @@ and hence it is completely transparent to the user.
\subsection{Method free\label{sec:precfree}}
\begin{center}
\verb|call p%free(p,info)|\\
\fortinline|call p%free(p,info)|\\
\end{center}
\noindent
This method deallocates the preconditioner data structure \verb|p|.
This method deallocates the preconditioner data structure \fortinline|p|.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{10.5cm}}
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\end{tabular}
@@ -758,20 +757,20 @@ This method deallocates the preconditioner data structure \verb|p|.
\subsection{Method descr\label{sec:precdescr}}
\begin{center}
\verb|call p%descr(info, [iout])|\\
\fortinline|call p%descr(info, [iout])|\\
\end{center}
\noindent
This method prints a description of the preconditioner \verb|p| to the standard output or
to a file. It must be called after \verb|hierachy_build| and \verb|smoothers_build|,
or \verb|build|, have been called.
This method prints a description of the preconditioner \fortinline|p| to the standard output or
to a file. It must be called after \fortinline|hierachy_build| and \fortinline|smoothers_build|,
or \fortinline|build|, have been called.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\verb|iout| & \verb|integer, intent(in), optional|.\\
\fortinline|iout| & \fortinline|integer, intent(in), optional|.\\
& The id of the file where the preconditioner description
will be printed; the default is the standard output.\\
\end{tabular}
@@ -784,7 +783,7 @@ preconditioner object.
\subsubsection{Method: dump}
\begin{center}
\verb|call p%dump(info[,istart,iend,prefix,head,ac,rp,smoother,solver,global_num])|\\
\fortinline|call p%dump(info[,istart,iend,prefix,head,ac,rp,smoother,solver,global_num])|\\
\end{center}
\noindent
@@ -793,9 +792,9 @@ Dump on file.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\verb|amold| & \verb|class(psb_|\emph{x}\verb|_base_sparse_mat), intent(in), optional|. \\
\fortinline|amold| & \fortinline|class(psb_|\emph{x}\fortinline|_base_sparse_mat), intent(in), optional|. \\
& The desired dynamic type for internal matrix
components; this allows e.g. running on GPUs; it needs not be the
same on all processes. See the PSBLAS User's Guide for
@@ -806,7 +805,7 @@ Dump on file.
\subsubsection{Method: clone}
\begin{center}
\verb|call p%clone(pout,info)|\\
\fortinline|call p%clone(pout,info)|\\
\end{center}
\noindent
@@ -815,11 +814,11 @@ Create a (deep) copy of the preconditioner object.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|pout| & \verb|type(amg_|\emph{x}\verb|prec_type), intent(out)|.\\
\fortinline|pout| & \fortinline|type(amg_|\emph{x}\fortinline|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 AMG4PSBLAS under use.\\
\verb|info| & \verb|integer, intent(out)|.\\
to the \fortinline|real|/\fortinline|complex|, single/double precision version of AMG4PSBLAS under use.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\end{tabular}
@@ -828,7 +827,7 @@ Create a (deep) copy of the preconditioner object.
\subsubsection{Method: sizeof}
\begin{center}
\verb|sz = p%sizeof()|\\
\fortinline|sz = p%sizeof()|\\
\end{center}
\noindent
@@ -837,7 +836,7 @@ Return memory footprint in bytes.
\subsubsection{Method: allocate\_wrk}
\begin{center}
\verb|call p%allocate_wrk(info[, vmold])|\\
\fortinline|call p%allocate_wrk(info[, vmold])|\\
\end{center}
\noindent
@@ -850,18 +849,18 @@ on some platforms, most notably GPUs, memory allocation is
a slow operation, and the default behaviour would lead to a
slowdown. This method allows to trade space for time by preallocating
the internal workspace outside of the invocation of a Krylov
method. When using GPUs or other specialized devices, the \verb|vmold|
method. When using GPUs or other specialized devices, the \fortinline|vmold|
argument is also necessary to ensure the internal work vectors are of
the appropriate dynamic type to exploit the accelerator hardware; when
allocation occurs internally this is taken care of based on the dynamic
type of the \verb|x| argument to the \verb|apply| method.
type of the \fortinline|x| argument to the \fortinline|apply| method.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\verb|vmold| & \verb|class(psb_|\emph{x}\verb|_base_vect_type), intent(in), optional|. \\
\fortinline|vmold| & \fortinline|class(psb_|\emph{x}\fortinline|_base_vect_type), intent(in), optional|. \\
& The desired dynamic type for internal vector
components; this allows e.g. running on GPUs. \\
\end{tabular}
@@ -871,7 +870,7 @@ type of the \verb|x| argument to the \verb|apply| method.
\subsubsection{Method: free\_wrk}
\begin{center}
\verb|call p%free_wrk(info)|\\
\fortinline|call p%free_wrk(info)|\\
\end{center}
\noindent
@@ -880,7 +879,7 @@ Deallocate internal work vectors.
{\vskip1.5\baselineskip\noindent\large\bfseries Arguments} \smallskip
\begin{tabular}{p{1.2cm}p{12cm}}
\verb|info| & \verb|integer, intent(out)|.\\
\fortinline|info| & \fortinline|integer, intent(out)|.\\
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
\end{tabular}