\label{sec:muelu_options}

In this section, we report the complete list of \muelu{} input parameters.  It
is important to notice, however, that \muelu{} relies on other \trilinos{}
packages to provide support for some of its algorithms. For instance,
\ifpack{}/\ifpacktwo{} provide standard smoothers like Jacobi, Gauss-Seidel or
Chebyshev, while \amesos{}/\amesostwo{} provide access to direct solvers. The
parameters affecting the behavior of the algorithms in those packages are
simply passed by \muelu{} to a routine from the corresponding library. Please
consult corresponding packages' documentation for a full list of supported
algorithms and corresponding parameters.

\section{Using parameters on individual levels}
Some of the parameters that affect the preconditioner can in principle be
different from level to level. By default, parameters affect all levels in
a multigrid hierarchy.

The settings on a particular level can be changed by using level sublists.
A level sublist is a \parameterlist{} sublist with the name ``level XX'', where XX is the level number. The
parameter names in the sublist do not require any modifications. For example,
the following fragment of code
\begin{lstlisting}[language=XML]
  <ParameterList name="level 2">
    <Parameter name="smoother: type" type="string" value="CHEBYSHEV"/>
  </ParameterList>
\end{lstlisting}
changes the smoother for level 2 to be a Chebyshev-type polynomial smoother.

\section{Parameter validation}
By default, \muelu{} validates the input parameter list. A parameter that is
misspelled is unknown. A parameter with an incorrect value type is also treated as invalid.
Both cases will cause an exception to be
thrown and execution to halt.

\begin{mycomment}
Spaces are important within a parameter's name. Please separate words
by just one space, and make sure there are no leading or trailing spaces.
\end{mycomment}

The option \verb|print initial parameters| prints the initial list given to the
interpreter. The option \verb|print unused parameters| prints the list of unused
parameters.

% ==================== GENERAL ====================
\section{General options}
\label{sec:options_general}

\begin{table}[h!]
  \begin{center}
    \begin{tabular}{p{3cm} p{12cm}}
      \toprule
      Verbosity level           & Description \\
      \midrule
      \verb!none!               & No output \\
      \verb!low!                & Errors, important warnings, and some statistics \\
      \verb!medium!             & Same as \verb!low!, but with more statistics \\
      \verb!high!               & Errors, all warnings, and all statistics \\
      \verb!extreme!            & Same as \verb!high!, but also includes output from other packages (\textit{i.e.}, \zoltan{}) \\
      \bottomrule
    \end{tabular}
    \caption{Verbosity levels.}
\label{t:verbosity_types}
  \end{center}
\end{table}

\begin{table}[h!]
  \begin{center}
    \begin{tabular}{p{4.3cm} p{4.3cm} c p{4.5cm}}
      \toprule
      Problem type                 & Multigrid algorithm    & Block size  & Smoother \\
      \midrule
      \verb!unknown!               & --                     & --          & -- \\
      \verb!Poisson-2D!            & Smoothed aggregation   & 1           & Chebyshev \\
      \verb!Poisson-3D!            & Smoothed aggregation   & 1           & Chebyshev \\
      \verb!Elasticity-2D!         & Smoothed aggregation   & 2           & Chebyshev \\
      \verb!Elasticity-3D!         & Smoothed aggregation   & 3           & Chebyshev \\
      \verb!Poisson-2D-complex!    & Smoothed aggregation   & 1           & Symmetric Gauss-Seidel \\
      \verb!Poisson-3D-complex!    & Smoothed aggregation   & 1           & Symmetric Gauss-Seidel \\
      \verb!Elasticity-2D-complex! & Smoothed aggregation   & 2           & Symmetric Gauss-Seidel \\
      \verb!Elasticity-3D-complex! & Smoothed aggregation   & 3           & Symmetric Gauss-Seidel \\
      \verb!ConvectionDiffusion!   & Petrov-Galerkin  AMG   & 1           & Gauss-Seidel \\
      \verb!MHD!                   & Unsmoothed aggregation & --          & Additive Schwarz method with one level of overlap and ILU(0) as a subdomain solver \\
      \bottomrule
    \end{tabular}
    \caption{Supported problem types (``--'' means not set).}
\label{t:problem_types}
  \end{center}
\end{table}

\input{options_general}

% ==================== SMOOTHERS ====================
\section{Smoothing and coarse solver options}
\label{sec:options_smoothing}

\muelu{} relies on other \trilinos{} packages to provide level smoothers and
coarse solvers. \ifpack{} and \ifpacktwo{} provide standard smoothers (see
Table~\ref{tab:smoothers}), and \amesos{} and \amesostwo{} provide direct
solvers (see Table~\ref{tab:coarse_solvers}). Note that it is completely possible to use
any level smoother as a direct solver.

\muelu{} checks parameters \verb|smoother: * type| and \verb|coarse: type| to
determine:
\begin{itemize}
  \item what package to use (i.e., is it a smoother or a direct solver);
  \item (possibly) transform a smoother type

    \ding{42} \ifpack{} and \ifpacktwo{} use different smoother type names,
    e.g., ``point relaxation stand-alone'' vs ``RELAXATION''.  \muelu{} tries to follow
    \ifpacktwo{} notation for smoother types. Please consult \ifpacktwo{}
    documentation~\cite{Ifpack2} for more information.
\end{itemize}
The parameter lists \verb|smoother: * params| and \verb|coarse: params| are
passed directly to the corresponding package without any examination of their
content. Please consult the documentation of the corresponding packages for a list of
possible values.

By default, \muelu{} uses one sweep of symmetric Gauss-Seidel for both pre- and
post-smoothing, and SuperLU for coarse system solver.

\begin{table}[tbh]
  \begin{center}
    \begin{tabular}{p{4.0cm} p{10cm}}
      \toprule
      \texttt{smoother: type}           & \\
      \midrule
      \verb|RELAXATION|                 & Point relaxation smoothers, including
                                          Jacobi, Gauss-Seidel, symmetric Gauss-Seidel,
                                          multithreaded (coloring-based) Gauss-Seidel, etc. The exact
                                          smoother is chosen by specifying \texttt{relaxation: type} parameter in
                                          the \texttt{smoother: params} sublist. \\
      \verb|CHEBYSHEV|                  & Chebyshev polynomial smoother. \\
      \verb|ILUT|, \verb|RILUK|         & Local (processor-based) incomplete factorization methods. \\
      \bottomrule
    \end{tabular}
    \caption{Commonly used smoothers provided by \ifpack{}/\ifpacktwo{}. Note
    that these smoothers can also be used as coarse grid solvers.}
\label{tab:smoothers}
  \end{center}
\end{table}

\begin{table}[tbh]
  \begin{center}
    \begin{tabular}{p{4.0cm} c c p{7cm}}
      \toprule
      \texttt{coarse: type}             & \amesos{} & \amesostwo{} &  \\
      \midrule
      \verb|KLU|                        & x & & Default \amesos{} solver~\cite{klu}. \\
      \verb|KLU2|                       & & x & Default \amesostwo{} solver~\cite{amesos2_belos}. \\
      \verb|SuperLU|                    & x & x & Third-party serial sparse direct solver~\cite{Li2011}. \\
      \verb|SuperLU_dist|               & x & x & Third-party parallel sparse direct solver~\cite{Li2011}. \\
      \verb|Umfpack|                    & x & & Third-party solver~\cite{umfpack}. \\
      \verb|Mumps|                      & x & & Third-party solver~\cite{mumps}. \\
      \bottomrule
    \end{tabular}
    \caption{Commonly used direct solvers provided by \amesos{}/\amesostwo{}}
\label{tab:coarse_solvers}
  \end{center}
\end{table}

In certain cases, the user may want to do no smoothing on a particular level, or do no solve on the coarsest level.
\begin{itemize}
  \item To skip smoothing, use the option \verb!smoother: pre or post! with value \verb!none!.
  \item To skip the coarse grid solve, use the option \verb!coarse: type! with value \verb!none!.
\end{itemize}

When a problem can be solved using structured aggregation algorithms it is also possible to use the structured line detection factory,
 this will allow \muelu{} to pass additional information to \ifpack2{} enabling it to perform line smoothing.
An example of line smoothing is provided in \texttt{packages/trilinoscouplings/examples/scaling/muelu\_Ifpack2\_line\_detection.xml}.

