Thyra::SpmdMultiVectorBase< Scalar > Class Template Reference
[Thyra Operator/Vector Base Support Subclasses for SPMD Thyra Implementations]

Base class for SPMD multi-vectors. More...

#include <Thyra_SpmdMultiVectorBaseDecl.hpp>

Inheritance diagram for Thyra::SpmdMultiVectorBase< Scalar >:

[legend]
List of all members.

Constructors / initializers / accessors

 SpmdMultiVectorBase ()
 

Pure virtual functions to be overridden by subclasses

virtual Teuchos::RCP< const
SpmdVectorSpaceBase< Scalar > > 
spmdSpace () const =0
 Returns the SPMD vector space object for the range of *this multi-vector.
virtual void getLocalData (Scalar **localValues, Index *leadingDim)=0
 Returns a non-const pointer to a Fortran-style view of the local multi-vector data.
virtual void commitLocalData (Scalar *localValues)=0
 Commit view of local data that was gotten from getLocalData().
virtual void getLocalData (const Scalar **localValues, Index *leadingDim) const =0
 Returns a const pointer to a Fortran-style view of the local multi-vector data.
virtual void freeLocalData (const Scalar *localValues) const =0
 Free view of local data that was gotten from getLocalData().

Overridden from EuclideanLinearOpBase

Teuchos::RCP< const ScalarProdVectorSpaceBase<
Scalar > > 
rangeScalarProdVecSpc () const
 Returns spmdSpace.

Overridden from LinearOpBase

void apply (const ETransp M_trans, const MultiVectorBase< Scalar > &X, MultiVectorBase< Scalar > *Y, const Scalar alpha, const Scalar beta) const
 Calls EuclideanLinearOpBase::apply() to disambiguate apply().

Overridden from MultiVectorBase

void mvMultiReductApplyOpImpl (const RTOpPack::RTOpT< Scalar > &primary_op, const int num_multi_vecs, const MultiVectorBase< Scalar > *const multi_vecs[], const int num_targ_multi_vecs, MultiVectorBase< Scalar > *const targ_multi_vecs[], RTOpPack::ReductTarget *const reduct_objs[], const Index primary_first_ele, const Index primary_sub_dim, const Index primary_global_offset, const Index secondary_first_ele, const Index secondary_sub_dim) const
 
