Thyra::MPIVectorBase< Scalar > Class Template Reference
[Thyra Operator/Vector Base Support Subclasses for MPI-based SPMD Thyra Implementations]

Base class for MPI-based SPMD vectors. More...

#include <Thyra_MPIVectorBaseDecl.hpp>

Inheritance diagram for Thyra::MPIVectorBase< Scalar >:

[legend]List of all members.

Pure virtual methods to be overridden by subclasses
virtual Teuchos::RefCountPtr< const MPIVectorSpaceBase< Scalar > >	mpiSpace () const =0
	Returns the MPI-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 methods 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().
Overridden from MultiVectorBase
Teuchos::RefCountPtr< const VectorSpaceBase< Scalar > >	space () const
	Returns this->mpiSpace().
void	applyOp (const RTOpPack::RTOpT< Scalar > &op, const int num_vecs, const VectorBase< Scalar > *vecs[], const int num_targ_vecs, VectorBase< Scalar > *targ_vecs[], RTOpPack::ReductTarget *reduct_obj, const Index first_ele, const Index sub_dim, const Index global_offset) const
	Implements the applyOp() method through the methods getSubVector(), freeSubVector() and commitSubVector() as described above.
void	getSubVector (const Range1D &rng, RTOpPack::SubVectorT< Scalar > *sub_vec) const
	Implemented through this->getLocalData().
void	freeSubVector (RTOpPack::SubVectorT< Scalar > *sub_vec) const
	Implemented through this->freeLocalData().
void	getSubVector (const Range1D &rng, RTOpPack::MutableSubVectorT< Scalar > *sub_vec)
	Implemented through this->getLocalData().
void	commitSubVector (RTOpPack::MutableSubVectorT< Scalar > *sub_vec)
	Implemented through this->commitLocalData().
Public Member Functions
	MPIVectorBase ()
Protected Member Functions
virtual void	updateMpiSpace ()
	Subclasses must call this function whenever the structure of the VectorSpaceBase changes.

---

Detailed Description

template<class Scalar>
class Thyra::MPIVectorBase< Scalar >

Base class for MPI-based SPMD vectors.

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

This base class contains an implementation of applyOp() that relies on implementations of the methods (const) getSubVector(), freeSubVector(), (non-const) getSubVector() and commitSubVector() (which all have default implementations in this subclass). In essence, this implementation will only call the getSubVector() methods using a range of (global) indexes for elements that exist on the local processor. As long as the number of local elements on each processor 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: mpiSpace() 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 mpiSpace() of course means having to implement or use a pre-implemented MPIVectorSpaceBase subclass.

Vector subclasses must also call the protected function updateMpiState() whenever the state of *this->mpiSpace() 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 getSubVector() methods are ever called with index ranges outside of those of the local processor, then the default implementations in VectorBase of all of the methods (const) getSubVector(), freeSubVector(), (non-const) getSubVector() and commitSubVector() are called instead. Alternatively, a subclass could provide more specialized implementations of these methods (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 methods 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 method. This is a truly elegant result.

As described in the documentation for MPIVectorSpaceBase, it is possible that at runtime it may be discovered that the mapping of vector data to processors does not fall under this design in which case the method applyOp() should be overridden to handle this which will of course remove the possibility of interoperability with other MPI-based vector objects. This, however, should never be the case.

Note that vector subclass derived from this node interface class must only be directly used in SPMD mode to work properly.

Definition at line 104 of file Thyra_MPIVectorBaseDecl.hpp.

---

Constructor & Destructor Documentation

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

Definition at line 43 of file Thyra_MPIVectorBase.hpp.

---

Member Function Documentation

template<class Scalar> virtual Teuchos::RefCountPtr<const MPIVectorSpaceBase<Scalar> > Thyra::MPIVectorBase< Scalar >::mpiSpace (   )  const [pure virtual]

Returns the MPI-based vector space object for *this vector. Implemented in Thyra::MPIVectorStd< Scalar >.

template<class Scalar> virtual void Thyra::MPIVectorBase< 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::MPIVectorStd< Scalar >.

template<class Scalar> virtual void Thyra::MPIVectorBase< 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::MPIVectorStd< Scalar >.

template<class Scalar> void Thyra::MPIVectorBase< 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::MPIVectorStd< Scalar >. Definition at line 53 of file Thyra_MPIVectorBase.hpp.

template<class Scalar> void Thyra::MPIVectorBase< 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::MPIVectorStd< Scalar >. Definition at line 59 of file Thyra_MPIVectorBase.hpp.

template<class Scalar> Teuchos::RefCountPtr< const VectorSpaceBase< Scalar > > Thyra::MPIVectorBase< Scalar >::space (   )  const

Returns this->mpiSpace(). Definition at line 68 of file Thyra_MPIVectorBase.hpp.

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

Implements the applyOp() method through the methods getSubVector(), freeSubVector() and commitSubVector() as described above. Note that if this method is entered again before a call has been completed, then this is an indication that the methods getSubVector(), freeSubVector() and/or commitSubVector() have not been overridden properly and this method will then throw an exception. Definition at line 74 of file Thyra_MPIVectorBase.hpp.

template<class Scalar> void Thyra::MPIVectorBase< Scalar >::getSubVector (  const Range1D &  rng, RTOpPack::SubVectorT< Scalar > *  sub_vec )  const

Implemented through this->getLocalData(). Definition at line 162 of file Thyra_MPIVectorBase.hpp.

template<class Scalar> void Thyra::MPIVectorBase< Scalar >::freeSubVector (  RTOpPack::SubVectorT< Scalar > *  sub_vec  )  const

Implemented through this->freeLocalData(). Definition at line 183 of file Thyra_MPIVectorBase.hpp.

template<class Scalar> void Thyra::MPIVectorBase< Scalar >::getSubVector (  const Range1D &  rng, RTOpPack::MutableSubVectorT< Scalar > *  sub_vec )

Implemented through this->getLocalData(). Definition at line 202 of file Thyra_MPIVectorBase.hpp.

template<class Scalar> void Thyra::MPIVectorBase< Scalar >::commitSubVector (  RTOpPack::MutableSubVectorT< Scalar > *  sub_vec  )

Implemented through this->commitLocalData(). Definition at line 223 of file Thyra_MPIVectorBase.hpp.

template<class Scalar> void Thyra::MPIVectorBase< Scalar >::updateMpiSpace (   )  [protected, virtual]

Subclasses must call this function whenever the structure of the VectorSpaceBase changes. Definition at line 243 of file Thyra_MPIVectorBase.hpp.

---

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

• Thyra_MPIVectorBaseDecl.hpp
• Thyra_MPIVectorBase.hpp

---