Ifpack2::BlockRelaxation< MatrixType, ContainerType > Class Template Reference

Block relaxation preconditioners (or smoothers) for Tpetra::RowMatrix and Tpetra::CrsMatrix sparse matrices. More...

#include <Ifpack2_BlockRelaxation_decl.hpp>

Inheritance diagram for Ifpack2::BlockRelaxation< MatrixType, ContainerType >:

List of all members.

Public Member Functions
	BlockRelaxation (const Teuchos::RCP< const row_matrix_type > &Matrix)
	Constructor.
virtual	~BlockRelaxation ()
	Destructor.
Preconditioner computation methods
void	setParameters (const Teuchos::ParameterList &params)
	Sets all the parameters for the preconditioner.
void	initialize ()
	Initialize.
bool	isInitialized () const
	Returns true if the preconditioner has been successfully initialized.
void	compute ()
	compute the preconditioner for the specified matrix, diagonal perturbation thresholds and relaxation parameters.
bool	isComputed () const
	Return true if compute() has been called.
Implementation of Ifpack2::Details::CanChangeMatrix
virtual void	setMatrix (const Teuchos::RCP< const row_matrix_type > &A)
	Change the matrix to be preconditioned.
Methods implementing the Tpetra::Operator interface.
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
	Applies the preconditioner to X, returns the result in Y.
Teuchos::RCP< const Tpetra::Map < local_ordinal_type, global_ordinal_type, node_type > >	getDomainMap () const
	Returns the Tpetra::Map object associated with the domain of this operator.
Teuchos::RCP< const Tpetra::Map < local_ordinal_type, global_ordinal_type, node_type > >	getRangeMap () const
	Returns the Tpetra::Map object associated with the range of this operator.
bool	hasTransposeApply () const
void	applyMat (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) const
	Applies the matrix to a Tpetra::MultiVector.
Mathematical functions
virtual magnitude_type TEUCHOS_DEPRECATED	computeCondEst (CondestType CT=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.
Attribute accessor methods
virtual magnitude_type TEUCHOS_DEPRECATED	getCondEst () const
	Return the computed condition number estimate, or -1 if not computed.
Teuchos::RCP< const Teuchos::Comm< int > >	getComm () const
	The communicator over which the input matrix is distributed.
Teuchos::RCP< const Tpetra::RowMatrix< scalar_type, local_ordinal_type, global_ordinal_type, node_type > >	getMatrix () const
	The input matrix of this preconditioner's constructor.
double	getComputeFlops () const
	Returns the number of flops in the computation phase.
double	getApplyFlops () const
	Returns the number of flops for the application of the preconditioner.
int	getNumInitialize () const
	Returns the number of calls to initialize().
int	getNumCompute () const
	Returns the number of calls to compute().
int	getNumApply () const
	Returns the number of calls to apply().
double	getInitializeTime () const
	Returns the time spent in initialize().
double	getComputeTime () const
	Returns the time spent in compute().
double	getApplyTime () const
	Returns the time spent in apply().
Implementation of the Teuchos::Describable interface
std::string	description () const
	A 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.
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
	Tpetra::RowMatrix specialization corresponding to MatrixType.
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".

---

Detailed Description

template<class MatrixType, class ContainerType>
class Ifpack2::BlockRelaxation< MatrixType, ContainerType >

Block relaxation preconditioners (or smoothers) for Tpetra::RowMatrix and Tpetra::CrsMatrix sparse matrices.

Template Parameters:

MatrixType	A specialization of Tpetra::CrsMatrix (better) or Tpetra::RowMatrix (acceptable).
ContainerType	A specialization or subclass of Container; a type that knows how to solve linear systems with diagonal blocks of MatrixType. Those blocks may be either sparse or dense; the subclass of Container controls the representation.

This class implements the construction and application of block relaxation preconditioners and smoothers, for sparse matrices represented as Tpetra::RowMatrix or Tpetra::CrsMatrix. This class implements Tpetra::Operator, and its apply() method applies the block relaxation.

BlockRelaxation implements block variants of the following relaxations:

• (Damped) Jacobi;
• (Damped) Gauss-Seidel, i.e., SOR
• (Damped) symmetric Gauss-Seidel, i.e., symmetric SOR

For a list of supported parameters, please refer to the documentation of setParameters().

---

Member Typedef Documentation

template<class MatrixType, class ContainerType>

typedef MatrixType::scalar_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::scalar_type

The type of the entries of the input MatrixType.

template<class MatrixType, class ContainerType>

typedef MatrixType::local_ordinal_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::local_ordinal_type

The type of local indices in the input MatrixType.

template<class MatrixType, class ContainerType>

typedef MatrixType::global_ordinal_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::global_ordinal_type

The type of global indices in the input MatrixType.

template<class MatrixType, class ContainerType>

typedef MatrixType::node_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::node_type

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

template<class MatrixType, class ContainerType>

typedef Teuchos::ScalarTraits<scalar_type>::magnitudeType Ifpack2::BlockRelaxation< MatrixType, ContainerType >::magnitude_type

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

Reimplemented from Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType, class ContainerType>

typedef Tpetra::RowMatrix<scalar_type, local_ordinal_type, global_ordinal_type, node_type> Ifpack2::BlockRelaxation< MatrixType, ContainerType >::row_matrix_type

Tpetra::RowMatrix specialization corresponding to MatrixType.

---

Constructor & Destructor Documentation

template<class MatrixType , class ContainerType >

Ifpack2::BlockRelaxation< MatrixType, ContainerType >::BlockRelaxation

(

const Teuchos::RCP< const row_matrix_type > &

Matrix

)

[explicit]

Constructor.

Parameters:

Matrix

[in] The matrix for which to make the constructor. Tpetra::RowMatrix is the base class of Tpetra::CrsMatrix, so you may give either a Tpetra::RowMatrix or a Tpetra::CrsMatrix here.

The results of apply() are undefined if you change the sparse matrix after invoking this constructor, without first calling initialize() and compute() (in that order) to reinitialize the preconditioner.

The "explicit" keyword just means that you must invoke the Relaxation constructor explicitly; you aren't allowed to use it as an implicit conversion ("cast"). For example, you may do this (namespaces and Tpetra template parameters omitted for brevity):

 RCP<const CrsMatrix<...> > A = ...;
 BlockRelaxation<CrsMatrix<...> > R (A);

but you may not do this:

 // Declaration of some user-defined function.
 void foo (const BlockRelaxation<CrsMatrix<...> >& R);

 RCP<const CrsMatrix<...> > A = ...;
 foo (A);

template<class MatrixType , class ContainerType >

Ifpack2::BlockRelaxation< MatrixType, ContainerType >::~BlockRelaxation

(

)

[virtual]

Destructor.

---

Member Function Documentation

template<class MatrixType , class ContainerType >

void Ifpack2::BlockRelaxation< MatrixType, ContainerType >::setParameters

(

const Teuchos::ParameterList &

params

)

[virtual]

Sets all the parameters for the preconditioner.

Valid parameters include the following:

• "relaxation: type"
  Valid values (string):
  
  • "Jacobi"
  • "Gauss-Seidel"
  • "Symmetric Gauss-Seidel"
• "relaxation: sweeps" (int)
• "relaxation: damping factor" (floating-point)
• "relaxation: min diagonal value" (floating-point)
• "relaxation: zero starting solution" (bool)
• "relaxation: backward mode" (bool)

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

void Ifpack2::BlockRelaxation< MatrixType, ContainerType >::initialize

(

)

[virtual]

Initialize.

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType, class ContainerType>

bool Ifpack2::BlockRelaxation< MatrixType, ContainerType >::isInitialized

(

)

const [inline, virtual]

Returns true if the preconditioner has been successfully initialized.

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

void Ifpack2::BlockRelaxation< MatrixType, ContainerType >::compute

(

)

[virtual]

compute the preconditioner for the specified matrix, diagonal perturbation thresholds and relaxation parameters.

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType, class ContainerType>

bool Ifpack2::BlockRelaxation< MatrixType, ContainerType >::isComputed

(

)

const [inline, virtual]

Return true if compute() has been called.

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

void Ifpack2::BlockRelaxation< MatrixType, ContainerType >::setMatrix

(

const Teuchos::RCP< const row_matrix_type > &

A

)

[virtual]

Change the matrix to be preconditioned.

Parameters:

A	[in] The new matrix.

Postcondition:

! isInitialized ()

! isComputed ()

Calling this method with a matrix different than the current matrix 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 ContainerType>

void Ifpack2::BlockRelaxation< MatrixType, ContainerType >::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 [virtual]

Applies the preconditioner to X, returns the result in Y.

Parameters:

X	- (In) A Tpetra::MultiVector of dimension NumVectors to be preconditioned.
Y	- (InOut) A Tpetra::MultiVector of dimension NumVectors containing result.

Returns:

Integer error code, set to 0 if successful.

Warning:

This routine is NOT AztecOO compliant.

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

Teuchos::RCP< const Tpetra::Map< typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type > > Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getDomainMap

(

)

const [virtual]

Returns the Tpetra::Map object associated with the domain of this operator.

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

Teuchos::RCP< const Tpetra::Map< typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type > > Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getRangeMap

(

)

const [virtual]

Returns the Tpetra::Map object associated with the range of this operator.

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType, class ContainerType>

void Ifpack2::BlockRelaxation< MatrixType, ContainerType >::applyMat	(	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
	)		const

Applies the matrix to a Tpetra::MultiVector.

Parameters:

X	- (In) A Tpetra::MultiVector of dimension NumVectors to multiply with matrix.
Y	- (Out) A Tpetra::MultiVector of dimension NumVectors containing the result.

template<class MatrixType , class ContainerType >

BlockRelaxation< MatrixType, ContainerType >::magnitude_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::computeCondEst	(	CondestType	CT = Cheap,
		typename MatrixType::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 ContainerType >

BlockRelaxation< MatrixType, ContainerType >::magnitude_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getCondEst

(

)

const [virtual]

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

Warning:

This method is DEPRECATED. See warning for computeCondEst().

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

Teuchos::RCP< const Teuchos::Comm< int > > Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getComm

(

)

const

The communicator over which the input matrix is distributed.

template<class MatrixType , class ContainerType >

Teuchos::RCP< const Tpetra::RowMatrix< typename MatrixType::scalar_type, typename MatrixType::local_ordinal_type, typename MatrixType::global_ordinal_type, typename MatrixType::node_type > > Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getMatrix

(

)

const [virtual]

The input matrix of this preconditioner's constructor.

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

double Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getComputeFlops

(

)

const

Returns the number of flops in the computation phase.

template<class MatrixType , class ContainerType >

double Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getApplyFlops

(

)

const

Returns the number of flops for the application of the preconditioner.

template<class MatrixType , class ContainerType >

int Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getNumInitialize

(

)

const [virtual]

Returns the number of calls to initialize().

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

int Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getNumCompute

(

)

const [virtual]

Returns the number of calls to compute().

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

int Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getNumApply

(

)

const [virtual]

Returns the number of calls to apply().

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

double Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getInitializeTime

(

)

const [virtual]

Returns the time spent in initialize().

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

double Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getComputeTime

(

)

const [virtual]

Returns the time spent in compute().

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

double Ifpack2::BlockRelaxation< MatrixType, ContainerType >::getApplyTime

(

)

const [virtual]

Returns the time spent in apply().

Implements Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

template<class MatrixType , class ContainerType >

std::string Ifpack2::BlockRelaxation< MatrixType, ContainerType >::description

(

)

const

A one-line description of this object.

template<class MatrixType , class ContainerType >

void Ifpack2::BlockRelaxation< MatrixType, ContainerType >::describe	(	Teuchos::FancyOStream &	out,
		const Teuchos::EVerbosityLevel	verbLevel = Teuchos::Describable::verbLevel_default
	)		const

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

---

Member Data Documentation

template<class MatrixType, class ContainerType>

TEUCHOS_DEPRECATED typedef MatrixType::scalar_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::Scalar

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

template<class MatrixType, class ContainerType>

TEUCHOS_DEPRECATED typedef MatrixType::local_ordinal_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::LocalOrdinal

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

template<class MatrixType, class ContainerType>

TEUCHOS_DEPRECATED typedef MatrixType::global_ordinal_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::GlobalOrdinal

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

template<class MatrixType, class ContainerType>

TEUCHOS_DEPRECATED typedef MatrixType::node_type Ifpack2::BlockRelaxation< MatrixType, ContainerType >::Node

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

template<class MatrixType, class ContainerType>

TEUCHOS_DEPRECATED typedef Teuchos::ScalarTraits<scalar_type>::magnitudeType Ifpack2::BlockRelaxation< MatrixType, ContainerType >::magnitudeType

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

Reimplemented from Ifpack2::Preconditioner< MatrixType::scalar_type, MatrixType::local_ordinal_type, MatrixType::global_ordinal_type, MatrixType::node_type >.

---

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

• Ifpack2_BlockRelaxation_decl.hpp
• Ifpack2_BlockRelaxation_def.hpp