void acquireDetachedMultiVectorViewImpl (const Range1D &rowRng, const Range1D &colRng, RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const
 
void releaseDetachedMultiVectorViewImpl (RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const
 
void acquireNonconstDetachedMultiVectorViewImpl (const Range1D &rowRng, const Range1D &colRng, RTOpPack::SubMultiVectorView< Scalar > *sub_mv)
 
void commitNonconstDetachedMultiVectorViewImpl (RTOpPack::SubMultiVectorView< Scalar > *sub_mv)
 

Overridden from SingleScalarEuclideanLinearOpBase

bool opSupported (ETransp M_trans) const
 For complex Scalar types returns true for NOTRANS, TRANS, and CONJTRANS and for real types returns true for all values of M_trans.
void euclideanApply (const ETransp M_trans, const MultiVectorBase< Scalar > &X, MultiVectorBase< Scalar > *Y, const Scalar alpha, const Scalar beta) const
 Uses GEMM() and Teuchos::reduceAll() to implement.

Protected functions for subclasses to call.

virtual void updateSpmdSpace ()
 Subclasses should call whenever the structure of the VectorSpaceBase changes.
Range1D validateRowRange (const Range1D &rowRng) const
 Validate and resize the row range.
Range1D validateColRange (const Range1D &rowCol) const
 Validate and resize the column range.

Detailed Description

template<class Scalar>
class Thyra::SpmdMultiVectorBase< Scalar >

Base class for SPMD multi-vectors.

By inheriting from this base class, multi-vector implementations allow their multi-vector objects to be seamlessly combined with other SPMD multi-vector objects (of different concrete types) in applyOp() and apply(). A big part of this protocol is that every multi-vector object can expose an SpmdVectorSpaceBase object through the virtual function spmdSpace().

This base class contains an implementation of applyOp() that relies on implementations of the const functions acquireDetachedView() and releaseDetachedView(), and the non-const functions acquireDetachedView() and commitDetachedView() (which all have default implementations in this subclass). In essence, this implementation will only call the acquireDetachedView() functions using a range of (global) indexes for elements that exist in the local process. As long as the number of local elements in each process is fairly large, the virtual function call overhead will be minimal and this will result in a near optimal implementation.

Notes to subclass developers

Concrete subclasses must override only five functions: spmdSpace(), getLocalData(const Scalar**,Index*), freeLocalData(const Scalar**,Index*), getLocalData(Scalar**,Index*), and commitLocalData(Scalar**,Index*). Note that overriding the spmdSpace() function requires implementing or using a pre-implemented concrete SpmdVectorSpaceBase subclass.

If the acquireDetachedView() functions are ever called with index ranges outside of those of the local process, then the default implementations in MultiVectorBase of all of the functions (const) MultiVectorBase::acquireDetachedView(), MultiVectorBase::releaseDetachedView(), (non-const) MultiVectorBase::acquireDetachedView() and MultiVectorBase::commitDetachedView() are called in instead. Alternatively, a subclass could provide more specialized implementations of these functions (for more efficient gather/scatter operations) if desired but this should not be needed for most use cases.

It is interesting to note that in the above use case that the explicit subvector access functions call on its default implementation defined in MultiVectorBase (which calls on applyOp()) and the operator will be properly applied since the version of applyOp() implemented in this class will only request local vector data and hence there will only be two levels of recursion for any call to an explicit subvector access function. This is a truly elegant result.

Note that a multi-vector subclass derived from this base class must only be directly used in SPMD mode for this to work properly.

Definition at line 98 of file Thyra_SpmdMultiVectorBaseDecl.hpp.


Constructor & Destructor Documentation

template<class Scalar>
Thyra::SpmdMultiVectorBase< Scalar >::SpmdMultiVectorBase (  ) 

Definition at line 54 of file Thyra_SpmdMultiVectorBase.hpp.


Member Function Documentation

template<class Scalar>
virtual Teuchos::RCP<const SpmdVectorSpaceBase<Scalar> > Thyra::SpmdMultiVectorBase< Scalar >::spmdSpace (  )  const [pure virtual]

Returns the SPMD vector space object for the range of *this multi-vector.

Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

template<class Scalar>
virtual void Thyra::SpmdMultiVectorBase< Scalar >::getLocalData ( Scalar **  localValues,
Index leadingDim 
) [pure virtual]

Returns a non-const pointer to a Fortran-style view of the local multi-vector data.

Parameters:
localValues [out] On output *localValues will point to the first element in the first column of the local multi-vector stored as a column-major dense Fortran-style matrix.
leadingDim [out] On output *leadingDim gives the leading dimension of the Fortran-style local multi-vector.
Preconditions:

Preconditions:

The function commitLocalData() must be called to commit changes to the data.

Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

template<class Scalar>
virtual void Thyra::SpmdMultiVectorBase< Scalar >::commitLocalData ( Scalar *  localValues  )  [pure virtual]

Commit view of local data that was gotten from getLocalData().

Parameters:
localValues [in/out] On input localValues must be the pointer set by getLocalData().
Preconditions:

Preconditions:

Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

template<class Scalar>
virtual void Thyra::SpmdMultiVectorBase< Scalar >::getLocalData ( const Scalar **  localValues,
Index leadingDim 
) const [pure virtual]

Returns a const pointer to a Fortran-style view of the local multi-vector data.

Parameters:
localValues [out] On output *localValues will point to the first element in the first column of the local multi-vector stored as a column-major dense Fortran-style matrix.
leadingDim [out] On output *leadingDim gives the leading dimension of the Fortran-style local multi-vector.
Preconditions:

Preconditions:

Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

template<class Scalar>
virtual void Thyra::SpmdMultiVectorBase< Scalar >::freeLocalData ( const Scalar *  localValues  )  const [pure virtual]

Free view of local data that was gotten from getLocalData().

Parameters:
localValues [in/out] On input localValues must be the pointer set by getLocalData().
Preconditions:

Preconditions:

Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

template<class Scalar>
Teuchos::RCP< const ScalarProdVectorSpaceBase< Scalar > > Thyra::SpmdMultiVectorBase< Scalar >::rangeScalarProdVecSpc (  )  const [virtual]

Returns spmdSpace.

Implements Thyra::EuclideanLinearOpBase< Scalar >.

Definition at line 70 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::apply ( const ETransp  M_trans,
const MultiVectorBase< Scalar > &  X,
MultiVectorBase< Scalar > *  Y,
const Scalar  alpha,
const Scalar  beta 
) const

Calls EuclideanLinearOpBase::apply() to disambiguate apply().

Definition at line 82 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::mvMultiReductApplyOpImpl ( const RTOpPack::RTOpT< Scalar > &  primary_op,
const int  num_multi_vecs,
const MultiVectorBase< Scalar > *const   multi_vecs[],
const int  num_targ_multi_vecs,
MultiVectorBase< Scalar > *const   targ_multi_vecs[],
RTOpPack::ReductTarget *const   reduct_objs[],
const Index  primary_first_ele,
const Index  primary_sub_dim,
const Index  primary_global_offset,
const Index  secondary_first_ele,
const Index  secondary_sub_dim 
) const [virtual]

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 98 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::acquireDetachedMultiVectorViewImpl ( const Range1D rowRng,
const Range1D colRng,
RTOpPack::ConstSubMultiVectorView< Scalar > *  sub_mv 
) const [virtual]

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 196 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::releaseDetachedMultiVectorViewImpl ( RTOpPack::ConstSubMultiVectorView< Scalar > *  sub_mv  )  const [virtual]

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 241 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::acquireNonconstDetachedMultiVectorViewImpl ( const Range1D rowRng,
const Range1D colRng,
RTOpPack::SubMultiVectorView< Scalar > *  sub_mv 
) [virtual]

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 268 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::commitNonconstDetachedMultiVectorViewImpl ( RTOpPack::SubMultiVectorView< Scalar > *  sub_mv  )  [virtual]

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 314 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
bool Thyra::SpmdMultiVectorBase< Scalar >::opSupported ( ETransp  M_trans  )  const [protected, virtual]

For complex Scalar types returns true for NOTRANS, TRANS, and CONJTRANS and for real types returns true for all values of M_trans.

Implements Thyra::SingleScalarEuclideanLinearOpBase< Scalar >.

Definition at line 615 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::euclideanApply ( const ETransp  M_trans,
const MultiVectorBase< Scalar > &  X,
MultiVectorBase< Scalar > *  Y,
const Scalar  alpha,
const Scalar  beta 
) const [protected, virtual]

Uses GEMM() and Teuchos::reduceAll() to implement.

ToDo: Finish documentation!

Implements Thyra::SingleScalarEuclideanLinearOpBase< Scalar >.

Definition at line 344 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::updateSpmdSpace (  )  [protected, virtual]

Subclasses should call whenever the structure of the VectorSpaceBase changes.

WARNING! This function can be overridden by subclasses but this particular function implementation must be called back from within any override (i.e. call SpmdMultiVectorBase<Scalar>::updateSpmdSpace();).

Definition at line 622 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
Range1D Thyra::SpmdMultiVectorBase< Scalar >::validateRowRange ( const Range1D rowRng  )  const [protected]

Validate and resize the row range.

This function throws an exception if the input range is invalid

Definition at line 643 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar>
Range1D Thyra::SpmdMultiVectorBase< Scalar >::validateColRange ( const Range1D rowCol  )  const [protected]

Validate and resize the column range.

This function throws an exception if the input range is invalid

Definition at line 659 of file Thyra_SpmdMultiVectorBase.hpp.


The documentation for this class was generated from the following files:
Generated on Tue Oct 20 12:47:01 2009 for Thyra Operator/Vector Support by doxygen 1.4.7