\section { User Interface\label { sec:userinterface} }
\markboth { \underline { MLD2P4 User's and Reference Guide} }
{ \underline { \ref { sec:userinterface} User Interface} }
The basic user interface of MLD2P4 consists of six routines. The four routines \verb |mld_ precinit|,
\verb |mld_ precset|, \verb |mld_ precbld| and \verb |mld_ precaply| encapsulate all the functionalities for the setup and application of any one-level and multi-level
preconditioner implemented in the package.
The routine \verb |mld_ precfree| deallocates the preconditioner data structure, while
\verb |mld_ precdescr| prints a description of the preconditioner setup by the user.
For each routine, the same user interface is overloaded with
respect to the real/complex case and the single/double precision;
arguments with appropriate data types must be passed to the routine,
i.e.
\begin { itemize}
\item the sparse matrix data structure, containing the matrix to be
preconditioned, must be of type \verb |mld_ |\emph { x} \verb |spmat_ type|
with \emph { x} = \verb |s| for real single precision, \emph { x} = \verb |d|
for real double precision, \emph { x} = \verb |c| for complex single precision,
\emph { x} = \verb |z| for complex double precision;
\item the preconditioner data structure must be of type
\verb |mld_ |\emph { x} \verb |prec_ type|, with \emph { x} =
\verb |s|, \verb |d|, \verb |c|, \verb |z|, according to the sparse
matrix data structure;
\item the arrays containing the vectors $ v $ and $ w $ involved in
the preconditioner application $ w = M ^ { - 1 } v $ must be of type
\emph { type} \verb |(|\emph { kind\_ parameter} \verb |)|, with \emph { type} =
\verb |real|, \verb |complex| and \emph { kind\_ parameter} = \verb |kind(1.e0)|,
\verb |kind(1.d0)|, according to the sparse matrix and preconditioner
data structure; note that the PSBLAS module provides the constants \verb |psb_ spk_ |
= \verb |kind(1.e0)| and \verb |psb_ dpk_ | = \verb |kind(1.d0)|;
\item real parameters defining the preconditioner must be declared
according to the precision of the previous data structures
(see Section~\ref { sec:precset} ).
\end { itemize}
A description of each routine is given in the remainder of this section.
\subsection { Subroutine mld\_ precinit\label { sec:precinit} }
\begin { center}
\verb |mld_ precinit(p,ptype,info)| \\
\verb |mld_ precinit(p,ptype,info,nlev)| \\
\end { center}
\noindent
This routine allocates and initializes the preconditioner data structure,
according to the preconditioner type chosen by the user.
\subsubsection * { Arguments}
\begin { tabular} { p{ 1.2cm} p{ 11.5cm} }
\verb |p| & \verb |type(mld_ |\emph { x} \verb |prec_ type), intent(inout)|.\\
& The preconditioner data structure. Note that \emph { x}
must be chosen according to the real/complex, single/double
precision version of MLD2P4 under use.\\
\verb |ptype| & \verb |character(len=*), intent(in)|.\\
& The type of preconditioner. Its values are specified in Table~\ref { tab:precinit} .\\
\verb |info| & \verb |integer, intent(out)|.\\
& Error code. See Section~\ref { sec:errors} for details.\\
\verb |nlev| & \verb |integer, optional, intent(in)|.\\
& The number of levels of the multilevel preconditioner.
If \verb |nlev| is not present and \verb |ptype|='ML'/'ml',
then \verb |nlev|=2 is assumed. Otherwise, \verb |nlev| is ignored.
\end { tabular}
\subsection { Subroutine mld\_ precset\label { sec:precset} }
\begin { center}
\verb |mld_ precset(p,what,val,info)|\\
\end { center}
\noindent
This routine sets the parameters defining the preconditioner. More
precisely, the parameter identified by \verb |what| is assigned the value
contained in \verb |val|.
\subsubsection * { Arguments}
\begin { tabular} { p{ 1.2cm} p{ 11.5cm} }
\verb |p| & \verb |type(mld_ |\emph { x} \verb |prec_ type), intent(inout)|.\\
& The preconditioner data structure. Note that \emph { x} must
be chosen according to the real/complex, single/double precision
version of MLD2P4 under use.\\
\verb |what| & \verb |integer, intent(in)|. \\
& The number identifying the parameter to be set.
A mnemonic constant has been associated to each of these
numbers, as reported in Tables~\ref { tab:p_ type} -\ref { tab:p_ coarse} .\\
\verb |val | & \verb |integer| \emph { or} \verb |character(len=*)| \emph { or}
\verb |real(psb_ spk_ )| \emph { or} \verb |real(psb_ dpk_ )|,
\verb |intent(in)|.\\
& The value of the parameter to be set. The list of allowed
values and the corresponding data types is given in
Table~\ref { tab:params} .\\
\verb |info| & \verb |integer, intent(out)|.\\
& Error code. See Section~\ref { sec:errors} for details.\\
%\verb|ilev| & \verb|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|
% is set at all the appropriate levels (see Table~\ref{tab:params}).
\end { tabular}
\ \\
A variety of (one-level and multi-level) preconditioner can be obtained
by a suitable setting of the preconditioner parameters. These parameters
can be logically divided into four groups, i.e.\ parameters defining
\begin { enumerate}
\item the type of multi-level preconditioner;
\item the one-level preconditioner to be used as smoother;
\item the aggregation algorithm;
\item the coarse-space correction at the coarsest level.
\end { enumerate}
A list of the parameters that can be set, along with their allowed and
default values, is given in Tables~\ref { tab:p_ type} -\ref { tab:p_ coarse} .
%Note that the routine allows to set different features of the
%preconditioner at each level through the use of \verb|ilev|.
%This should be done by users with experience in the field of
%multi-level preconditioners. Non-expert users are recommended
%to call \verb| mld_precset| without specifying \verb|ilev|.
\textbf { CORREGGERE LA ROUTINE E LA DOC INTERNA - ilev NON E' PIU'
ACCESSIBILE ALL'UTENTE.}
\begin { sidewaystable}
\begin { center}
\begin { tabular} { |l|l|p{ 2cm} |l|p{ 7cm} |}
\hline
\verb |what| & \emph { data type} & \verb |val| & \emph { default} &
\emph { comments} \\ \hline
%\multicolumn{5}{|c|}{\emph{type of the multi-level preconditioner}}\\ \hline
\verb |mld_ ml_ type_ | & \verb |character(len=*)|
& 'ADD' \ \ \ 'MULT'
& 'MULT'
& basic multi-level framework: additive or multiplicative
among the levels always additive inside a level) \\
\verb |mld_ smoother_ type_ |& \verb |character(len=*)|
& 'DIAG' \ \ \ 'BJAC' \ \ \ 'AS'
& 'AS'
& basic one-level preconditioner (i.e.\ smoother) of the
multi-level preconditioner \\
\verb |mld_ smoother_ pos_ | & \verb |character(len=*)|
& 'PRE' \ \ \ 'POST' \ \ \ 'TWOSIDE'
& 'POST'
& ``position'' of the smoother: pre-smoother, post-smoother,
pre-/post-smoother \\
\hline
\end { tabular}
\end { center}
\caption { Parameters defining the type of multi-level preconditioner.
\label { tab:p_ type} }
\end { sidewaystable}
\begin { sidewaystable}
\begin { center}
\begin { tabular} { |l|l|p{ 2cm} |l|p{ 7cm} |}
\hline
\verb |what| & \emph { data type} & \verb |val| & \emph { default} &
\emph { comments} \\ \hline
%\multicolumn{5}{|c|}{\emph{basic one-level preconditioner (smoother)}} \\ \hline
\verb |mld_ sub_ ovr| & \verb |integer|
& any number $ \ge 0 $
& 1
& number of overlap in the basic Schwarz preconditioner \\
\verb |mld_ sub_ restr_ | & \verb |character(len=*)|
& 'HALO' \ \ \ 'NONE'
& 'HALO'
& type of restriction operator used in basic Schwarz preconditioner: 'HALO' for taking into account contributions from the overlap \\
\verb |mld_ sub_ prol_ | & \verb |character(len=*)|
& 'SUM' \ \ \ 'NONE'
& 'NONE'
& type of prolongator operator used in basic Schwarz preconditioner: 'NONE' for neglecting contributions from the overlap \\
\verb |mld_ sub_ solve_ | & \verb |character(len=*)|
& 'ILU' \ \ \ 'MILU' \ \ \ 'ILUT' \ \ \ 'UMF' \ \ \ 'SLU'
& 'UMF'
& available local solver: 'ILU' for incomplete LU, 'MILU' for modified incomplete LU, 'ILUT'
for incomplete LU with threshold, 'UMF' for complete LU using UMFPACK~\cite { UMFPACK} version 4.4, 'SLU' for complete LU using SuperLU~\cite { SUPERLU} , version 3.0 \\
\verb |mld_ sub_ fillin_ | & \verb |integer|
& any number $ \ge 0 $
& 0
& fill-in level for 'ILU', 'MILU' and 'ILUT' of local blocks\\
\verb |mld_ sub_ thresh_ | & \verb |real|
& any number $ \ge 0 . $
& 0.
& drop tolerance for 'ILUT' \\
\verb |mld_ sub_ ren_ | & \verb |character(len=*)|
& 'RENUM\_ NONE', 'RENUM\_ GLOBAL' %, 'RENUM\_GPS'
&
& reordering algorithm for the local blocks \\
\hline
\end { tabular}
\end { center}
\caption { Parameters defining the basic one-level preconditioner (smoother).
\label { tab:p_ smoother} }
\end { sidewaystable}
\begin { sidewaystable}
\begin { center}
\begin { tabular} { |l|l|p{ 2cm} |l|p{ 7cm} |}
\hline
\verb |what| & \emph { data type} & \verb |val| & \emph { default} &
\emph { comments} \\ \hline
%\multicolumn{5}{|c|}{\emph{aggregation algorithm}} \\ \hline
\verb |mld_ aggr_ alg_ | & \verb |character(len=*)|
& 'DEC'
& 'DEC'
& define the aggregation scheme. Now, only decoupled aggregation is available\\
\verb |mld_ aggr_ kind_ | & \verb |character(len=*)|
& 'SMOOTH', 'RAW'
& 'SMOOTH'
& define the type of aggregation technique (smoothed or nonsmoothed). \\
\verb |mld_ aggr_ thresh_ | & \verb |real|
& any number $ \in [ 0 , 1 ] $
& 0.
& dropping threshold in aggregation \\
\verb |mld_ aggr_ eig_ | & \verb |character(len=*)|
& 'A\_ NORMI'
&
& define the algorithm to evaluate the maximum eigenvalue of $ D ^ { - 1 } A $ for smoothed
aggregation. Currently only the infinity norm of the matrix A is available\\
\hline
\end { tabular}
\end { center}
\caption { Parameters defining the aggregation algorithm.
\label { tab:p_ aggregation} }
\end { sidewaystable}
\begin { sidewaystable}
\begin { center}
\begin { tabular} { |l|l|p{ 2cm} |l|p{ 7cm} |}
\hline
\verb |what| & \emph { data type} & \verb |val| & \emph { default} &
\emph { comments} \\ \hline
%\multicolumn{5}{|c|}{\emph{coarse-space correction at the coarsest level}}\\ \hline
\verb |mld_ coarse_ mat_ | & \verb |character(len=*)|
& 'DISTR', 'REPL'
& 'DISTR'
& Coarse matrix: distributed or replicated \\
\verb |mld_ coarse_ solve_ | & \verb |character(len=*)|
& 'BJAC' \ \ \ 'UMF' \ \ \ 'SLU' \ \ \ 'SLUDIST'
& 'BJAC'
& Only 'BJAC' and 'SLUDIST' can be used for distributed coarse matrix. 'BJAC' corresponds to some sweeps of a block-Jacobi solver, while 'SLUDIST' corresponds
to the use of the external package SuperLU\_ Dist~\cite { SUPERLUDIST} , version 2.0, for distributed sparse factorization and solve. \\
\verb |mld_ coarse_ subsolve_ | & \verb |character(len=*)|
& 'ILU' \ \ \ 'MILU' \ \ \ 'ILUT' \ \ \ 'UMF' \ \ \ 'SLU'
& 'UMF'
& available solver for diagonal local blocks of the coarse matrix, when 'BJAC' is used as coarse solver\\
\verb |mld_ coarse_ sweeps_ |& \verb |integer|
& any number $ > 0 $
& 4
& number of Block-Jacobi sweeps when 'BJAC' is used as coarse solver \\
\verb |mld_ coarse_ fillin_ | & \verb |integer|
& any number $ \ge 0 $
& 0
& fill-in level in incomplete factorization of local diagonal blocks of the coarse matrix, when 'BJAC' is used as coarse solver and 'ILU' or 'MILU' is used as local solver \textbf { MODIFICA NOME PARAM. NEL SW} \\
\verb |mld_ coarse_ thresh_ | & \verb |real|
& any number $ \ge 0 . $
& 0.
& drop tolerance in incomplete factorization of local diagonal blocks of the coarse matrix, when 'BJAC' is used as coarse solver and 'ILUT' is used as local solver \\ \hline
\end { tabular}
\end { center}
\caption { Parameters defining the coarse-space correction at the coarsest
level.\label { tab:p_ coarse} }
\end { sidewaystable}
\clearpage
\subsection { Subroutine mld\_ precbld\label { sec:precbld} }
\begin { center}
\verb |mld_ precbld(a,desc_ a,p,info)|\\
\end { center}
\noindent
This routine builds the preconditioner according to the requirements made by
the user through the routines \verb |mld_ precinit| and \verb |mld_ precset|.
\subsubsection * { Arguments}
\begin { tabular} { p{ 1.2cm} p{ 11.5cm} }
\verb |a| & \verb |type(psb_ |\emph { x} \verb |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 MLD2P4 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 a. See the PSBLAS User's Guide for
details \cite { PSBLASGUIDE} .\\
\verb |p| & \verb |type(mld_ |\emph { x} \verb |prec_ type), intent(inout)|.\\
& The preconditioner data structure. Note that \emph { x} must be chosen according
to the real/complex, single/double precision version of MLD2P4 under use.\\
\verb |info| & \verb |integer, intent(out)|.\\
& Error code. See Section~\ref { sec:errors} for details.\\
\end { tabular}
\clearpage
\subsection { Subroutine mld\_ precaply\label { sec:precaply} }
\begin { center}
\verb |mld_ precaply(p,x,y,desc_ a,info)|\\
\verb |mld_ precaply(p,x,y,desc_ a,info,trans,work)|\\
\end { center}
\noindent
This routine computes $ y = op ( M ^ { - 1 } ) \, x $ , where $ M $ is a previously built
preconditioner, stored in the \verb |p| data structure, and $ op $
denotes the preconditioner itself or its transpose, according to
the value of \verb |trans|.
Note that, when MLD2P4 is used with a Krylov solver from PSBLAS,
\verb |mld_ precaply| is called within the PSBLAS routine \verb |mld_ krylov|
and hence is completely transparent to the user.
\subsubsection * { Arguments}
\begin { tabular} { p{ 1.2cm} p{ 11.5cm} }
\verb |p| & \verb |type(mld_ |\emph { x} \verb |prec_ type), intent(inout)|.\\
& The preconditioner data structure, containing the local part of $ M $ .
Note that \emph { x} must be chosen according
to the real/complex, single/double precision version of MLD2P4 under use.\\
\verb |x| & \emph { type} \verb |(|\emph { kind\_ parameter} \verb |), 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 MLD2P4 under use.\\
\verb |y| & \emph { type} \verb |(|\emph { kind\_ parameter} \verb |), 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 MLD2P4 under use.\\
\verb |desc_ a| & \verb |type(psb_ desc_ type), intent(in)|. \\
& The communication descriptor associated to the matrix to be
preconditioned.\\
\verb |info| & \verb |integer, intent(out)|.\\
& Error code. See Section~\ref { sec:errors} for details.\\
\verb |trans| & \verb |character(len=1), optional, intent(in).|\\
& If \verb |trans| = \verb |'N','n'| then $ op ( M ^ { - 1 } ) = M ^ { - 1 } $ ;
if \verb |trans| = \verb |'T','t'| then $ op ( M ^ { - 1 } ) = M ^ { - T } $
(transpose of $ M ^ { - 1 } ) $ ; if \verb |trans| = \verb |'C','c'| then $ op ( M ^ { - 1 } ) = M ^ { - C } $
(conjugate transpose of $ M ^ { - 1 } ) $ .\\
\verb |work| & \emph { type} \verb |(|\emph { kind\_ parameter} \verb |), dimension(:), optional, target|.\\
& Workspace. Its size should be at
least \verb |4 * psb_ cd_ get_ local_ 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 MLD2P4 under use.\\
\end { tabular}
\subsection { Subroutine mld\_ precfree\label { sec:precfree} }
\begin { center}
\verb |mld_ precfree(p,info)|\\
\end { center}
\noindent
This routine deallocates the preconditioner data structure.
\subsubsection * { Arguments}
\begin { tabular} { p{ 1.2cm} p{ 11.5cm} }
\verb |p| & \verb |type(mld_ |\emph { x} \verb |prec_ type), intent(inout)|.\\
& The preconditioner data structure. Note that \emph { x} must be chosen according
to the real/complex, single/double precision version of MLD2P4 under use.\\
\verb |info| & \verb |integer, intent(out)|.\\
& Error code. See Section~\ref { sec:errors} for details.\\
\end { tabular}
\subsection { Subroutine mld\_ precdescr\label { sec:precdescr} }
\begin { center}
\verb |mld_ precdescr(p,iout)|\\
\end { center}
\noindent
This routine prints a description of the preconditioner
to a file.
\subsubsection * { Arguments}
\begin { tabular} { p{ 1.2cm} p{ 10.6cm} }
\verb |p| & \verb |type(mld_ |\emph { x} \verb |prec_ type), intent(in)|.\\
& The preconditioner data structure. Note that \emph { x} must be chosen according
to the real/complex, single/double precision version of MLD2P4 under use.\\
\verb |iout| & \verb |integer, intent(in), optional|.\\
& The id of the file where the preconditioner description
will be printed, default is standard output.\\
\end { tabular}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "userguide"
%%% End:
