New docs for release: merged Daniela's comments.
Salvatore Filippone
9 years ago
parent
9330489e6e
commit
6097a8fbb6
File diff suppressed because one or more lines are too long
@ -1,34 +0,0 @@
|
||||
\section{Introduction}\label{sec:intro}
|
||||
\markboth{\underline{MLD2P4 User's and Reference Guide}}
|
||||
{\underline{\ref{sec:overview} Introduction}}
|
||||
|
||||
The MLD2P4 library provides ....
|
||||
|
||||
|
||||
\subsection{Programming model}
|
||||
|
||||
The MLD2P4 librarary is based on the Single Program Multiple Data
|
||||
(SPMD) programming model: each process participating in the
|
||||
computation performs the same actions on a chunk of data. Parallelism
|
||||
is thus data-driven.
|
||||
|
||||
Because of this structure, many subroutines coordinate their action
|
||||
across the various processes, thus providing an implicit
|
||||
synchronization point, and therefore \emph{must} be
|
||||
called simultaneously by all processes participating in the
|
||||
computation.
|
||||
However there are many cases where no synchronization, and indeed no
|
||||
communication among processes, is implied.
|
||||
|
||||
Throughout this user's guide each subroutine will be clearly indicated
|
||||
as:
|
||||
\begin{description}
|
||||
\item[Synchronous:] must be called simultaneously by all the
|
||||
processes in the relevant communication context;
|
||||
\item[Asynchronous:] may be called in a totally independent manner.
|
||||
\end{description}
|
||||
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
%%% TeX-master: "userguide"
|
||||
%%% End:
|
||||
@ -0,0 +1,85 @@
|
||||
|
||||
\clearpage
|
||||
|
||||
\section{Adding new smoother and solver objects to MLD2P4\label{sec:adding}}
|
||||
|
||||
Developers can add completely new smoother and/or solver classes
|
||||
derived from the base objects in the library (see Remark~2 in Section~\ref{sec:precset}),
|
||||
without recompiling the library itself.
|
||||
|
||||
To do so, it is necessary first to select the base type to be extended.
|
||||
In our experience, it is quite likely that the new application needs
|
||||
only the definition of a ``solver'' object, which is almost
|
||||
always acting only on the local part of the distributed matrix.
|
||||
The parallel actions required to connect the various solver objects
|
||||
are most often already provided by the block-Jacobi or the additive
|
||||
Schwarz smoothers. To define a new solver, the developer will then
|
||||
have to define its components and methods, perhaps taking one of the
|
||||
predefined solvers as a starting point, if possible.
|
||||
|
||||
Once the new smoother/solver class has been developed, to use it in
|
||||
the context of the multilevel preconditioners it is necessary to:
|
||||
\begin{itemize}
|
||||
\item declare in the application program a variable of the new type;
|
||||
\item pass that variable as the argument to the \verb|set| routine as in the
|
||||
following:
|
||||
\begin{center}
|
||||
\verb|call p%set(smoother,info [,ilev,ilmax,pos])|\\
|
||||
\verb|call p%set(solver,info [,ilev,ilmax,pos])|
|
||||
\end{center}
|
||||
\item link the code implementing the various methods into the application executable.
|
||||
\end{itemize}
|
||||
The new solver object is then dynamically included in the
|
||||
preconditioner structure, and acts as a \emph{mold} to which the
|
||||
preconditioner will conform, even though the MLD2P4 library has not
|
||||
been modified to account for this new development.
|
||||
|
||||
It is possible to define new values for the keyword \verb|WHAT| in the
|
||||
\verb|set| routine; if the library code does not recognize a keyword,
|
||||
it passes it down the composition hierarchy (levels containing
|
||||
smoothers containing in turn solvers), so that it can be eventually caught by
|
||||
the new solver.
|
||||
|
||||
An example is provided in the source code distribution under the
|
||||
folder \verb|tests/newslv|. In this example we are implementing a new
|
||||
incomplete factorization variant (which is simply the ILU(0)
|
||||
factorization under a new name). Because of the specifics of this case, it is
|
||||
possible to reuse the basic structure of the ILU solver, with its
|
||||
L/D/U components and the methods needed to apply the solver; only a
|
||||
few methods, such as the description and most importantly the build,
|
||||
need to be ovverridden (rewritten).
|
||||
|
||||
The interfaces for the calls shown above are defined using
|
||||
\begin{center}
|
||||
\begin{tabular}{p{1.4cm}p{12cm}}
|
||||
\verb|smoother| & \verb|class(mld_x_base_smoother_type)| \\
|
||||
& The user-defined new smoother to be employed in the
|
||||
preconditioner.\\
|
||||
\verb|solver| & \verb|class(mld_x_base_solver_type)| \\
|
||||
& The user-defined new solver to be employed in the
|
||||
preconditioner.
|
||||
\end{tabular}
|
||||
\end{center}
|
||||
The other arguments are defined in the way described in
|
||||
Sec.~\ref{sec:precset}. As an example, in the \verb|tests/newslv|
|
||||
code we define a new object of type \verb|mld_d_tlu_solver_type|, and
|
||||
we pass it as follows:
|
||||
\begin{verbatim}
|
||||
|
||||
! sparse matrix and preconditioner
|
||||
type(psb_dspmat_type) :: a
|
||||
type(mld_dprec_type) :: prec
|
||||
type(mld_d_tlu_solver_type) :: tlusv
|
||||
|
||||
......
|
||||
!
|
||||
! prepare the preconditioner: an ML with defaults, but with TLU solver at
|
||||
! intermediate levels. All other parameters are at default values.
|
||||
!
|
||||
call prec%init('ML', info)
|
||||
call prec%hierarchy_build(a,desc_a,info)
|
||||
nlv = prec%get_nlevs()
|
||||
call prec%set(tlusv, info,ilev=1,ilmax=max(1,nlv-1))
|
||||
call prec%smoothers_build(a,desc_a,info)
|
||||
|
||||
\end{verbatim}
|
||||
@ -1,384 +0,0 @@
|
||||
\section{Preconditioner routines}
|
||||
\label{sec:precs}
|
||||
\markboth{\underline{MLD2P4 User's and Reference Guide}}
|
||||
{\underline{\ref{sec:precs} Preconditioners}}
|
||||
|
||||
% \section{Preconditioners}
|
||||
\label{sec:psprecs}
|
||||
The MLD2P4 library contains the implementation of many preconditioning
|
||||
techniques. The preconditioners may be applied as normal ``base''
|
||||
preconditioners; alternatively multiple ``base'' preconditioners may
|
||||
be combined in a multilevel framework.
|
||||
|
||||
The base (one-level) preconditioners include:
|
||||
\begin{itemize}
|
||||
\item Diagonal Scaling
|
||||
\item Block Jacobi
|
||||
\item Hybrid Gauss-Seidel;
|
||||
\item Additive Schwarz, Restricted Additive Schwarz and
|
||||
Additive Schwarz with Harmonic extensions;
|
||||
\end{itemize}
|
||||
The Jacobi and Additive Schwarz preconditioners can make use of the
|
||||
following solvers:
|
||||
\begin{itemize}
|
||||
\item Level-$p$ Incomplete LU factorization ($ILU(p)$);
|
||||
\item Threshold Incomplete LU factorization ($ILU(\tau,p)$);
|
||||
\item Complete LU factorization by means of the following optional
|
||||
external packages:
|
||||
\begin{itemize}
|
||||
\item UMFPACK;
|
||||
\item SuperLU;
|
||||
\item SuperLU\_Dist.
|
||||
\end{itemize}
|
||||
\end{itemize}
|
||||
|
||||
The supporting data type and subroutine interfaces are defined in the
|
||||
module \verb|mld_prec_mod|; the module also overrides the variables
|
||||
and tyep definitions of \verb|psb_prec_mod| so as to function as a
|
||||
drop-in replacement for the PSBLAS methods. Thus if the user does not
|
||||
wish to employ the additional MLD2P4 capabitlities, it is possible to
|
||||
migrate an existing PSBLAS program without any source code
|
||||
modifications, only a recompilation is needed.
|
||||
|
||||
%% We also provide a companion package of multi-level Additive
|
||||
%% Schwarz preconditioners called MD2P4; this is actually a family of
|
||||
%% preconditioners since there is the possibility to choose between
|
||||
%% many variants, and is currently in an experimental stateIts
|
||||
%% documentation is planned to appear after stabilization of the
|
||||
%% package, which will characterize release 2.1 of our library.
|
||||
|
||||
|
||||
|
||||
|
||||
\subroutine{mld\_precinit}{Initialize a preconditioner}
|
||||
|
||||
\syntax{call mld\_precinit}{prec, ptype, info}
|
||||
\syntax*{call mld\_precinit}{prec, ptype, info, nlev}
|
||||
|
||||
\begin{description}
|
||||
\item[Type:] Asynchronous.
|
||||
\item[\bf On Entry]
|
||||
\item[ptype] the type of preconditioner.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}.\\
|
||||
Specified as: a character string, see usage notes.
|
||||
\item[nlev] Number of levels in a multilevel precondtioner.
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: an integer value, see usage notes.
|
||||
%% \item[rs]
|
||||
%% Scope: {\bf global} \\
|
||||
%% Type: {\bf optional}\\
|
||||
%% Specified as: a long precision real number.
|
||||
\item[\bf On Exit]
|
||||
|
||||
\item[prec]
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: a preconditioner data structure \precdata.
|
||||
\item[info]
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf out}.\\
|
||||
Error code: if no error, 0 is returned.
|
||||
\end{description}
|
||||
\subsection*{Usage Notes}
|
||||
%% The PSBLAS 2.0 contains a number of preconditioners, ranging from a
|
||||
%% simple diagonal scaling to 2-level domain decomposition. These
|
||||
%% preconditioners may use the SuperLU or the UMFPACK software, if
|
||||
%% installed; see~\cite{SUPERLU,UMFPACK}.
|
||||
Legal inputs to this subroutine are interpreted depending on the
|
||||
$ptype$ string as follows\footnote{The string is case-insensitive}:
|
||||
\begin{description}
|
||||
\item[NONE] No preconditioning, i.e. the preconditioner is just a copy
|
||||
operator.
|
||||
\item[DIAG] Diagonal scaling; each entry of the input vector is
|
||||
multiplied by the reciprocal of the sum of the absolute values of
|
||||
the coefficients in the corresponding row of matrix $A$;
|
||||
\item[BJAC] Precondition by a factorization of the
|
||||
block-diagonal of matrix $A$, where block boundaries are determined
|
||||
by the data allocation boundaries for each process; requires no
|
||||
communication.
|
||||
\item[AS] Additive Schwarz; default is to apply the Restricted
|
||||
Additive Schwarz variant, with an $ILU(0)$ factorization
|
||||
\item[ML] Multilevel preconditioner.
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
\subroutine{mld\_precset}{Set preconditioner features}
|
||||
|
||||
\syntax{call mld\_precset}{prec, what, val, info, ilev, pos}
|
||||
\syntax{call prec\%set}{what, val, info, ilev, pos}
|
||||
|
||||
|
||||
\begin{description}
|
||||
\item[Type:] Asynchronous.
|
||||
\item[\bf On Entry]
|
||||
\item[prec] the preconditioner.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: an already initialized precondtioner data structure \precdata\\
|
||||
\item[what] The feature to be set. \\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}.\\
|
||||
Specified as: an integer constant or a string. Symbolic names are
|
||||
available in the library module, see usage notes for legal values.
|
||||
\item[val] The value to set the chosen feature to. \\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}.\\
|
||||
Specified as: an integer, double precision or character variable.
|
||||
Symbolic names for some choices are available in the library module,
|
||||
see usage notes for legal values.
|
||||
\item[ilev] The level of a multilevel preconditioner to which the
|
||||
feature choice should apply.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: an integer value, see usage notes.
|
||||
\item[pos] The position of the smoother/solver to which the current
|
||||
setting applies.
|
||||
feature choice should apply.\\
|
||||
Scope: {\bf global} \\
|
||||
Type: {\bf optional}\\
|
||||
Specified as: a character variable, with values \verb|pre| or \verb|post|.
|
||||
\end{description}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Return]
|
||||
\item[prec] the preconditioner.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: a precondtioner data structure \precdata\\
|
||||
\item[info] Error code.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required} \\
|
||||
Intent: {\bf out}.\\
|
||||
An integer value; 0 means no error has been detected.
|
||||
\end{description}
|
||||
|
||||
\subsection*{Usage Notes}
|
||||
Legal inputs to this subroutine are interpreted depending on the value
|
||||
of \verb|what| input as follows
|
||||
\begin{description}
|
||||
\item[mld\_coarse\_mat\_]
|
||||
\end{description}
|
||||
|
||||
\subroutine{mld\_hierarchy\_bld}{Builds a matrix hierarchy}
|
||||
|
||||
\syntax{call mld\_hierarchy\_bld}{a, desc\_a, prec, info}
|
||||
|
||||
\begin{description}
|
||||
\item[Type:] Synchronous.
|
||||
\item[\bf On Entry]
|
||||
\item[a] the system sparse matrix.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}, target.\\
|
||||
Specified as: a sparse matrix data structure \spdata.
|
||||
\item[prec] the preconditioner.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: an already initialized precondtioner data structure \precdata\\
|
||||
\item[desc\_a] the problem communication descriptor.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}, target.\\
|
||||
Specified as: a communication descriptor data structure \descdata.
|
||||
%% \item[upd]
|
||||
%% Scope: {\bf global} \\
|
||||
%% Type: {\bf optional}\\
|
||||
%% Intent: {\bf in}.\\
|
||||
%% Specified as: a character.
|
||||
\end{description}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Return]
|
||||
\item[prec] the preconditioner, with all the matrices and transfer
|
||||
operators updated.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: a precondtioner data structure \precdata\\
|
||||
\item[info] Error code.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required} \\
|
||||
Intent: {\bf out}.\\
|
||||
An integer value; 0 means no error has been detected.
|
||||
\end{description}
|
||||
|
||||
|
||||
\subroutine{mld\_smoothers\_bld}{Builds the smoothers}
|
||||
|
||||
\syntax{call mld\_smoothers\_bld}{a, desc\_a, prec, info}
|
||||
|
||||
\begin{description}
|
||||
\item[Type:] Synchronous.
|
||||
\item[\bf On Entry]
|
||||
\item[a] the system sparse matrix.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}, target.\\
|
||||
Specified as: a sparse matrix data structure \spdata.
|
||||
\item[prec] the preconditioner.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: an already initialized precondtioner data structure
|
||||
\precdata\ with an already built matrix hierarchy \\
|
||||
\item[desc\_a] the problem communication descriptor.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}, target.\\
|
||||
Specified as: a communication descriptor data structure \descdata.
|
||||
%% \item[upd]
|
||||
%% Scope: {\bf global} \\
|
||||
%% Type: {\bf optional}\\
|
||||
%% Intent: {\bf in}.\\
|
||||
%% Specified as: a character.
|
||||
\end{description}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Return]
|
||||
\item[prec] the preconditioner, with all the smoothers and solvers
|
||||
updated.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: a precondtioner data structure \precdata\\
|
||||
\item[info] Error code.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required} \\
|
||||
Intent: {\bf out}.\\
|
||||
An integer value; 0 means no error has been detected.
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
|
||||
\subroutine{mld\_precbld}{Builds a preconditioner}
|
||||
|
||||
\syntax{call mld\_precbld}{a, desc\_a, prec, info}
|
||||
|
||||
\begin{description}
|
||||
\item[Type:] Synchronous.
|
||||
\item[\bf On Entry]
|
||||
\item[a] the system sparse matrix.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}, target.\\
|
||||
Specified as: a sparse matrix data structure \spdata.
|
||||
\item[prec] the preconditioner.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: an already initialized precondtioner data structure \precdata\\
|
||||
\item[desc\_a] the problem communication descriptor.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}, target.\\
|
||||
Specified as: a communication descriptor data structure \descdata.
|
||||
%% \item[upd]
|
||||
%% Scope: {\bf global} \\
|
||||
%% Type: {\bf optional}\\
|
||||
%% Intent: {\bf in}.\\
|
||||
%% Specified as: a character.
|
||||
\end{description}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Return]
|
||||
\item[prec] the preconditioner.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: a precondtioner data structure \precdata\\
|
||||
\item[info] Error code.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required} \\
|
||||
Intent: {\bf out}.\\
|
||||
An integer value; 0 means no error has been detected.
|
||||
\end{description}
|
||||
|
||||
|
||||
\subsection*{Usage Notes}
|
||||
A call to this routine is equivalent to a call to
|
||||
\verb|mld_hierarchy_bld| followed by a call to \verb|mld_smnoothers_bld|.
|
||||
|
||||
|
||||
\subroutine{mld\_precaply}{Preconditioner application routine}
|
||||
|
||||
\syntax{call mld\_precaply}{prec,x,y,desc\_a,info,trans,work}
|
||||
\syntax*{call mld\_precaply}{prec,x,desc\_a,info,trans}
|
||||
|
||||
\begin{description}
|
||||
\item[Type:] Synchronous.
|
||||
\item[\bf On Entry]
|
||||
\item[prec] the preconditioner.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}.\\
|
||||
Specified as: a preconditioner data structure \precdata.
|
||||
\item[x] the source vector.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: a double precision array.
|
||||
\item[desc\_a] the problem communication descriptor.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}.\\
|
||||
Specified as: a communication data structure \descdata.
|
||||
\item[trans]
|
||||
Scope: {\bf } \\
|
||||
Type: {\bf optional}\\
|
||||
Intent: {\bf in}.\\
|
||||
Specified as: a character.
|
||||
\item[work] an optional work space
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf optional}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: a double precision array.
|
||||
\end{description}
|
||||
|
||||
\begin{description}
|
||||
\item[\bf On Return]
|
||||
\item[y] the destination vector.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf inout}.\\
|
||||
Specified as: a double precision array.
|
||||
\item[info] Error code.\\
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required} \\
|
||||
Intent: {\bf out}.\\
|
||||
An integer value; 0 means no error has been detected.
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
\subroutine{mld\_prec\_descr}{Prints a description of current preconditioner}
|
||||
|
||||
\syntax{call mld\_prec\_descr}{prec}
|
||||
|
||||
\begin{description}
|
||||
\item[Type:] Asynchronous.
|
||||
\item[\bf On Entry]
|
||||
\item[prec] the preconditioner.
|
||||
Scope: {\bf local} \\
|
||||
Type: {\bf required}\\
|
||||
Intent: {\bf in}.\\
|
||||
Specified as: a preconditioner data structure \precdata.
|
||||
\end{description}
|
||||
|
||||
|
||||
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
%%% TeX-master: "userguide"
|
||||
%%% End:
|
||||
Loading…
Reference in New Issue