Ifpack2 Templated Preconditioning Package Version 1.0
Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType > Class Template Reference

Additive Schwarz domain decomposition for Tpetra sparse matrices. More...

#include <Ifpack2_AdditiveSchwarz_decl.hpp>

Inheritance diagram for Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >:
[legend]

List of all members.

## Public Types

Typedefs
typedef MatrixType::scalar_type scalar_type
The type of the entries of the input MatrixType.
typedef
MatrixType::local_ordinal_type
local_ordinal_type
The type of local indices in the input MatrixType.
typedef
MatrixType::global_ordinal_type
global_ordinal_type
The type of global indices in the input MatrixType.
typedef MatrixType::node_type node_type
The type of the Kokkos Node used by the input MatrixType.
typedef Teuchos::ScalarTraits
< scalar_type >::magnitudeType
magnitude_type
The type of the magnitude (absolute value) of a matrix entry.
typedef Tpetra::RowMatrix
< scalar_type,
local_ordinal_type,
global_ordinal_type, node_type
row_matrix_type
The Tpetra::RowMatrix specialization matching MatrixType.

## Public Member Functions

virtual Teuchos::RCP< const
row_matrix_type
getMatrix () const
The input matrix.
virtual void setParameters (const Teuchos::ParameterList &plist)
Set the preconditioner's parameters.
void setParameterList (const Teuchos::RCP< Teuchos::ParameterList > &plist)
Set the preconditioner's parameters.
Teuchos::RCP< const
Teuchos::ParameterList
getValidParameters () const
Get a list of the preconditioner's default parameters.
virtual void initialize ()
Computes all (graph-related) data necessary to initialize the preconditioner.
virtual bool isInitialized () const
Returns true if the preconditioner has been successfully initialized, false otherwise.
virtual void compute ()
Computes all (coefficient) data necessary to apply the preconditioner.
virtual bool isComputed () const
Returns true if the preconditioner has been successfully computed, false otherwise.
virtual magnitude_type
TEUCHOS_DEPRECATED
computeCondEst (CondestType CT=Ifpack2::Cheap, local_ordinal_type MaxIters=1550, magnitude_type Tol=1e-9, const Teuchos::Ptr< const row_matrix_type > &Matrix=Teuchos::null)
Compute the condition number estimate and return its value.
virtual magnitude_type
TEUCHOS_DEPRECATED
getCondEst () const
Return the computed condition number estimate, or -1 if not computed.
virtual int getNumInitialize () const
Returns the number of calls to initialize().
virtual int getNumCompute () const
Returns the number of calls to compute().
virtual int getNumApply () const
Returns the number of calls to apply().
virtual double getInitializeTime () const
Returns the time spent in initialize().
virtual double getComputeTime () const
Returns the time spent in compute().
virtual double getApplyTime () const
Returns the time spent in apply().
virtual std::ostream & print (std::ostream &os) const
Prints basic information on iostream. This function is used by operator<<.
virtual int getOverlapLevel () const
Returns the level of overlap.
AdditiveSchwarz (const Teuchos::RCP< const row_matrix_type > &A)
Constructor that takes a matrix.
AdditiveSchwarz (const Teuchos::RCP< const row_matrix_type > &A, const int overlapLevel)
Constructor that takes a matrix and the level of overlap.
Destructor.
Implementation of Tpetra::Operator
virtual Teuchos::RCP< const
Tpetra::Map
< local_ordinal_type,
global_ordinal_type, node_type > >
getDomainMap () const
The domain Map of this operator.
virtual Teuchos::RCP< const
Tpetra::Map
< local_ordinal_type,
global_ordinal_type, node_type > >
getRangeMap () const
The range Map of this operator.
virtual void apply (const Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type > &X, Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type > &Y, Teuchos::ETransp mode=Teuchos::NO_TRANS, scalar_type alpha=Teuchos::ScalarTraits< scalar_type >::one(), scalar_type beta=Teuchos::ScalarTraits< scalar_type >::zero()) const
Apply the preconditioner to X, putting the result in Y.
Implementation of Ifpack2::Details::NestedPreconditioner
virtual void setInnerPreconditioner (const Teuchos::RCP< Preconditioner< scalar_type, local_ordinal_type, global_ordinal_type, node_type > > &innerPrec)
Set the inner preconditioner.
Implementation of Ifpack2::Details::CanChangeMatrix
virtual void setMatrix (const Teuchos::RCP< const row_matrix_type > &A)
Change the matrix to be preconditioned.
Implementation of Teuchos::Describable
std::string description () const
Return a simple one-line description of this object.
void describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
Print the object with some verbosity level to an FancyOStream object.