\input{options_smoothing_and_coarse}

% ==================== AGGREGATION ====================
\section{Aggregation options}
\label{sec:options_aggregation}

\begin{table}[H]
  \begin{center}
    \begin{tabular}{p{5.0cm} p{10cm}}
      \toprule
      \verb!structured!   & Attempts to construct hexahedral aggregates on a structured
                            mesh using a default coarsening rate of $3$ in each spatial
                            dimension.\\
      \verb!hybrid!       & This option takes in a user parameter that varies on each
                            rank and that specifies whether the local aggregation
                            scheme should be \verb!structured! or \verb!unstructured!.\\
      \verb!uncoupled!    & Attempts to construct aggregates of optimal size ($3^d$
                            nodes in $d$ dimensions). Each process works independently, and
                            aggregates cannot span multiple processes.\\
      \verb!brick!        & Attempts to construct rectangular aggregates \\
      %\verb!METIS!     & Use graph partitioning algorithm to create aggregates,
      %                   working process-wise. Number of nodes in each aggregate
      %                   is specified with option \texttt{aggregation: max agg
      %                   size}. \\
      % \verb!ParMETIS!  & As \verb!METIS!, but partition global graph. Aggregates
                         % can span arbitrary number of processes. Specify global
                         % number of aggregates with {\tt aggregation: global
                         % number}. \\
      \bottomrule
    \end{tabular}
    \caption{Available coarsening schemes. }
\label{t:aggregation}
  \end{center}
\end{table}

\begin{table}[H]
  \begin{center}
    \begin{tabular}{p{4.0cm} p{8.5cm} p{1.5cm} p{2.0cm}}
      Algorithm & Description & Parallel? & Deterministic? \\
      \toprule
      \verb!mis2 aggregation! &     Uses distance-2 MIS to perform aggregation similar to non-Kokkos refactor.
                                    Faster than coloring-based aggregation.
                                    Cannot control min/max aggregate size. & Yes & Yes \\
      \verb!mis2 coarsening! &      Uses distance-2 MIS to perform simple coarsening where only independent vertices become aggregate roots.
                                    This means the coarse ratio is higher than in \verb!mis2 aggregation!.
                                    Faster than coloring-based aggregation.  Cannot control min/max aggregate size. & Yes & Yes \\
      \verb!serial! &               Computes a D2 coloring on host, and then does 4-phase aggregation on device. & No & Optional \\
      \verb!default! &              Computes \verb!serial! on a serial device and \verb!net based bit set! on a parallel device. & Yes & Optional \\
      \verb!vertex based! &         Computes a D2 coloring in parallel with conflicts resolved by neighbors-of-neighbors loop. Then does 4-phase aggregation on device. & Yes & No \\
      \verb!vertex based bit set! & Computes the same as \verb!vertex based!, but with an optimization using a 32-bit integer instead of 32 bools to track forbidden colors. & Yes & No \\
      \verb!edge filtering! &       Computes the same as \verb!vertex based bit set!, but with an optimization that can filter and skip some edges. & Yes & No \\
      \verb!net based bit set! &    Computes a D2 coloring in parallel with net-based algorithm, which is asymptotically faster than vertex-based (though not always faster in practice).
                                    Then does 4-phase aggregation on device. & Yes & No \\
      \bottomrule
    \end{tabular}
    \caption{Available choices for \texttt{aggregation: coloring algorithm}. This controls Kokkos-refactored uncoupled aggregation. }
\label{t:coloring_algs}
  \end{center}
\end{table}

Table \ref{t:coloring_algs} lists the available values for \verb!aggregation: coloring algorithm!, which (in Kokkos-refactored uncoupled aggregation) controls how aggregate roots are selected and aggregates are constructed. Under ``Deterministic?'', Yes means the same aggregates are produced for a given graph every run, on any machine. Optional means deterministic only if \verb!aggregation: deterministic! is true, and in this case determinism comes with a speed penalty.

\input{options_aggregation}

