Belos Version of the Day
Public Types | Public Member Functions | Static Public Member Functions
Belos::StatusTestFactory< Scalar, MV, OP > Class Template Reference

A factory for making common cases of stopping criteria. More...

#include <BelosStatusTestFactory.hpp>

List of all members.

Public Types

typedef Teuchos::ScalarTraits
< Scalar >::magnitudeType 
magnitude_type
typedef StatusTest< Scalar, MV,
OP > 
base_test
typedef StatusTestGenResNorm
< Scalar, MV, OP > 
res_norm_test
typedef StatusTestMaxIters
< Scalar, MV, OP > 
max_iter_test
typedef StatusTestCombo
< Scalar, MV, OP > 
combo_test

Public Member Functions

Teuchos::RCP< const
Teuchos::ParameterList
getValidGmresParameters ()
 Default parameters for a status test suitable for GMRES.

Static Public Member Functions

static Teuchos::RCP< base_testgmresTest (const magnitude_type convTol, const int maxIterCount, const bool haveLeftPreconditioner, const ScaleType implicitScaleType=Belos::NormOfPrecInitRes, const ScaleType explicitScaleType=Belos::NormOfInitRes, const int blockSize=1, const int defQuorum=-1, const bool showMaxResNormOnly=false)
 Status test suitable for (preconditioned) GMRES.
static Teuchos::RCP< base_testgmresTest (const bool haveLeftPreconditioner, const Teuchos::RCP< Teuchos::ParameterList > &params)
 Overloaded gmresTest() for ParameterList input.
static std::pair< bool, bool > changeConvTolAndMaxIters (const Teuchos::RCP< base_test > &test, const magnitude_type convTol, const int maxIterCount)
 Change convergence tolerance and max number of iterations.
static bool changeMaxNumIters (const Teuchos::RCP< base_test > &test, const int maxIterCount)
 Change max number of iterations in place.
static bool changeConvTol (const Teuchos::RCP< base_test > &test, const magnitude_type convTol)
 Change convergence tolerance in place.
static ScaleType stringToScaleType (const std::string &scaleType)
 Convert string to enum that tells residual test how to scale.

Detailed Description

template<class Scalar, class MV, class OP>
class Belos::StatusTestFactory< Scalar, MV, OP >

A factory for making common cases of stopping criteria.

Author:
Mark Hoemmen Belos::StatusTest is an abstract interface for different stopping criteria ("status tests") for the iterative methods implemented in Belos. There are many different kinds of status tests implemented in Belos, and they can be combined in different ways to make aggregate status tests (e.g., "reached max number of iterations, or residual norm converged"). We include a few common cases of those aggregate status tests in this factory class so that people implementing subclasses of Belos::SolverManager can minimize code duplication.

This factory also provides ways to change the convergence tolerance and/or maximum number of iterations, in place, for existing and possibly aggregate status tests. This is an experimental optimization that attempts to avoid the overhead of constructing new status tests, but it comes at the cost of requiring $O(1)$ dynamic casts for each test in an aggregate collection (StatusTestCombo) of tests. It may be useful if you are not allowed to create new status test objects, for example if you only have access to them through a copied RCP and not through a reference to the RCP.

The general idea of factory classes like this one is to avoid duplicated code whenever possible. Scientific programmers' time is limited, so it's often better to avoid duplicated code, even if it means adding a new class or making the nonduplicated code a bit more complicated.

Definition at line 81 of file BelosStatusTestFactory.hpp.


Member Typedef Documentation

template<class Scalar, class MV, class OP>
typedef Teuchos::ScalarTraits<Scalar>::magnitudeType Belos::StatusTestFactory< Scalar, MV, OP >::magnitude_type

Definition at line 83 of file BelosStatusTestFactory.hpp.

template<class Scalar, class MV, class OP>
typedef StatusTest<Scalar,MV,OP> Belos::StatusTestFactory< Scalar, MV, OP >::base_test

Definition at line 84 of file BelosStatusTestFactory.hpp.

template<class Scalar, class MV, class OP>
typedef StatusTestGenResNorm<Scalar,MV,OP> Belos::StatusTestFactory< Scalar, MV, OP >::res_norm_test

Definition at line 85 of file BelosStatusTestFactory.hpp.

template<class Scalar, class MV, class OP>
typedef StatusTestMaxIters<Scalar,MV,OP> Belos::StatusTestFactory< Scalar, MV, OP >::max_iter_test

Definition at line 86 of file BelosStatusTestFactory.hpp.

template<class Scalar, class MV, class OP>
typedef StatusTestCombo<Scalar,MV,OP> Belos::StatusTestFactory< Scalar, MV, OP >::combo_test

Definition at line 87 of file BelosStatusTestFactory.hpp.


Member Function Documentation

template<class Scalar, class MV, class OP>
static Teuchos::RCP<base_test> Belos::StatusTestFactory< Scalar, MV, OP >::gmresTest ( const magnitude_type  convTol,
const int  maxIterCount,
const bool  haveLeftPreconditioner,
const ScaleType  implicitScaleType = Belos::NormOfPrecInitRes,
const ScaleType  explicitScaleType = Belos::NormOfInitRes,
const int  blockSize = 1,
const int  defQuorum = -1,
const bool  showMaxResNormOnly = false 
) [static]

Status test suitable for (preconditioned) GMRES.

The returned status test stops iteration if the maximum number of iterations has been reached, OR if the residual norm has converged. The latter first iterates until the implicit residual norm (the one computed as a side effect of solving the projected least-squares problem in GMRES) reaches the given tolerance. Then, it switches to computing the explicit residual norm ( $\|b - Ax\|_2$) and iterates until that has reached the tolerance.

Parameters:
convTol[in] Convergence tolerance. The meaning of this depends on the scaling used.
maxIterCount[in] Maximum number of iterations of GMRES to execute before stopping.
haveLeftPreconditioner[in] Whether we will be running GMRES with a left preconditioner. This affects the residual norm computation.
implicitScaleType[in] Type of scaling to use for the implicit residual norm computation. Default is to scale by the norm of the preconditioned (if applicable) initial residual vector. The stringToScaleType() method might be useful.
explicitScaleType[in] Type of scaling to use for the explicit residual norm computation. Default is to scale by the norm of the (nonpreconditioned) initial residual vector. The stringToScaleType() method might be useful.
blockSize[in] Number of linear system(s) that the solver can solve at one time. Block iterative methods support blockSize > 1. Non-block iterative methods require blockSize = 1. This parameter is only used to verify defQuorum, if the latter is not -1.
defQuorum[in] "Deflation Quorum": number of converged systems before deflation is allowed. Cannot be larger than "Block Size". -1 is the default in Belos::StatusTestGenResNorm, and it means that all of the systems must converge before deflation is allowed.
showMaxResNormOnly[in] "Show Maximum Residual Norm Only" is only meaningful when the "Block Size" parameter is > 1.
Returns:
Aggregate status test for GMRES.
template<class Scalar , class MV , class OP >
Teuchos::RCP< typename StatusTestFactory< Scalar, MV, OP >::base_test > Belos::StatusTestFactory< Scalar, MV, OP >::gmresTest ( const bool  haveLeftPreconditioner,
const Teuchos::RCP< Teuchos::ParameterList > &  params 
) [static]

Overloaded gmresTest() for ParameterList input.

Does the same thing as the other gmresTest(), except it reads the values from the given parameter list. The parameter list must be nonnull and valid. We make only a modest effort to fill in default values for nonrequired parameters only. We throw std::invalid_argument if any required parameter is missing or any provided value is invalid.

Definition at line 314 of file BelosStatusTestFactory.hpp.

template<class Scalar, class MV, class OP>
static std::pair<bool, bool> Belos::StatusTestFactory< Scalar, MV, OP >::changeConvTolAndMaxIters ( const Teuchos::RCP< base_test > &  test,
const magnitude_type  convTol,
const int  maxIterCount 
) [static]

Change convergence tolerance and max number of iterations.

The changes take place in place in the given status test. If the status test is a StatusTestCombo, we recurse on all children, changing them if they are of the appropriate type. If we don't find anything to change, we do nothing, except report back in the return value.

Returns:
First element of the pair is whether we found at least one residual norm test for which to change the convergence tolerance. Second element is whether we found at least one maximum number of iterations test for which to change the maximum iteration count.
Note:
This method does nothing to protect against infinite recursion if the StatusTestCombo tests were constructed incorrectly. However, StatusTestCombo itself prevents you from forming loops in the graph of status tests, so this method should always terminate.
The given status test does _not_ need to be one that this factory created. This method should work with any Belos::StatusTest instance.
template<class Scalar, class MV, class OP>
bool Belos::StatusTestFactory< Scalar, MV, OP >::changeMaxNumIters ( const Teuchos::RCP< base_test > &  test,
const int  maxIterCount 
) [static]

Change max number of iterations in place.

See the notes for changeConvTolAndMaxIters().

Returns:
Whether we found at least one test to change.

Definition at line 405 of file BelosStatusTestFactory.hpp.

template<class Scalar, class MV, class OP>
bool Belos::StatusTestFactory< Scalar, MV, OP >::changeConvTol ( const Teuchos::RCP< base_test > &  test,
const magnitude_type  convTol 
) [static]

Change convergence tolerance in place.

See the notes for changeConvTolAndMaxIters().

Returns:
Whether we found at least one test to change.

Definition at line 511 of file BelosStatusTestFactory.hpp.

template<class Scalar , class MV , class OP >
static ScaleType Belos::StatusTestFactory< Scalar, MV, OP >::stringToScaleType ( const std::string &  scaleType) [static]

Convert string to enum that tells residual test how to scale.

Parameters:
scaleType[in] A string describing the type of scaling to be used in a residual norm convergence test. Valid values include:
  • "Norm of Initial Residual"
  • "Norm of Preconditioned Initial Residual"
  • "Norm of RHS" / "Norm of Right-Hand Side"
  • "None" (no scaling)
Returns:
The ScaleType enum value that tells the residual test how to perform scaling.

Definition at line 560 of file BelosStatusTestFactory.hpp.

template<class Scalar, class MV, class OP>
Teuchos::RCP<const Teuchos::ParameterList> Belos::StatusTestFactory< Scalar, MV, OP >::getValidGmresParameters ( )

Default parameters for a status test suitable for GMRES.

This method is nonconst because it creates and caches the list of default parameters on demand.


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