## Public Attributes

TEUCHOS_DEPRECATED typedef
MatrixType::scalar_type
Scalar
Preserved only for backwards compatibility. Please use "scalar_type".
TEUCHOS_DEPRECATED typedef
MatrixType::local_ordinal_type
LocalOrdinal
Preserved only for backwards compatibility. Please use "local_ordinal_type".
TEUCHOS_DEPRECATED typedef
MatrixType::global_ordinal_type
GlobalOrdinal
Preserved only for backwards compatibility. Please use "global_ordinal_type".
TEUCHOS_DEPRECATED typedef
MatrixType::node_type
Node
Preserved only for backwards compatibility. Please use "node_type".
TEUCHOS_DEPRECATED typedef
Teuchos::ScalarTraits
< scalar_type >::magnitudeType
magnitudeType
Preserved only for backwards compatibility. Please use "magnitude_type".
TEUCHOS_DEPRECATED typedef
Tpetra::RowMatrix< scalar_type,
local_ordinal_type,
global_ordinal_type, node_type
LocalMatrixType
Preserved only for backwards compatibility. Please use "row_matrix_type".

## Detailed Description

### template<class MatrixType, class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>> class Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >

Additive Schwarz domain decomposition for Tpetra sparse matrices.

Template Parameters:
 MatrixType A specialization of Tpetra::CrsMatrix LocalInverseType The type of the solver for the local (subdomain) problem. This must be a specialization of a concrete subclass of Ifpack2::Preconditioner. Using a type here other than Ifpack2::Preconditioner is DEPRECATED, because the subdomain solver's type is determined entirely at run time. Please refer to discussion below for more details.

## Summary

This class implements Additive Schwarz domain decomposition, with optional overlap. It operates on a given Tpetra::RowMatrix. Each subdomain corresponds to exactly one MPI process in the given matrix's MPI communicator. For nonoverlapping domain decomposition within an MPI process, please use BlockRelaxation.

This class is a subclass of Tpetra::Operator, like all other subclasses of Preconditioner. Thus, the apply() method applies the preconditioner to a multivector.

## Algorithm

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 takes two steps:

1. Definition of the restriction and prolongation operators
2. Definition of a solver for linear systems involving $$A_i$$

The definition of the restriction and prolongation operators $$R_i$$ and $$R_i^T$$ depends on the level of overlap. If the overlap level is zero (no overlap), their implementation is trivial; $$R_i$$ will return all the local components. For nonzero overlap, Tpetra's data redistribution facilities (Tpetra::Import) will be used to bring in the required data. Users may control how these data are combined with existing data, by setting the combine mode parameter. Valid combine modes include "ADD", "INSERT", "REPLACE", "ABSMAX", and "ZERO". These correspond to the valid values of Tpetra::CombineMode.

To solve linear systems involving $$A_i$$ on each subdomain, the user can adopt any subclass of Preconditioner. Currently, users control this at compile time by setting the second template parameter LocalInverseType. Soon, this option will be removed in favor of run-time control of the subdomain solver.

The local matrix $$A_i$$ can be filtered, to eliminate singletons, and reordered. At the present time, the only available reordering algorithm is RCM (reverse Cuthill-Mckee).

## Combine modes

AdditiveSchwarz supports different combine modes. These are rules for combining overlapping entries from the subdomain solves' results, to form the final additive Schwarz result. The two modes that users will likely find most useful are "Add" and "Zero". "Add" sums overlapping results, and "Zero" ignores them.

The Zero combine mode can be a bit confusing. It helps to compare the Add combine mode without overlap, to the Zero combine mode with overlap. Consider the following 4 x 4 linear system $$Ax = b$$, where

$A = \left( \begin{array}{rrrr} 2 & -1 & 0 & 0 \\ -1 & 2 & -1 & 0 \\ 0 & -1 & 2 & -1 \\ 0 & 0 & -1 & 2 \end{array} \right)$

and

$b = \left( \begin{array}{rrrr} 1 \\ 4 \\ 9 \\ 16 \end{array} \right) .$

Suppose that we give the first two rows of A and b to Process 0, and the last two rows of A and b to Process 1.

If we use additive Schwarz without overlap, and use the (default) Add combine mode, then each process must solve a linear system with the following 2 x 2 matrix:

$A_{local} = \left( \begin{array}{rr} 2 & -1 \\ -1 & 2 \end{array} \right).$

The inverse of this matrix is

$A_{local}^{-1} = \frac{1}{3} \cdot \left( \begin{array}{rr} 2 & 1 \\ 1 & 2 \end{array} \right).$

Process 0 gets the right-hand side $$(1, 4)^T$$ and thus the local solution $$(2, 3)^T$$. Process 1 gets the right-hand side $$(9, 16)^T$$ and thus the local solution $$(34/3, 41/3)^T$$. The Add combine mode sums entries corresponding to overlap, but in this case there is no overlap, so we just concatenate the local results. Thus, the result of applying additive Schwarz once is

$x_{Add} = \begin{array}{r} 2 \\ 3 \\ 34/3 \\ 41/3 \end{array}.$

If we introduce one level of overlap on each of these processes, and use the Zero combine mode with additive Schwarz, then each process has to solve a linear system with the following 3 x 3 matrix:

$A_{local} = \left( \begin{array}{rrr} 2 & -1 & 0 \\ -1 & 2 & -1 \\ 0 & -1 & 2 \end{array} \right).$

The inverse of this matrix is

$A_{local}^{-1} = \frac{1}{4} \cdot \left( \begin{array}{rrr} 3 & 2 & 1 \\ 2 & 4 & 2 \\ 1 & 2 & 3 \end{array} \right).$

Process 0 gets the right-hand side $$(1, 4, 9)^T$$ and thus the local solution $$(5, 9, 9)^T$$. Process 1 gets the right-hand side $$(4, 9, 16)^T$$ and thus the local solution $$(23/2, 19, 35/2)^T$$. The Zero combine mode ignores "remote entries," so that the result of applying additive Schwarz once is

$x_{Zero} = \begin{array}{r} 5 \\ 9 \\ 19 \\ 35/2 \end{array}.$

Even though both of the above examples combine the local results in the same way, Zero produces a different final result than Add, because the Zero example uses overlap 1, whereas the Add example uses overlap 0.

## Subdomain solver

This class gives you two ways to specify the subdomain solver. First, you may set the "subdomain solver name" or "inner preconditioner name" parameters in the input to setParameters() or setParameterList(). Second, you may construct the subdomain solver yourself, as an Ifpack2::Preconditioner instance, and give it to setInnerPreconditioner().

A third, deprecated method is to specify the concrete type of the subdomain solver at compile time, as the second template parameter LocalInverseType. This method has been DEPRECATED, because it causes a lot of trouble for explicit template instantiation. Users may perfectly well pick the type of the subdomain solver at run time, using either of the above two methods. This has no performance cost.

Please refer to the documentation of setParameters for a complete discussion of subdomain solvers and their parameters.

## Member Typedef Documentation

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 typedef MatrixType::scalar_type Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::scalar_type

The type of the entries of the input MatrixType.

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 typedef MatrixType::local_ordinal_type Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::local_ordinal_type

The type of local indices in the input MatrixType.

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 typedef MatrixType::global_ordinal_type Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::global_ordinal_type

The type of global indices in the input MatrixType.

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 typedef MatrixType::node_type Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::node_type

The type of the Kokkos Node used by the input MatrixType.

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 typedef Teuchos::ScalarTraits::magnitudeType Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::magnitude_type

The type of the magnitude (absolute value) of a matrix entry.

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 typedef Tpetra::RowMatrix Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::row_matrix_type

The Tpetra::RowMatrix specialization matching MatrixType.

MatrixType may be either a Tpetra::CrsMatrix specialization or a Tpetra::RowMatrix specialization. This typedef will always be a Tpetra::RowMatrix specialization which is either the same as MatrixType, or the parent class of MatrixType.

## Constructor & Destructor Documentation

template<class MatrixType , class LocalInverseType >
 Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::AdditiveSchwarz ( const Teuchos::RCP< const row_matrix_type > & A )

Constructor that takes a matrix.

Parameters:
 A [in] The matrix to be preconditioned.
template<class MatrixType , class LocalInverseType >
 Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::AdditiveSchwarz ( const Teuchos::RCP< const row_matrix_type > & A, const int overlapLevel )

Constructor that takes a matrix and the level of overlap.

Warning:
This version of the constructor is DEPRECATED, because the single-argument version suffices; users may specify the overlap level via the "schwarz: overlap level" parameter.
Parameters:
 A [in] The matrix to be preconditioned. overlapLevel [in] The level of overlap. Must be nonnegative. Zero means no overlap.
template<class MatrixType , class LocalInverseType >
 Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::~AdditiveSchwarz ( )  [virtual]

Destructor.

## Member Function Documentation

template<class MatrixType , class LocalInverseType >
 Teuchos::RCP< const Tpetra::Map< typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type > > Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getDomainMap ( ) const [virtual]

The domain Map of this operator.

template<class MatrixType , class LocalInverseType >
 Teuchos::RCP< const Tpetra::Map< typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type > > Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getRangeMap ( ) const [virtual]

The range Map of this operator.

template<class MatrixType , class LocalInverseType >
 void Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::apply ( const Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type > & X, Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type > & Y, Teuchos::ETransp mode = Teuchos::NO_TRANS, scalar_type alpha = Teuchos::ScalarTraits::one(), scalar_type beta = Teuchos::ScalarTraits::zero() ) const [virtual]

Apply the preconditioner to X, putting the result in Y.

template<class MatrixType , class LocalInverseType >
 void Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::setInnerPreconditioner ( const Teuchos::RCP< Preconditioner< scalar_type, local_ordinal_type, global_ordinal_type, node_type > > & innerPrec )  [virtual]

Set the inner preconditioner.

Most users do not need to call this method. Factory will handle calling this method if necessary. One case in which users might need to call this method, is if they implement their own subdomain solver as a subclass of Preconditioner, and want to use that subdomain solver in this class.

Parameters:
 innerPrec [in/out] The inner preconditioner. Its matrix (if it has one) may be replaced by a matrix specified by the outer (this) preconditioner.
Warning:
CYCLIC DEPENDENCIES ARE FORBIDDEN. You may NOT give this object (*this) to itself as an inner solver, or otherwise set up a cyclic dependency between preconditioner instances. You MAY use an inner solver of the same TYPE as this object (as long as this makes sense mathematically), but it must be a different instance of that type.

It does not make sense to nest different instances of AdditiveSchwarz, since it currently only sets up one subdomain per MPI process in the input matrix's communicator. Thus, if you were to use another AdditiveSchwarz instance as the inner preconditioner for AdditiveSchwarz, it would not do anything, since the inner preconditioner's input matrix would only have one process in its communicator. (AdditiveSchwarz does nothing in that case.)

Precondition:
&*innerPrec != this.

This method has collective semantics, because it may call initialize() or compute() on innerPrec, in order to synchronize the inner preconditioner's state with that of the AdditiveSchwarz instance.

template<class MatrixType , class LocalInverseType >
 void Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::setMatrix ( const Teuchos::RCP< const row_matrix_type > & A )  [virtual]

Change the matrix to be preconditioned.

Parameters:
 [in] A The new matrix.
Postcondition:
! isInitialized ()
! isComputed ()

Calling this method resets the preconditioner's state. After calling this method with a nonnull input, you must first call initialize() and compute() (in that order) before you may call apply().

You may call this method with a null input. If A is null, then you may not call initialize() or compute() until you first call this method again with a nonnull input. This method invalidates any previous factorization whether or not A is null, so calling setMatrix() with a null input is one way to clear the preconditioner's state (and free any memory that it may be using).

The new matrix A need not necessarily have the same Maps or even the same communicator as the original matrix.

template<class MatrixType , class LocalInverseType >
 Teuchos::RCP< const Tpetra::RowMatrix< typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type > > Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getMatrix ( ) const [virtual]
template<class MatrixType , class LocalInverseType >
 void Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::setParameters ( const Teuchos::ParameterList & plist )  [virtual]

Set the preconditioner's parameters.

Parameters:
 plist [in] List of parameters.

This version of the method takes a const list, as required by the Preconditioner interface. setParameterList() takes a nonconst pointer to a list, in order to match the Teuchos::ParameterListAcceptor interface.

Both this method and setParameterList() have "delta" behavior. That is, if called twice with two different lists, any unspecified parameters in the new list retain their values in the old list.

In many cases, calling this method may require calling initialize() and compute() to recompute the preconditioner.

Accepted parameters include the following:

• "inner preconditioner name" or "subdomain solver name" or "schwarz: subdomain solver name" or "schwarz: inner preconditioner name" (std::string): the name of the subdomain solver. See discussion below.
• "inner preconditioner parameters" or "subdomain solver parameters" or "schwarz: subdomain solver parameters" or "schwarz: inner preconditioner parameters" (sublist): parameters for the subdomain solver. If not provided, the subdomain solver will use its specific default parameters. See discussion below.
• "schwarz: compute condest" (bool): If true, estimate the condition number each time compute() is called. Default is false.
• "schwarz: combine mode" (std::string): The rule for combining incoming data with existing data in overlap regions. Valid values include "ADD", "INSERT", "REPLACE", "ABSMAX", and "ZERO". These correspond to the valid values of Tpetra::CombineMode. The default combine mode is "ZERO", meaning that overlapping incoming entries from different processes are not combined. (See the class documentation for an explanation and example of the "ZERO" vs. "ADD" combine modes.)
• "schwarz: overlap level" (int): The level of overlap. The default is zero, meaning no overlap.
• "schwarz: use reordering" (bool): Whether to use Zoltan2 to do reordering. If true, then Trilinos must have been built with Zoltan2 and Xpetra enabled. Default is false.
• "schwarz: subdomain id" (int): This option does not currently work.
• "schwarz: filter singletons" (bool): If true, exclude rows with just a single entry on the calling process. Default is false.

## Subdomain solver parameters

### Default subdomain solver

This class lets users specify any subdomain solver they want, by calling setInnerPreconditioner(). However, users may instead specify the subdomain solver by setting the "inner preconditioner name" parameter (or any of its aliases). If they choose to do so, they may only use inner preconditioners supported by Ifpack2::Details::OneLevelFactory. These include but are not necessarily limited to the following:

• "AMESOS2": Use Amesos2's interface to sparse direct solvers. This is only allowed if Trilinos was built with the Amesos2 package enabled. Otherwise, AdditiveSchwarz will throw an exception with an informative message.
• "CHEBYSHEV": Chebyshev iteration, implemented with Ifpack::Chebyshev. WARNING: This currently only works if the subdomain problem is real and symmetric positive definite.
• "DENSE" or "LAPACK": Convert the subdomain matrix to a dense matrix, and use LAPACK's LU factorization with partial pivoting to factor it and solve subdomain problems. WARNING: This will take a lot of memory if the subdomain problem is large!
• "DIAGONAL": Diagonal scaling, implemented through Ifpack2::Diagonal
• "ILUT": ILUT (incomplete LU with threshold), implemented with Ifpack2::ILUT
• "RELAXATION": Point relaxation (Jacobi, Gauss-Seidel, or symmetric Gauss-Seidel), implemented with Ifpack2::Relaxation
• "RILUK": ILU(k) (incomplete LU with fill level k), implemented with Ifpack2::RILUK

This name need not necessarily correspond with LocalInverseType. If the user does not specify this parameter, the following procedure specifies the default:

1. If LocalInverseType is just Preconditioner, then this class uses a default, which is currently "ILUT". </il>
2. If LocalInverseType is a concrete Preconditioner subclass, and if that subclass is in the above supported list of subdomain solver types, then this class uses that subclass as the subdomain solver.
3. If LocalInverseType is a concrete Preconditioner subclass, and if that subclass is not in the above supported list of subdomain solver types, then users have one of two options, both of which we discuss below.

The subdomain solver names "INVALID" and "CUSTOM" are reserved for internal use.

### Arbitrary subdomain solvers

AdditiveSchwarz only knows, on its own, how to create "non-nested" preconditioners as inner preconditioners (i.e., subdomain solvers). It can't create nested preconditioners (e.g., AdditiveSchwarz, Krylov, and SupportGraph) on its own as inner preconditioners, and it doesn't know how to create arbitrary subclasses of Ifpack2::Preconditioner unless Details::OneLevelFactory knows how to create them.

This leaves users two options in order to have any preconditioner as AdditiveSchwarz's inner preconditioner:

1. If Ifpack2::Factory knows how to create a preconditioner whose string name is prec, then users who don't want to create the inner preconditioner themselves must create AdditiveSchwarz using Factory, not by invoking AdditiveSchwarz's constructor themselves. Factory will set up the inner preconditioner for them before it returns the AdditiveSchwarz instance.
2. If Ifpack2::Factory does not know how to create a preconditioner prec (for example, if it is not even implemented in Ifpack2), then users must create the inner preconditioner instance themselves, and give it to AdditiveSchwarz using setInnerPreconditioner. In this case, AdditiveSchwarz's ParameterList must not specify the inner preconditioner's name.

### Subdomain solver parameters and setInnerPreconditioner

Users are responsible for ensuring that the parameters they provide to setParameters() are up to date. For example, if the users first set an inner preconditioner using setInnerPreconditioner(), and then call setParameters() with the "inner preconditioner name" parameter set, AdditiveSchwarz will get rid of the users' inner preconditioner and attempt to create a new inner preconditioner itself. Remember that AdditiveSchwarz's ParameterList has "delta" (relative) semantics! If you don't specify a parameter, the current state is not changed. If you specify a sublist of parameters to give to the subdomain solver, setInnerPreconditioner() does not pass that sublist to its argument. This is because we presume that if you call setInnerPreconditioner(), the input subdomain solver probably has a type that AdditiveSchwarz does not know how to create by itself, so the existing parameter list cannot apply.

On the other hand, if, after calling setInnerPreconditioner(), you then call setParameters(), we do pass any provided sublist of subdomain solver parameters to the inner solver. If no such sublist was provided, we do not call setParameters() on the inner solver.

The reason the last sentence matters is because not every inner solver necessarily has "delta" semantics for setParameters(). "Delta" or "relative" semantics means that an empty input ParameterList doesn't change any existing parameters. "Non-delta" or "absolute" semantics means that an empty input ParameterList causes all parameters to be set to their default values. (The difference matters if the user has called setParameters() before on the subdomain solver, with nondefault values.) If the user didn't specify a sublist for the inner solver, we assume that the user doesn't want to change the inner solver's parameters.

template<class MatrixType , class LocalInverseType >
 void Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::setParameterList ( const Teuchos::RCP< Teuchos::ParameterList > & plist )

Set the preconditioner's parameters.

This version of the method takes a nonconst pointer to a list, in order to match the Teuchos::ParameterListAcceptor interface. setParameters() takes a const list, as required by the Preconditioner interface.

Both this method and setParameterList() have "delta" behavior. That is, if called twice with two different lists, any unspecified parameters in the new list retain their values in the old list.

In many cases, calling this method may require calling initialize() and compute() to recompute the preconditioner.

Parameters:
 plist [in/out] On input: List of parameters, or Teuchos::null (meaning "do not change the current parameter values"). On output: If nonnull, any missing parameters are filled in with their current values (or their default values, if they have not yet been set).

See the documentation of setParameters() for a list of the parameters this method accepts, and their default values.

template<class MatrixType , class LocalInverseType >
 Teuchos::RCP< const Teuchos::ParameterList > Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getValidParameters ( ) const

Get a list of the preconditioner's default parameters.

See the documentation of setParameters() for a list of the parameters that AdditiveSchwarz accepts.

template<class MatrixType , class LocalInverseType >
 void Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::initialize ( )  [virtual]

Computes all (graph-related) data necessary to initialize the preconditioner.

template<class MatrixType , class LocalInverseType >
 bool Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::isInitialized ( ) const [virtual]

