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

Base class for SPMD vectors that can provide views of contiguous elements in a process.. More...

#include <Thyra_SpmdVectorBaseDecl.hpp>

Inheritance diagram for Thyra::SpmdVectorBase< Scalar >:

[legend]
List of all members.

Pure virtual functions to be overridden by subclasses

virtual Teuchos::RefCountPtr<
const SpmdVectorSpaceBase<
Scalar > > 
spmdSpace () const =0
 Returns the Spmd-based vector space object for *this vector.
virtual void getLocalData (Scalar **localValues, Index *stride)=0
 Returns a non-const pointer to the beginning of the local vector data (and its stride).
virtual void commitLocalData (Scalar *localValues)=0
 Commits updated local vector data that was accessed using this->getLocalData().

Virtual functions with default implementations.

virtual void getLocalData (const Scalar **localValues, Index *stride) const
 Returns a const pointer to the beginning of the local vector data.
virtual void freeLocalData (const Scalar *localValues) const
 Frees a const view of local vector data that was accessed using this->getLocalData().
void applyOp (const Teuchos::Comm< Index > *comm, const RTOpPack::RTOpT< Scalar > &op, const int num_vecs, const VectorBase< Scalar > *const vecs[], const int num_targ_vecs, VectorBase< Scalar > *const targ_vecs[], RTOpPack::ReductTarget *reduct_obj, const Index first_ele_offset, const Index sub_dim, const Index global_offset) const
 Implements the applyOp() function through the functions acquireDetachedView(), releaseDetachedView() and commitDetachedView() as described above.

Overridden from MultiVectorBase

Teuchos::RefCountPtr< const
VectorSpaceBase< Scalar > > 
space () const
 Returns this->spmdSpace().
void applyOp (const RTOpPack::RTOpT< Scalar > &op, const int num_vecs, const VectorBase< Scalar > *const vecs[], const int num_targ_vecs, VectorBase< Scalar > *const targ_vecs[], RTOpPack::ReductTarget *reduct_obj, const Index first_ele_offset, const Index sub_dim, const Index global_offset) const
 Calls this->applyOp(NULL,op,...).
void acquireDetachedView (const Range1D &rng, RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const
 Implemented through this->getLocalData().
void releaseDetachedView (RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const
 Implemented through this->freeLocalData().
void acquireDetachedView (const Range1D &rng, RTOpPack::SubVectorView< Scalar > *sub_vec)
 Implemented through this->getLocalData().
void commitDetachedView (RTOpPack::SubVectorView< Scalar > *sub_vec)
 Implemented through this->commitLocalData().

Public Member Functions

 SpmdVectorBase ()
 

Protected Member Functions

virtual void updateSpmdSpace ()
 Subclasses must call this function whenever the structure of the VectorSpaceBase changes.

Private Member Functions

Range1D validateRange (const Range1D &rng_in) const

Private Attributes

bool in_applyOp_
Index globalDim_
Index localOffset_
Index localSubDim_

Detailed Description

template<class Scalar>
class Thyra::SpmdVectorBase< Scalar >

Base class for SPMD vectors that can provide views of contiguous elements in a process..

By inheriting from this base class, vector implementations allow their vector objects to be seamlessly combined with other SPMD vector objects (of potentially different concrete types) in applyOp(). A big part of this protocol is that every 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 two functions: spmdSpace() and getLocalData(Scalar**,Index*). The default implementation of getLocalData(cons Scalar**,Index*) should rarely need to be overridden as it just calls the pure-virtual non-const version. Note that providing an implementation for spmdSpace() of course means having to implement or use a pre-implemented SpmdVectorSpaceBase subclass.

Vector subclasses must also call the protected function updateSpmdState() whenever the state of *this->spmdSpace() vector space changes. This function gathers some cached data that makes the rest of the class more efficient. This function must be called in a constructor or any other function that changes the state of the vector space.

If the acquireDetachedView() functions are ever called with index ranges outside of those of the local process, then the default implementations in VectorBase of all of the functions acquireDetachedView(), releaseDetachedView(), and commitDetachedView() are called 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 when the explicit subvector access functions call on its default implementation defined in VectorBase (which calls on applyOp()), 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 vector subclasses derived from this node interface class must only be directly used in SPMD mode to work properly.

Definition at line 101 of file Thyra_SpmdVectorBaseDecl.hpp.


Constructor & Destructor Documentation

template<class Scalar>
Thyra::SpmdVectorBase< Scalar >::SpmdVectorBase  ) 
 

Definition at line 49 of file Thyra_SpmdVectorBase.hpp.


Member Function Documentation

template<class Scalar>
virtual Teuchos::RefCountPtr<const SpmdVectorSpaceBase<Scalar> > Thyra::SpmdVectorBase< Scalar >::spmdSpace  )  const [pure virtual]
 

Returns the Spmd-based vector space object for *this vector.

Implemented in Thyra::DefaultSpmdVector< Scalar >.

template<class Scalar>
virtual void Thyra::SpmdVectorBase< Scalar >::getLocalData Scalar **  localValues,
Index stride
[pure virtual]
 

Returns a non-const pointer to the beginning of the local vector data (and its stride).

Parameters:
localValues [out] On output *localValues will point to an array of the local values.
stride [out] On output *stride will be the stride between elements in (*localValues)[]
Preconditions:
  • localValues!=NULL
  • stride!=NULL

Postconditions:

  • *localValues!=NULL
  • *stride!=0

Note, the data view returned from this function must be committed back by a call to this->commitLocalData() in case dynamic memory allocation had to be used and therefore the pointer return does not point to internal storage.

Implemented in Thyra::DefaultSpmdVector< Scalar >.

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

Commits updated local vector data that was accessed using this->getLocalData().

Parameters:
localValues [in/out] On input localValues must have been set by a previous call to this->getData().
Preconditions:
  • localValues!=NULL

Preconditions:

  • *this will be updated to the entries in *localValues.

Implemented in Thyra::DefaultSpmdVector< Scalar >.

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::getLocalData const Scalar **  localValues,
Index stride
const [virtual]
 

Returns a const pointer to the beginning of the local vector data.

Parameters:
localValues [out] On output *localValues will point to an array of the local values.
stride [out] On output *stride will be the stride between elements in (*localValues)[]
Preconditions:
  • localValues!=NULL
  • stride!=NULL

Postconditions:

  • *localValues!=NULL
  • *stride!=0

Note, the data view returned from this function must be freed by a call to this->freeLocalData() in case dynamic memory allocation had to be used and therefore the pointer returned does not point to internal storage.

The default implementation performs a const_cast of this and then calls the non-const version of this function. An override of this function should only be provided if dynamic memory allocation is used and data copies have to be performed. If this function is overridden then the function freeLocalData() must be overridden as well!

Reimplemented in Thyra::DefaultSpmdVector< Scalar >.

Definition at line 59 of file Thyra_SpmdVectorBase.hpp.

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

Frees a const view of local vector data that was accessed using this->getLocalData().

Parameters:
localValues [in/out] On input localValues must have been set by a previous call to this->getLocalData().
Preconditions:
  • localValues!=NULL

The default implementation performs a const_cast of this and then calls the non-const function this->commitLocalData(). If the const version of the getData() function is overridden then this function must be overridden also.

Reimplemented in Thyra::DefaultSpmdVector< Scalar >.

Definition at line 65 of file Thyra_SpmdVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::applyOp const Teuchos::Comm< Index > *  comm,
const RTOpPack::RTOpT< Scalar > &  op,
const int  num_vecs,
const VectorBase< Scalar > *const   vecs[],
const int  num_targ_vecs,
VectorBase< Scalar > *const   targ_vecs[],
RTOpPack::ReductTarget reduct_obj,
const Index  first_ele_offset,
const Index  sub_dim,
const Index  global_offset
const
 

Implements the applyOp() function through the functions acquireDetachedView(), releaseDetachedView() and commitDetachedView() as described above.

Parameters:
comm [in] The Spmd communicator to use in the global reduction. If comm==NULL, then the local communicator will be used instead.
Note that if this function is entered again before a call has been completed, then this is an indication that the functions acquireDetachedView(), releaseDetachedView() and/or commitDetachedView() have not been overridden properly and this function will then throw an exception.

Definition at line 71 of file Thyra_SpmdVectorBase.hpp.

template<class Scalar>
Teuchos::RefCountPtr< const VectorSpaceBase< Scalar > > Thyra::SpmdVectorBase< Scalar >::space  )  const [virtual]
 

Returns this->spmdSpace().

Implements Thyra::VectorBase< Scalar >.

Definition at line 204 of file Thyra_SpmdVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::applyOp const RTOpPack::RTOpT< Scalar > &  op,
const int  num_vecs,
const VectorBase< Scalar > *const   vecs[],
const int  num_targ_vecs,
VectorBase< Scalar > *const   targ_vecs[],
RTOpPack::ReductTarget reduct_obj,
const Index  first_ele_offset,
const Index  sub_dim,
const Index  global_offset
const [virtual]
 

Calls this->applyOp(NULL,op,...).

Implements Thyra::VectorBase< Scalar >.

Definition at line 210 of file Thyra_SpmdVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::acquireDetachedView const Range1D rng,
RTOpPack::ConstSubVectorView< Scalar > *  sub_vec
const [virtual]
 

Implemented through this->getLocalData().

Reimplemented from Thyra::VectorDefaultBase< Scalar >.

Definition at line 230 of file Thyra_SpmdVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::releaseDetachedView RTOpPack::ConstSubVectorView< Scalar > *  sub_vec  )  const [virtual]
 

Implemented through this->freeLocalData().

Reimplemented from Thyra::VectorDefaultBase< Scalar >.

Definition at line 261 of file Thyra_SpmdVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::acquireDetachedView const Range1D rng,
RTOpPack::SubVectorView< Scalar > *  sub_vec
[virtual]
 

Implemented through this->getLocalData().

Reimplemented from Thyra::VectorDefaultBase< Scalar >.

Definition at line 280 of file Thyra_SpmdVectorBase.hpp.

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::commitDetachedView RTOpPack::SubVectorView< Scalar > *  sub_vec  )  [virtual]
 

Implemented through this->commitLocalData().

Reimplemented from Thyra::VectorDefaultBase< Scalar >.

Definition at line 311 of file Thyra_SpmdVectorBase.hpp.

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

Subclasses must call this function whenever the structure of the VectorSpaceBase changes.

Definition at line 331 of file Thyra_SpmdVectorBase.hpp.

template<class Scalar>
Range1D Thyra::SpmdVectorBase< Scalar >::validateRange const Range1D rng_in  )  const [private]
 

Definition at line 351 of file Thyra_SpmdVectorBase.hpp.


Member Data Documentation

template<class Scalar>
bool Thyra::SpmdVectorBase< Scalar >::in_applyOp_ [mutable, private]
 

Definition at line 293 of file Thyra_SpmdVectorBaseDecl.hpp.

template<class Scalar>
Index Thyra::SpmdVectorBase< Scalar >::globalDim_ [mutable, private]
 

Definition at line 296 of file Thyra_SpmdVectorBaseDecl.hpp.

template<class Scalar>
Index Thyra::SpmdVectorBase< Scalar >::localOffset_ [mutable, private]
 

Definition at line 297 of file Thyra_SpmdVectorBaseDecl.hpp.

template<class Scalar>
Index Thyra::SpmdVectorBase< Scalar >::localSubDim_ [mutable, private]
 

Definition at line 298 of file Thyra_SpmdVectorBaseDecl.hpp.


The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:33:13 2008 for Thyra Package Browser (Single Doxygen Collection) by doxygen 1.3.9.1