Thyra Version of the Day

Factory interface for creating LinearOpWithSolveBase
objects from compatible LinearOpBase
objects.
More...
#include <Thyra_LinearOpWithSolveFactoryBase_decl.hpp>
Related Functions  
(Note that these are not member functions.)  
template<class Scalar >  
bool  isCompatible (const LinearOpWithSolveFactoryBase< Scalar > &lowsFactory, const LinearOpBase< Scalar > &fwdOp) 
Return if the forward operator is a compatible source for a LOWSFB object.  
template<class Scalar >  
void  setDefaultObjectLabel (const LinearOpBase< Scalar > &fwdOp, const Ptr< LinearOpWithSolveBase< Scalar > > &Op) 
Set default label on a LOWSB object.  
template<class Scalar >  
void  initializeOp (const LinearOpWithSolveFactoryBase< Scalar > &lowsFactory, const RCP< const LinearOpBase< Scalar > > &fwdOp, const Ptr< LinearOpWithSolveBase< Scalar > > &Op, const ESupportSolveUse supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED) 
Initialize a precreated LOWSB object given a forward operator.  
template<class Scalar >  
void  initializeAndReuseOp (const LinearOpWithSolveFactoryBase< Scalar > &lowsFactory, const RCP< const LinearOpBase< Scalar > > &fwdOp, const Ptr< LinearOpWithSolveBase< Scalar > > &Op) 
Reinitialize a precreated LOWSB object given a forward operator, reusing a much as possible from the prior LOWSB object.  
template<class Scalar >  
void  initializePreconditionedOp (const LinearOpWithSolveFactoryBase< Scalar > &lowsFactory, const RCP< const LinearOpBase< Scalar > > &fwdOp, const RCP< const PreconditionerBase< Scalar > > &prec, const Ptr< LinearOpWithSolveBase< Scalar > > &Op, const ESupportSolveUse supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED) 
Initialize a preconditioned LOWSB object given an external preconditioner.  
template<class Scalar >  
void  initializeApproxPreconditionedOp (const LinearOpWithSolveFactoryBase< Scalar > &lowsFactory, const RCP< const LinearOpBase< Scalar > > &fwdOp, const RCP< const LinearOpBase< Scalar > > &approxFwdOp, const Ptr< LinearOpWithSolveBase< Scalar > > &Op, const ESupportSolveUse supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED) 
Initialize a preconditioned LOWSB object given an external operator to be used to generate the preconditioner internally.  
template<class Scalar >  
RCP< LinearOpWithSolveBase < Scalar > >  linearOpWithSolve (const LinearOpWithSolveFactoryBase< Scalar > &lowsFactory, const RCP< const LinearOpBase< Scalar > > &fwdOp, const ESupportSolveUse supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED) 
Create and initialize a LinearOpWithSolveBase object from a LinearOpBase object using a LinearOpWithSolveFactoryBase strategy object.  
template<class Scalar >  
RCP< LinearOpBase< Scalar > >  inverse (const LinearOpWithSolveFactoryBase< Scalar > &LOWSF, const RCP< const LinearOpBase< Scalar > > &fwdOp, const ESupportSolveUse supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED, const Ptr< const SolveCriteria< Scalar > > &fwdSolveCriteria=Teuchos::null, const EThrowOnSolveFailure throwOnFwdSolveFailure=THROW_ON_SOLVE_FAILURE, const Ptr< const SolveCriteria< Scalar > > &adjSolveCriteria=Teuchos::null, const EThrowOnSolveFailure throwOnAdjSolveFailure=THROW_ON_SOLVE_FAILURE) 
Form a const implicit inverse operator M = inv(A) given a factory.  
template<class Scalar >  
void  uninitializeOp (const LinearOpWithSolveFactoryBase< Scalar > &lowsFactory, const Ptr< LinearOpWithSolveBase< Scalar > > &Op, const Ptr< RCP< const LinearOpBase< Scalar > > > &fwdOp=Teuchos::null, const Ptr< RCP< const PreconditionerBase< Scalar > > > &prec=Teuchos::null, const Ptr< RCP< const LinearOpBase< Scalar > > > &approxFwdOp=Teuchos::null, const Ptr< ESupportSolveUse > &supportSolveUse=Teuchos::null) 
Uninitialized a precreated LOWSB object, returning input objects used to initialize it.  
Preconditioner Factory Management  
virtual bool  acceptsPreconditionerFactory () const 
Determines if *this accepts external preconditioner factories.  
virtual void  setPreconditionerFactory (const RCP< PreconditionerFactoryBase< Scalar > > &precFactory, const std::string &precFactoryName) 
Set a preconditioner factory object.  
virtual RCP < PreconditionerFactoryBase < Scalar > >  getPreconditionerFactory () const 
Get a preconditioner factory object.  
virtual void  unsetPreconditionerFactory (RCP< PreconditionerFactoryBase< Scalar > > *precFactory=NULL, std::string *precFactoryName=NULL) 
Unset the preconditioner factory (if one is set).  
Creation/Initialization of basic LinearOpWithSolveBase objects  
virtual bool  isCompatible (const LinearOpSourceBase< Scalar > &fwdOpSrc) const =0 
Check that a LinearOpBase object is compatible with *this factory object.  
virtual RCP < LinearOpWithSolveBase < Scalar > >  createOp () const =0 
Create an (uninitialized) LinearOpWithSolveBase object to be initialized later in this>initializeOp() .  
virtual void  initializeOp (const RCP< const LinearOpSourceBase< Scalar > > &fwdOpSrc, LinearOpWithSolveBase< Scalar > *Op, const ESupportSolveUse supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED) const =0 
Initialize a precreated LinearOpWithSolveBase object given a "compatible" LinearOpBase object.  
virtual void  initializeAndReuseOp (const RCP< const LinearOpSourceBase< Scalar > > &fwdOpSrc, LinearOpWithSolveBase< Scalar > *Op) const 
Initialize a precreated LinearOpWithSolveBase object given a "compatible" LinearOpBase object but allow for reuse of any preprocessing that is in *Op .  
virtual void  uninitializeOp (LinearOpWithSolveBase< Scalar > *Op, RCP< const LinearOpSourceBase< Scalar > > *fwdOpSrc=NULL, RCP< const PreconditionerBase< Scalar > > *prec=NULL, RCP< const LinearOpSourceBase< Scalar > > *approxFwdOpSrc=NULL, ESupportSolveUse *supportSolveUse=NULL) const =0 
Uninitialize a LinearOpWithSolveBase object and return its remembered forward linear operator and potentially also its externally generated preconditioner.  
Creation/Initialization of Preconditioned LinearOpWithSolveBase objects  
virtual bool  supportsPreconditionerInputType (const EPreconditionerInputType precOpType) const 
Determines if *this supports given preconditioner type.  
virtual void  initializePreconditionedOp (const RCP< const LinearOpSourceBase< Scalar > > &fwdOpSrc, const RCP< const PreconditionerBase< Scalar > > &prec, LinearOpWithSolveBase< Scalar > *Op, const ESupportSolveUse supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED) const 
Initialize a precreated LinearOpWithSolveBase object given a "compatible" LinearOpBase object and an optional PreconditionerBase object.  
virtual void  initializeApproxPreconditionedOp (const RCP< const LinearOpSourceBase< Scalar > > &fwdOpSrc, const RCP< const LinearOpSourceBase< Scalar > > &approxFwdOpSrc, LinearOpWithSolveBase< Scalar > *Op, const ESupportSolveUse supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED) const 
Initialize a precreated LinearOpWithSolveBase object given a "compatible" forward LinearOpBase object and an approximate forward LinearOpBase object. 
Factory interface for creating LinearOpWithSolveBase
objects from compatible LinearOpBase
objects.
This strategy interface allows a client to take one or more "compatible" LinearOpBase
objects and then create one or more LinearOpWithSolveBase
objects that can then be used to solve for linear systems. This interface carefully separates the construction from the initialization of a LinearOpWithSolveBase
object.
Note that the nonmember functions defined here provide for simpler use cases and are demonstrated in the example code below.
This interface can be implemented by both direct and iterative linear solvers.
This interface supports the concept of an external preconditioner that can be created by the client an passed into the function initializePreconditionedOp()
The following use cases demonstrate and specify the behavior of this interface in several different situations. These use cases don't cover very possible variation but implementors and clients should get a pretty good idea of the desired behavior from what is specified below.
Note: All of the code fragments shown in the below use cases is code that is compiled and run automatically by the test harness and the code fragments are automatically pulled into this HTML documentation whenever the documentation is rebuilt. Therefore, one can have a very high degree of confidence that the code shown in these examples is correct.
The following use cases are described below:
Performing a single linear solve is at minimum a two step process. The following example function shows how to take a LinearOpBase
object, a compatible LinearOpWithSolveFactoryBase
object, a RHS and a LHS and then solve the linear system using the default solve criteria:
See the documentation for the LinearOpWithSolveBase
interface for how to specify solve criteria, how to perform adjoint (i.e. transpose) solve, and how to solve systems with multiple RHSs.
Note that the forward operator A
is passed into this function singleLinearSolve(...)
as a raw object reference and not as a Teuchos::RCP
wrapped object since no persisting relationship with this object will be last after this function exists, even if an exception is thrown.
Also note that once the above function exits that all memory of the invertible operator created as part of the invertibleA
object will be erased. The following use cases show more sophisticated uses of these interfaces.
This interface requires that all good implementations support implicitly scaled and adjoint (or transposed) forward operators. The following example function shows how this looks:
In the above example, the functions adjoint()
and scale()
create an implicitly scaled adjoint operator of type DefaultScaledAdjointLinearOp
which is then unwrapped by the lowsFactory
implementation. The idea is that any operation that works with a particular forward operator A
should automatically work with an implicitly scaled and/or adjoint view of that forward operator. The specification of this interface actually says that all LinearOpBase
objects that support the abstract mixin interface ScaledAdjointLinearOpBase
will allow this feature.
Above also note that the forward operator A
is passed in as a Teuchos::RCP
wrapped object since it will be used to create a persisting relationship with the returned Thyra::LinearOpWithSolveBase
object. Also note that the lowsFactory
object is still passed in as a raw object reference since no persisting relationship with lowsFactory
is created as a side effect of calling this function. Remember, the specification of this interface requires that the returned LinearOpWithSolveBase
objects be independent from the lowsFactory
object that creates them. In other words, once a LinearOpWithSolveFactoryBase
object creates a LinearOpWithSolveBase
object, then the LinearOpWithSolveFactoryBase
object can be deleted and the LinearOpWithSolveBase
it created must still be valid.
In this use case is comprised of:
LinearOpWithSolveBase
object from a LinearOpBase
object LinearOpWithSolveBase
object to solve one or more linear systems LinearOpBase
object and reinitializing the LinearOpWithSolveBase
object LinearOpWithSolveBase
object to solve one or more linear systems The below code fragment shows how this looks.
In the above code fragment the call to the function lowsFactory.uninitializeOp(&*invertibleA)
may not fully uninitialize the *invertibleA
object as it may contain memory of a factorization structure, or a communication pattern, or whatever may have been computed in the first call to lowsFactory.initializeOp(rcpA,&*invertibleA)
. This allows for a more efficient reinitialization on the second call of lowsFactory.initializeOp(rcpA,&*invertibleA)
.
This interface supports the notion of the reuse of all factorizations or other expensive preprocessing used in the last initialization of the LinearOpWithSolveBase
object. The primary use for this is the reuse of a preconditioner for small changes in the matrix values. While this approach generally is not very effective in many cases, there are some cases, such as in transient solvers, where this has been shown to be effective in some problems.
The below example function shows what this looks like:
Note that the *invertibleA
object reinitialized in the second call to lowsFactory.initializeAndReuseOp(rcpA,&*invertibleA)
must be able to correctly solve the linear systems to an appropriate accuracy. For example, a preconditioned iterative linear solver might keep the same preconditioner but would use the updated forward operator to define the linear system. A direct solver can not reuse the factorization unless it has an iterative refinement feature (which uses the updated forward operator) or some other device. Or a direct solver might, for instance, reuse the same factorization structure and not repivot where it might repivot generally.
A major change in the shape or structure of a forward operator generally eliminates the possibility of reusing any computations between different calls to initializeOp()
. In these instances, the client might as well just recreate the LinearOpWithSolveBase
using createOp()
before the reinitialization.
The below example function shows what this looks like:
This interface also supports the use of externally defined preconditioners that are created and controlled by the client. Clientcreated and clientcontrolled preconditioners can be passed along with the forward operator through the function initializePreconditionedOp(). Only LinearOpWithSolveFactoryBase
objects that return supportsPreconditionerType()==true
will support externally defined preconditioners. In general, iterative linear solver implementations will support externally defined preconditioners and direct linear solver implementations will not.
Externally defined preconditioners can be passed in as operators or as matrices and these two sub use cases are described below.
The client can use externally defined preconditioner linear operator(s) for LinearOpWithSolveFactoryBase
objects that accept preconditioners. Preconditioner operator(s) are specified through the PreconditionerBase
interface. A PreconditionerBase
object is essentially an encapsulation of a left, right, or split left/right preconditioner.
Using an externally defined PreconditionerBase
object
Given an externally defined PreconditionerBase
object, the client can pass it allow with a forward linear operator to initialize a LinearOpWithSolveBase
object as shown in the following code fragment:
Using a single externally defined LinearOpBase
object as an unspecified preconditioner
A client can easily use any compatible appropriately defined LinearOpBase
object as a preconditioner operator. To do so, it can just be wrapped by the default PreconditionerBase
implementation class DefaultPreconditioner
.
The following code fragment shows show to use an externally defined LinearOpBase
object as a preconditioner operator without specifying whether it should be applied on the right or on the left.
Using a single externally defined LinearOpBase
object as a left preconditioner
An externally defined LinearOpBase
object can be used as a preconditioner operator targeted as a left preconditioner as shown in the following code fragment:
Using a single externally defined LinearOpBase
object as a right preconditioner
An externally defined LinearOpBase
object can be used as a preconditioner operator targeted as a right preconditioner as shown in the following code fragement:
Using two single externally defined LinearOpBase
objects as a split left/right preconditioner
Two externally defined LinearOpBase
objects can be used as preconditioner operators for form a split preconditioner targeted to the left and right as shown in the following code fragement:
A different linear operator can be used to build a preconditioner internally when initializing a LinearOpWithSolveBase
object. The following code fragement shows how to use an approximate forward linear from which to form a preconditioner internally:
Reusing an externally defined preconditioner is a very straightforward matter conceptually. Since the client controls the creation and initialization of the preconditioner, the client can control which preconditioners are paired with which forward operators in order to form LinearOpWithSolveBase
objects. However, when an abstract PreconditionerFactoryBase
object is used to create and maintain the preconditioner, the exact nature of the preconditioner after the operator is updated is undefined. The following code fragment show a use case where the operator is reused without explicitly updating the preconditioner between solves:
This interface does not guarantee the correct reuse of externally defined preconditioner matrices. The problem is that the internally generated preconditioner may be dependent on the input preconditioner matrix and it is not clear for the current interface design how to cleanly handle this use case. However, when the client knows that the internally generated preconditioner operator is independent from the externally defined preconditioner input matrix, then the function initializeAndReuseOp()
can be called to reuse the internal preconditioner but this is implementation defined.
TODO: Provide some guidance on how clients and subclasses should interpret Teuchos::EVerbLevel.
This interface assumes a minimal default set of functionality that is appropriate for direct and simple iterative linear solver implementations. The pure virtual functions that must be overridden by a subclass are isCompatible()
, createOp()
, initializeOp()
, and uninitializeOp()
. By far the most complex function to implement is initializeOp()
which is where the real guts of the factory method is defined.
If the concrete subclass can support some significant type of preprocessing reuse then it may override to function initializeAndReuseOp()
. The most common use of this function it to support the reuse of preconditioners between small changes in forward operator matrix values.
If the concrete subclass can utilize a preconditioner, then it should override the functions supportsPreconditionerInputType()
and initializePreconditionedOp()
. The subclass implementation can decide if preconditioner operators and/or matrices are supported or not and this is determined by the return value from supportsPreconditionerInputType()
.
Definition at line 404 of file Thyra_LinearOpWithSolveFactoryBase_decl.hpp.
bool Thyra::LinearOpWithSolveFactoryBase< Scalar >::acceptsPreconditionerFactory  (  )  const [virtual] 
Determines if *this
accepts external preconditioner factories.
The default implementation returns false
.
Reimplemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, and Thyra::DelayedLinearOpWithSolveFactory< Scalar >.
Definition at line 53 of file Thyra_LinearOpWithSolveFactoryBase_def.hpp.
void Thyra::LinearOpWithSolveFactoryBase< Scalar >::setPreconditionerFactory  (  const RCP< PreconditionerFactoryBase< Scalar > > &  precFactory, 
const std::string &  precFactoryName  
)  [virtual] 
Set a preconditioner factory object.
precFactory  [in] The preconditioner factory to be used internally to create preconditioners. 
precFactoryName  [in] The name to give to the preconditioner factory internally. This name is used when setting parameters in the parameter list. 
Preconditions:
this>acceptsPreconditionerFactory()==true
precFactory.get()!=NULL
Postconditions:
this>getPreconditionerFactory().get()==precFactory.get()
The default implementation thrown an exception which is consistent with the default implementation acceptsPreconditionerFactory()==false
.
Reimplemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, and Thyra::DelayedLinearOpWithSolveFactory< Scalar >.
Definition at line 60 of file Thyra_LinearOpWithSolveFactoryBase_def.hpp.
RCP< PreconditionerFactoryBase< Scalar > > Thyra::LinearOpWithSolveFactoryBase< Scalar >::getPreconditionerFactory  (  )  const [virtual] 
Get a preconditioner factory object.
The default implementation returns Teuchos::null
.
Reimplemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, and Thyra::DelayedLinearOpWithSolveFactory< Scalar >.
Definition at line 75 of file Thyra_LinearOpWithSolveFactoryBase_def.hpp.
void Thyra::LinearOpWithSolveFactoryBase< Scalar >::unsetPreconditionerFactory  (  RCP< PreconditionerFactoryBase< Scalar > > *  precFactory = NULL , 
std::string *  precFactoryName = NULL 

)  [virtual] 
Unset the preconditioner factory (if one is set).
Postconditions:
this>getPreconditionerFactory().get()==NULL
The default implementation returns Teuchos::null
.
Reimplemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, and Thyra::DelayedLinearOpWithSolveFactory< Scalar >.
Definition at line 82 of file Thyra_LinearOpWithSolveFactoryBase_def.hpp.
virtual bool Thyra::LinearOpWithSolveFactoryBase< Scalar >::isCompatible  (  const LinearOpSourceBase< Scalar > &  fwdOpSrc  )  const [pure virtual] 
Check that a LinearOpBase
object is compatible with *this
factory object.
Implemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, Thyra::DelayedLinearOpWithSolveFactory< Scalar >, and Thyra::DiagonalEpetraLinearOpWithSolveFactory.
virtual RCP<LinearOpWithSolveBase<Scalar> > Thyra::LinearOpWithSolveFactoryBase< Scalar >::createOp  (  )  const [pure virtual] 
Create an (uninitialized) LinearOpWithSolveBase
object to be initialized later in this>initializeOp()
.
Note that on output return>domain().get()==NULL
may be true which means that the operator is not fully initialized. In fact, the output operator object is not guaranteed to be fully initialized until after it is passed through this>initializeOp()
.
Implemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, Thyra::DelayedLinearOpWithSolveFactory< Scalar >, and Thyra::DiagonalEpetraLinearOpWithSolveFactory.
virtual void Thyra::LinearOpWithSolveFactoryBase< Scalar >::initializeOp  (  const RCP< const LinearOpSourceBase< Scalar > > &  fwdOpSrc, 
LinearOpWithSolveBase< Scalar > *  Op,  
const ESupportSolveUse  supportSolveUse = SUPPORT_SOLVE_UNSPECIFIED 

)  const [pure virtual] 
Initialize a precreated LinearOpWithSolveBase
object given a "compatible" LinearOpBase
object.
fwdOpSrc  [in] The forward linear operator that will be used to create the output LinearOpWithSolveBase object. Note that this object is remembered by the *Op object on output. 
Op  [in/out] The output LinearOpWithSolveBase object. This object must have be created first by this>createOp() . The object may have also already been passed through this function several times. Note that subclasses should always first strip off the transpose and scaling by calling unwrap() before attempting to dynamic cast the object. 
supportSolveUse  [in] Determines if Op>solve(...) or Op>solveTranspose(...) will be called. This allows *this factory object to determine how to best initialize the *Op object. Default supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED 
Preconditions:
fwdOpSrc.get()!=NULL
this>isCompatible(*fwdOpSrc)==true
Op!=NULL
*Op
must have been created by this>createOp()
prior to calling this function.
[supportSolveUse==SUPPORT_SOLVE_FORWARD_ONLY
]
this>solveSupportsConj(conj)==true
for any value of conj
[
supportSolveUse==SUPPORT_SOLVE_TRANSPOSE_ONLY
]
this>solveTransposeSupportsConj(conj)==true
for any value of conj
[
supportSolveUse==SUPPORT_SOLVE_FORWARD_AND_TRANSPOSE
]
this>solveSupportsConj(conj)==true && this>solveTransposeSupportsConj(conj)==true
for any value of conj
Postconditions:

Throws CatastrophicSolveFailure
if the underlying linear solver could not be created successfully (e.g. due to a factorization failure or some other cause).

Op>range()>isCompatible(*fwdOpSrc>range())==true

Op>domain()>isCompatible(*fwdOpSrc>domain())==true

Op>apply()
and Op>applyTranspose()
must behave exactly the same as fwdOpSrc>apply()
and fwdOpSrc>applyTranspose()

Op>solveSupportsConj(conj)==this>solveSupportsConj(conj)

Op>solveTransposeSupportsConj(conj)==this>solveTransposeSupportsConj(conj)

fwdOpSrc.count()
after output is greater than fwdOpSrc.count()
just before this call and therefore the client can assume that the *fwdOpSrc
object will be remembered by the *Op
object. The client must be careful not to modify the *fwdOpSrc
object or else the *Op
object may also be modified and become invalid.
Implemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, Thyra::DelayedLinearOpWithSolveFactory< Scalar >, and Thyra::DiagonalEpetraLinearOpWithSolveFactory.
void Thyra::LinearOpWithSolveFactoryBase< Scalar >::initializeAndReuseOp  (  const RCP< const LinearOpSourceBase< Scalar > > &  fwdOpSrc, 
LinearOpWithSolveBase< Scalar > *  Op  
)  const [virtual] 
Initialize a precreated LinearOpWithSolveBase
object given a "compatible" LinearOpBase
object but allow for reuse of any preprocessing that is in *Op
.
fwdOpSrc  [in] The forward linear operator that will be used to create the output LinearOpWithSolveBase object. 
Op  [in/out] The output LinearOpWithSolveBase object. This object must have be created first by this>createOp() and may have already been through at least one previous set of calls to this>initializeOp() and this>uninitializeOp() . Note that subclasses should always first strip off the transpose and scaling by calling unwrap() before attempting to dynamic cast the object. 
Preconditions:
fwdOpSrc.get()!=NULL
this>isCompatible(*fwdOpSrc)==true
Op!=NULL
*Op
must have been created by this>createOp()
prior to calling this function.
Postconditions:
Throws CatastrophicSolveFailure
if the underlying linear solver could not be created successfully (e.g. due to a factorization failure or some other cause).
Op>range()>isCompatible(*fwdOpSrc>range())==true
Op>domain()>isCompatible(*fwdOpSrc>domain())==true
Op>apply()
and Op>applyTranspose()
must behave exactly the same as fwdOpSrc>apply()
and fwdOpSrc>applyTranspose()
Op>solveSupportsConj(conj)==this>solveSupportsConj(conj)
Op>solveTransposeSupportsConj(conj)==this>solveTransposeSupportsConj(conj)
fwdOpSrc.count()
after output is greater than fwdOpSrc.count()
just before this call and therefore the client can assume that the *fwdOpSrc
object will be remembered by the *Op
object. The client must be careful not to modify the *fwdOpSrc
object or else the *Op
object may also be modified.
The purpose of this function is to allow the reuse of old factorizations and/or preconditioners that may go into the initialization of the *Op
objects. Note that by calling this function, the performance Op>solve(...)
may not be as good as when calling the function this>initializeOp(...,Op)
to initialize *Op
.
The default implementation of this function just calls this>initializeOp(fwdOpSrc,Op)
which does the default implementation.
Reimplemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, and Thyra::DelayedLinearOpWithSolveFactory< Scalar >.
Definition at line 93 of file Thyra_LinearOpWithSolveFactoryBase_def.hpp.
virtual void Thyra::LinearOpWithSolveFactoryBase< Scalar >::uninitializeOp  (  LinearOpWithSolveBase< Scalar > *  Op, 
RCP< const LinearOpSourceBase< Scalar > > *  fwdOpSrc = NULL , 

RCP< const PreconditionerBase< Scalar > > *  prec = NULL , 

RCP< const LinearOpSourceBase< Scalar > > *  approxFwdOpSrc = NULL , 

ESupportSolveUse *  supportSolveUse = NULL 

)  const [pure virtual] 
Uninitialize a LinearOpWithSolveBase
object and return its remembered forward linear operator and potentially also its externally generated preconditioner.
Op  [in/out] On input, *Op is an initialized or uninitialized object and on output is uninitialized. Note that "uninitialized" does not mean that Op is completely stateless. It may still remember some aspect of the matrix fwdOpSrc that will allow for a more efficient initialization next time through this>initializeOp() . 
fwdOpSrc  [in/out] If fwdOpSrc!=NULL on input, then on output this is set to the same forward operator passed into this>initializeOp() . 
prec  [in/out] If prep!=NULL on input, then on output, this this is set to same preconditioner that was passed into this>initializePreconditionedOp() . 
approxFwdOpSrc  [in/out] If approxFwdOpSrc!=NULL on input, then on output, this is set to same approximate forward operator that was passed into this>initializePreconditionedOp() . 
ESupportSolveUse  [in/out] If fwdOpSrc!=NULL on input, then on output this is set to same option value passed to this>initializeOp() . 
Preconditions:
*Op
must have been created by this>createOp()
prior to calling this function.
Op
may or may not have been passed through a call to this>initializeOp()
or this>initializePreconditionedOp()
.
Postconditions:
If *Op
on input was initialized through a call to this>initializeOp()
and if fwdOpSrc!=NULL
then (*fwdOpSrc).get()!=NULL
.
If *Op
was uninitialized on input and fwdOpSrc!=NULL
then fwdOpSrc>get()==NULL
out output.
On output, *Op
can be considered to be uninitialized and it is safe to modify the forward operator object *(*fwdOpSrc)
returned in fwdOpSrc
. The default is fwdOpSrc==NULL
in which case the forward operator will not be returned in *fwdOpSrc
.
This function should be called before the forward operator passed in to this>initializeOp()
is modified. Otherwise, *this
could be left in an inconsistent state. However, this is not required.
Implemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, Thyra::DelayedLinearOpWithSolveFactory< Scalar >, and Thyra::DiagonalEpetraLinearOpWithSolveFactory.
bool Thyra::LinearOpWithSolveFactoryBase< Scalar >::supportsPreconditionerInputType  (  const EPreconditionerInputType  precOpType  )  const [virtual] 
Determines if *this
supports given preconditioner type.
The default implementation returns false
.
Reimplemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, and Thyra::DelayedLinearOpWithSolveFactory< Scalar >.
Definition at line 103 of file Thyra_LinearOpWithSolveFactoryBase_def.hpp.
void Thyra::LinearOpWithSolveFactoryBase< Scalar >::initializePreconditionedOp  (  const RCP< const LinearOpSourceBase< Scalar > > &  fwdOpSrc, 
const RCP< const PreconditionerBase< Scalar > > &  prec,  
LinearOpWithSolveBase< Scalar > *  Op,  
const ESupportSolveUse  supportSolveUse = SUPPORT_SOLVE_UNSPECIFIED 

)  const [virtual] 
Initialize a precreated LinearOpWithSolveBase
object given a "compatible" LinearOpBase
object and an optional PreconditionerBase
object.
fwdOpSrc  [in] The forward linear operator that will be used to create the output LinearOpWithSolveBase object. 
prec  [in] The preconditioner that will be used to create the output LinearOpWithSolveBase object if preconditioners are supported. 
Op  [in/out] The output LinearOpWithSolveBase object. This object must have be created first by this>createOp() . The object may have also already been passed through this function several times. Note that subclasses should always first strip off the transpose and scaling by calling unwrap() before attempting to dynamic cast the object. 
supportSolveUse  [in] Determines if Op>solve(...) or Op>solveTranspose(...) will be called. This allows *this factory object determine how to best initialize the *Op object. Default supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED 
Preconditions:
fwdOpSrc.get()!=NULL
prec.get()!=NULL
this>isCompatible(*fwdOpSrc)==true
Op!=NULL
*Op
must have been created by this>createOp()
prior to calling this function.
It is allowed for an implementation to throw an exception if this>supportsPreconditionerInputType(PRECONDITIONER_INPUT_TYPE_AS_OPERATOR)==false
but this is not required.
[supportSolveUse==SUPPORT_SOLVE_FORWARD_ONLY
]
this>solveSupportsConj(conj)==true
for any value of conj
[
supportSolveUse==SUPPORT_SOLVE_TRANSPOSE_ONLY
]
this>solveTransposeSupportsConj(conj)==true
for any value of conj
[
supportSolveUse==SUPPORT_SOLVE_FORWARD_AND_TRANSPOSE
]
this>solveSupportsConj(conj)==true && this>solveTransposeSupportsConj(conj)==true
for any value of conj
Postconditions:

