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< ParameterList >	extraParameters
	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`
	)