Base class for all Ifpack2 preconditioners. More...

#include <Ifpack2_Preconditioner.hpp>

Inheritance diagram for Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >:

Public Member Functions
virtual	~Preconditioner ()
	Destructor.
virtual void	setParameters (const Teuchos::ParameterList &List)=0
	Sets all parameters for the preconditioner.
virtual void	initialize ()=0
	Computes all (graph-related) data necessary to initialize the preconditioner.
virtual bool	isInitialized () const =0
	Returns true if the preconditioner has been successfully initialized, false otherwise.
virtual void	compute ()=0
	Computes all (coefficient) data necessary to apply the preconditioner.
virtual bool	isComputed () const =0
	Returns true if the preconditioner has been successfully computed, false otherwise.
virtual magnitudeType	computeCondEst (CondestType CT=Ifpack2::Cheap, LocalOrdinal MaxIters=1550, magnitudeType Tol=1e-9, const Teuchos::Ptr< const Tpetra::RowMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node > > &Matrix=Teuchos::null)=0
	Computes the condition number estimate and returns its value.
virtual magnitudeType	getCondEst () const =0
	Returns the computed condition number estimate, or -1.0 if not computed.
virtual Teuchos::RCP< const Tpetra::RowMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node > >	getMatrix () const =0
	Returns a pointer to the input matrix.
virtual int	getNumInitialize () const =0
	Returns the number of calls to initialize().
virtual int	getNumCompute () const =0
	Returns the number of calls to compute().
virtual int	getNumApply () const =0
	Returns the number of calls to Apply().
virtual double	getInitializeTime () const =0
	Returns the time spent in Initialize().
virtual double	getComputeTime () const =0
	Returns the time spent in Compute().
virtual double	getApplyTime () const =0
	Returns the time spent in Apply().
Methods implementing Tpetra::Operator.
virtual const Teuchos::RCP < const Tpetra::Map < LocalOrdinal, GlobalOrdinal, Node > > &	getDomainMap () const =0
	Returns the Map associated with the domain of this operator, which must be compatible with X.getMap().
virtual const Teuchos::RCP < const Tpetra::Map < LocalOrdinal, GlobalOrdinal, Node > > &	getRangeMap () const =0
	Returns the Map associated with the range of this operator, which must be compatible with Y.getMap().
virtual void	apply (const Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node > &X, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node > &Y, Teuchos::ETransp mode=Teuchos::NO_TRANS, Scalar alpha=Teuchos::ScalarTraits< Scalar >::one(), Scalar beta=Teuchos::ScalarTraits< Scalar >::zero()) const =0
	Applies the effect of the preconditioner.

Detailed Description

template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
class Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >

Base class for all Ifpack2 preconditioners.

Ifpack2::Preconditioner is a pure virtual class, and it defines the structure of all Ifpack2 preconditioners.

This class is a simple extension to Tpetra::Operator. It provides the following additional methods:

initialize() performs all operations based on the graph of the matrix (without considering the numerical values);
isInitialized() returns true if the preconditioner has been successfully initialized;
compute() computes everything required to apply the preconditioner, using matrix values (and assuming that the sparsity of the matrix has not been changed);
isComputed() should return true if the preconditioner has been successfully computed, false otherwise.
computeCondest() returns an estimation of the condition number, or -1.0 if not available
getMatrix() returns a reference to the matrix to be preconditioned.

It is required that compute() internally call initialize() if isInitialized() returns false. The preconditioner is applied by apply() (which returns if isComputed() is false). Every time that initialize() is called, the object destroys all the previously allocated information, and re-initializes the preconditioner. Every time compute() is called, the object re-computes the actual values of the preconditioner.

Estimating Preconditioner Condition Numbers

The condition of a matrix \(B\), called \(cond_p(B)\), is defined as \(cond_p(B) = \|B\|_p\|B^{-1}\|_p\) in some appropriate norm \(p\). \(cond_p(B)\) gives some indication of how many accurate floating point digits can be expected from operations involving the matrix and its inverse. A condition number approaching the accuracy of a given floating point number system, about 15 decimal digits in IEEE double precision, means that any results involving \(B\) or \(B^{-1}\) may be meaningless.

Method compute() can be used to estimate of the condition number. compute() requires one parameter, of type Ifpack2::CondestType (default value is Ifpack2::Cheap; other valid choices are Ifpack2::CG and Ifpack2::GMRES).

While Ifpack2::CG and Ifpack2::GMRES construct a solver, and use methods AZ_cg_condnum and AZ_gmres_condnum to evaluate an accurate (but very expensive) estimate of the condition number, Ifpack2::Cheap computes \(\|(P)^{-1}e\|_\infty\), which is only a very crude estimation of the actual condition number. Note that this estimated number can be less than 1.0. However, this approach has the following advantages:

since finding \(z\) such that \(P z = y\) is a basic kernel for applying the preconditioner, computing this estimate of \(cond_\infty(P^{-1})\) is performed by setting \(y = e\), calling the solve kernel to compute \(z\) and then computing \(\|z\|_\infty\);
the only cost is one application of the preconditioner.

If this estimate is very large, the application of the computed preconditioner may generate large numerical errors. Hence, the user may check this number, and decide to recompute the preconditioner is the computed estimate is larger than a given threshold. This is particularly useful in ICT and RILUK factorizations, as for ill-conditioned matrices, we often have difficulty computing usable incomplete factorizations. The most common source of problems is that the factorization may encounter a small or zero pivot, in which case the factorization can fail, or even if the factorization succeeds, the factors may be so poorly conditioned that use of them in the iterative phase produces meaningless results. Before we can fix this problem, we must be able to detect it.