The option \texttt{aggregation: strength-of-connection matrix} allows to select the matrix which is used in the construction of the strength-of-connection.
Two options are available:
\begin{itemize}
\item \texttt{A}: use the system matrix,
\item \texttt{distance laplacian}: use a distance Laplacian matrix that has been constructed using the graph of the system matrix \(A\), nodal coordinates \(X\) and a metric \(d\) determined by the option \texttt{aggregation: distance laplacian metric}, i.e.
  \begin{equation}
    L_{d}(A, X)_{ij} :=
    \begin{cases}
      -\frac{1}{d(X_{i,:},X_{j,:})^{2}} & \text{if } i\neq j \text{ and } A_{ij}\neq 0,\\
      0 & \text{if } i\neq j \text{ and } A_{ij}= 0,\\
      -\sum_{j\neq i}L_{d}(A, X)_{ij} & \text{if } i=j.
    \end{cases}
  \end{equation}
\end{itemize}

The available options for \texttt{aggregation: strength-of-connection measure} are listed in Table \ref{t:aggregation_soc_measures}.

\begin{table}[H]
  \begin{center}
    \begin{tabular}{ll}
      \verb!aggregation: strength-of-connection measure! & \\
      \toprule
      \verb!smoothed aggregation! & \(\frac{\left|M_{ij}\right|}{\sqrt{\left|M_{ii}\right|\left|M_{jj}\right|}} \) \\
      \verb!signed smoothed aggregation! & \(\frac{-\operatorname{sign} \left(M_{ij}\right) \left|M_{ij}\right|}{\sqrt{\left|M_{ii}\right|\left|M_{jj}\right|}} \) \\
      \verb!signed ruge-stueben! & \(\frac{-\operatorname{Re} \left(M_{ij}\right)}{\max_{j\neq i} -\operatorname{Re}M_{ij}} \) \\
      \verb!unscaled! & \(\left|M_{ij}\right|\) \\
      \bottomrule
    \end{tabular}
    \caption{Available choices for \texttt{aggregation: strength-of-connection measure}. Depending on the choice of \texttt{aggregation: strength-of-connection matrix} the matrix \(M\) is either the system matrix (\texttt{A}) or the distance Laplacian matrix (\texttt{distance laplacian}).}
\label{t:aggregation_soc_measures}
  \end{center}
\end{table}


Once a strength-of-connection matrix \(S\) has been computed a dropping scheme is applied to determine which entries of the graph should be kept or dropped.
All schemes use the dropping tolerance \(\theta\) set by \texttt{aggregation: drop tol}.
Two options are available for \texttt{aggregation: drop scheme}:
\begin{itemize}
\item \texttt{point-wise}: Drop entries in point-wise fashion, i.e. drop \((i,j)\) if \(\left|S_{ij}\right|\leq\theta\).
\item \texttt{cut-drop}: Drop entries in row-wise fashion. In the \(i\)-th row \(S_{i,:}\), sorts entries by absolute value and finds the first relative gap between entries of size bigger than \(\theta\). Drop all smaller entries.
\end{itemize}

A classical choice is to use \texttt{aggregation: strength-of-connection matrix} = \texttt{A}, \texttt{aggregation: strength-of-connection measure} = \texttt{smoothed aggregation} and \texttt{aggregation: drop scheme} = \texttt{point-wise}, resulting in the dropping criterion
\begin{equation}
  \frac{\left|A_{ij}\right|}{\sqrt{\left|A_{ii}\right|\left|A_{jj}\right|}} \leq \theta.
\end{equation}

To guarantee backward compatibility, \texttt{aggregation: drop scheme} also allows several legacy values.
These values trigger particular combinations of other parameter settings as shown in Table~\ref{t:old_aggregation_schemes}.

\begin{table}[H]
  \begin{center}
    \begin{tabular}{p{7.0cm} | p{10cm}}
      \texttt{aggregation: drop scheme} & \texttt{aggregation: strength-of-connection matrix}, \texttt{aggregation: strength-of-connection measure}\\
      \toprule
      \texttt{classical} & \texttt{A}, \texttt{smoothed aggregation} \\
      \texttt{signed classical sa} & \texttt{A}, \texttt{signed smoothed aggregation} \\
      \texttt{signed classical} & \texttt{A}, \texttt{signed ruge-stueben} \\
      \texttt{distance laplacian} &  \texttt{distance laplacian}, \texttt{smoothed aggregation} \\
      \texttt{signed classical sa distance laplacian} &  \texttt{distance laplacian}, \texttt{signed smoothed aggregation} \\
      \texttt{signed classical distance laplacian} &  \texttt{distance laplacian}, \texttt{signed ruge-stueben} \\
      \bottomrule
    \end{tabular}
    \caption{Legacy choices for \texttt{aggregation: drop scheme}.}