Returns true if the preconditioner has been successfully initialized, false otherwise.

template<class MatrixType , class LocalInverseType >
 void Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::compute ( )  [virtual]

Computes all (coefficient) data necessary to apply the preconditioner.

template<class MatrixType , class LocalInverseType >
 bool Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::isComputed ( ) const [virtual]

Returns true if the preconditioner has been successfully computed, false otherwise.

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 virtual magnitude_type TEUCHOS_DEPRECATED Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::computeCondEst ( CondestType CT = Ifpack2::Cheap, local_ordinal_type MaxIters = 1550, magnitude_type Tol = 1e-9, const Teuchos::Ptr< const row_matrix_type > & Matrix = Teuchos::null )  [virtual]

Compute the condition number estimate and return its value.

Warning:
This method is DEPRECATED. It was inherited from Ifpack, and Ifpack never clearly stated what this method computes. Furthermore, Ifpack's method just estimates the condition number of the matrix A, and ignores the preconditioner -- which is probably not what users thought it did. If there is sufficient interest, we might reintroduce this method with a different meaning and a better algorithm.
template<class MatrixType , class LocalInverseType >
 Teuchos::ScalarTraits< typename MatrixType::scalar_type >::magnitudeType Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getCondEst ( ) const [virtual]

Return the computed condition number estimate, or -1 if not computed.

Warning:
This method is DEPRECATED. See warning for computeCondEst().
template<class MatrixType , class LocalInverseType >
 int Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getNumInitialize ( ) const [virtual]

Returns the number of calls to initialize().

template<class MatrixType , class LocalInverseType >
 int Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getNumCompute ( ) const [virtual]

Returns the number of calls to compute().

template<class MatrixType , class LocalInverseType >
 int Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getNumApply ( ) const [virtual]

Returns the number of calls to apply().

template<class MatrixType , class LocalInverseType >
 double Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getInitializeTime ( ) const [virtual]

Returns the time spent in initialize().

template<class MatrixType , class LocalInverseType >
 double Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getComputeTime ( ) const [virtual]

Returns the time spent in compute().

template<class MatrixType , class LocalInverseType >
 double Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getApplyTime ( ) const [virtual]

Returns the time spent in apply().

template<class MatrixType , class LocalInverseType >
 std::string Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::description ( ) const

Return a simple one-line description of this object.

template<class MatrixType , class LocalInverseType >
 void Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::describe ( Teuchos::FancyOStream & out, const Teuchos::EVerbosityLevel verbLevel = Teuchos::Describable::verbLevel_default ) const

Print the object with some verbosity level to an FancyOStream object.

template<class MatrixType , class LocalInverseType >
 std::ostream & Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::print ( std::ostream & os ) const [virtual]

Prints basic information on iostream. This function is used by operator<<.

template<class MatrixType , class LocalInverseType >
 int Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::getOverlapLevel ( ) const [virtual]

Returns the level of overlap.

## Member Data Documentation

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 TEUCHOS_DEPRECATED typedef MatrixType::scalar_type Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::Scalar

Preserved only for backwards compatibility. Please use "scalar_type".

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 TEUCHOS_DEPRECATED typedef MatrixType::local_ordinal_type Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::LocalOrdinal

Preserved only for backwards compatibility. Please use "local_ordinal_type".

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 TEUCHOS_DEPRECATED typedef MatrixType::global_ordinal_type Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::GlobalOrdinal

Preserved only for backwards compatibility. Please use "global_ordinal_type".

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 TEUCHOS_DEPRECATED typedef MatrixType::node_type Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::Node

Preserved only for backwards compatibility. Please use "node_type".

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 TEUCHOS_DEPRECATED typedef Teuchos::ScalarTraits::magnitudeType Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::magnitudeType

Preserved only for backwards compatibility. Please use "magnitude_type".

template<class MatrixType , class LocalInverseType = Preconditioner<typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type>>
 TEUCHOS_DEPRECATED typedef Tpetra::RowMatrix Ifpack2::AdditiveSchwarz< MatrixType, LocalInverseType >::LocalMatrixType

Preserved only for backwards compatibility. Please use "row_matrix_type".

The documentation for this class was generated from the following files: