\label{sec:options}
In this section, we report the complete list of input parameters. Input
parameters are passed to \ifpacktwo in a single \parameterlist.

In some cases, the parameter types may depend on runtime template parameters.
In such cases, we will follow the conventions in Table~\ref{tab:conventions}.

\begin{table}[htbp]
  \centering
  \begin{tabular}{p{13.3cm} p{2.5cm}}
    \toprule
    \verb!MatrixType::local_ordinal_type!                                  & \verb!local_ordinal! \\
    \verb!MatrixType::global_ordinal_type!                                 & \verb!global_ordinal! \\
    \verb!MatrixType::scalar_type!                                         & \verb!scalar! \\
    \verb!MatrixType::node_type!                                           & \verb!node! \\
    \verb!Tpetra::Vector<scalar,local_ordinal,global_ordinal,node>!        & \verb!vector!\\
    \verb!Tpetra::MultiVector<scalar,local_ordinal,global_ordinal,node>!   & \verb!multi_vector!\\
    \verb!vector::mag_type!                                                & \verb!magnitude! \\
    \bottomrule
  \end{tabular}
  \caption{\label{tab:conventions}Conventions for option types that depend on templates.}
\end{table}

\noindent\textbf{Note:} if \verb!scalar! is \texttt{double}, then \verb!magnitude! is also \texttt{double}.

\section{Point relaxation}\label{s:relaxation}

\textbf{Preconditioner type:} ``RELAXATION''.

\ifpacktwo{} implements the following classical relaxation methods: Jacobi (with
optional damping), Gauss-Seidel, Successive Over-Relaxation (SOR), symmetric
version of Gauss-Seidel and SOR. \ifpacktwo{} calls both Gauss-Seidel and SOR
"Gauss-Seidel". The algorithmic details can be found in~\cite{Saad2003}.

Besides the classical relaxation methods, \ifpacktwo{} also implements $l_1$
variants of Jacobi and Gauss-Seidel methods proposed in~\cite{Baker2011}, which
lead to a better performance in parallel applications.

\noindent{\bf Note:} if a user provides a \texttt{Tpetra::BlockCrsMatrix}, the point relaxation
methods become block relaxation methods, such as block Jacobi or block
Gauss-Seidel.

The following parameters are used in the point relaxation methods:

\ccc{relaxation: type}
    {string}
    {``Jacobi''}
    {Relaxation method to use. Accepted values: ``Jacobi'',
     ``Gauss-Seidel'', ``Symmetric Gauss-Seidel''.}
\ccc{relaxation: sweeps}
    {int}
    {1}
    {Number of sweeps of the relaxation.}
\ccc{relaxation: damping factor}
    {scalar}
    {1.0}
    {The value of the damping factor $\omega$ for the relaxation.}
\ccc{relaxation: backward mode}
    {bool}
    {\false}
    {Governs whether Gauss-Seidel is done in forward-mode (\false) or
     backward-mode (\true). Only valid for ``Gauss-Seidel'' type.}
\ccc{relaxation: use l1}
    {bool}
    {\false}
    {Use the $l_1$ variant of Jacobi or Gauss-Seidel.}
\ccc{relaxation: l1 eta}
    {magnitude}
    {1.5}
    {$\eta$ parameter for $l_1$ variant of Gauss-Seidel. Only used if
     {\tt "relaxation: use l1"} is \true.}
\ccc{relaxation: zero starting solution}
    {bool}
    {\true}
    {Governs whether or not \ifpacktwo{} uses existing values in the left hand
     side vector. If true, \ifpacktwo{} fill it with zeros before applying
     relaxation sweeps which may make the first sweep more efficient.}
\ccc{relaxation: fix tiny diagonal entries}
    {bool}
    {\false}
    {If true, the compute() method will do extra work (computation only, no MPI
     communication) to fix diagonal entries. Specifically, the diagonal values
     with a magnitude smaller than the magnitude of the threshold \texttt{relaxation: min
     diagonal value} are increased to threshold for the diagonal inversion. The
     matrix is not modified, instead the updated diagonal values are stored. If the
     threshold is zero, only the diagonal entries that are exactly zero are replaced
     with a small nonzero value (machine precision).}
\ccc{relaxation: min diagonal value}
    {scalar}
    {0.0}
    {The threshold value used in {\tt "relaxation: fix tiny diagonal entries"}.
     Only used if {\tt "relaxation: fix tiny diagonal entries"} is \true.}
\ccc{relaxation: check diagonal entries}
    {bool}
    {\false}
    {If true, the \texttt{compute()} method will do extra work (both computation
     and communication) to count diagonal entries that are zero, have negative
     real part, or are small in magnitude. This information can be later shown
     in the description.}
\ccc{relaxation: mtgs cluster size}
    {int}
    {1}
    {Only has an effect if {\tt "relaxation: type"} is {\tt "MT Gauss-Seidel"}
     or {\tt "MT Symmetric Gauss-Seidel"}. If equal to 1 (default), point
     coloring parallel Gauss-Seidel is used. This has a faster \texttt{compute()}
     but may cause the preconditioned solver
     to converge more slowly. If set to $k > 1$, then multicolor block Gauss-Seidel
     is used with blocks of size $k$ (see \cite{Saad1999}).
     In the \texttt{apply()} there is significantly less
     error due to parallel updates of the LHS vector.}
\ccc{relaxation: mtgs coloring algorithm}
    {string}
    {``Default''}
    {Only has an effect if {\tt "relaxation: type"} is {\tt "MT Gauss-Seidel"}
     or {\tt "MT Symmetric Gauss-Seidel"}. Selects which graph coloring algorithm
     from Kokkos Kernels will be used to find sets of independent rows. ``Default''
     selects the algorithm based on the Node type. ``Serial'' is sequential and greedy.
     ``VB'', ``VBBIT'' and ``VBCS'' are parallel vertex-based (out of these, ``VBBIT'' is recommended).
     ``EB'' is parallel edge-based (faster than ``VBBIT'' on GPUs for irregular graphs).
     ``VBD'' and ``VBDBIT'' are parallel and deterministic.}
\ccc{relaxation: local smoothing indices}
    {Teuchos::ArrayRCP<local\_ordinal>}
    {empty}
    {}

%Teuchos::ArrayRCP MatrixType::local_ordinal_type}{\texttt{Teuchos::null}}
    {A given method will only relax on the local indices listed in the
     \texttt{ArrayRCP}, in the order that they are listed. This can be used to
     reorder the relaxation, or to only relax on a subset of ids.}

\section{Block relaxation}\label{s:block_relaxation}

\textbf{Preconditioner type:} ``BLOCK\_RELAXATION''.

% \info[inline]{AP}{ILUTP cannot be constructed through {\tt Ifpack2::Factory},
% only through additive Schwarz}

\ifpacktwo{} supports block relaxation methods. Each block corresponds to a set
of degrees of freedom within a local subdomain. The blocks can be
non-overlapping or overlapping. Block relaxation can be considered as domain
decomposition within an MPI process, and should not be confused with additive
Schwarz preconditioners (see~\ref{s:schwarz}) which implement domain
decomposition across MPI processes.

There are several ways the blocks are constructed:
\begin{itemize}
  \item Linear partitioning of unknowns

    The unknowns are divided equally among a specified number of
    partitions $L$ defined by {\tt "partitioner: local parts"}. In other words,
    assuming number of unknowns $n$ is divisible by $L$, unknown $i$ will belong
    to block number $\lfloor iL/n \rfloor$.

  \item Line partitioning of unknowns

    The unknowns are grouped based on a geometric criteria which tries to
    identify degrees of freedom that form an approximate geometric line.
    Current approach uses a local line detection inspired by the work of
    Mavriplis~\cite{Mavriplis1999} for convection-diffusion. \ifpacktwo uses
    coordinate information provided by {\tt "partitioner: coordinates"} to pick
    "close" points if they are sufficiently far away from the "far" points. It
    also makes sure the line can never double back on itself.

    These "line" partitions were found to be very beneficent to problems on
    highly anisotropic geometries such as ice-sheet simulations.

  \item User partitioning of unknowns

    The unknowns are grouped according to a user provided partition. A user
    may provide a non-overlapping partition {\tt "partitioner: map"} or an
    overlapping one via either {\tt "partitioner: parts"} or {\tt "partitioner: global ID parts"}.

    A particular example of a smoother using  this type of approach might be a Vanka
    smoother~\cite{Vanka1986}, where a user may in {\tt "partition: parts"} pressure
    degrees of freedom, and request a overlap of one thus constructing Vanka
    blocks.

    When blocks overlap, multiple solutions at each dof are combined for all blocks
    that contain this dof. When overlapping blocks reside on 
    different MPI ranks,  use block relaxation with 
    Schwarz  by setting {\tt "subdomain solver name"} to {\tt "BLOCK\_RELAXATION"} (see \ref{s:schwarz}).
    {\tt "schwarz: overlap level"} must be sufficient so that each block is
    fully contained within a subdomain. {\tt "schwarz: combine mode"}
    determines how overlapped values across MPI ranks are combined. If 
    {\tt "Jacobi"} is used for {\tt "relaxation: type"} when either 
    {\tt "schwarz: overlap level"} is not zero or when using
    {\tt "partitioner: parts"} or {\tt "partitioner: global ID parts"}, the main overlap combinations are
\begin{itemize}
        \item average solutions at each dof from all block solves containing the dof even when blocks
           reside on different MPI ranks. Set {\tt "schwarz: combine mode"} to {\tt "ADD"},
           and  {\tt "partitioner: nonsymmetric overlap combine"} to {\tt "true"} to do this.
        \item average solutions from all block solves containing the dof residing on MPI rank owning the dof within non-overlapped
           version of sub-domain (RAS or Restrictive Additive Schwarz). Set {\tt "schwarz: combine mode"} to {\tt "ZERO"}
           and {\tt "partitioner: nonsymmetric overlap combine"} to {\tt "true"} for this.
        \item symmetric version of first option when employing CG Krylov solver (i.e., first average block residuals and then average block solutions). 
           Set {\tt "schwarz: combine mode"} to {\tt "ADD"} and  {\tt "partitioner: nonsymmetric overlap combine"} to {\tt "false"}.
        \item symmetric version of second option when employing CG Krylov solver (i.e., average block residuals and block solutions
           for blocks on owning MPI rank). 
           Set {\tt "schwarz: combine mode"} to {\tt "ZERO"} and  {\tt "partitioner: nonsymmetric overlap combine"} to {\tt "false"}.
\end{itemize}

\end{itemize}
The original partitioning may be further modified with {\tt "partitioner: overlap"}
parameter which will use the local matrix graph to construct overlapping
partitions.

The blocks are applied in the order they were constructed. This means that in
the case of overlap the entries in the solution vector relaxed by one block may
later be overwritten by relaxing another block.

The following parameters are used in the block relaxation methods:

\cccc{relaxation: type}
    {See~\ref{s:relaxation}.}
\cccc{relaxation: container}
    {string}
    {``TriDi''}
    {Containers are used to store and solve block matrices. These container
     types are always available: ``Dense'', ``TriDi''
     (equivalent to ``Tridiagonal''), ``Banded'' and ``SparseILUT''.
     ``Dense'', ``TriDi'' and ``Banded'' block matrices are
     solved exactly LAPACK routines, and ``SparseILUT'' blocks are solved approximately
     using an incomplete LU factorization with thresholding.

     If Amesos2 is enabled, ``SparseAmesos'' (equivalent to ``SparseAmesos2'') is available.
     The default Amesos2 sparse solver is KLU2, but this can be configured by setting
     ``Amesos2 solver name'' (see the Amesos2 documentation for all available solvers).

     If experimental kokkos-kernels features are enabled (true by default), the ``BlockTriDi''
     container (equivalent to ``Block Tridiagonal'') is available. This container's solver is the damped Jacobi method, using
     block tridiagonal matrices as the diagonal D.
     For a block size of 1, this is equivalent to standard damped Jacobi.
     This container is designed for high performance on KNL and GPU.}
\cccc{relaxation: sweeps}
    {See~\ref{s:relaxation}.}
\cccc{relaxation: damping factor}
    {See~\ref{s:relaxation}.}
\cccc{relaxation: zero starting solution}
    {See~\ref{s:relaxation}.}
\cccc{relaxation: backward mode}
    {See~\ref{s:relaxation}. Currently has no effect. }
\ccc{block relaxation: decouple dofs}
    {bool}
    {false}
    {Whether to separate blocks according to the different degrees of
     freedom (PDEs) at each node. This assumes that dofs/node is constant
     throughout the matrix. Each block will have the same sparsity
     pattern as the mesh graph's corresponding diagonal block.
     For example, when using a line partitioner this
     enables the use of the tridiagonal container even if the matrix's
     bandwidth is greater than 3.
     Decoupling matches the behavior of line smoothing in ML.}
\ccc{partitioner: type}
    {string}
    {``linear''}
    {The partitioner to use for defining the blocks.  This can be either
     ``linear'', ``line'' or ``user''.}
\ccc{partitioner: overlap}
    {int}
    {0}
    {The amount of overlap between partitions (0 corresponds to no overlap).
     Only valid for ``Jacobi'' relaxation.}
\ccc{partitioner: local parts}
    {int}
    {1}
    {Number of local partitions (1 corresponds to one local partition, which
     means "do not partition locally"). Only valid for ``linear'' partitioner
     type.}
\ccc{partitioner: map}
    {Teuchos::ArrayRCP<local\_ordinal>}
    {empty}
    {An array containing the partition number for each element.
     The $i$th entry in the \texttt{ArrayRCP} is the part (block) number that
     row $i$ belongs to. Use this option if parts (blocks) do not
     overlap. Only valid for ``user'' partitioner type.}
\ccc{partitioner: parts}
    {Teuchos::Array<Teuchos::ArrayRCP\\<local\_ordinal>>}
    {empty}
    {Use this option if parts (blocks) overlap. The $i$th entry in the
     \texttt{Array} is an \texttt{ArrayRCP} containing all rows (local IDs) in part
     (block) $i$. Only valid for ``user'' partitioner type.}
\ccc{partitioner: global ID parts}
    {Teuchos::Array<Teuchos::ArrayRCP\\<global\_ordinal>>}
    {empty}
    {Use this option if parts (blocks) overlap. The $i$th entry in the
     \texttt{Array} is an \texttt{ArrayRCP} containing all rows (global IDs) in part
     (block) $i$. Only valid for ``user'' partitioner type.}
