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 >:


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.

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

Returns this->spmdSpace().

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

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

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.

The documentation for this class was generated from the following files:

Generated on Thu Sep 18 12:32:34 2008 for Thyra Operator/Vector Support by

1.3.9.1

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

Pure virtual functions to be overridden by subclasses

Virtual functions with default implementations.

Overridden from MultiVectorBase

Public Member Functions

Protected Member Functions

Detailed Description

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

Constructor & Destructor Documentation

Member Function Documentation

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

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