fdurastante/amg4psblas
1
0
Fork 0
mirror of https://github.com/sfilippone/amg4psblas.git synced 2026-10-24 14:51:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

mld2p4-2:

Browse Source 
Docs updates.
This commit is contained in:
Salvatore Filippone
2017-04-21 13:37:08 +00:00
parent 05ab5f4d55
commit 597c6c58c7
3 changed files with 191 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/userinterface.tex
+64 -35
View File
@@ -99,7 +99,7 @@ contained in \verb|val|.
% & 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)| \emph{or} \verb|character(len=*)|. \\
\verb|what| & \verb|character(len=*)|. \\
& The parameter to be set. It can be specified by
a predefined constant, or through its name; the string
is case-insensitive. See also
@@ -169,7 +169,7 @@ For a description of the meaning of the parameters, please
refer also to Section~\ref{sec:background}. \\
\textbf{Remark 2.} A smoother is usually obtained by combining two objects:
a smoother (\verb|mld_smoother_type_|) and a local solver (\verb|mld_sub_solve_|),
a smoother (\verb|SMOOTHER_TYPE|) and a local solver (\verb|SUB_SOLVE|),
as specified in Tables~\ref{tab:p_smoother}-\ref{tab:p_smoother_1}.
For example, the block-Jacobi smoother using
ILU(0) on the blocks is obtained by combining the block-Jacobi smoother
@@ -181,9 +181,9 @@ result of combining the block-Jacobi smoother object with a single sweep
of the pointwise-Jacobi solver object. However, for simplicity, shortcuts are
provided to set point-Jacobi, hybrid (forward) Gauss-Seidel, and
hybrid backward Gauss-Seidel, i.e., the previous smoothers can be defined
by setting only \verb|mld_smoother_type_| to appropriate values (see
by setting only \verb|SMOOTHER_TYPE| to appropriate values (see
Tables~\ref{tab:p_smoother}), i.e., without setting
\verb|mld_sub_solve_| too.
\verb|SUB_SOLVE| too.
The smoother and solver objects are arranged in a
hierarchical manner. When specifying a smoother object, its parameters,
@@ -239,7 +239,8 @@ solver is changed to the default sequential solver.
\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_cycle_| \par \verb|ML_CYCLE| & \verb|character(len=*)|
%\verb|mld_ml_cycle_| \par
\verb|ML_CYCLE| & \verb|character(len=*)|
& \texttt{'VCYCLE'} \par \texttt{'WCYCLE'} \par \texttt{'KCYCLE'} \par
\texttt{'MULT'} \par \texttt{'ADD'}
& \texttt{'VCYCLE'}
@@ -247,7 +248,8 @@ solver is changed to the default sequential solver.
and Additive Schwarz. \par
Note that hybrid Multiplicative Schwarz is equivalent to V-cycle and
is included for compatibility with previous versions of MLD2P4. \\ \hline
\verb|mld_outer_sweeps_| \par \verb|OUTER_SWEEPS| & \texttt{integer} &
%\verb|mld_outer_sweeps_| \par
\verb|OUTER_SWEEPS| & \texttt{integer} &
Any integer \par number $\ge 1$ & 1 &
Number of multi-level cycles. \\ \hline
%\verb|mld_smoother_type_| \par \verb|SMOOTHER_TYPE| & \verb|character(len=*)|
@@ -276,7 +278,8 @@ be applied.
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\textsc{comments} \\ \hline
%\multicolumn{5}{|c|}{\emph{aggregation algorithm}} \\ \hline
\verb|mld_min_coarse_size_| \par \verb|MIN_COARSE_SIZE| & \verb|integer|
%\verb|mld_min_coarse_size_| \par
\verb|MIN_COARSE_SIZE| & \verb|integer|
& Any number \par $> 0$
& $\lfloor 40 \sqrt[3]{n} \rfloor$, where $n$ is the dimension
of the matrix at the finest level
@@ -291,19 +294,22 @@ be applied.
% the maximum number of levels is reached
% (see \verb|mld_n_prec_levs_|).
\\ \hline
\verb|mld_min_cr_ratio_| \par \verb|MIN_CR_RATIO| & \verb|real|
%\verb|mld_min_cr_ratio_| \par
\verb|MIN_CR_RATIO| & \verb|real|
& Any number \par $> 1$
& 1.5
& Minimum coarsening ratio. The aggregation stops
if the ratio between the matrix dimensions
at two consecutive levels is lower than or equal to this
threshold (see Note).\\ \hline
\verb|mld_max_levs_| \par \verb|MAX_LEVS| & \verb|integer|
%\verb|mld_max_levs_| \par
\verb|MAX_LEVS| & \verb|integer|
& Any integer \par number $> 1$
& 20
& Maximum number of levels. The aggregation stops
if the number of levels reaches this value (see Note). \\ \hline
\verb|mld_par_aggr_alg_| \par \verb|PAR_AGGR| & \verb|character(len=*)| \hspace*{-3mm}
%\verb|mld_par_aggr_alg_| \par
\verb|PAR_AGGR| & \verb|character(len=*)| \hspace*{-3mm}
& \texttt{'DEC'}, \texttt{'SYMDEC'}
& \texttt{'DEC'}
& Parallel aggregation algorithm. \par Currently, only the
@@ -311,12 +317,14 @@ be applied.
\verb|SYMDEC| option applies decoupled
aggregation to the sparsity pattern
of $A+A^T$.\\ \hline
\verb|mld_aggr_type_| \par \verb|AGGR_TYPE| & \verb|character(len=*)| \hspace*{-3mm}
%\verb|mld_aggr_type_| \par
\verb|AGGR_TYPE| & \verb|character(len=*)| \hspace*{-3mm}
& \textbf{\texttt{'VMB'}} & \textbf{\texttt{'VMB'}}
& Type of aggregation algorithm: currently, the scalar aggregation
algorithm by Van\v{e}k, Mandel and Brezina is implemented
\cite{VANEK_MANDEL_BREZINA}. \\ \hline
\verb|mld_aggr_prol_| \par \verb|AGGR_PROL| & \verb|character(len=*)| \hspace*{-3mm}
%\verb|mld_aggr_prol_| \par
\verb|AGGR_PROL| & \verb|character(len=*)| \hspace*{-3mm}
& \texttt{'SMOOTHED'}, \texttt{'UNSMOOTHED'} & \texttt{'SMOOTHED'}
& Prolongator used by the aggregation algorithm: smoothed or unsmoothed
(i.e., tentative prolongator). \\
@@ -342,7 +350,8 @@ of levels. } \\
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|mld_aggr_ord_| \par \verb|AGGR_ORD| & \verb|character(len=*)|
%\verb|mld_aggr_ord_| \par
\verb|AGGR_ORD| & \verb|character(len=*)|
& \texttt{'NATURAL'} \par \texttt{'DEGREE'}
& \texttt{'NATURAL'}
& Initial ordering of indices for the aggregation
@@ -351,17 +360,20 @@ of levels. } \\
matrix graph. \\ \hline
%Since aggregation is
%heuristic, results will be different.
\verb|mld_aggr_thresh_| \par \verb|AGGR_THRESH| & \verb|real(|\emph{kind\_parameter}\verb|)|
%\verb|mld_aggr_thresh_| \par
\verb|AGGR_THRESH| & \verb|real(|\emph{kind\_parameter}\verb|)|
& Any~real \par number~$\in [0, 1]$
& 0.05
& The threshold $\theta$ in the aggregation algorithm
(see Note). \\ \hline
%\verb|mld_aggr_scale_| \par \verb|AGGR_SCALE| & \verb|real(|\emph{kind\_parameter}\verb|)|
%%\verb|mld_aggr_scale_| \par
% \verb|AGGR_SCALE| & \verb|real(|\emph{kind\_parameter}\verb|)|
% & Any~real \par number~$\in [0, 1]$
% & 1.0
% & Scale factor applied to the threshold in going
% from level $ilev$ to level $ilev+1$. \\ \hline
\verb|mld_aggr_omega_alg_| \par \verb|AGGR_OMEGA_ALG|& \verb|character(len=*)|
%\verb|mld_aggr_omega_alg_| \par
\verb|AGGR_OMEGA_ALG|& \verb|character(len=*)|
& \texttt{'EIG\_EST'} \par \texttt{'USER\_CHOICE'}
& \texttt{'EIG\_EST'}
& How the damping parameter $\omega$ in the
@@ -371,13 +383,15 @@ of levels. } \\
level and $D$ is the diagonal matrix with
the same diagonal entires as $A$, or explicily
specified by the user. \\ \hline
\verb|mld_aggr_eig_| \par \verb|AGGR_EIG| & \verb|character(len=*)|
%\verb|mld_aggr_eig_| \par
\verb|AGGR_EIG| & \verb|character(len=*)|
& \texttt{'A\_NORMI'}
& \texttt{'A\_NORMI'}
& How to estimate the spectral radius of $D^{-1}A$.
Currently only the infinity norm estimate
is available. \\ \hline
\verb|mld_aggr_omega_val_| \par \verb|AGGR_OMEGA_VAL| & \verb|real(|\emph{kind\_parameter}\verb|)|
%\verb|mld_aggr_omega_val_| \par
\verb|AGGR_OMEGA_VAL| & \verb|real(|\emph{kind\_parameter}\verb|)|
& Any real \par number $>0$
& $4/(3\rho(D^{-1}A))$
& Damping parameter $\omega$ in the smoothed aggregation algorithm.
@@ -387,7 +401,8 @@ of levels. } \\
otherwise it is computed by the library, using the
selected estimate of the spectral radius $\rho(D^{-1}A)$ of
$D^{-1}A$.\\ \hline
\verb|mld_aggr_filter_| \par \verb|AGGR_FILTER|
%\verb|mld_aggr_filter_| \par
\verb|AGGR_FILTER|
& \verb|character(len=*)|
& \texttt{'FILTER'} \par \texttt{'NOFILTER'}
& \texttt{'NOFILTER'} & Matrix used in computing the smoothed
@@ -412,12 +427,14 @@ the parameter \texttt{ilev}.} \\
\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_| \par \verb|COARSE_MAT| & \verb|character(len=*)|
%\verb|mld_coarse_mat_| \par
\verb|COARSE_MAT| & \verb|character(len=*)|
& \texttt{'DIST'} \par \texttt{'REPL'}
& \texttt{'REPL'}
& Coarsest matrix layout: distributed among the processes or
replicated on each of them. \\ \hline
\verb|mld_coarse_solve_| \par \verb|COARSE_SOLVE| & \verb|character(len=*)|
%\verb|mld_coarse_solve_| \par
\verb|COARSE_SOLVE| & \verb|character(len=*)|
& \texttt{'MUMPS'} \par \texttt{'UMF'} \par
\texttt{'SLU'} \par \texttt{'SLUDIST'} \par
\texttt{'JACOBI'} \par \texttt{'GS'} \par \texttt{'BJAC'}
@@ -438,7 +455,8 @@ the parameter \texttt{ilev}.} \\
which allows the use
value UMFPACK and SuperLU\_Dist
are available only in double precision. \\ \hline
\verb|mld_coarse_subsolve_| \par \verb|COARSE_SUBSOLVE| & \verb|character(len=*)|
%\verb|mld_coarse_subsolve_| \par
\verb|COARSE_SUBSOLVE| & \verb|character(len=*)|
& \texttt{'ILU'} \par \texttt{'ILUT'} \par \texttt{'MILU'} \par
\texttt{'MUMPS'} \par \texttt{'SLU'} \par \texttt{'UMF'}
& See~Note.
@@ -450,8 +468,8 @@ the parameter \texttt{ilev}.} \\
Note that UMFPACK and SuperLU\_Dist
are available only in double precision. \\
\hline
\multicolumn{5}{|l|}{{\bfseries Note.} Defaults for \texttt{mld\_coarse\_solve\_} and
\texttt{mld\_coarse\_subsolve\_} are chosen in the following order:} \\
\multicolumn{5}{|l|}{{\bfseries Note.} Defaults for \texttt{COARSE\_SOLVE} and
\texttt{COARSE\_SUBSOLVE} are chosen in the following order:} \\
\multicolumn{5}{|l|}{single precision version -- \texttt{MUMPS} if installed,
then \texttt{SLU} if installed,
\texttt{ILU} otherwise;}\\
@@ -472,16 +490,19 @@ level.\label{tab:p_coarse}}
\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_sweeps_| \par \verb|COARSE_SWEEPS| & \verb|integer|
%\verb|mld_coarse_sweeps_| \par
\verb|COARSE_SWEEPS| & \verb|integer|
& Any integer \par number $> 0$
& 10
& Number of sweeps when \verb|JACOBI|, \verb|GS| or \verb|BJAC|
is chosen as coarsest-level solver. \\ \hline
\verb|mld_coarse_fillin_| \par \verb|COARSE_FILLIN| & \verb|integer|
%\verb|mld_coarse_fillin_| \par
\verb|COARSE_FILLIN| & \verb|integer|
& Any integer \par number $\ge 0$
& 0
& Fill-in level $p$ of the ILU factorizations. \\ \hline
\verb|mld_coarse_iluthrs_| \par \verb|COARSE_ILUTHRS|
%\verb|mld_coarse_iluthrs_| \par
\verb|COARSE_ILUTHRS|
& \verb|real(|\emph{kind\_parameter}\verb|)|
& Any real \par number $\ge 0$
& 0
@@ -501,7 +522,8 @@ level (continued).\label{tab:p_coarse_1}}
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\textsc{comments} \\ \hline
%\multicolumn{5}{|c|}{\emph{basic one-level preconditioner (smoother)}} \\ \hline
\verb|mld_smoother_type_| \par \verb|SMOOTHER_TYPE| & \verb|character(len=*)|
%\verb|mld_smoother_type_| \par
\verb|SMOOTHER_TYPE| & \verb|character(len=*)|
& \verb|'JACOBI'| \par \verb|'GS'| \par \verb|'BGS'| \par \verb|'BJAC'|
\par \verb|'AS'|
& \verb|'FBGS'|
@@ -510,7 +532,8 @@ level (continued).\label{tab:p_coarse_1}}
hybrid backward Gauss-Seidel, block-Jacobi, and
Additive Schwarz. \par
It is ignored by one-level preconditioners. \\ \hline
\verb|mld_sub_solve_| \par \verb|SUB_SOLVE| & \verb|character(len=*)|
%\verb|mld_sub_solve_| \par
\verb|SUB_SOLVE| & \verb|character(len=*)|
& \texttt{'JACOBI'} \par
\texttt{'GS'} \par \texttt{'BGS'} \par \texttt{'ILU'} \par
\texttt{'ILUT'} \par \texttt{'MILU'} \par
@@ -526,7 +549,8 @@ level (continued).\label{tab:p_coarse_1}}
LU from MUMPS, SuperLU or UMFPACK
(plus triangular solve). See Note for details on hybrid
Gauss-Seidel. \\ \hline
\verb|mld_moother_sweeps_| \par \verb|SMOOTHER_SWEEPS| & \verb|integer|
%\verb|mld_moother_sweeps_| \par
\verb|SMOOTHER_SWEEPS| & \verb|integer|
& Any integer \par number~$\ge 0$
& 1
& Number of sweeps of the smoother or one-level preconditioner.
@@ -534,7 +558,8 @@ level (continued).\label{tab:p_coarse_1}}
post-smoother is used if this parameter is set to 0
together with \verb|pos='PRE'| or \verb|pos='POST|,
respectively. \\ \hline
\verb|mld_sub_ovr_| \par \verb|SUB_OVR| & \verb|integer|
%\verb|mld_sub_ovr_| \par
\verb|SUB_OVR| & \verb|integer|
& Any integer \par number~$\ge 0$
& 1
& Number of overlap layers, for Additive Schwarz only. \\
@@ -552,7 +577,8 @@ level (continued).\label{tab:p_coarse_1}}
\hline
\verb|what| & \textsc{data type} & \verb|val| & \textsc{default} &
\textsc{comments} \\ \hline
\verb|mld_sub_restr_| \par \verb|SUB_RESTR| & \verb|character(len=*)|
%\verb|mld_sub_restr_| \par
\verb|SUB_RESTR| & \verb|character(len=*)|
& \texttt{'HALO'} \par \texttt{'NONE'}
& \texttt{'HALO'}
& Type of restriction operator, for Additive Schwarz only:
@@ -560,7 +586,8 @@ level (continued).\label{tab:p_coarse_1}}
for neglecting it. \par
Note that \texttt{HALO} must be chosen for
the classical Addditive Schwarz smoother and its RAS variant.\\ \hline
\verb|mld_sub_prol_| \par \verb|SUB_PROL| & \verb|character(len=*)|
%\verb|mld_sub_prol_| \par
\verb|SUB_PROL| & \verb|character(len=*)|
& \texttt{'SUM'} \par \texttt{'NONE'}
& \texttt{'NONE'}
& Type of prolongation operator, for Additive Schwarz only:
@@ -568,11 +595,13 @@ level (continued).\label{tab:p_coarse_1}}
for neglecting them. \par
Note that \texttt{SUM} must be chosen for the classical Additive
Schwarz smoother, and \texttt{NONE} for its RAS variant. \\ \hline
\verb|mld_sub_fillin_| \par \verb|SUB_FILLIN| & \verb|integer|
%\verb|mld_sub_fillin_| \par
\verb|SUB_FILLIN| & \verb|integer|
& Any integer \par number~$\ge 0$
& 0
& Fill-in level $p$ of the incomplete LU factorizations. \\ \hline
\verb|mld_sub_iluthrs_| \par \verb|SUB_ILUTHRS| & \verb|real(|\emph{kind\_parameter}\verb|)|
%\verb|mld_sub_iluthrs_| \par
\verb|SUB_ILUTHRS| & \verb|real(|\emph{kind\_parameter}\verb|)|
& Any real number~$\ge 0$
& 0
& Drop tolerance $t$ in the ILU($p,t$) factorization. \\ %\hline