\ccc{partitioner: nonsymmetric overlap combine"}
    {bool}
    {\false}
    {Valid when using Jacobi relaxation with overlapping blocks.
     Corresponds to averaging only overlapping solutions as opposed
     to symmetric averaging which also averages residuals before performing block solves.}
\ccc{partitioner: line detection threshold}
    {magnitude}
    {0.0}
    {Threshold used in line detection. If the distance between two connected
     points $i$ and $j$ is within the threshold times maximum distance of all
     points connected to $i$, then point $j$ is considered close enough to line
     smooth. Only valid for ``line'' partition type.}
\ccc{partitioner: PDE equations}
    {int}
    {1}
    {Number of equations per node. Only used for ``line'' partitioning, and
     decoupled BlockRelaxation.}
\ccc{partitioner: coordinates}
    {Teuchos::RCP<multi\_vector>}
    {null}
    {Coordinates of local nodes. Only valid for ``line'' partitioner type.}
\ccc{partitioner: maintain sparsity}
    {bool}
    {\false}
    {For OverlappingPartitioner, whether to sort the entries in each partition.}

\section{Chebyshev}\label{s:Chebyshev}

\textbf{Preconditioner type:} ``CHEBYSHEV''.

% Mark Hoemmen (2016/05/31):
%   The "textbook version" of Chebyshev doesn't really
%   work; we need to get rid of it.

\ifpacktwo{} implements a variant of Chebyshev iterative method following
\ifpack{}'s implementation.  \ifpack{} has a special-case modification of the
eigenvalue bounds for the case where the maximum eigenvalue estimate is close to
one. Experiments show that the \ifpack{} imitation is much less sensitive to the
eigenvalue bounds than the textbook version.

\ifpacktwo{} uses the diagonal of the matrix to precondition the linear system on the
left. Diagonal elements less than machine precision are replaced with machine
precision.

\ifpacktwo{} requires can take any matrix $A$ but can only guarantee convergence
for real valued symmetric positive definite matrices.
\iffalse
If users could provide the ellipse parameters ($d$ and $c$ in the literature,
where $d$ is the real-valued center of the ellipse, and $d-c$ and $d+c$ the two
foci), the iteration itself would work fine with nonsymmetric real-valued $A$,
as long as the eigenvalues of $A$ can be bounded in an ellipse that is entirely
to the right of the origin.
\unsure[inline]{AP}{Really unsure about Chebyshev nonsymmetric matrices. There does not
seem anything in the code to work with ellipse. I need to ask Mark Hoemmen
about this.}
\fi

The following parameters are used in the Chebyshev method:

\ccc{chebyshev: degree}
    {int}
    {1}
    {Degree of the Chebyshev polynomial, or the number of iterations. This
     overrides parameters {\tt "relaxation: sweeps"} and {\tt "smoother: sweeps"}.}
\cccc{relaxation: sweeps}
    {Same as {\tt "chebyshev: degree"}, for compatibility with \ifpack{}.}
\cccc{smoother: sweeps}
    {Same as {\tt "chebyshev: degree"}, for compatibility with \ml{}.}
\ccc{chebyshev: max eigenvalue}
    {scalar|double}
    {computed}
    {An upper bound of the matrix eigenvalues. If not provided, the value will
     be computed by power method (see parameters {\tt "eigen-analysis: type"} and
     {\tt "chebyshev: eigenvalue max iterations"}).}
\ccc{chebyshev: min eigenvalue}
    {scalar|double}
    {computed}
    {A lower bound of the matrix eigenvalues.  If not provided, \ifpacktwo{}
     will provide an estimate based on the maximum eigenvalue and the ratio.}
\ccc{chebyshev: ratio eigenvalue}
    {scalar|double}
    {30.0}
    {The ratio of the maximum and minimum estimates of the matrix
     eigenvalues.}
\cccc{smoother: Chebyshev alpha}
    {Same as {\tt "chebyshev: ratio eigenvalue"}, for compatibility with \ml{}.}
% \ccc{chebyshev: textbook algorithm}
    % {bool}
    % {\false}
    % {If true, use the textbook variant; otherwise, use the \ifpack{} variant.}
\ccc{chebyshev: algorithm}
    {string}
    {"first"}
    {The algorithm for the Chebyshev polynomial. Currently supports
     the default \ifpack{} variant, otherwise known as the first-kind ("first") Chebyshev polynomials.
     Chebyshev smoothing via the fourth-kind ("fourth") and optimized fourth-kind ("opt_fourth")
     are also implemented as in ~\cite{Lottes2022}.
     Note that these latter two algorithms do not require the ad-hoc minimum eigenvalue estimate
     as the standard \ifpack{} algorithm ("first").
     The textbook algorithm ("textbook") as described in ~\cite{Saad2003} is also available.
     However, the "first", "fourth", and "opt_fourth" kinds are preferred.
     Currently supported: "first", "fourth", "opt_fourth", and "textbook".
     Generally, the "fourth" and "opt_fourth" provide better smoothing properties
     when employing the Chebyshev polynomials as multigrid smoothers, especially at orders
     greater than or equal to 3.
    }
\ccc{chebyshev: compute max residual norm}
    {bool}
    {\false}
    {The \texttt{apply} call will optionally return the norm of the residual.}
\ccc{chebyshev: compute spectral radius}
    {bool}
    {\true}
    {The power method will compute the spectral radius if true. If false, it will
     instead compute the dominant eigenvalue (these differ by absolute value).}
\ccc{eigen-analysis: type}
    {string}
    {"power-method"}
    {The algorithm for estimating the max eigenvalue. Currently only supports
     power method ("power-method" or "power method"). The cost of the procedure is
     roughly equal to several matrix-vector multiplications.}
\ccc{chebyshev: eigenvalue max iterations}
    {int}
    {10}
    {Number of iterations to be used in calculating the estimate for the maximum
     eigenvalue, if it is not provided by the user.}
\cccc{eigen-analysis: iterations}
    {Same as {\tt "chebyshev: eigenvalue max iterations"}, for compatibility with \ml{}.}
\ccc{chebyshev: min diagonal value}
    {scalar}
    {0.0}
    {Values on the diagonal smaller than this value are increased to this value
     for the diagonal inversion.}
\ccc{chebyshev: boost factor}
    {double}
    {1.1}
    {Factor used to increase the estimate of matrix maximum eigenvalue to ensure
    the high-energy modes are not magnified by a smoother.}
\ccc{chebyshev: assume matrix does not change}
    {bool}
    {\false}
    {Whether \texttt{compute()} should assume that the matrix has not changed
     since the last call to \texttt{compute()}. If true, \texttt{compute()}
     will not recompute inverse diagonal or eigenvalue estimates.}
\ccc{chebyshev: operator inv diagonal}
    {Teuchos::RCP<const vector>|\\Teuchos::RCP<vector>|const vector*|\\vector}
    {Teuchos::null}
    {If nonnull, a deep copy of this vector will be used as the inverse
     diagonal of the matrix, instead of computing it. Expert use only.}
\ccc{chebyshev: min diagonal value}
    {scalar}
    {machine precision}
    {If any entry of the matrix diagonal is less that this in magnitude, it will
     be replaced with this value in the inverse diagonal used for left scaling.}
\cccc{chebyshev: zero starting solution}
    {See {\tt "relaxation: zero starting solution"}.}

\section{Incomplete factorizations}

\subsection{ILU($k$)}\label{s:ILU}

\textbf{Preconditioner type:} ``RILUK''.

\ifpacktwo{} implements a standard and modified (MILU) variants of the
ILU($k$) factorization~\cite{Saad2003}. In addition, it also provides an
optional \textit{a priori} modification of the diagonal entries of a matrix to
improve the stability of the factorization.

The following parameters are used in the ILU($k$) method:

\ccc{fact: iluk level-of-fill}
    {int|global\_ordinal|magnitude|double}
    {0}
    {Level-of-fill of the factorization.}
\ccc{fact: relax value}
    {magnitude|double}
    {0.0}
    {MILU diagonal compensation value. Entries dropped during factorization
     times this factor are added to diagonal entries.}
\ccc{fact: absolute threshold}
    {magnitude|double}
    {0.0}
    {Prior to the factorization, each diagonal entry is updated by adding
     this value (with the sign of the actual diagonal entry). Can be combined
     with {\tt "fact: relative threshold"}. The matrix remains unchanged.}
\ccc{fact: relative threshold}
    {magnitude|double}
    {1.0}
    {Prior to the factorization, each diagonal element is scaled by this factor
     (not including contribution specified by {\tt "fact: absolute
     threshold"}). Can be combined with {\tt "fact: absolute threshold"}.
     The matrix remains unchanged.}
\ccc{fact: type}
    {string}
    {"Serial"}
    {The RILUK factorization implementation type. Currently supports two types:
     "Serial" (serial execution on the host) and "KSPILUK" (a Kokkos Kernels's
     SpILUK on multi-core or GPU).}
\ccc{trisolver: type}
    {string}
    {"Internal"}
    {The triangular solver type. Currently supports three solver types:
     "Internal" (serial execution on the host), "HTS" (a ShyLU's sparse
     triangular solver that uses OpenMP on the host), and "KSPTRSV" (a Kokkos
     Kernels's SpTRSV on multi-core or GPU).}
\ccc{fact: kspiluk number-of-streams}
    {int|global\_ordinal}
    {0}
    {Number of streams used by Kokkos Kernels's SpILUK and SpTRSV. When using
     streams, the sub-domain on each MPI process is divided to diagonal blocks,
     each of which is handled by SpILUK and SpTRSV on a stream. Because
     information in off-diagonals of the sub-domain is ignored, it is expected
     that iterative solvers take more interations to converge. However, since
     these streams can run concurrently, the total time can be faster. When
     this option is not set (i.e. not using stream), the entire sub-domain is
     used instead.}
\ccc{fact: kspiluk reordering in streams}
    {bool}
    {\false}
    {Whether RCM reordering is applied to diagonal blocks in streams.}
% All overlap-related code was removed by M. Hoemmen in
%
% commit 162f64572fbf93e2cac73e3034d76a3db918a494
% Author: Mark Hoemmen <mhoemme@sandia.gov>
% Date:   Fri Jan 24 17:16:19 2014 -0700
%
%     Ifpack2: RILUK: Removed all overlap-related code.
%
%     Overlap never had a correct implementation in RILUK.  Furthermore,
%     AdditiveSchwarz is the proper place for overlap to be implemented, not
%     RILUK.  Ifpack2's incomplete factorizations are local (per MPI
%     process) solvers and don't need to know anything about overlap across
%     processes.  Thus, this commit removes all overlap-related code from
%     RILUK.
%
% So, older parameter "fact: iluk level-of-overlap" is no longer valid and is ignored.

\subsection{ILUT}\label{s:ILUT}

\textbf{Preconditioner type:} ``ILUT''.

\ifpacktwo{} implements a slightly modified variant of the standard ILU factorization with specified fill and
drop tolerance ILUT($p,\tau$)~\cite{Saad1994}. The modifications follow the \aztecoo implementation.
The main difference between the \ifpacktwo implementation and the algorithm in \cite{Saad1994} is the definition of
\texttt{fact: ilut level-of-fill}.

The following parameters are used in the ILUT method:

\ccc{fact: ilut level-of-fill}
    {int|magnitude|double}
    {1}
    {Maximum fill fraction that controls the
     number of entries to keep in the strict upper triangle of the
     current row, and in the strict lower triangle of the current
     row.  This value must be $>= 1.0$.  Each row of $L$ ($U$) will have at most $\lceil\frac{(\mbox{\small\tt
     level-of-fill}-1)nnz(A)}{2n}\rceil$ nonzero entries, in addition to those from the sparsity pattern of A, where $nnz(A)$ is the
     number of nonzero entries in the matrix, and $n$ is the number of rows.
     ILUT always keeps the diagonal entry in the current row, regardless of the
     drop tolerance or fill level. \textbf{Note:} \textit{This is
     different from the $p$ in the classic algorithm in~\cite{Saad1994}.}}
\ccc{fact: drop tolerance}
    {magnitude|double}
    {0.0}
    {A threshold for dropping entries ($\tau$ in~\cite{Saad1994}).}
\cccc{fact: absolute threshold}
    {See~\ref{s:ILU}.}
\cccc{fact: relative threshold}
    {See~\ref{s:ILU}.}
\cccc{fact: relax value}
    {Currently has no effect. For backwards compatibility only.}

\subsection{ILUTP}\label{s:ILUTP}

\textbf{Preconditioner type:} ``AMESOS2''.

% \info[inline]{AP}{ILUTP cannot be constructed through {\tt Ifpack2::Factory},
% only through additive Schwarz}

\ifpacktwo{} implements a standard ILUTP factorization~\cite{Saad2003}. This is
done through is through the \amesostwo interface to SuperLU~\cite{Li2011}. We
reproduce the \amesostwo options here for convenience. {\em You should consider
the \href{http://trilinos.org/docs/dev/packages/amesos2/doc/html/group__amesos2__solver__parameters.html#superlu_parameters}{\amesostwo
documentation} to be the final authority.}

The following parameters are used in the ILUTP method:

\ccc{ILU\_DropTol}
    {double}
    {1e-4}
    {ILUT drop tolerance.}
\ccc{ILU\_FillFactor}
    {double}
    {10.0}
    {ILUT fill factor.}
\ccc{ILU\_Norm}
    {string}
    {``INF\_NORM''}
    {Norm to be used in factorization. Accepted values: ``ONE\_NORM'', ``TWO\_NORM'', or ``INF\_NORM''.}
\ccc{ILU\_MILU}
    {string}
    {``SILU''}
    {Type of modified ILU to use. Accepted values: ``SILU'', ``SMILU\_1'', ``SMILU\_2'', or ``SMILU\_3''.}

\subsection{ShyLU FastILU}\label{s:FastILU}
\ifpacktwo{} provides an interface to the FastILU family of factorizations provided by ShyLU.
They are available if Trilinos was configured with the

\texttt{-D Trilinos\_ENABLE\_ShyLU\_Node=ON}

option. There are three values of ``Preconditioner type:'' that use the FastILU subpackage:

\begin{table}[h!]
\centering
\begin{tabular}{|l|l|}
\hline
``Preconditioner type:'' & Factorization   \\ \hline \hline
FAST\_ILU                & Incomplete LU       \\ \hline
FAST\_IC                 & Incomplete Cholesky \\ \hline
FAST\_ILDL               & Incomplete LDL*     \\ \hline
\end{tabular}
\end{table}

FAST\_ILU, FAST\_IC, and FAST\_ILDL all use iterative factorization algorithms in compute(). \texttt{"sweeps"} controls
this iteration count. A higher number of sweeps improves the quality of the factorization. All three
preconditioners also use an triangular block Jacobi solver in apply().
The Jacobi iteration count is controlled by \texttt{"triangular solve iterations"}.
The valid set of parameters is the same for FAST\_ILU, FAST\_IC, and FAST\_ILDL:

\ccc{sweeps}
    {int}
    {5}
    {Number of iterations of ILU/IC/ILDL factorization algorithm.}
\ccc{triangular solve type}
    {string}
    {Fast}
    {Type of triangular solve algorithm to use: ``Fast'' for the block Jacobi triangular solver, ``Standard'' for the standard (forward/backward) substitution based triangular solver (calls Kokkos-Kernels {\bf sptrsv}), or "Standard Host" for the standard triangular solver on host CPU (calls Kokkos-Kernels {\bf trsv} on the host).}
\ccc{triangular solve iterations}
    {int}
    {1}
    {Number of iterations of the block Jacobi triangular solver.}
\ccc{level}
    {int}
    {0}
    {Level of fill.}
\ccc{damping factor}
    {double}
    {0.5}
    {Damping factor $\omega$ for the Jacobi triangular solver. $0 < \omega \leq 1$. A lower $\omega$ slows convergence but improves stability.}
\ccc{shift}
    {double}
    {0}
    {Manteuffel shifting parameter $\alpha$.}
\ccc{guess}
    {bool}
    {true}
    {Whether to run another instance of FastILU/IC/ILDL (but with a lower level of fill) to compute the initial guess (only has an effect if level of fill $> 0$).} 
 \ccc{block size for ILU}
    {int}
    {1}
    {Block size for the iterative factorization algorithm.}
\ccc{block size for SpTRSV}
    {int}
    {1}
    {Block size for the block Jacobi solver.}

\section{Additive Schwarz}\label{s:schwarz}

\textbf{Preconditioner type:} ``SCHWARZ''.

\ifpacktwo{} implements additive Schwarz domain decomposition with optional
overlap. Each subdomain corresponds to exactly one MPI process in the given
matrix's MPI communication. For domain decomposition within an
MPI process see~\ref{s:block_relaxation}.

One-level overlapping domain decomposition preconditioners use local solvers of
Dirichlet type. This means that the inverse of the local matrix (possibly with
overlap) is applied to the residual to be preconditioned. The preconditioner can
be written as:
$$ P_{AS}^{-1} = \sum_{i=1}^M P_i A_i^{-1} R_i, $$
where $M$ is the number of subdomains (in this case, the number of (MPI)
processes in the computation), $R_i$ is an operator that restricts the global
vector to the vector lying on subdomain $i$, $P_i$ is the prolongator
operator, and $A_i = R_i A P_i$.

Constructing a Schwarz preconditioner requires defining two components.

{\bf Definition of the restriction and prolongation operators.}
Users may control how the data is combined with existing data by setting {\tt
"combine mode"} parameter. Table~\ref{t:combine_mode} contains a list of modes to
combine overlapped entries. The default mode is ``ZERO'' which is equivalent to
using a restricted additive Schwarz~\cite{Cai1999} method.

\begin{table}[htbp]
  \centering
  \begin{tabular}{p{3.5cm} p{12.0cm}}
    \toprule
    Combine mode name & Description \\
    \midrule
    ``ADD''           & Sum values into existing values \\
    ``ZERO''          & Replace old values with zero \\
    ``INSERT''        & Insert new values that don't currently exist \\
    ``REPLACE''       & Replace existing values with new values \\
    ``ABSMAX''        & Replace old values with maximum of magnitudes of old and new values \\
    \bottomrule
  \end{tabular}
  \caption{\label{t:combine_mode}Combine mode descriptions.}
\end{table}

{\bf Definition of a solver for subdomain linear system.}
Some preconditioners may benefit from local modifications to the subdomain
matrix. It can be filtered to eliminate singletons and/or reordered.
Reordering will often improve performance during incomplete factorization setup,
and improve the convergence. The matrix reordering algorithms specified in {\tt
"schwarz: reordering list"} are provided by \zoltantwo.  At the present time,
the only available reordering algorithm is RCM (reverse Cuthill-McKee). Other
orderings will be supported by the Zoltan2 package in the future.

To solve linear systems involving $A_i$ on each subdomain, a user can specify
the inner solver by setting {\tt "inner preconditioner name"} parameter (or any
of its aliases) which allows to use any \ifpacktwo preconditioner. These include
but are not necessarily limited to the preconditioners in
Table~\ref{t:schwarz_inner}.

\begin{table}[htbp]
  \centering
  \begin{tabular}{p{5.0cm} p{10.5cm}}
    \toprule
    Inner solver type       & Description \\
    \midrule
    ``DIAGONAL''            & Diagonal scaling \\
    ``RELAXATION''          & Point relaxation (see~\ref{s:relaxation}) \\
    ``BLOCK\_RELAXATION''   & Block relaxation (see~\ref{s:block_relaxation}) \\
    ``CHEBYSHEV''           & Chebyshev iteration (see~\ref{s:Chebyshev}) \\
    ``RILUK''               & ILU($k$) (see~\ref{s:ILU}) \\
    ``ILUT''                & ILUT (see~\ref{s:ILUT}) \\
    ``FAST\_ILU''             & FastILU (see~\ref{s:FastILU}) \\
    ``FAST\_IC''              & FastIC (see~\ref{s:FastILU}) \\
    ``FAST\_ILDL''            & FastILDL(see~\ref{s:FastILU}) \\
    ``AMESOS2''             & \amesostwo's interface to sparse direct solvers \\
    ``DENSE'' or ``LAPACK'' & LAPACK's LU factorization for a dense representation of a subdomain matrix \\
    ``CUSTOM''              & User provided inner solver \\
    % ``RBILUK''
    \bottomrule
  \end{tabular}
  \caption{\label{t:schwarz_inner}Additive Schwarz solver preconditioner types.}
\end{table}

The following parameters are used in the Schwarz method:

\ccc{schwarz: inner preconditioner name}
    {string}
    {none}
    {The name of the subdomain solver.}
\cccc{inner preconditioner name}
    {Same as {\tt "schwarz: inner preconditioner name"}.}
\cccc{schwarz: subdomain solver name}
    {Same as {\tt "schwarz: inner preconditioner name"}.}
\cccc{subdomain solver name}
    {Same as {\tt "schwarz: inner preconditioner name"}.}
\ccc{schwarz: inner preconditioner parameters}
    {\parameterlist}
    {empty}
    {Parameters for the subdomain solver. If not provided, the subdomain solver
     will use its specific default parameters.}
\cccc{inner preconditioner parameters}
    {Same as {\tt "schwarz: inner preconditioner parameters"}.}
\cccc{schwarz: subdomain solver parameters}
    {Same as {\tt "schwarz: inner preconditioner parameters"}.}
\cccc{subdomain solver parameters}
    {Same as {\tt "schwarz: inner preconditioner parameters"}.}
\ccc{schwarz: combine mode}
    {string}
    {``ZERO''}
    {The rule for combining incoming data with existing data in overlap regions.
     Accepted values: see Table~\ref{t:combine_mode}.}
\ccc{schwarz: overlap level}
    {int}
    {0}
    {The level of overlap (0 corresponds to no overlap).}
\ccc{schwarz: num iterations}
    {int}
    {1}
    {Number of iterations to perform.}
\ccc{schwarz: use reordering}
    {bool}
    {\false}
    {If true, local matrix is reordered before computing subdomain solver. \trilinos must have been built with
     \zoltantwo and \xpetra enabled.}
\ccc{schwarz: reordering list}
    {\parameterlist}
    {empty}
    {Specify options for a \zoltantwo reordering algorithm to use. See {\tt
     "order\_method"}. {\em You should consider the
     \href{http://trilinos.org/docs/dev/packages/zoltan2/doc/html/z2_parameters.html}{\zoltantwo
     documentation} to be the final authority.}}
\ccc{order\_method}
    {string}
    {``rcm''}
    {Reordering algorithm. Accepted values: ``rcm'', ``minimum\_degree'',
     ``natural'', ``random'', or ``sorted\_degree''. Only used in {\tt
     "schwarz: reordering list"} sublist.}
\cccc{schwarz: zero starting solution}
    {See {\tt "relaxation: zero starting solution"}.}
\ccc{schwarz: filter singletons}
    {bool}
    {\false}
    {If true, exclude rows with just a single entry on the calling process.}
\cccc{schwarz: subdomain id}
    {Currently has no effect.}
\cccc{schwarz: compute condest}
    {Currently has no effect. For backwards compatibility only.}
\ccc{schwarz: update damping}
    {double}
    {1.0}
    {The amount by which to damp the updates from the Schwarz solve
      (1.0 is no damping).}
\section{Hiptmair}

\ifpacktwo{} implements Hiptmair algorithm of~\cite{Hiptmair1997}. The method
operates on two spaces: a primary space and an auxiliary space. This situation
arises, for instance,  when preconditioning Maxwell's equations discretized by
edge elements. It is used in \muelu~\cite{MueLu} ``RefMaxwell''
solver~\cite{RefMaxwell}.

Hiptmair's algorithm does not use \texttt{Ifpack2::Factory} interface for
construction.  Instead, a user must explicitly call the constructor
\begin{lstlisting}[language=C++]
  Teuchos::RCP<Tpetra::CrsMatrix<> > A, Aaux, P;
  // create A, Aaux, P here ...
  Teuchos::ParameterList paramList;
  paramList.set("hiptmair: smoother type 1", "CHEBYSHEV");
  // ...
  RCP<Ifpack2::Ifpack2Preconditioner<> > ifpack2Preconditioner =
    Teuchos::rcp(new Ifpack2::Hiptmair(A, Aaux, P);
  ifpack2Preconditioner->setParameters(paramList);
\end{lstlisting}
\noindent Here, $A$ is a matrix in the primary space, $Aaux$ is a matrix in
auxiliary space, and $P$ is a prolongator/restrictor between the two spaces.

The following parameters are used in the Hiptmair method:

\ccc{hiptmair: smoother type 1}
    {string}
    {"CHEBYSHEV"}
    {Smoother type for smoothing the primary space.}
\ccc{hiptmair: smoother list 1}
    {\parameterlist}
    {empty}
    {Smoother parameters for smoothing the primary space.}
\ccc{hiptmair: smoother type 2}
    {string}
    {"CHEBYSHEV"}
    {Smoother type for smoothing the auxiliary space.}
\ccc{hiptmair: smoother list 2}
    {\parameterlist}
    {empty}
    {Smoother parameters for smoothing the auxiliary space.}
\ccc{hiptmair: pre or post}
    {string}
    {``both''}
    {\ifpacktwo{} always relaxes on the auxiliary space. ``pre'' (``post'') means
     that it relaxes on the primary space before (after) the relaxation on the
     auxiliary space. ``both'' means that we do both ``pre'' and ``post''.}
\cccc{hiptmair: zero starting solution}
    {See {\tt "relaxation: zero starting solution"}.}