\label{t:old_aggregation_schemes}
  \end{center}
\end{table}

% ==================== REBALANCING ====================
\section{Rebalancing options}
\label{sec:options_rebalancing}

\input{options_rebalancing}

% ==================== MULTIGRID ====================
\section{Multigrid algorithm options}
\label{sec:options_mg}

\begin{table}[H]
  \begin{center}
    \begin{tabular}{p{3.5cm} p{11cm}}
      \toprule
      \verb!sa!          & Classic smoothed aggregation~\cite{VMB1996} \\
      \verb!unsmoothed!  & Aggregation-based, same as \verb!sa! but without damped Jacobi prolongator improvement step \\
      \verb!pg!          & Prolongator smoothing using $A$, restriction smoothing using $A^T$, local damping factors~\cite{ST2008} \\
      \verb!emin!        & Constrained minimization of energy in basis functions of grid transfer operator~\cite{WTWG2014,OST2011} \\
      \verb!interp!      & Interpolation based grid transfer operator, using piece-wise constant or linear interpolation from coarse nodes to fine nodes. This requires the use of structured aggregation.\\
      \verb!semicoarsen! & Semicoarsening grid transfer operator used to reduce a n-dimensional problem into a (n-1)-dimensional problem by coarsening fully in one of the spacial dimensions~\cite{TPSTP2015}.\\
      \verb!replicate!      & Transforms existing scalar prolongator to one  for PDE systems with multiple dofs per node.\\
      \verb!pcoarsen!    & \\
      \bottomrule
    \end{tabular}
    \caption{Available multigrid algorithms for generating grid transfer matrices. }
\label{t:mgs}
  \end{center}
\end{table}

\input{options_multigrid}

% ==================== REUSE ====================
\section{Reuse options}
\label{sec:options_reuse}

Reuse options are a way for a user to speed up the setup stage of multigrid.
The main requirement to use reuse is that the matrix' graph structure does not
change. Only matrix values are allowed to change.

The reuse options control the degree to which the multigrid hierarchy is preserved
for a subsequent setup call.

In addition, please note that not all combinations of multigrid algorithms and
reuse options are valid, or even make sense. For instance, the "emin" reuse
option should only be used with the "emin" multigrid algorithm.

Table~\ref{t:reuse_types} contains the information about different reuse
options. The options are ordered in increasing number of reuse components, from
the no reuse to the full reuse ("full").

\begin{table}[H]
  \begin{center}
    \begin{tabular}{p{3.0cm} p{12cm}}
      \toprule
      \verb!none!   & No reuse \\
      \verb!S!      & Reuse only the symbolic information of the level smoothers. \\
      \verb!tP!     & Reuse tentative prolongator. The graphs of smoothed
                      prolongator and matrices in Galerkin product are reused
                      only if filtering is not being used ({\it i.e.}, either
                      \verb!sa: use filtered matrix! or \verb!aggregation: drop tol! is false) \\
      \verb!emin!   & Reuse old prolongator as an initial guess to energy
                      minimization, and reuse the prolongator pattern \\
      \verb!RP!     & Reuse smoothed prolongator and restrictor. Smoothers are
                      recomputed.  \ding{42} \verb!RP! should reuse matrix graphs for
                      matrix-matrix product, but currently that is disabled as only \epetra{}
                      supports it. \\
      \verb!RAP!    & Recompute only the finest level smoothers, reuse all other operators \\
      \verb!full!   & Reuse everything \\
      \bottomrule
    \end{tabular}
    \caption{Available reuse options.}
\label{t:reuse_types}
  \end{center}
\end{table}

\input{options_reuse}

% ==================== MISCELLANEOUS ====================
\section{Miscellaneous options}

\input{options_misc}


% ==================== MAXWELL ====================
\section{Maxwell solver options}

\input{options_refmaxwell}

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