Thyra::LinearOpWithSolveBase< Scalar > Class Template Reference
[Thyra operator solve fundamental interfaces]

Base class for all linear operators that can support a high-level solve operation. More...

#include <Thyra_LinearOpWithSolveBase_decl.hpp>

Inheritance diagram for Thyra::LinearOpWithSolveBase< Scalar >:

Inheritance graph
[legend]
List of all members.

Public interface funtions.

bool solveSupports (EOpTransp transp) const
 Return if solve() supports the argument transp.
bool solveSupportsSolveMeasureType (EOpTransp transp, const SolveMeasureType &solveMeasureType) const
 Return if solve() supports the given the solve measure type.
SolveStatus< Scalar > solve (const EOpTransp A_trans, const MultiVectorBase< Scalar > &B, const Ptr< MultiVectorBase< Scalar > > &X, const Ptr< const SolveCriteria< Scalar > > solveCriteria=Teuchos::null) const
 Request the solution of a block linear system.

Deprecated.

THYRA_DEPRECATED bool solveSupportsConj (EConj conj) const
 Deprecated.
THYRA_DEPRECATED bool solveTransposeSupportsConj (EConj conj) const
 Deprecated.
THYRA_DEPRECATED void solve (const EConj conj, const MultiVectorBase< Scalar > &B, MultiVectorBase< Scalar > *X, const int numBlocks=0, const BlockSolveCriteria< Scalar > blockSolveCriteria[]=NULL, SolveStatus< Scalar > blockSolveStatus[]=NULL) const
 Deprecated.
THYRA_DEPRECATED bool solveSupportsSolveMeasureType (EConj conj, const SolveMeasureType &solveMeasureType) const
 Deprecated.
THYRA_DEPRECATED bool solveTransposeSupportsSolveMeasureType (EConj conj, const SolveMeasureType &solveMeasureType) const
 Deprecated.
THYRA_DEPRECATED void solveTranspose (const EConj conj, const MultiVectorBase< Scalar > &B, MultiVectorBase< Scalar > *X, const int numBlocks=0, const BlockSolveCriteria< Scalar > blockSolveCriteria[]=NULL, SolveStatus< Scalar > blockSolveStatus[]=NULL) const
 Deprecated.

Protected virtual functions to be overridden by subclasses.

virtual bool solveSupportsImpl (EOpTransp transp) const
 Virtual implementation for solveSupports().
virtual bool solveSupportsSolveMeasureTypeImpl (EOpTransp transp, const SolveMeasureType &solveMeasureType) const
 Virtual implementation for solveSupportsSolveMeasureType().
virtual SolveStatus< Scalar > solveImpl (const EOpTransp transp, const MultiVectorBase< Scalar > &B, const Ptr< MultiVectorBase< Scalar > > &X, const Ptr< const SolveCriteria< Scalar > > solveCriteria) const =0
 Virtual implementation for solve().

Detailed Description

template<class Scalar>
class Thyra::LinearOpWithSolveBase< Scalar >

Base class for all linear operators that can support a high-level solve operation.

Outline

Introduction

This interface supports linear operators (with potentially different range and domain scalar types) that can also support a forward solve operation (using solve()) of the form:

\[ A X = B \]

and/or a transpose solve operation (using solveTranspose()) of the form:

\[ A^T X = B \]

and/or an adjoint solve operation (using solveTranspose()) of the form:

\[ A^H X = B \]

where $A$ is *this linear operator, $B$ is an appropriate RHS multi-vector with $m$ columns, and $X$ is a LHS multi-vector with $m$ columns that is computed by this interface. Note that if the underlying operator has real-valued entries then the transpose $A^T$ and the adjoint $A^H$ are the same.

Note that this interface does not assume that the linear operator itself is nonsingular or invertible in the classic sense (i.e. an inverse operator may not exist).

Let $op(A)$ signify either the forward operator $A$, the transpose operator $A^T$ or the adjoint operator $A^H$. What this interface assumes is that for any appropriately selected consistent multi-vector RHS B that a solve of $A X = B$ will yield an approximate solution LHS multi-vector X such that A X == B. Note that this interface does not assume that a solution $X$ can be computed for any random RHS multi-vector $B$. Solutions for any random RHS can on be expected for relatively well conditioned non-singular operators.

Note: It is recommended that clients use the non-member helper functions defined here rather than call these member functions directly as they support a number of other simpler use cases.

Solve Criteria

This interface potentially allows clients to specify a relative tolerance on either the relative residual norm or the relative norm of the solution error and can target different solution criteria to different blocks of linear systems. This interface tries to allow for mathematically rigorous solution tolerances that are not based only any implementation-dependent features like the number of iterations of some solver algorithm. This interface, however, allows *this operator to exclude support certain types of solve measures (see the functions solveSupportsSolveMeasureType() and solveTransposeSupportsSolveMeasureType()). Also, this interface assumes that all implementations can support a "default" solve criteria that is determined internally to *this.

This interface is meant to support direct and iterative linear solvers as well as combinations of the two in a variety of configurations. Because of the almost infinite number of types of linear solver configurations possible, this interface tries not to specify any particular solver-specific solution control options. The one exception is a maximum number of iterations which is totally implementation defined. These types of control options are better specified in lower lever implementations and should be kept out of an interface such as this.

Let solveCriteria be a SolveCriteria object setup by a client to be passed into a solve operation. This object can be set up in a variety of ways to support several different use cases which are described below:

Solve Status

After the solve() and solveTranspose() functions return, the client can optionally get back a solution status for each block of linear systems for of block solve criteria. Specifically, for each block of linear systems

\[ A X_{(:,i_{j}+1:i_j)} = B_{(:,i_{j}+1:i_j)} \]

whose solution criteria is specified by a SolveCriteria object, a SolveStatus object can optionally be returned that lets the client know the status of the linear solve.

A note about direct solvers is in order. The "inexact" solve features of this interface are primarily designed to support "loose" solve tolerances that exploit the properties of iterative linear solvers. With that said, any decent direct solver can assume that it has met the convergence criteria as requested by the client but does not have to return an estimate of the actual tolerance achieved.

If solveStatus is a SolveStatus object returned for the above block linear system the the following return status are significant:

The implementation of the function accumulateSolveStatus() defines how to accumulate the individual solve status for each RHS in a block into the overall solve status for an entire block returned in the SolveStatus object from teh solve().

Use cases

This interface supports a variety of use cases where where described, more or less, in the above sections. Here, we give specific examples for a number of important use cases and show how to use the non-member helper functions defined here.

ToDo: Finish documentation!

Notes to subclass developers

This interface assumes, by default, that subclasses will only support the forward solve operation. See LinearOpBase for what other virtual functions must be overridden to completely define a concrete subclass.

Definition at line 295 of file Thyra_LinearOpWithSolveBase_decl.hpp.


Member Function Documentation

template<class Scalar>
bool Thyra::LinearOpWithSolveBase< Scalar >::solveSupports ( EOpTransp  transp  )  const [inline]

Return if solve() supports the argument transp.

The default implementation returns true for non-transposed, non-conjugate solves..

Definition at line 309 of file Thyra_LinearOpWithSolveBase_decl.hpp.

template<class Scalar>
bool Thyra::LinearOpWithSolveBase< Scalar >::solveSupportsSolveMeasureType ( EOpTransp  transp,
const SolveMeasureType solveMeasureType 
) const [inline]

Return if solve() supports the given the solve measure type.

The default implementation returns true for solveMeasureType.useDefault()==true.

Definition at line 318 of file Thyra_LinearOpWithSolveBase_decl.hpp.

template<class Scalar>
SolveStatus<Scalar> Thyra::LinearOpWithSolveBase< Scalar >::solve ( const EOpTransp  A_trans,
const MultiVectorBase< Scalar > &  B,
const Ptr< MultiVectorBase< Scalar > > &  X,
const Ptr< const SolveCriteria< Scalar > >  solveCriteria = Teuchos::null 
) const [inline]

Request the solution of a block linear system.

Parameters:
A_trans [in] Determines if the elements are non-conjugate non-transposed (NONTRANS) or conjugate transposed (CONJTRANS).
B [in] The RHS multi-vector with m = B.domain()->dim() columns.
X [in/out] The LHS multi-vector with with m = X->domain()->dim() columns. On input, contains the initial guess for the solution (only significant for iterative solvers) and on output contains an estimate of the solution.
solveCriteria [in] Gives the desired solution criteria for linear systems. A value of solveCriteria==null means to use the default solve criteria.
Returns:
Return the solve status if any program has been made.
Preconditions:

Postconditions:

See the above introduction for a more complete description of how this function behaves and the meaning of the argument solveCriteria and the return value.

Definition at line 371 of file Thyra_LinearOpWithSolveBase_decl.hpp.

template<class Scalar>
bool Thyra::LinearOpWithSolveBase< Scalar >::solveSupportsConj ( EConj  conj  )  const

Deprecated.

Definition at line 42 of file Thyra_LinearOpWithSolveBase_def.hpp.

template<class Scalar>
bool Thyra::LinearOpWithSolveBase< Scalar >::solveTransposeSupportsConj ( EConj  conj  )  const

Deprecated.

Definition at line 77 of file Thyra_LinearOpWithSolveBase_def.hpp.

template<class Scalar>
void Thyra::LinearOpWithSolveBase< Scalar >::solve ( const EConj  conj,
const MultiVectorBase< Scalar > &  B,
MultiVectorBase< Scalar > *  X,
const int  numBlocks = 0,
const BlockSolveCriteria< Scalar >  blockSolveCriteria[] = NULL,
SolveStatus< Scalar >  blockSolveStatus[] = NULL 
) const

Deprecated.

Definition at line 57 of file Thyra_LinearOpWithSolveBase_def.hpp.

template<class Scalar>
bool Thyra::LinearOpWithSolveBase< Scalar >::solveSupportsSolveMeasureType ( EConj  conj,
const SolveMeasureType solveMeasureType 
) const

Deprecated.

Definition at line 49 of file Thyra_LinearOpWithSolveBase_def.hpp.

template<class Scalar>
bool Thyra::LinearOpWithSolveBase< Scalar >::solveTransposeSupportsSolveMeasureType ( EConj  conj,
const SolveMeasureType solveMeasureType 
) const

Deprecated.

Definition at line 84 of file Thyra_LinearOpWithSolveBase_def.hpp.

template<class Scalar>
void Thyra::LinearOpWithSolveBase< Scalar >::solveTranspose ( const EConj  conj,
const MultiVectorBase< Scalar > &  B,
MultiVectorBase< Scalar > *  X,
const int  numBlocks = 0,
const BlockSolveCriteria< Scalar >  blockSolveCriteria[] = NULL,
SolveStatus< Scalar >  blockSolveStatus[] = NULL 
) const

Deprecated.

Definition at line 93 of file Thyra_LinearOpWithSolveBase_def.hpp.

template<class Scalar>
bool Thyra::LinearOpWithSolveBase< Scalar >::solveSupportsImpl ( EOpTransp  transp  )  const [protected, virtual]

Virtual implementation for solveSupports().

Reimplemented in Thyra::DefaultAdjointLinearOpWithSolve< Scalar >, Thyra::DefaultBlockedTriangularLinearOpWithSolve< Scalar >, Thyra::DefaultDiagonalLinearOpWithSolve< Scalar >, Thyra::DefaultMultiVectorLinearOpWithSolve< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolve< Scalar >, and Thyra::DelayedLinearOpWithSolve< Scalar >.

Definition at line 117 of file Thyra_LinearOpWithSolveBase_def.hpp.

template<class Scalar>
bool Thyra::LinearOpWithSolveBase< Scalar >::solveSupportsSolveMeasureTypeImpl ( EOpTransp  transp,
const SolveMeasureType solveMeasureType 
) const [protected, virtual]

Virtual implementation for solveSupportsSolveMeasureType().

Reimplemented in Thyra::DefaultAdjointLinearOpWithSolve< Scalar >, Thyra::DefaultBlockedTriangularLinearOpWithSolve< Scalar >, Thyra::DefaultDiagonalLinearOpWithSolve< Scalar >, Thyra::DefaultMultiVectorLinearOpWithSolve< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolve< Scalar >, and Thyra::DelayedLinearOpWithSolve< Scalar >.

Definition at line 126 of file Thyra_LinearOpWithSolveBase_def.hpp.

template<class Scalar>
virtual SolveStatus<Scalar> Thyra::LinearOpWithSolveBase< Scalar >::solveImpl ( const EOpTransp  transp,
const MultiVectorBase< Scalar > &  B,
const Ptr< MultiVectorBase< Scalar > > &  X,
const Ptr< const SolveCriteria< Scalar > >  solveCriteria 
) const [protected, pure virtual]

Virtual implementation for solve().

Implemented in Thyra::DefaultAdjointLinearOpWithSolve< Scalar >, Thyra::DefaultBlockedTriangularLinearOpWithSolve< Scalar >, Thyra::DefaultDiagonalLinearOpWithSolve< Scalar >, Thyra::DefaultMultiVectorLinearOpWithSolve< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolve< Scalar >, and Thyra::DelayedLinearOpWithSolve< Scalar >.


The documentation for this class was generated from the following files:
Generated on Tue Jul 13 09:26:32 2010 for Thyra by  doxygen 1.4.7