Ifpack2 Templated Preconditioning Package Version 1.0
Public Member Functions
Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node > Class Template Reference

Base class for all Ifpack2 preconditioners. More...

#include <Ifpack2_Preconditioner.hpp>

Inheritance diagram for Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >:
Inheritance graph
[legend]

List of all members.

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:

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:

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.


Constructor & Destructor Documentation

template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::~Preconditioner ( ) [inline, virtual]

Destructor.


Member Function Documentation

template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual const Teuchos::RCP<const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> >& Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getDomainMap ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual const Teuchos::RCP<const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> >& Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getRangeMap ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual void Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::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 [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual void Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::setParameters ( const Teuchos::ParameterList List) [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual void Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::initialize ( ) [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual bool Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::isInitialized ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual void Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::compute ( ) [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual bool Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::isComputed ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual magnitudeType Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::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 
) [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual magnitudeType Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getCondEst ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual Teuchos::RCP<const Tpetra::RowMatrix<Scalar,LocalOrdinal,GlobalOrdinal,Node> > Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getMatrix ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual int Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getNumInitialize ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual int Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getNumCompute ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual int Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getNumApply ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual double Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getInitializeTime ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual double Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getComputeTime ( ) const [pure virtual]
template<class Scalar, class LocalOrdinal = int, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
virtual double Ifpack2::Preconditioner< Scalar, LocalOrdinal, GlobalOrdinal, Node >::getApplyTime ( ) const [pure virtual]

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends