\section{User Interface\label{sec:highlevel}}
\markboth{\underline{MLD2P4 User's and Reference Guide}}
         {\underline{\ref{sec:overview} 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 available independently of the real/complex case
and of the single/double precision. However, 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{precision}\verb|)|, with \emph{type} = \verb|real|, \verb|complex| and
  \emph{precision} = \verb|1.|, \verb|1.d0|, according to the sparse matrix and preonditioner data structure;
\item some parameters defining the preconditioner are \verb|real(1.)| or \verb|real(1.d0)|, 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}
\begin{tabular}{|c|}
\hline
\verb|mld_precinit(p,ptype,info)|\\
\verb|mld_precinit(p,ptype,info,nlev)|\\
\hline
\end{tabular}
\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)|\\
\verb|mld_precset(p,what,val,info,ilev)|
\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 Table~\ref{tab:params}.\\
\verb|val |   & \verb|integer| \emph{or} \verb|character(len=*)| \emph{or} \verb|real(1.0)|
                \emph{or} \verb|real(1.0d0)|,\\
              & \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 basic structure of the 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, and the levels
at which their are appropriate is given in Table~\ref{tab:params}. Note that the routines 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|. 


% \begin{table}[p]
\begin{sidewaystable}
\begin{center}
\begin{tabular}{|l|l|p{1.5cm}|l|p{6cm}|}
\hline
\verb|what|              & \emph{data type}        &  \verb|val|      &  \verb|ilev|  & \emph{comments} \\ \hline
\multicolumn{5}{|c|}{\emph{basic structure of the multi-level preconditioner}}                          \\ \hline
\verb|mld_ml_type_|      & \verb|character(len=*)|
                         & 'ADD', 'MULT'   
                         &  2,...,\verb|nlev|
                         & basic multi-level framework: additive or multiplicative among the levels
                          (always additive inside a level); when \verb|ilev| is present, it refers
                          only to the combination of levels \verb|ilev|-1 and  \verb|ilev|.    \\  
\verb|mld_baseprec_type_|& \verb|character(len=*)|
                         & 'DIAG', 'BJAC', 'AS'
                         & 1,...,\verb|nlev|-1
                         & basic one-level preconditioner (i.e.\ smoother) of the multi-level
                           preconditioner \textbf{CAMBIARE NOME COSTANTE; ora e' mld\_prec\_type,
                           ma questo puo' generare confusione!}                                 \\
\verb|mld_smooth_pos_|   & \verb|character(len=*)|
                         & 'PRE', 'POST', 'BOTH'
                         & 2,...,\verb|nlev|
                         & ``position'' of the smoother: pre-smoother, post-smoother, pre-/post-smoother
                           \textbf{per l'utente NON HA SENSO settarlo ai livelli 2,..., nlev; l'utente
                           deve specificare un livello tra 1 e nlev-1 e la precset deve shiftare il livello
                           tenendo conto della struttura del tipo di
                           dato precondizionatore}           \\ \hline
                       \end{tabular}
                     \end{center}                       
                   \end{sidewaystable}
                   
\begin{sidewaystable}
\begin{center}
\begin{tabular}{|l|l|p{1.5cm}|l|p{6cm}|}
\multicolumn{5}{|c|}{\emph{basic one-level preconditioner (smoother)}}                                 \\ \hline
\verb|mld_n_ovr|         & 
                         & 
                         &
                         &     \\
\verb|mld_sub_restr_|    & 
                         & 
                         &
                         &     \\
\verb|mld_sub_prol_|     & 
                         & 
                         &
                         &     \\
\verb|mld_sub_solve_|    & 
                         & 
                         &
                         &     \\    
\verb|mld_sub_fillin_|   &
                         &
                         &
                         &     \textbf{MODIFICA: fill\_in $-->$ fillin} \\
\verb|mld_sub_thresh_|   &
                         &
                         &
                         &     \textbf{AGGIUNGERE THRESHOLD ILU(t)} \\
\verb|mld_sub_ren_|      &
                         &
                         &
                         &  \textbf{MANCA COSTANTE STRINGA ASSOCIATA}                                \\ \hline

                       \end{tabular}
                     \end{center}
                   \end{sidewaystable}                     
                   
\begin{sidewaystable}
\begin{center}
\begin{tabular}{|l|l|p{1.5cm}|l|p{6cm}|}
\multicolumn{5}{|c|}{\emph{aggregation algorithm}}                                                   \\ \hline
\verb|mld_aggr_alg_|     &
                         &
                         &
                         &                                                                           \\
\verb|mld_aggr_kind_|    &
                         &
                         &
                         &     \\
\verb|mld_aggr_thresh_|  &
                         &
                         &
                         &     \\
\verb|mld_aggr_eig_|     &
                         &
                         &
                         & \textbf{NON E' DEFINITA LA STRINGA CORRISPONDENTE a mld\_max\_norm}           \\ \hline
                       \end{tabular}
                     \end{center}
                   \end{sidewaystable}                     
\begin{sidewaystable}
\begin{center}
\begin{tabular}{|l|l|p{1.5cm}|l|p{6cm}|}
\multicolumn{5}{|c|}{\emph{coarse-space correction at the coarsest level}}                               \\ \hline
\verb|mld_coarse_mat_|   &
                         &
                         &
                         &     \\
\verb|mld_coarse_solve_| &
                         &
                         &
                         & \textbf{VEDI OSSERVAZIONI EMAIL 15-16/06/08}\\
\verb|mld_coarse_subsolve_| &
                         &
                         &
                         & \textbf{VEDI OSSERVAZIONI EMAIL 15-16/06/08}\\
\verb|mld_coarse_sweeps_|&                         
                         &
                         &
                         &     \\
\verb|mld_coarse_fillin_| &
                         &
                         &
                         &     \textbf{MODIFICA: fill\_in $-->$ fillin} \\
\verb|mld_coarse_thresh_| &
                         &
                         &
                         &    \textbf{AGGIUNGERE THRESHOLD ILU(t)} \\ \hline
\end{tabular}
\end{center}
\end{sidewaystable}
% \caption{Parameters defining the preconditioner.\label{tab:precinit}}

\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{ }.\\
\verb|desc_a| & \verb|type(psb_desc_type), intent(in)|. \\
              & The communication descriptor of a. See the PSBLAS User's Guide for
                details \cite{ }.\\
\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{precision}\verb|), dimension(:), intent(in)|.\\
              & The local part of the vector $x$. Note that \emph{type} and \emph{precision}
                must be chosen according
                to the real/complex, single/double precision version of MLD2P4 under use.\\
\verb|y|      & \emph{type}\verb|(|\emph{precision}\verb|), dimension(:), intent(out)|.\\
              & The local part of the vector $y$. Note that \emph{type} and \emph{precision}
                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 trans='N','n' then $op(M^{-1}) = M^{-1}$;
                if trans='T','t' then $op(M^{-1}) = M^{-T}$ (transpose of $M^{-1})$.\\
\verb|work|  & \emph{type}\verb|(|\emph{precision}\verb|), dimension(:), optional, target|.\\
             & Workspace. Its size must be at
               least $4 *$ \verb|psb_cd_get_local_cols(desc_a)| (see the PSBLAS User's Guide).
               Note that \emph{type} and \emph{precision} must be chosen according
               to the real/complex, single/double precision version of MLD2P4 under use.\\\\
\end{tabular}


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

\clearpage
\subsection{Subroutine mld\_precdescr\label{sec:precdescr}}

\begin{center}
\verb|mld_precdescr(p)|\\
\verb|mld_precdescr(iout,p)|\\
\end{center}

\noindent
This routine prints a description of the preconditioner to the standard output or 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)|.\\
              & The id of the file where the preconditioner description
                will be printed. If \verb|iout| is missing, the description is printed on
                the standard output.\\
\end{tabular}


\clearpage
\noindent
=========================================\\

\begin{figure}[h]
\begin{center}
{\small
\begin{verbatim}
mld_precfree(p,info)

Arguments:
    p       -  type(mld_dprec_type), input/output.
               The preconditioner data structure to be deallocated.
    info    -  integer, output.
               Error code.
\end{verbatim}
}
\end{center}
\caption{API of the routine for preconditioner deallocation.\label{fig:prcfree}}
\end{figure}

A twin routine for deallocation of the preconditioner data structure is the \verb|mld_precfree| routine, whose API is reported in
Fig.~\ref{fig:prcfree}.
As mentioned in Section~\ref{sec:multilevel}, a multi-level preconditioner is a combination
of coarse-level corrections and one-level preconditioner (or smoothers).
Different combinations of these components together with different type of one-level preconditioner
as well as different algorithms to build and apply coarse-level corrections allow to the user of defining different multi-level
preconditioners.
The user of MLD2P4 may specify the type of multi-level framework (additive or multiplicative), details on the
aggregation algorithm, details on the type and the way for applying the one-level preconditioner
(as pre-smoother, post-smoother or both), the coarsest matrix storage
(distributed or replicated), the type of the solver to be employed at the coarsest level
and related details, by setting some parameters through the routine \verb|mld_precset| (see Section~\ref{sec:list}).
The API of this routine is reported in Fig.~\ref{fig:prcset}.
%
\begin{figure}[h]
\begin{center}
{\small
\begin{verbatim}
mld_precset(p,what,val,info,ilev)

 Arguments:
    p       -  type(mld_dprec_type), input/output.
               The preconditioner data structure.
    what    -  integer, input.
               The number identifying the parameter to be set.
               A mnemonic constant has been associated to each of these
               numbers.
    val     -  integer/character, input.
               The value of the parameter to be set. 
    info    -  integer, output.
               Error code.
    ilev    -  integer, optional, input.
               For the multilevel preconditioner, the level at which the
               preconditioner parameter has to be set. 
               If nlev is not present, the parameter identified by 'what'
               is set at all the appropriate levels.
\end{verbatim}
}
\end{center}
\caption{API of the routine for preconditioner setup.\label{fig:prcset}}
\end{figure}
%
Finally, to build a preconditioner, according to the requirements made trough the routines \verb|mld_precinit| and \verb|mld_precset|,
a user of MLD2P4 have to call the \verb|prec_build| routine, whose API is reported in Figure~\ref{fig:prcbld}.
%
\begin{figure}[h]
\begin{center}
{\small
\begin{verbatim} 
mld_precbld(a,desc_a,prec,info)

 Arguments:
    a       -  type(psb_dspmat_type).
               The sparse matrix structure containing the local part of the
               matrix to be preconditioned.
    desc_a  -  type(psb_desc_type), input.
               The communication descriptor of a.
    p       -  type(mld_dprec_type), input/output.
               The preconditioner data structure containing the local part
               of the preconditioner to be built.
    info    -  integer, output.
               Error code.              
\end{verbatim}
}
\end{center}
\caption{API of the routine for preconditioner building.\label{fig:prcbld}}
\end{figure}

\subsubsection{List of the preconditioner parameters\label{sec:list}}

In the following we report the list of possible parameters to be set through the \verb|mld_precset| routine,
in order to choose the type of multi-level preconditioner. The parameters are classified depending on their scope.
Note that for character data both uppercase and lowercase strings are allowed.


In order to build a coarse matrix from a fine one, this version of MLD2P4 implements the
smoothed aggregation algorithm described in Section~\ref{sec:aggregation}. However, since for nonsymmetric problems the
application of a correct smoothed procedure is yet an open problem~\cite{lin}, the user
may also choose to apply a nonsmoothed aggregation technique, where the prolongator operator from 
the coarse to fine-space vertices is the simple piecewice constant interpolation
(the tentative prolongator) operator defined in Section~\ref{sec:aggregation}. 
The coarsening scheme takes into account possible anisotropic features of the problems, by using
a threshold level to be used for dropping matrix coefficients during the process. 
The parallel implementation of the coarsening algorithm is based on a decoupled approach, where each process applies the coarsening scheme
to its own local data. The uncoupled scheme can be applied to the matrix $A+A^T$, in the case of matrices with nonsymmetric sparsity pattern.
In the Table \ref{tab:aggr_type} we list the parameters that the user can specify for the aggregation algorithm.
\begin{table}[h]
{\small \label{tab:aggr_type} 
\begin{tabular}{ll}
Parameter               & Allowed values \\
(\verb|what|)           & ( \verb|val|)\\
\verb|mld_aggr_alg_|    & 'DEC', 'SYMDEC'\\
                        & Define the aggregation scheme\\
                        & Now, only decoupled aggregation is available \\
                        & (if 'SYMDEC' is set, the symmetric part of the matrix is considered)\\
\verb|mld_aggr_kind_|   & 'SMOOTH', 'RAW'\\
                        & Define the type of aggregation technique (smoothed or nonsmoothed).\\
\verb|mld_aggr_thresh_| & Dropping threshold in aggregation.\\
                        & Default 0.0\\
\verb|mld_aggr_eig_|    & NON E' DEFINITA LA STRINGA CORRISPONDENTE a mldmaxnorm\\
                        & Define the algorithm to evaluate the maximum eigenvalue\\
                        & of $D^{-1}A$ for smoothed aggregation. Now only the A-norm of the\\
                        & matrix is available.\\
\end{tabular}
\caption{Parameters for aggregation type.}
}
\end{table}

Some options are available for the system involving the coarsest matrix. 
Indeed, this matrix can be replicated or distributed among the processors.
In the former case, various versions of incomplete LU (ILU) factorizations of the 
coarsest matrix are available in order to solve the coarsest system.
In the current version of MLD2P4, the following factorizations are available~\cite{saad}:
\begin{description}
\item[ILU(k):] ILU factorization with fill-in level $k$;
\item[MILU(k):] modified ILU factorization with fill-in level $k$;
\item[ILU(k,t):] ILU with threshold $t$ and $k$ additional entries in each row of the L and U factors with respect to the initial sparsity pattern.
\end{description}
Furthermore, interfaces to UMFPACK~\cite{UMFPACK}, version 4.4, and to SuperLU package~\cite{SUPERLU}, version 3.0, have been also available to deal 
with the coarsest system, when the coarsest matrix is replicated among the processors.
On the other hand, to solve the coarsest-level system when the coarsest matrix is distributed,
a block-Jacobi routine has been developed. It uses the different versions of ILU or the LU
factorization on the coarse matrix diagonal blocks held by the processors. In the case of
distributed coarsest matrix is also available an interface to SupeLU$\_$dist~\cite{SUPERLUDIST}, version 2.0, for distributed 
sparse factorization and solve.
See the Table \ref{tab:coarse_mat} for details. 
\begin{table}[h]
{\small \label{tab:coarse_mat}
\begin{tabular}{ll}
Parameter & Allowed values\\
( \verb|what|) & ( \verb|val|)\\
\verb|mld_coarse_mat_|         & 'DISTR', 'REPL' \\
                               & Coarse Matrix: distributed or replicated \\
\verb|mld_coarse_solve_|       & 'ILU', 'MILU', 'ILUT', 'SLU', 'UMF', SLUDIST', BJAC????\\
                               & Available Coarse solver.\\
                               & Only SLUDIST e BJAC can be used when coarse matrix is distributed\\
\verb|mld_coarse_BJAC_sweeps_| & (NON VA BENE mldcoarsesweeps) number of Block-Jacobi sweeps when BJAC is used as coarsest solver\\
\verb|mld_coarse_fill_in_|     & level of fill-in in MILU and ILU factorization\\
                               & E IL THRESHOLD PER ILUT? \\
\end{tabular}
\caption{Parameters for coarsest matrix solver.}
}
\end{table}

When a Schwarz algorithm is considered as smoother at a certain level or as one-level preconditioner, the user may set many parameters 
in order to choose the type of additive Schwarz version (AS,RAS,ASH), the number of overlaps as well as the local solver. 
All the parameters are reported in Table \ref{tab:schwarz_type}.
\begin{table}[h]
{\small \label{tab:schwarz_type}
\begin{tabular}{ll}
Parameter & Allowed values\\
(\verb|what|) & (\verb|val|)\\
\verb|mld_n_ovr_|            & Number of overlaps \\
\verb|mld_sub_restr_|        & 'HALO', 'NONE'\\
\verb|mld_sub_prol_|         & 'SUM', 'NONE'\\
\verb|mld_sub_solve_|        & 'ILU', 'MILU', 'ILUT', 'SLU', 'UMF'\\
\verb|mld_sub_ren_|          & MANCANO LE STRINGHE\\
\verb|mld_sub_fill_in_|      & level of fill-in in local diagonal blocks, when ILU-type factorizations are used\\
\end{tabular}
\caption{Parameters for Schwarz smoother/preconditioner type.}
}
\end{table}
Its worth noting that, the classical AS method corresponds to the couple of values 'HALO' and 'SUM' of the argument \verb|val|, 
for the values \verb|mld_sub_restr_| and \verb|mld_sub_prol_| of the argument \verb|what|, respectively. While, the RAS method corresponds to 
the couple of values 'NONE' and 'SUM' and ASH method corresponds to the couple of values 'HALO' and 'NONE'.

\subsection{Preconditioner Application} \label{sec:application}

Once the preconditioner has been built, it may be applied at each iteration
of a Krylov solver by calling the routine \verb|mld_precaply| (CAMBIARE NOME ROUTINE NEL SOFTWARE EVITANDO L'UNDERSCORE),
whose API is shown in Figure~\ref{fig:prcaply}.
This routine computes $y = op(M^{-1})\, x$, where $M$ is the previously built
preconditioner, stored in the \verb|prec| data structure, and $op$
denotes the matrix itself or its transpose, according to the value of \verb|trans|.
Note that this routine is called within the PSBLAS-based Krylov solver available in the PSBLAS library (see the PSBLAS User's Guide for details), 
therefore, the use of this routine is generally transparent to the MLD2P4 user.
%
\begin{figure}[h]
\begin{center}
{\small
\begin{verbatim} 
   mld_precaply(prec,x,y,desc_data,info,trans,work)

 Arguments:
    prec       -  type(mld_dprec_type), input.
                  The preconditioner data structure containing the local part
                  of the preconditioner to be applied.
    x          -  real(psb_dpk_), dimension(:), input.
                  The local part of the vector X in Y := op(M^(-1)) * X.
    y          -  real(psb_dpk_), dimension(:), output.
                  The local part of the vector Y in Y := op(M^(-1)) * X.
    desc_data  -  type(psb_desc_type), input.
                  The communication descriptor associated to the matrix to be
                  preconditioned.
    info       -  integer, output.
                  Error code.
    trans      -  character(len=1), optional.
                  If trans='N','n' then op(M^(-1)) = M^(-1);
                  if trans='T','t' then op(M^(-1)) = M^(-T) (transpose of M^(-1)).
    work       -  real(psb_dpk_), dimension (:), optional, target.
                  Workspace. Its size must be at
                  least 4*psb_cd_get_local_cols(desc_data).
\end{verbatim}
}
\end{center}
\caption{API of the routine for preconditioner application.\label{fig:prcaply}}
\end{figure}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: 