Throws CatastrophicSolveFailure
if the underlying linear solver could not be created successfully (e.g. due to a factorization failure or some other cause).

Op>range()>isCompatible(*fwdOpSrc>range())==true

Op>domain()>isCompatible(*fwdOpSrc>domain())==true

Op>apply()
and Op>applyTranspose()
must behave exactly the same as fwdOpSrc>apply()
and fwdOpSrc>applyTranspose()

<t>Op>solveSupportsConj(conj)==this>solveSupportsConj(conj)

<t>Op>solveTransposeSupportsConj(conj)==this>solveTransposeSupportsConj(conj)

fwdOpSrc.count()
after output is greater than fwdOpSrc.count()
just before this call and therefore the client can assume that the *fwdOpSrc
object will be remembered by the *Op
object. The client must be careful not to modify the *fwdOpSrc
object or else the *Op
object may also be modified.

If this>supportsPreconditionerInputType(PRECONDITIONER_INPUT_TYPE_AS_OPERATOR)==true
then

prec.count()
after output is greater than prec.count()
just before this call and therefore the client can assume that the *prec
object will be remembered by the *Op
object. The client must be careful not to modify the *prec
object or else the *Op
object may also be modified.

else if an exception is not thrown then

prec.count()
after output is equal to prec.count()
just before this call and therefore the *prec
is ignored and is not remembered.
Warning! It is allowed for an implementation to throw an exception if this>supportsPreconditionerInputType(PRECONDITIONER_INPUT_TYPE_AS_OPERATOR)==false
so therefore a client should not call this function if preconditioners are not supported! The mode of silently ignoring preconditioners is acceptable in some cases and is therefore allowed behavior.
The default implementation throws an exception which is consistent with the default implementation of this>supportsPreconditionerInputType()
which assumes by default that preconditioners can not be supported..
Reimplemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, and Thyra::DelayedLinearOpWithSolveFactory< Scalar >.
Definition at line 112 of file Thyra_LinearOpWithSolveFactoryBase_def.hpp.
void Thyra::LinearOpWithSolveFactoryBase< Scalar >::initializeApproxPreconditionedOp  (  const RCP< const LinearOpSourceBase< Scalar > > &  fwdOpSrc, 
const RCP< const LinearOpSourceBase< Scalar > > &  approxFwdOpSrc,  
LinearOpWithSolveBase< Scalar > *  Op,  
const ESupportSolveUse  supportSolveUse = SUPPORT_SOLVE_UNSPECIFIED 

)  const [virtual] 
Initialize a precreated LinearOpWithSolveBase
object given a "compatible" forward LinearOpBase
object and an approximate forward LinearOpBase
object.
fwdOpSrc  [in] The forward linear operator that will be used to create the output LinearOpWithSolveBase object. 
approxFwdOpSrc  [in] Approximation to fwdOpSrc from which a preconditioner will be created for. 
Op  [in/out] The output LinearOpWithSolveBase object. This object must have be created first by this>createOp() . The object may have also already been passed through this function several times. Note that subclasses should always first strip off the transpose and scaling by calling unwrap() before attempting to dynamic cast the object. 
supportSolveUse  [in] Determines if Op>solve(...) or Op>solveTranspose(...) will be called. This allows *this factory object determine how to best initialize the *Op object. Default supportSolveUse=SUPPORT_SOLVE_UNSPECIFIED 
ToDo: finish documentation!
Reimplemented in Thyra::DefaultBlockedTriangularLinearOpWithSolveFactory< Scalar >, Thyra::DefaultSerialDenseLinearOpWithSolveFactory< Scalar >, and Thyra::DelayedLinearOpWithSolveFactory< Scalar >.
Definition at line 128 of file Thyra_LinearOpWithSolveFactoryBase_def.hpp.
bool isCompatible  (  const LinearOpWithSolveFactoryBase< Scalar > &  lowsFactory, 
const LinearOpBase< Scalar > &  fwdOp  
)  [related] 
Return if the forward operator is a compatible source for a LOWSFB object.
Definition at line 60 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.
void setDefaultObjectLabel  (  const LinearOpBase< Scalar > &  fwdOp, 
const Ptr< LinearOpWithSolveBase< Scalar > > &  Op  
)  [related] 
Set default label on a LOWSB object.
Definition at line 74 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.
void initializeOp  (  const LinearOpWithSolveFactoryBase< Scalar > &  lowsFactory, 
const RCP< const LinearOpBase< Scalar > > &  fwdOp,  
const Ptr< LinearOpWithSolveBase< Scalar > > &  Op,  
const ESupportSolveUse  supportSolveUse = SUPPORT_SOLVE_UNSPECIFIED 

)  [related] 
Initialize a precreated LOWSB object given a forward operator.
Definition at line 91 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.
void initializeAndReuseOp  (  const LinearOpWithSolveFactoryBase< Scalar > &  lowsFactory, 
const RCP< const LinearOpBase< Scalar > > &  fwdOp,  
const Ptr< LinearOpWithSolveBase< Scalar > > &  Op  
)  [related] 
Reinitialize a precreated LOWSB object given a forward operator, reusing a much as possible from the prior LOWSB object.
Definition at line 109 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.
void initializePreconditionedOp  (  const LinearOpWithSolveFactoryBase< Scalar > &  lowsFactory, 
const RCP< const LinearOpBase< Scalar > > &  fwdOp,  
const RCP< const PreconditionerBase< Scalar > > &  prec,  
const Ptr< LinearOpWithSolveBase< Scalar > > &  Op,  
const ESupportSolveUse  supportSolveUse = SUPPORT_SOLVE_UNSPECIFIED 

)  [related] 
Initialize a preconditioned LOWSB object given an external preconditioner.
Definition at line 126 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.
void initializeApproxPreconditionedOp  (  const LinearOpWithSolveFactoryBase< Scalar > &  lowsFactory, 
const RCP< const LinearOpBase< Scalar > > &  fwdOp,  
const RCP< const LinearOpBase< Scalar > > &  approxFwdOp,  
const Ptr< LinearOpWithSolveBase< Scalar > > &  Op,  
const ESupportSolveUse  supportSolveUse = SUPPORT_SOLVE_UNSPECIFIED 

)  [related] 
Initialize a preconditioned LOWSB object given an external operator to be used to generate the preconditioner internally.
Definition at line 146 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.
RCP< LinearOpWithSolveBase< Scalar > > linearOpWithSolve  (  const LinearOpWithSolveFactoryBase< Scalar > &  lowsFactory, 
const RCP< const LinearOpBase< Scalar > > &  fwdOp,  
const ESupportSolveUse  supportSolveUse = SUPPORT_SOLVE_UNSPECIFIED 

)  [related] 
Create and initialize a LinearOpWithSolveBase
object from a LinearOpBase
object using a LinearOpWithSolveFactoryBase
strategy object.
Definition at line 166 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.
RCP< LinearOpBase< Scalar > > inverse  (  const LinearOpWithSolveFactoryBase< Scalar > &  LOWSF, 
const RCP< const LinearOpBase< Scalar > > &  fwdOp,  
const ESupportSolveUse  supportSolveUse = SUPPORT_SOLVE_UNSPECIFIED , 

const Ptr< const SolveCriteria< Scalar > > &  fwdSolveCriteria = Teuchos::null , 

const EThrowOnSolveFailure  throwOnFwdSolveFailure = THROW_ON_SOLVE_FAILURE , 

const Ptr< const SolveCriteria< Scalar > > &  adjSolveCriteria = Teuchos::null , 

const EThrowOnSolveFailure  throwOnAdjSolveFailure = THROW_ON_SOLVE_FAILURE 

)  [related] 
Form a const implicit inverse operator M = inv(A)
given a factory.
Definition at line 185 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.
void uninitializeOp  (  const LinearOpWithSolveFactoryBase< Scalar > &  lowsFactory, 
const Ptr< LinearOpWithSolveBase< Scalar > > &  Op,  
const Ptr< RCP< const LinearOpBase< Scalar > > > &  fwdOp = Teuchos::null , 

const Ptr< RCP< const PreconditionerBase< Scalar > > > &  prec = Teuchos::null , 

const Ptr< RCP< const LinearOpBase< Scalar > > > &  approxFwdOp = Teuchos::null , 

const Ptr< ESupportSolveUse > &  supportSolveUse = Teuchos::null 

)  [related] 
Uninitialized a precreated LOWSB object, returning input objects used to initialize it.
Definition at line 206 of file Thyra_LinearOpWithSolveFactoryHelpers.hpp.