Thyra Package Browser (Single Doxygen Collection) Version of the Day
Public Member Functions | Private Member Functions | Private Attributes
Thyra::SpmdVectorBase< Scalar > Class Template Reference

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

#include <Thyra_SpmdVectorBase_decl.hpp>

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

List of all members.

Public Member Functions

virtual void applyOpImplWithComm (const Ptr< const Teuchos::Comm< Ordinal > > &comm, const RTOpPack::RTOpT< Scalar > &op, const ArrayView< const Ptr< const VectorBase< Scalar > > > &vecs, const ArrayView< const Ptr< VectorBase< Scalar > > > &targ_vecs, const Ptr< RTOpPack::ReductTarget > &reduct_obj, const Ordinal global_offset) const
 Implementation of applyOpImpl(...) that uses an input Comm.

Private Member Functions

Range1D validateRange (const Range1D &rng_in) const

Private Attributes

bool in_applyOpImpl_
Ordinal globalDim_
Ordinal localOffset_
Ordinal localSubDim_

Public interface functions

 SpmdVectorBase ()
 
virtual Teuchos::RCP< const
SpmdVectorSpaceBase< Scalar > > 
spmdSpace () const =0
 Returns the Spmd-based vector space object for *this vector.
RTOpPack::SubVectorView< Scalar > getNonconstLocalSubVector ()
 Get a nonconst view of the local data.
RTOpPack::ConstSubVectorView
< Scalar > 
getLocalSubVector () const
 Get a const view of the local data.
void getNonconstLocalData (const Ptr< ArrayRCP< Scalar > > &localValues)
 Returns a non-const pointer to the beginning of the local vector data.
void getLocalData (const Ptr< ArrayRCP< const Scalar > > &localValues) const
 Returns a const pointer to the beginning of the local vector data.

Overridden form Teuchos::Describable

std::string description () const
 

Overridden public functions from VectorBase

Teuchos::RCP< const
VectorSpaceBase< Scalar > > 
space () const
 Returns this->spmdSpace().

Deprecated

THYRA_DEPRECATED void getLocalData (Scalar **localValues, Ordinal *stride)
 Deprecated.
THYRA_DEPRECATED void commitLocalData (Scalar *localValues)
 Deprecated.
THYRA_DEPRECATED void getLocalData (const Scalar **localValues, Ordinal *stride) const
 Deprecated.
THYRA_DEPRECATED void freeLocalData (const Scalar *localValues) const
 Deprecated.

Protected pure virtual functions to be overridden

virtual void getNonconstLocalDataImpl (const Ptr< ArrayRCP< Scalar > > &localValues)=0
 Implementation of getNonconstLocalData()
virtual void getLocalDataImpl (const Ptr< ArrayRCP< const Scalar > > &localValues) const =0
 Implementation of getLocalData()

Overridden protected functions from VectorBase

void applyOpImpl (const RTOpPack::RTOpT< Scalar > &op, const ArrayView< const Ptr< const VectorBase< Scalar > > > &vecs, const ArrayView< const Ptr< VectorBase< Scalar > > > &targ_vecs, const Ptr< RTOpPack::ReductTarget > &reduct_obj, const Ordinal global_offset) const
 Calls applyOpImplWithComm(null,op,...).
void acquireDetachedVectorViewImpl (const Range1D &rng, RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const
 Implemented through this->getLocalData()
void releaseDetachedVectorViewImpl (RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const
 Implemented through this->freeLocalData()
void acquireNonconstDetachedVectorViewImpl (const Range1D &rng, RTOpPack::SubVectorView< Scalar > *sub_vec)
 Implemented through this->getLocalData()
void commitNonconstDetachedVectorViewImpl (RTOpPack::SubVectorView< Scalar > *sub_vec)
 Implemented through this->commitLocalData()

Protected functions to be used by subclasses

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**,Ordinal*). The default implementation of getLocalData(cons Scalar**,Ordinal*) 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 applyOpImpl()), the operator will be properly applied since the version of applyOpImpl() 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 105 of file Thyra_SpmdVectorBase_decl.hpp.


Constructor & Destructor Documentation

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

Definition at line 51 of file Thyra_SpmdVectorBase_def.hpp.


Member Function Documentation

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

Referenced by Thyra::get_Epetra_MultiVector().

template<class Scalar >
RTOpPack::SubVectorView< Scalar > Thyra::SpmdVectorBase< Scalar >::getNonconstLocalSubVector ( )

Get a nonconst view of the local data.

ToDo: Refactor this interface to use iterator access.

Definition at line 61 of file Thyra_SpmdVectorBase_def.hpp.

template<class Scalar >
RTOpPack::ConstSubVectorView< Scalar > Thyra::SpmdVectorBase< Scalar >::getLocalSubVector ( ) const

Get a const view of the local data.

ToDo: Refactor this interface to use iterator access.

Definition at line 77 of file Thyra_SpmdVectorBase_def.hpp.

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::getNonconstLocalData ( const Ptr< ArrayRCP< Scalar > > &  localValues) [inline]

Returns a non-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.

Preconditions:

  • nonnull(localValues)==true

Postconditions:

  • nonnull(*localValues)==true

Note, the data view returned from this function must be freed by removing all of the ArrayRCP objects (or setting them to null).

Definition at line 147 of file Thyra_SpmdVectorBase_decl.hpp.

References Thyra::SpmdVectorBase< Scalar >::getNonconstLocalDataImpl().

Referenced by Thyra::get_Epetra_MultiVector().

template<class Scalar>
void Thyra::SpmdVectorBase< Scalar >::getLocalData ( const Ptr< ArrayRCP< const Scalar > > &  localValues) const [inline]

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.

Preconditions:

  • nonnull(localValues)==true

Postconditions:

  • nonnull(*localValues)==true

Note, the data view returned from this function must be freed by removing all of the ArrayRCP objects (or setting them to null).

Definition at line 167 of file Thyra_SpmdVectorBase_decl.hpp.

References Thyra::SpmdVectorBase< Scalar >::getLocalDataImpl().

Referenced by Thyra::get_Epetra_MultiVector().

template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::applyOpImplWithComm ( const Ptr< const Teuchos::Comm< Ordinal > > &  comm,
const RTOpPack::RTOpT< Scalar > &  op,
const ArrayView< const Ptr< const VectorBase< Scalar > > > &  vecs,
const ArrayView< const Ptr< VectorBase< Scalar > > > &  targ_vecs,
const Ptr< RTOpPack::ReductTarget > &  reduct_obj,
const Ordinal  global_offset 
) const [virtual]

Implementation of applyOpImpl(...) that uses an input Comm.

Parameters:
comm[in] The Spmd communicator to use in the global reduction. If comm==NULL, then the local communicator will be used instead.

Definition at line 92 of file Thyra_SpmdVectorBase_def.hpp.

References Thyra::apply_op_validate_input(), Teuchos::dyn_cast(), Teuchos::Ptr< T >::get(), get_default_workspace_store(), Thyra::SpmdVectorSpaceBase< Scalar >::getComm(), Teuchos::Range1D::lbound(), nonnull(), Teuchos::null, Teuchos::Workspace< T >::size(), RTOpPack::SPMD_apply_op(), and TEST_FOR_EXCEPTION.

template<class Scalar >
std::string Thyra::SpmdVectorBase< Scalar >::description ( ) const [virtual]

Reimplemented from Thyra::VectorDefaultBase< Scalar >.

Definition at line 182 of file Thyra_SpmdVectorBase_def.hpp.

References Teuchos::null, typeName(), and Teuchos::typeName().

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

Returns this->spmdSpace().

Implements Thyra::VectorBase< Scalar >.

Definition at line 197 of file Thyra_SpmdVectorBase_def.hpp.

template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::getLocalData ( Scalar **  localValues,
Ordinal stride 
)

Deprecated.

Definition at line 207 of file Thyra_SpmdVectorBase_def.hpp.

References Teuchos::ArrayRCP< T >::getRawPtr(), and TEUCHOS_ASSERT.

template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::commitLocalData ( Scalar *  localValues)

Deprecated.

Definition at line 221 of file Thyra_SpmdVectorBase_def.hpp.

template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::getLocalData ( const Scalar **  localValues,
Ordinal stride 
) const

Deprecated.

Definition at line 228 of file Thyra_SpmdVectorBase_def.hpp.

References Teuchos::ArrayRCP< T >::getRawPtr(), and TEUCHOS_ASSERT.

template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::freeLocalData ( const Scalar *  localValues) const

Deprecated.

Definition at line 242 of file Thyra_SpmdVectorBase_def.hpp.

template<class Scalar>
virtual void Thyra::SpmdVectorBase< Scalar >::getNonconstLocalDataImpl ( const Ptr< ArrayRCP< Scalar > > &  localValues) [protected, pure virtual]
template<class Scalar>
virtual void Thyra::SpmdVectorBase< Scalar >::getLocalDataImpl ( const Ptr< ArrayRCP< const Scalar > > &  localValues) const [protected, pure virtual]
template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::applyOpImpl ( const RTOpPack::RTOpT< Scalar > &  op,
const ArrayView< const Ptr< const VectorBase< Scalar > > > &  vecs,
const ArrayView< const Ptr< VectorBase< Scalar > > > &  targ_vecs,
const Ptr< RTOpPack::ReductTarget > &  reduct_obj,
const Ordinal  global_offset 
) const [protected, virtual]

Calls applyOpImplWithComm(null,op,...).

Implements Thyra::VectorBase< Scalar >.

Definition at line 255 of file Thyra_SpmdVectorBase_def.hpp.

References Teuchos::null.

template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::acquireDetachedVectorViewImpl ( const Range1D rng,
RTOpPack::ConstSubVectorView< Scalar > *  sub_vec 
) const [protected, virtual]
template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::releaseDetachedVectorViewImpl ( RTOpPack::ConstSubVectorView< Scalar > *  sub_vec) const [protected, virtual]
template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::acquireNonconstDetachedVectorViewImpl ( const Range1D rng,
RTOpPack::SubVectorView< Scalar > *  sub_vec 
) [protected, virtual]
template<class Scalar >
void Thyra::SpmdVectorBase< Scalar >::commitNonconstDetachedVectorViewImpl ( RTOpPack::SubVectorView< Scalar > *  sub_vec) [protected, virtual]
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 396 of file Thyra_SpmdVectorBase_def.hpp.

References Thyra::VectorSpaceBase< Scalar >::dim(), Thyra::SpmdVectorSpaceBase< Scalar >::localOffset(), and Thyra::SpmdVectorSpaceBase< Scalar >::localSubDim().

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

Member Data Documentation

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

Definition at line 276 of file Thyra_SpmdVectorBase_decl.hpp.

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

Definition at line 279 of file Thyra_SpmdVectorBase_decl.hpp.

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

Definition at line 280 of file Thyra_SpmdVectorBase_decl.hpp.

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

Definition at line 281 of file Thyra_SpmdVectorBase_decl.hpp.


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