Thyra  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Related Functions | List of all members
Thyra::SolveCriteria< Scalar > Struct Template Reference

Simple struct that defines the requested solution criteria for a solve. More...

#include <Thyra_SolveSupportTypes.hpp>

Public Types

typedef Teuchos::ScalarTraits
< Scalar >::magnitudeType 
ScalarMag
 

Public Member Functions

 SolveCriteria ()
 Default construction to use default solve criteria. More...
 
 SolveCriteria (SolveMeasureType solveMeasureType_in, ScalarMag requestedTol_in, const RCP< ParameterList > &extraParameters_in=Teuchos::null, const RCP< ReductionFunctional< Scalar > > &numeratorReductionFunc_in=Teuchos::null, const RCP< ReductionFunctional< Scalar > > &denominatorReductionFunc_in=Teuchos::null)
 Construct with a specified solve criteria. More...
 

Static Public Member Functions

static ScalarMag unspecifiedTolerance ()
 

Public Attributes

SolveMeasureType solveMeasureType
 The type of solve tolerance requested as given in this->requestedTol. More...
 
ScalarMag requestedTol
 The requested solve tolerance (what the client would like to see). Only significant if !this->solveMeasureType.useDefault() More...
 
RCP< ParameterListextraParameters
 Any extra control parameters (e.g. max iterations). More...
 
RCP< const ReductionFunctional
< Scalar > > 
numeratorReductionFunc
 Reduction function to be used in place of the natural norm of the numerator. More...
 
RCP< const ReductionFunctional
< Scalar > > 
denominatorReductionFunc
 Reduction function to be used in place of the natural norm of the numerator. More...
 

Related Functions

(Note that these are not member functions.)

template<class Scalar >
std::ostream & operator<< (std::ostream &out, const SolveCriteria< Scalar > &solveCriteria)
 Output operator. More...
 

Detailed Description

template<class Scalar>
struct Thyra::SolveCriteria< Scalar >

Simple struct that defines the requested solution criteria for a solve.

A solve criteria defines the solution to a linear (or nonlinear) system of equations in terms of purely mathematical entities. The form of the linear system is:

 A * x = b

 r = b - A * x

with x0 defining the initial guess for the solution and:

 r0 = b - A * x0

The mathematical representation of the solve criteria takes the form:

   gN(vN) / gD(vD) <= requestedTol

where gN(vN) and gD(vD) are defined as g(v)=

||r|| : if solveMeasureValue==SOLVE_MEASURE_NORM_RESIDUAL && reductionFunc==null
reductionFunc.reduce(r) : if solveMeasureValue==SOLVE_MEASURE_NORM_RESIDUAL && reductionFunc!=null
||x|| : if solveMeasureValue==SOLVE_MEASURE_NORM_SOLUTION && reductionFunc==null
reductionFunc.reduce(x) : if solveMeasureValue==SOLVE_MEASURE_NORM_SOLUTION && reductionFunc!=null
||r0|| : if solveMeasureValue==SOLVE_MEASURE_NORM_INIT_RESIDUAL && reductionFunc==null
reductionFunc.reduce(r0) : if solveMeasureValue==SOLVE_MEASURE_NORM_INIT_RESIDUAL && reductionFunc!=null
||b|| : if solveMeasureValue==SOLVE_MEASURE_NORM_RHS && reductionFunc==null
reductionFunc.reduce(b) : if solveMeasureValue==SOLVE_MEASURE_NORM_RHS && reductionFunc!=null
1 : if solveMeasureValue==SOLVE_MEASURE_ONE

where solveMeasureValue = solveMeasure.numerator and reductionFunc = numeratorReductionFunc for gN(vN) while solveMeasureValue = solveMeasure.denominator and reductionFunc = denominatorReductionFunc for gD(vD).

For example, for solveMeasure.numerator==SOLVE_MEASURE_NORM_RESIDUAL and solveMeasure.denominator==SOLVE_MEASURE_ONE we have the solve convergence criteria:

   ||r|| / 1 <= requestedTol

For solveMeasure.numerator==SOLVE_MEASURE_NORM_RESIDUAL and solveMeasure.denominator==SOLVE_MEASURE_NORM_INIT_RESIDUAL we have the solve convergence criteria:

   ||r|| / ||r0|| <= requestedTol

The objects numeratorReductionFunc and denominatorReductionFunc basically override the use of the natural norm ||.|| for the given vector. This is needed to implement some unusual convergence criteria needed for certain types of nonlinear ANAs (such as the optimization solvers in the Aristos package).

There are several reasons for the structure of the solve convergence criteria shown above. First, we want to give the solver implementation as much information as we can as to the nature of the solve convergence criteria. That way, the solver implementation can compute the different quantities more efficiently in many cases.. For example, with GMRES no direct estimate of the residual vector r is cheaply available but a cheap estimate of the natural norm ||r|| is readily available. Also, while the vectors r0 and b could be computed by the client before the solve, it is potentially more efficient to let the solver do it since it may compute theses quantities as a natural byproduct of the solve process.

Definition at line 312 of file Thyra_SolveSupportTypes.hpp.

Member Typedef Documentation

template<class Scalar>
typedef Teuchos::ScalarTraits<Scalar>::magnitudeType Thyra::SolveCriteria< Scalar >::ScalarMag

Definition at line 314 of file Thyra_SolveSupportTypes.hpp.

Constructor & Destructor Documentation

template<class Scalar>
Thyra::SolveCriteria< Scalar >::SolveCriteria ( )
inline

Default construction to use default solve criteria.

Definition at line 336 of file Thyra_SolveSupportTypes.hpp.

template<class Scalar>
Thyra::SolveCriteria< Scalar >::SolveCriteria ( SolveMeasureType  solveMeasureType_in,
ScalarMag  requestedTol_in,
const RCP< ParameterList > &  extraParameters_in = Teuchos::null,
const RCP< ReductionFunctional< Scalar > > &  numeratorReductionFunc_in = Teuchos::null,
const RCP< ReductionFunctional< Scalar > > &  denominatorReductionFunc_in = Teuchos::null 
)
inline

Construct with a specified solve criteria.

Definition at line 340 of file Thyra_SolveSupportTypes.hpp.

Member Function Documentation

template<class Scalar>
static ScalarMag Thyra::SolveCriteria< Scalar >::unspecifiedTolerance ( )
inlinestatic

Definition at line 316 of file Thyra_SolveSupportTypes.hpp.

Friends And Related Function Documentation

template<class Scalar >
std::ostream & operator<< ( std::ostream &  out,
const SolveCriteria< Scalar > &  solveCriteria 
)
related

Output operator.

Definition at line 361 of file Thyra_SolveSupportTypes.hpp.

Member Data Documentation

template<class Scalar>
SolveMeasureType Thyra::SolveCriteria< Scalar >::solveMeasureType

The type of solve tolerance requested as given in this->requestedTol.

Definition at line 319 of file Thyra_SolveSupportTypes.hpp.

template<class Scalar>
ScalarMag Thyra::SolveCriteria< Scalar >::requestedTol

The requested solve tolerance (what the client would like to see). Only significant if !this->solveMeasureType.useDefault()

Definition at line 322 of file Thyra_SolveSupportTypes.hpp.

template<class Scalar>
RCP<ParameterList> Thyra::SolveCriteria< Scalar >::extraParameters

Any extra control parameters (e.g. max iterations).

Note that the contents of this parameter list is totally undefined and any client that uses this does so at their own peril!

Definition at line 328 of file Thyra_SolveSupportTypes.hpp.

template<class Scalar>
RCP<const ReductionFunctional<Scalar> > Thyra::SolveCriteria< Scalar >::numeratorReductionFunc

Reduction function to be used in place of the natural norm of the numerator.

Definition at line 331 of file Thyra_SolveSupportTypes.hpp.

template<class Scalar>
RCP<const ReductionFunctional<Scalar> > Thyra::SolveCriteria< Scalar >::denominatorReductionFunc

Reduction function to be used in place of the natural norm of the numerator.

Definition at line 334 of file Thyra_SolveSupportTypes.hpp.


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