Belos::StatusTestResNorm< ScalarType, MV, OP > Class Template Reference

An implementation of StatusTest using a family of residual norms. More...

#include <BelosStatusTestResNorm.hpp>

Inheritance diagram for Belos::StatusTestResNorm< ScalarType, MV, OP >:


Public Types
typedef Teuchos::ScalarTraits< ScalarType >	SCT
typedef SCT::magnitudeType	MagnitudeType
typedef MultiVecTraits< ScalarType, MV >	MVT
Enums.
enum	ResType { Implicit, Explicit }
	Select how the residual vector is produced. More...
enum	ScaleType { NormOfRHS, NormOfInitRes, NormOfPrecInitRes, None, UserProvided }
	Select the scale type. More...
Public Member Functions
Constructors/destructors.
	StatusTestResNorm (MagnitudeType Tolerance, bool showMaxResNormOnly=false)
	Constructor.
virtual	~StatusTestResNorm ()
	Destructor.
Form and parameter definition methods.
int	DefineResForm (ResType TypeOfResidual, NormType TypeOfNorm)
	Define form of the residual, its norm and optional weighting vector.
int	DefineScaleForm (ScaleType TypeOfScaling, NormType TypeOfNorm, MagnitudeType ScaleValue=Teuchos::ScalarTraits< MagnitudeType >::one())
	Define form of the scaling, its norm, its optional weighting vector, or, alternatively, define an explicit value.
int	ResetTolerance (MagnitudeType Tolerance)
	Reset the value of the tolerance.
Status methods
StatusType	CheckStatus (IterativeSolver< ScalarType, MV, OP > *iSolver)
	Check convergence status: Unconverged, Converged, Failed.
StatusType	GetStatus () const
	Return the result of the most recent CheckStatus call.
Reset methods
void	Reset ()
	Resets the internal configuration to the initial state.
Attribute methods
bool	ResidualVectorRequired () const
	Indicates if residual vector is required by this convergence test.
Print methods
ostream &	Print (ostream &os, int indent=0) const
	Output formatted description of stopping test to output stream.
Methods to access data members.
MagnitudeType	GetTolerance () const
	Returns the value of the tolerance, $\tau$ , set in the constructor.
const std::vector< MagnitudeType > *	GetTestValue () const
	Returns the test value, $\frac{\\|r\\|}{\sigma}$ , computed in most recent call to CheckStatus.
const std::vector< MagnitudeType > *	GetResNormValue () const
	Returns the residual norm value, $\\|r\\|$ , computed in most recent call to CheckStatus.
const std::vector< MagnitudeType > *	GetScaledNormValue () const
	Returns the scaled norm value, $\sigma$ .
Misc.
StatusType	FirstcallCheckStatusSetup (IterativeSolver< ScalarType, MV, OP > *iSolver)
	Call to setup initial scaling vector.

Detailed Description

template<class ScalarType, class MV, class OP>
class Belos::StatusTestResNorm< ScalarType, MV, OP >

An implementation of StatusTest using a family of residual norms.

StatusTestResNorm is an implementation of StatusTest that allows a user to construct one of a family of residual tests for use as a status/convergence test for Belos. The form of the test is

$\frac{\|r_i\|}{\sigma_i} \le \tau$

where

is the i-th residual vector, implicitly or explicitly computed (determined by enum ResType),
$\|r_i\|$ is the i-th residual norm determined by the enum NormType (1-norm, 2-norm or inf-norm),
$\sigma_i$ is the i-th scale factor that can be passed in as a precomputed number of the templated type, or can be selected from by the enum ScaleType (norm of RHS, norm of initial residual).
$\tau$ is the tolerance that is passed in as a number of the templated type to the constructor. The value of $\tau$ can be reset using the ResetTolerance() method.

Definition at line 66 of file BelosStatusTestResNorm.hpp.

Member Typedef Documentation

template<class ScalarType, class MV, class OP>

typedef Teuchos::ScalarTraits<ScalarType> Belos::StatusTestResNorm< ScalarType, MV, OP >::SCT

Definition at line 71 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

typedef SCT::magnitudeType Belos::StatusTestResNorm< ScalarType, MV, OP >::MagnitudeType

Definition at line 72 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

typedef MultiVecTraits<ScalarType,MV> Belos::StatusTestResNorm< ScalarType, MV, OP >::MVT

Definition at line 73 of file BelosStatusTestResNorm.hpp.

Member Enumeration Documentation

template<class ScalarType, class MV, class OP>

enum Belos::StatusTestResNorm::ResType

Select how the residual vector is produced.

Enumeration values:

Implicit Use the residual vector produced by the iterative solver.

Explicit Explicitly compute the residual vector r = b - A*x using the linear problem.

Definition at line 80 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

enum Belos::StatusTestResNorm::ScaleType

Select the scale type.

Enumeration values:

NormOfRHS Use the norm of the right-hand-side.

NormOfInitRes Use the initial residual vector (exlicitly computed).

NormOfPrecInitRes Use the preconditioned initial residual vector (exlicitly computed).

None Use unscaled residual.

UserProvided User provides an explicit value that the norm of the residual will be divided by.

Definition at line 88 of file BelosStatusTestResNorm.hpp.

Constructor & Destructor Documentation

template<class ScalarType, class MV, class OP>

Belos::StatusTestResNorm< ScalarType, MV, OP >::StatusTestResNorm ( MagnitudeType Tolerance,

bool showMaxResNormOnly = false

)

Constructor.
The constructor takes a single argument specifying the tolerance ( $\tau$ ). If none of the form definition methods are called, we use $\|r\|_2/\|r^{(0)}\|_2 \le \tau$ as the stopping criterion, where $\|r\|_2$ uses the least costly form of the 2-norm of residual available from the iterative method and $\|r^{(0)}\|_2$ is the corresponding norm of the initial residual. The least costly form of the 2-norm depends on the chosen iterative method. Most Krylov methods produce the preconditioned residual vector in a form that would be exact in infinite precision arithmetic. This vector may be different from the true residual either because left scaling or preconditioning was used, or because round-off error has introduced significant error, or both.
Definition at line 303 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

Belos::StatusTestResNorm< ScalarType, MV, OP >::~StatusTestResNorm ( ) [virtual]

Destructor.

Definition at line 325 of file BelosStatusTestResNorm.hpp.

Member Function Documentation

template<class ScalarType, class MV, class OP>

int Belos::StatusTestResNorm< ScalarType, MV, OP >::DefineResForm ( ResType TypeOfResidual,

NormType TypeOfNorm

)

Define form of the residual, its norm and optional weighting vector.
This method defines the form of $\|r\|$ . We specify:

Whether the residual vector should be explicitly computed, or taken from the iterative method.

The norm to be used on the residual (this may be different than the norm used in DefineScaleForm()).

Definition at line 339 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

int Belos::StatusTestResNorm< ScalarType, MV, OP >::DefineScaleForm ( ScaleType TypeOfScaling,

NormType TypeOfNorm,

MagnitudeType ScaleValue = Teuchos::ScalarTraits< MagnitudeType >::one()

)

Define form of the scaling, its norm, its optional weighting vector, or, alternatively, define an explicit value.
This method defines the form of how the residual is scaled (if at all). It operates in two modes:

User-provided scaling value:

Set argument TypeOfScaling to UserProvided.

Set ScaleValue to a non-zero value that the residual norm will be divided by.

TypeOfNorm argument will be ignored.

Sample use: Define ScaleValue = $\|A\|_{\infty}$ where $ A $ is the matrix of the linear problem.

Use a supported Scaling Form:

Define TypeOfScaling to be the norm of the right hand side, the initial residual vector, or to none.

Define norm to be used on the scaling vector (this may be different than the norm used in DefineResForm()).

Definition at line 355 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

int Belos::StatusTestResNorm< ScalarType, MV, OP >::ResetTolerance ( MagnitudeType Tolerance ) [inline]

Reset the value of the tolerance.
We allow the tolerance to be reset for cases where, in the process of testing the residual, we find that the initial tolerance was too tight or too lax.
Definition at line 156 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

StatusType Belos::StatusTestResNorm< ScalarType, MV, OP >::CheckStatus ( IterativeSolver< ScalarType, MV, OP > * iSolver ) [virtual]

Check convergence status: Unconverged, Converged, Failed.
This method checks to see if the convergence criteria are met. Depending on how the residual test is constructed this method will return the appropriate status type.

Returns:
StatusType: Unconverged, Converged or Failed.

Implements Belos::StatusTest< ScalarType, MV, OP >.
Definition at line 370 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

StatusType Belos::StatusTestResNorm< ScalarType, MV, OP >::GetStatus ( ) const [inline, virtual]

Return the result of the most recent CheckStatus call.

Implements Belos::StatusTest< ScalarType, MV, OP >.
Definition at line 172 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

void Belos::StatusTestResNorm< ScalarType, MV, OP >::Reset ( ) [virtual]

Resets the internal configuration to the initial state.

Implements Belos::StatusTest< ScalarType, MV, OP >.
Definition at line 329 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

bool Belos::StatusTestResNorm< ScalarType, MV, OP >::ResidualVectorRequired ( ) const [inline, virtual]

Indicates if residual vector is required by this convergence test.
The value returned by this method will depend on several factors. Once an StatusTestResNorm object is constructed and the DefineResForm and DefineScaleForm methods are optionally called, this method can tested. For most Krylov solvers, there is no extra cost to providing the residual vector. However, GMRES and Transpose-free QMR will need to explicitly compute this vector if ResidualVectorRequired() returns true, so this is an extra cost for these two iterative methods.
Implements Belos::StatusTest< ScalarType, MV, OP >.
Definition at line 195 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

ostream & Belos::StatusTestResNorm< ScalarType, MV, OP >::Print ( ostream & os,

int indent = 0

) const [virtual]

Output formatted description of stopping test to output stream.

Implements Belos::StatusTest< ScalarType, MV, OP >.
Definition at line 481 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

MagnitudeType Belos::StatusTestResNorm< ScalarType, MV, OP >::GetTolerance ( ) const [inline]

Returns the value of the tolerance, $\tau$ , set in the constructor.

Definition at line 210 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

const std::vector<MagnitudeType>* Belos::StatusTestResNorm< ScalarType, MV, OP >::GetTestValue ( ) const [inline]

Returns the test value, $\frac{\|r\|}{\sigma}$ , computed in most recent call to CheckStatus.

Definition at line 213 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

const std::vector<MagnitudeType>* Belos::StatusTestResNorm< ScalarType, MV, OP >::GetResNormValue ( ) const [inline]

Returns the residual norm value, $\|r\|$ , computed in most recent call to CheckStatus.

Definition at line 216 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

const std::vector<MagnitudeType>* Belos::StatusTestResNorm< ScalarType, MV, OP >::GetScaledNormValue ( ) const [inline]

Returns the scaled norm value, $\sigma$ .

Definition at line 219 of file BelosStatusTestResNorm.hpp.

template<class ScalarType, class MV, class OP>

StatusType Belos::StatusTestResNorm< ScalarType, MV, OP >::FirstcallCheckStatusSetup ( IterativeSolver< ScalarType, MV, OP > * iSolver )

Call to setup initial scaling vector.
After this function is called GetScaledNormValue() can be called to get the scaling vector.
Definition at line 532 of file BelosStatusTestResNorm.hpp.

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

BelosStatusTestResNorm.hpp

Generated on Thu Sep 18 12:30:13 2008 for Belos by

1.3.9.1