Thyra Version of the Day
Thyra::SpmdMultiVectorBase< Scalar > Class Template Reference

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

#include <Thyra_SpmdMultiVectorBase_decl.hpp>

Inheritance diagram for Thyra::SpmdMultiVectorBase< Scalar >:
Inheritance graph
[legend]

List of all members.

Constructors / initializers / accessors

 SpmdMultiVectorBase ()
 

Pure virtual functions to be overridden by subclasses

virtual RCP< const
SpmdVectorSpaceBase< Scalar > > 
spmdSpace () const =0
 Returns the SPMD vector space object for the range of *this multi-vector.
void getNonconstLocalData (const Ptr< ArrayRCP< Scalar > > &localValues, const Ptr< Ordinal > &leadingDim)
 Returns a non-const pointer to a Fortran-style view of the local multi-vector data.
void getLocalData (const Ptr< ArrayRCP< const Scalar > > &localValues, const Ptr< Ordinal > &leadingDim) const
 Returns a const pointer to a Fortran-style view of the local multi-vector data.

Overridden public functions from MultiVectorAdapterBase

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

Virtual functions to be overridden by sublcasses.

virtual void getNonconstLocalDataImpl (const Ptr< ArrayRCP< Scalar > > &localValues, const Ptr< Ordinal > &leadingDim)=0
 Virtual implementation for getNonconstLocalData().
virtual void getLocalDataImpl (const Ptr< ArrayRCP< const Scalar > > &localValues, const Ptr< Ordinal > &leadingDim) const =0
 Virtual implementation for getLocalData().

Protected functions overridden from MultiVectorBase

void mvMultiReductApplyOpImpl (const RTOpPack::RTOpT< Scalar > &primary_op, const ArrayView< const Ptr< const MultiVectorBase< Scalar > > > &multi_vecs, const ArrayView< const Ptr< MultiVectorBase< Scalar > > > &targ_multi_vecs, const ArrayView< const Ptr< RTOpPack::ReductTarget > > &reduct_objs, const Ordinal primary_global_offset) 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)
 

Protected functions overridden from MultiVectorAdapterBase

void euclideanApply (const EOpTransp M_trans, const MultiVectorBase< Scalar > &X, const Ptr< 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**,Ordinal*), freeLocalData(const Scalar**,Ordinal*), getLocalData(Scalar**,Ordinal*), and commitLocalData(Scalar**,Ordinal*). 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 113 of file Thyra_SpmdMultiVectorBase_decl.hpp.


Constructor & Destructor Documentation

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

Definition at line 68 of file Thyra_SpmdMultiVectorBase_def.hpp.


Member Function Documentation

template<class Scalar>
virtual 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 >, and Thyra::TpetraMultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::getNonconstLocalData ( const Ptr< ArrayRCP< Scalar > > &  localValues,
const Ptr< Ordinal > &  leadingDim 
) [inline]

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:

  • localValues!=NULL
  • leadingDim!=NULL

Preconditions:

  • *localValues!=NULL
  • *leadingDim!=0

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

Definition at line 157 of file Thyra_SpmdMultiVectorBase_decl.hpp.

template<class Scalar>
void Thyra::SpmdMultiVectorBase< Scalar >::getLocalData ( const Ptr< ArrayRCP< const Scalar > > &  localValues,
const Ptr< Ordinal > &  leadingDim 
) const [inline]

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:

  • localValues!=NULL
  • leadingDim!=NULL

Preconditions:

  • *localValues!=NULL
  • *leadingDim!=0

Definition at line 184 of file Thyra_SpmdMultiVectorBase_decl.hpp.

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

Returns spmdSpace.

Implements Thyra::MultiVectorAdapterBase< Scalar >.

Definition at line 82 of file Thyra_SpmdMultiVectorBase_def.hpp.

template<class Scalar>
virtual void Thyra::SpmdMultiVectorBase< Scalar >::getNonconstLocalDataImpl ( const Ptr< ArrayRCP< Scalar > > &  localValues,
const Ptr< Ordinal > &  leadingDim 
) [protected, pure virtual]
template<class Scalar>
virtual void Thyra::SpmdMultiVectorBase< Scalar >::getLocalDataImpl ( const Ptr< ArrayRCP< const Scalar > > &  localValues,
const Ptr< Ordinal > &  leadingDim 
) const [protected, pure virtual]
template<class Scalar >
void Thyra::SpmdMultiVectorBase< Scalar >::mvMultiReductApplyOpImpl ( const RTOpPack::RTOpT< Scalar > &  primary_op,
const ArrayView< const Ptr< const MultiVectorBase< Scalar > > > &  multi_vecs,
const ArrayView< const Ptr< MultiVectorBase< Scalar > > > &  targ_multi_vecs,
const ArrayView< const Ptr< RTOpPack::ReductTarget > > &  reduct_objs,
const Ordinal  primary_global_offset 
) const [protected, virtual]

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 94 of file Thyra_SpmdMultiVectorBase_def.hpp.

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

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 182 of file Thyra_SpmdMultiVectorBase_def.hpp.

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

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 215 of file Thyra_SpmdMultiVectorBase_def.hpp.

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

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 234 of file Thyra_SpmdMultiVectorBase_def.hpp.

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

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >.

Definition at line 272 of file Thyra_SpmdMultiVectorBase_def.hpp.

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

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

ToDo: Finish documentation!

Implements Thyra::MultiVectorAdapterBase< Scalar >.

Definition at line 294 of file Thyra_SpmdMultiVectorBase_def.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 572 of file Thyra_SpmdMultiVectorBase_def.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 593 of file Thyra_SpmdMultiVectorBase_def.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 609 of file Thyra_SpmdMultiVectorBase_def.hpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines