\section{Preconditioner routines}
\label{sec:precs}

% \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 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}


\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 constants. 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. 
\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\_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}



\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: