Belos Version of the Day
Public Types
Belos::StatusTestImpResNorm< ScalarType, MV, OP > Class Template Reference

Convergence test using the implicit residual norm(s), with an explicit residual norm(s) check for loss of accuracy if necessary. More...

#include <BelosStatusTestImpResNorm.hpp>

Inheritance diagram for Belos::StatusTestImpResNorm< ScalarType, MV, OP >:
Inheritance graph
[legend]

List of all members.

Public Types

typedef Teuchos::ScalarTraits
< ScalarType >::magnitudeType 
MagnitudeType
 The type of the magnitude (absolute value) of a ScalarType.

Public Member Functions

Constructors and destructor.
 StatusTestImpResNorm (MagnitudeType Tolerance, int quorum=-1, bool showMaxResNormOnly=false)
 Constructor.
virtual ~StatusTestImpResNorm ()
 Destructor (virtual for memory safety).
Form and parameter definition methods.
int defineResForm (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 setTolerance (MagnitudeType tolerance)
 Set the value of the tolerance.
int setQuorum (int quorum)
 Sets the number of residuals that must pass the convergence test before Passed is returned.
int setShowMaxResNormOnly (bool showMaxResNormOnly)
 Set whether the only maximum residual norm is displayed when the print() method is called.
Status methods
StatusType checkStatus (Iteration< ScalarType, MV, OP > *iSolver)
 Check convergence status: Passed, Failed, or Undefined.
StatusType getStatus () const
 Return the result of the most recent CheckStatus call.
Reset methods
void reset ()
 Resets the internal configuration to the initial state.
Print methods
void print (std::ostream &os, int indent=0) const
 Output formatted description of stopping test to output stream.
void printStatus (std::ostream &os, StatusType type) const
 Print message for each status specific to this stopping test.
Methods to access data members.
Teuchos::RCP< MV > getSolution ()
 Returns the current solution estimate that was computed for the most recent residual test.
int getQuorum () const
 Returns the number of residuals that must pass the convergence test before Passed is returned.
bool getShowMaxResNormOnly ()
 Returns whether the only maximum residual norm is displayed when the print() method is called.
std::vector< int > convIndices ()
 Returns the vector containing the indices of the residuals that passed the test.
MagnitudeType getTolerance () const
 "Original" convergence tolerance $\tau$ as set by user.
MagnitudeType getCurrTolerance () const
 Current convergence tolerance; may be changed to prevent loss of accuracy.
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 $.
bool getLOADetected () const
 Returns a boolean indicating a loss of accuracy has been detected in computing the residual.
Misc.
StatusType firstCallCheckStatusSetup (Iteration< ScalarType, MV, OP > *iSolver)
 Call to setup initial scaling vector.
Overridden from Teuchos::Describable
std::string description () const
 Method to return description of the maximum iteration status test.

Detailed Description

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

Convergence test using the implicit residual norm(s), with an explicit residual norm(s) check for loss of accuracy if necessary.

This test passes when a quorum of residual vectors (for all right-hand sides) passes a residual norm test. For residual vector $r_i$, the form of the test is $\|r_i\| / \sigma_i \le \tau$, where $\tau$ is the convergence tolerance set in the constructor or by setTolerance(). The default quorum consists of all the vectors, but you can set the number of vectors that must pass before the whole test passes, either by the constructor argument or by calling setQuorum().

The default residual vector norm (the norm used in the numerator of the test, and applied to the current residual vectors) is the 2-norm, but you can change the norm type (1-norm, 2-norm, or infinity norm) using defineResForm(). The default scaling factor $\sigma_i$ for residual vector i is the 2-norm of the initial residual vector, but you can change this using defineScaleForm(). The norm used for the scaling factors may be different than the norm used for the current residual vectors. Furthermore, each residual vector may use a different scaling factor $\sigma_i$.

This test starts by using the "implicit" residual norm, otherwise called the "recursive" or "native" residual norm. It comes from the iterative method's projected problem, unlike the "explicit" residual norm, which comes from explicitly computing $R = B - A * X$. Once the implicit residual norm reaches the convergence tolerance, this test then checks the explicit residual norm to make sure that it has reached the convergence tolerance as well.

We say that there is a "potential loss of accuracy" when we first detect that the implicit residual norm(s) have met the desired original convergence tolerance, but the explicit residual norm(s) have not. We don't actually call this a "loss of accuracy" (in the sense of getLOADetected() returning true) unless we tried to remedy this situation, but couldn't fix it. Upon detecting a potential loss of accuracy, this test tells the solver to "iterate a few more steps" by making the "current" residual tolerance (the value of getCurrTolerance()) smaller, and forcing the implicit residual norm(s) to meet the current tolerance before moving on to test the explicit norm(s). If that doesn't work, this test declares a loss of accuracy.

Definition at line 104 of file BelosStatusTestImpResNorm.hpp.


Member Typedef Documentation

template<class ScalarType , class MV , class OP >
typedef Teuchos::ScalarTraits<ScalarType>::magnitudeType Belos::StatusTestImpResNorm< ScalarType, MV, OP >::MagnitudeType

The type of the magnitude (absolute value) of a ScalarType.

Reimplemented from Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 107 of file BelosStatusTestImpResNorm.hpp.


Constructor & Destructor Documentation

template<class ScalarType , class MV , class OP >
Belos::StatusTestImpResNorm< ScalarType, MV, OP >::StatusTestImpResNorm ( MagnitudeType  Tolerance,
int  quorum = -1,
bool  showMaxResNormOnly = false 
)

Constructor.

Parameters:
Tolerance[in] Convergence tolerance $\tau$.
quorum[in] The number of vectors in the problem that must pass the convergence criteria before this StatusTest passes. -1 means that all residuals must pass.
showMaxResNormOnly[in] Whether only the maximum residual norm (of all vectors) is displayed when the print() method is called.

Definition at line 421 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
Belos::StatusTestImpResNorm< ScalarType, MV, OP >::~StatusTestImpResNorm ( ) [virtual]

Destructor (virtual for memory safety).

Definition at line 445 of file BelosStatusTestImpResNorm.hpp.


Member Function Documentation

template<class ScalarType , class MV , class OP >
int Belos::StatusTestImpResNorm< ScalarType, MV, OP >::defineResForm ( NormType  TypeOfNorm)

Define form of the residual, its norm and optional weighting vector.

This method defines the form of $\|r\|$. We specify:

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

Definition at line 464 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
int Belos::StatusTestImpResNorm< 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:

  1. 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.

  2. 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 476 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
int Belos::StatusTestImpResNorm< ScalarType, MV, OP >::setTolerance ( MagnitudeType  tolerance) [inline]

Set 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 179 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
int Belos::StatusTestImpResNorm< ScalarType, MV, OP >::setQuorum ( int  quorum) [inline, virtual]

Sets the number of residuals that must pass the convergence test before Passed is returned.

Note:
If quorum=-1 then all residuals must pass the convergence test before Passed is returned.

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 186 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
int Belos::StatusTestImpResNorm< ScalarType, MV, OP >::setShowMaxResNormOnly ( bool  showMaxResNormOnly) [inline, virtual]

Set whether the only maximum residual norm is displayed when the print() method is called.

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 192 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
StatusType Belos::StatusTestImpResNorm< ScalarType, MV, OP >::checkStatus ( Iteration< ScalarType, MV, OP > *  iSolver) [virtual]

Check convergence status: Passed, Failed, or Undefined.

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: Passed, Failed, or Undefined.

Implements Belos::StatusTest< ScalarType, MV, OP >.

Definition at line 492 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
StatusType Belos::StatusTestImpResNorm< 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 211 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
void Belos::StatusTestImpResNorm< ScalarType, MV, OP >::reset ( ) [virtual]

Resets the internal configuration to the initial state.

Implements Belos::StatusTest< ScalarType, MV, OP >.

Definition at line 449 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
void Belos::StatusTestImpResNorm< ScalarType, MV, OP >::print ( std::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 752 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
void Belos::StatusTestImpResNorm< ScalarType, MV, OP >::printStatus ( std::ostream &  os,
StatusType  type 
) const [virtual]

Print message for each status specific to this stopping test.

Reimplemented from Belos::StatusTest< ScalarType, MV, OP >.

Definition at line 784 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
Teuchos::RCP<MV> Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getSolution ( ) [inline, virtual]

Returns the current solution estimate that was computed for the most recent residual test.

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 236 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
int Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getQuorum ( ) const [inline, virtual]

Returns the number of residuals that must pass the convergence test before Passed is returned.

Note:
If quorum=-1 then all residuals must pass the convergence test before Passed is returned.

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 240 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
bool Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getShowMaxResNormOnly ( ) [inline, virtual]

Returns whether the only maximum residual norm is displayed when the print() method is called.

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 243 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
std::vector<int> Belos::StatusTestImpResNorm< ScalarType, MV, OP >::convIndices ( ) [inline, virtual]

Returns the vector containing the indices of the residuals that passed the test.

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 246 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
MagnitudeType Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getTolerance ( ) const [inline, virtual]

"Original" convergence tolerance $\tau$ as set by user.

This value is the convergence tolerance as set by the user in the constructor, or by the setTolerance() method. See this class' main documentation and the documentation of getCurrTolerance() for an explanation of the difference between the "original" and "current" tolerances.

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 255 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
MagnitudeType Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getCurrTolerance ( ) const [inline]

Current convergence tolerance; may be changed to prevent loss of accuracy.

The difference between "original" tolerance (the value of getTolerance()) and "current" tolerance (the value of this method) relates to the idea of "loss of accuracy." See this class' main documentation for details. We do not allow users to set the "current" tolerance.

Definition at line 266 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
const std::vector<MagnitudeType>* Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getTestValue ( ) const [inline, virtual]

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

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 271 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
const std::vector<MagnitudeType>* Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getResNormValue ( ) const [inline]

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

Definition at line 274 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
const std::vector<MagnitudeType>* Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getScaledNormValue ( ) const [inline]

Returns the scaled norm value, $ \sigma $.

Definition at line 277 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
bool Belos::StatusTestImpResNorm< ScalarType, MV, OP >::getLOADetected ( ) const [inline, virtual]

Returns a boolean indicating a loss of accuracy has been detected in computing the residual.

Implements Belos::StatusTestResNorm< ScalarType, MV, OP >.

Definition at line 280 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
StatusType Belos::StatusTestImpResNorm< ScalarType, MV, OP >::firstCallCheckStatusSetup ( Iteration< 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 808 of file BelosStatusTestImpResNorm.hpp.

template<class ScalarType , class MV , class OP >
std::string Belos::StatusTestImpResNorm< ScalarType, MV, OP >::description ( ) const [inline, virtual]

Method to return description of the maximum iteration status test.

Reimplemented from Teuchos::Describable.

Definition at line 299 of file BelosStatusTestImpResNorm.hpp.


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