You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
psblas3/docs/pdf/precs.tex

197 lines
5.7 KiB
TeX

19 years ago
\section{Preconditioner routines}
\label{sec:precs}
% \section{Preconditioners}
\label{sec:psprecs}
18 years ago
The base PSBLAS library contains the implementation of two simple
preconditioning techniques:
\begin{itemize}
\item Diagonal Scaling
\item Block Jacobi with ILU(0) factorization
%% \item Additive Schwarz with the Restricted Additive Schwarz and
%% Additive Schwarz with Harmonic extensions;
\end{itemize}
18 years ago
The supporting data type and subroutine interfaces are defined in the
module \verb|psb_prec_mod|.
%% 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{psb\_precinit}{Initialize a preconditioner}
\syntax{call psb\_precinit}{prec, ptype, info}
\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.
18 years ago
%% \item[iv] integer parameters for the precondtioner.
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Specified as: an integer array, 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}
18 years ago
%% 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. Only the incomplete factorization $ILU(0)$ is
currently implemented.
\end{description}
\subroutine{psb\_precbld}{Builds a preconditioner}
\syntax{call psb\_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}
\subroutine{psb\_precaply}{Preconditioner application routine}
\syntax{call psb\_precaply}{prec,x,y,desc\_a,info,trans,work}
\syntax*{call psb\_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{psb\_prec\_descr}{Prints a description of current preconditioner}
\syntax{call psb\_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}
19 years ago
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: