|
|
|
|
@ -1,395 +1,420 @@
|
|
|
|
|
\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:
|
|
|
|
|
\section{User Interface\label{sec:userinterface}}
|
|
|
|
|
\markboth{\textsc{MLD2P4 User's and Reference Guide}}
|
|
|
|
|
{\textsc{\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 the 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_prec\-descr| 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 \verb|psb_base_mod|
|
|
|
|
|
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{10.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}.\\
|
|
|
|
|
Note that the uppercase and lowercase letters can be used indifferently.\\
|
|
|
|
|
\verb|info| & \verb|integer, intent(out)|.\\
|
|
|
|
|
& Error code. If no error, 0 is returned. 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|=\verb|'ML'|, \verb|'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{10.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
|
|
|
|
|
Tables~\ref{tab:p_type}-\ref{tab:p_coarse}.
|
|
|
|
|
When the value is of type \verb|character(len=*)|,
|
|
|
|
|
uppercase and lowercase letters can be used indifferently.\\
|
|
|
|
|
\verb|info| & \verb|integer, intent(out)|.\\
|
|
|
|
|
& Error code. If no error, 0 is returned. 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) preconditioners 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 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}.
|
|
|
|
|
For a better understanding of the meaning of the parameters, the user
|
|
|
|
|
is referred to Section \ref{sec:background}.
|
|
|
|
|
%
|
|
|
|
|
%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|.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\begin{sidewaystable}
|
|
|
|
|
\begin{center}
|
|
|
|
|
\begin{tabular}{|l|l|p{2cm}|l|p{7cm}|}
|
|
|
|
|
\hline
|
|
|
|
|
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
|
|
|
|
|
\textsc{comments} \\ \hline
|
|
|
|
|
%\multicolumn{5}{|c|}{\emph{type of the multi-level preconditioner}}\\ \hline
|
|
|
|
|
\verb|mld_ml_type_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'ADD'} \ \ \ \texttt{'MULT'}
|
|
|
|
|
& \texttt{'MULT'}
|
|
|
|
|
& basic multi-level framework: additive or multiplicative
|
|
|
|
|
among the levels (always additive inside a level) \\
|
|
|
|
|
\verb|mld_smoother_type_|& \verb|character(len=*)|
|
|
|
|
|
& \texttt{'DIAG'} \ \ \ \texttt{'BJAC'} \ \ \ \texttt{'AS'}
|
|
|
|
|
& \texttt{'AS'}
|
|
|
|
|
& basic one-level preconditioner (i.e.\ smoother) of the
|
|
|
|
|
multi-level preconditioner: diagonal, block Jacobi,
|
|
|
|
|
AS \\
|
|
|
|
|
\verb|mld_smoother_pos_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'PRE'} \ \ \ \texttt{'POST'} \ \ \ \texttt{'TWOSIDE'}
|
|
|
|
|
& \texttt{'POST'}
|
|
|
|
|
& ``position'' of the smoother: pre-smoother, post-smoother,
|
|
|
|
|
pre- and 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{2.6cm}|l|p{7cm}|}
|
|
|
|
|
\hline
|
|
|
|
|
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
|
|
|
|
|
\textsc{comments} \\ \hline
|
|
|
|
|
%\multicolumn{5}{|c|}{\emph{basic one-level preconditioner (smoother)}} \\ \hline
|
|
|
|
|
\verb|mld_sub_ovr_| & \verb|integer|
|
|
|
|
|
& any integer number $\ge 0$
|
|
|
|
|
& 1
|
|
|
|
|
& Number of overlap layers. \\
|
|
|
|
|
\verb|mld_sub_restr_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'HALO'} \ \ \ \ \ \texttt{'NONE'}
|
|
|
|
|
& \texttt{'HALO'}
|
|
|
|
|
& Type of restriction operator:
|
|
|
|
|
\texttt{'HALO'} for taking into account the overlap, \texttt{'NONE'}
|
|
|
|
|
for neglecting it. \\
|
|
|
|
|
\verb|mld_sub_prol_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'SUM'} \ \ \ \ \ \texttt{'NONE'}
|
|
|
|
|
& \texttt{'NONE'}
|
|
|
|
|
& Type of prolongator operator:
|
|
|
|
|
\texttt{'SUM'} for adding the contributions from the overlap, \texttt{'NONE'}
|
|
|
|
|
for neglecting them. \\
|
|
|
|
|
\verb|mld_sub_solve_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'ILU'} \ \ \ \ \ \texttt{'MILU'} \ \ \ \ \ \texttt{'ILUT'} \ \ \ \ \
|
|
|
|
|
\texttt{'UMF'} \ \ \ \ \ \texttt{'SLU'}
|
|
|
|
|
& \texttt{'UMF'}
|
|
|
|
|
& Local solver: ILU($p$), MILU($p$), ILU($p,t$), LU from UMFPACK, LU from SuperLU,
|
|
|
|
|
plus triangular solve. \\
|
|
|
|
|
\verb|mld_sub_fillin_| & \verb|integer|
|
|
|
|
|
& any integer number $\ge 0$
|
|
|
|
|
& 0
|
|
|
|
|
& Fill-in level $p$ of the incomplete LU factorizations. \\
|
|
|
|
|
\verb|mld_sub_thresh_| & \verb|real(|\emph{kind\_parameter}\verb|)|
|
|
|
|
|
& any real number $\ge 0$
|
|
|
|
|
& \texttt{0.e0} (or \texttt{0.d0})
|
|
|
|
|
& Drop tolerance $t$ in the ILU($p,t$) factorization. \\
|
|
|
|
|
\verb|mld_sub_ren_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'RENUM\_NONE'}, \texttt{'RENUM\_GLOBAL'} %, \texttt{'RENUM_GPS'}
|
|
|
|
|
& \texttt{'RENUM\_NONE'}
|
|
|
|
|
& Row and column reordering of the local submatrices: no reordering,
|
|
|
|
|
reordering according to the global numbering of the rows and columns of
|
|
|
|
|
the whole matrix. \\
|
|
|
|
|
\hline
|
|
|
|
|
\end{tabular}
|
|
|
|
|
\end{center}
|
|
|
|
|
\caption{Parameters defining the one-level preconditioner used as smoother.
|
|
|
|
|
\label{tab:p_smoother}}
|
|
|
|
|
\end{sidewaystable}
|
|
|
|
|
|
|
|
|
|
\begin{sidewaystable}
|
|
|
|
|
\begin{center}
|
|
|
|
|
\begin{tabular}{|l|l|p{2.6cm}|l|p{7cm}|}
|
|
|
|
|
\hline
|
|
|
|
|
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
|
|
|
|
|
\textsc{comments} \\ \hline
|
|
|
|
|
%\multicolumn{5}{|c|}{\emph{aggregation algorithm}} \\ \hline
|
|
|
|
|
\verb|mld_aggr_alg_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'DEC'}
|
|
|
|
|
& \texttt{'DEC'}
|
|
|
|
|
& Aggregation algorithm. Currently, only the decoupled aggregation is available. \\
|
|
|
|
|
\verb|mld_aggr_kind_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'SMOOTH'} \ \ \ \ \ \texttt{'RAW'}
|
|
|
|
|
& \texttt{'SMOOTH'}
|
|
|
|
|
& Type of aggregation: smoothed or raw, i.e.\ using the tentative prolongator. \\
|
|
|
|
|
\verb|mld_aggr_thresh_| & \verb|real(|\emph{kind\_parameter}\verb|)|
|
|
|
|
|
& any real number $\in [0, 1]$
|
|
|
|
|
& \texttt{0.e0} (or \texttt{0.d0})
|
|
|
|
|
& The threshold $\theta$ in the aggregation algorithm. \\
|
|
|
|
|
\verb|mld_aggr_eig_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'A\_NORMI'}
|
|
|
|
|
& \texttt{'A\_NORMI'}
|
|
|
|
|
& Estimate of the maximum eigenvalue of $D^{-1}A$
|
|
|
|
|
for the smoothed aggregation. Currently, only the infinity norm of
|
|
|
|
|
the matrix 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{2.6cm}|l|p{7cm}|}
|
|
|
|
|
\hline
|
|
|
|
|
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
|
|
|
|
|
\textsc{comments} \\ \hline
|
|
|
|
|
%\multicolumn{5}{|c|}{\emph{coarse-space correction at the coarsest level}}\\ \hline
|
|
|
|
|
\verb|mld_coarse_mat_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'DISTR'} \ \ \ \ \ \texttt{'REPL'}
|
|
|
|
|
& \texttt{'DISTR'}
|
|
|
|
|
& Coarsest matrix: distributed among the processors or replicated on each of them. \\
|
|
|
|
|
\verb|mld_coarse_solve_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'BJAC'} \ \ \ \ \ \texttt{'UMF'} \ \ \ \ \ \ \ \ \texttt{'SLU'}
|
|
|
|
|
\ \ \ \ \ \texttt{'SLUDIST'}
|
|
|
|
|
& \texttt{'BJAC'}
|
|
|
|
|
& Solver used at the coarsest level: block Jacobi, sequential LU from UMFPACK,
|
|
|
|
|
sequential LU from SuperLU, or distributed LU from SuperLU\_Dist.
|
|
|
|
|
If the coarsest matrix is distributed, only \texttt{'BJAC'} and \texttt{'SLUDIST'}
|
|
|
|
|
can be chosen; if it is replicated, only \emph{'BJAC'} or \texttt{'SLUDIST'} can
|
|
|
|
|
be selected. \\
|
|
|
|
|
\verb|mld_coarse_subsolve_| & \verb|character(len=*)|
|
|
|
|
|
& \texttt{'ILU'} \ \ \ \ \ \ \ \texttt{'MILU'} \ \ \ \ \ \ \ \ \texttt{'ILUT'}
|
|
|
|
|
\ \ \ \ \ \ \ \texttt{'UMF'} \ \ \ \ \ \ \ \texttt{'SLU'}
|
|
|
|
|
& \texttt{'UMF'}
|
|
|
|
|
& Solver for the diagonal blocks of the coarse matrix, in case the block Jacobi solver
|
|
|
|
|
is chosen as coarsest-level solver: ILU($p$), MILU($p$), ILU($p,t$), LU from UMFPACK,
|
|
|
|
|
LU from SuperLU, plus triangular solve. \\
|
|
|
|
|
\verb|mld_coarse_sweeps_|& \verb|integer|
|
|
|
|
|
& any integer number $> 0$
|
|
|
|
|
& \texttt{4}
|
|
|
|
|
& Number of Block-Jacobi sweeps when 'BJAC' is used as coarsest-level solver. \\
|
|
|
|
|
\verb|mld_coarse_fillin_| & \verb|integer|
|
|
|
|
|
& any integer number $\ge 0$
|
|
|
|
|
& \texttt{0}
|
|
|
|
|
& Fill-in level $p$ of the incomplete LU factorizations. \\
|
|
|
|
|
\verb|mld_coarse_thresh_| & \verb|real(|\emph{kind\_parameter}\verb|)|
|
|
|
|
|
& any real number $\ge 0$
|
|
|
|
|
& \texttt{0.d0} (or \texttt{0.e0})
|
|
|
|
|
& Drop tolerance $t$ in the ILU($p,t$) factorization. \\
|
|
|
|
|
\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{10.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 \verb|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. If no error, 0 is returned. 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 into \verb|p|, 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 it is completely transparent to the user.
|
|
|
|
|
|
|
|
|
|
\subsubsection*{Arguments}
|
|
|
|
|
|
|
|
|
|
\begin{tabular}{p{1.2cm}p{10.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. If no error, 0 is returned. 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{10.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. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
|
|
|
|
|
\end{tabular}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
\subsection{Subroutine mld\_precdescr\label{sec:precdescr}}
|
|
|
|
|
|
|
|
|
|
\begin{center}
|
|
|
|
|
\verb|mld_precdescr(p,info,iout)|\\
|
|
|
|
|
\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|info| & \verb|integer, intent(out)|.\\
|
|
|
|
|
& Error code. If no error, 0 is returned. See Section~\ref{sec:errors} for details.\\
|
|
|
|
|
\verb|iout| & \verb|integer, intent(in), optional|.\\
|
|
|
|
|
& The id of the file where the preconditioner description
|
|
|
|
|
will be printed; the default is the standard output.\\
|
|
|
|
|
\end{tabular}
|
|
|
|
|
|
|
|
|
|
%%% Local Variables:
|
|
|
|
|
%%% mode: latex
|
|
|
|
|
%%% TeX-master: "userguide"
|
|
|
|
|
%%% End:
|
|
|
|
|
|
Salvatore Filippone
17 years ago