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

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

#include <Thyra_SpmdMultiVectorBaseDecl.hpp>

Inheritance diagram for Thyra::SpmdMultiVectorBase< Scalar >:

[legend]List of all members.

Constructors / initializers / accessors
	SpmdMultiVectorBase ()
Pure virtual functions to be overridden by subclasses
virtual Teuchos::RefCountPtr< const SpmdVectorSpaceBase< Scalar > >	spmdSpace () const =0
	Returns the SPMD vector space object for the range of *this multi-vector.
virtual void	getLocalData (Scalar **localValues, Index *leadingDim)=0
	Returns a non-const pointer to a Fortran-style view of the local multi-vector data.
virtual void	commitLocalData (Scalar *localValues)=0
	Commit view of local data that was gotten from getLocalData().
virtual void	getLocalData (const Scalar **localValues, Index *leadingDim) const =0
	Returns a const pointer to a Fortran-style view of the local multi-vector data.
virtual void	freeLocalData (const Scalar *localValues) const =0
	Free view of local data that was gotten from getLocalData().
Overridden from EuclideanLinearOpBase
Teuchos::RefCountPtr< const ScalarProdVectorSpaceBase< Scalar > >	rangeScalarProdVecSpc () const
	Returns spmdSpace.
Overridden from LinearOpBase
void	apply (const ETransp M_trans, const MultiVectorBase< Scalar > &X, MultiVectorBase< Scalar > *Y, const Scalar alpha, const Scalar beta) const
	Calls EuclideanLinearOpBase::apply() to disambiguate apply().
Overridden from MultiVectorBase
void	applyOp (const RTOpPack::RTOpT< Scalar > &primary_op, const int num_multi_vecs, const MultiVectorBase< Scalar > *const multi_vecs[], const int num_targ_multi_vecs, MultiVectorBase< Scalar > *const targ_multi_vecs[], RTOpPack::ReductTarget *const reduct_objs[], const Index primary_first_ele, const Index primary_sub_dim, const Index primary_global_offset, const Index secondary_first_ele, const Index secondary_sub_dim) const
void	acquireDetachedView (const Range1D &rowRng, const Range1D &colRng, RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const
void	releaseDetachedView (RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const
void	acquireDetachedView (const Range1D &rowRng, const Range1D &colRng, RTOpPack::SubMultiVectorView< Scalar > *sub_mv)
void	commitDetachedView (RTOpPack::SubMultiVectorView< Scalar > *sub_mv)
Overridden from SingleScalarEuclideanLinearOpBase
bool	opSupported (ETransp M_trans) const
	For complex Scalar types returns true for NOTRANS, TRANS, and CONJTRANS and for real types returns true for all values of M_trans.
void	euclideanApply (const ETransp M_trans, const MultiVectorBase< Scalar > &X, 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**,Index*), freeLocalData(const Scalar**,Index*), getLocalData(Scalar**,Index*), and commitLocalData(Scalar**,Index*). 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 98 of file Thyra_SpmdMultiVectorBaseDecl.hpp.

---

Constructor & Destructor Documentation

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

Definition at line 50 of file Thyra_SpmdMultiVectorBase.hpp.

---

Member Function Documentation

template<class Scalar> virtual Teuchos::RefCountPtr<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 >.

template<class Scalar> virtual void Thyra::SpmdMultiVectorBase< Scalar >::getLocalData (  Scalar **  localValues, Index *  leadingDim )  [pure virtual]

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. Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

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

Commit view of local data that was gotten from getLocalData(). Parameters: localValues  [in/out] On input localValues must be the pointer set by getLocalData(). Preconditions: localValues!=NULL Preconditions: *this will be updated to the entries in *localValues. Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

template<class Scalar> virtual void Thyra::SpmdMultiVectorBase< Scalar >::getLocalData (  const Scalar **  localValues, Index *  leadingDim )  const [pure virtual]

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 Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

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

Free view of local data that was gotten from getLocalData(). Parameters: localValues  [in/out] On input localValues must be the pointer set by getLocalData(). Preconditions: localValues!=NULL Preconditions: *this will be updated to the entries in *localValues. Implemented in Thyra::DefaultSpmdMultiVector< Scalar >.

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

Returns spmdSpace. Implements Thyra::EuclideanLinearOpBase< Scalar >. Definition at line 62 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar> void Thyra::SpmdMultiVectorBase< Scalar >::apply (  const ETransp  M_trans, const MultiVectorBase< Scalar > &  X, MultiVectorBase< Scalar > *  Y, const Scalar  alpha, const Scalar  beta )  const

Calls EuclideanLinearOpBase::apply() to disambiguate apply(). Definition at line 72 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar> void Thyra::SpmdMultiVectorBase< Scalar >::applyOp (  const RTOpPack::RTOpT< Scalar > &  primary_op, const int  num_multi_vecs, const MultiVectorBase< Scalar > *const   multi_vecs[], const int  num_targ_multi_vecs, MultiVectorBase< Scalar > *const   targ_multi_vecs[], RTOpPack::ReductTarget *const   reduct_objs[], const Index  primary_first_ele, const Index  primary_sub_dim, const Index  primary_global_offset, const Index  secondary_first_ele, const Index  secondary_sub_dim )  const [virtual]

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >. Definition at line 86 of file Thyra_SpmdMultiVectorBase.hpp.

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

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >. Definition at line 183 of file Thyra_SpmdMultiVectorBase.hpp.

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

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >. Definition at line 213 of file Thyra_SpmdMultiVectorBase.hpp.

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

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >. Definition at line 227 of file Thyra_SpmdMultiVectorBase.hpp.

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

Reimplemented from Thyra::MultiVectorDefaultBase< Scalar >. Definition at line 257 of file Thyra_SpmdMultiVectorBase.hpp.

template<class Scalar> bool Thyra::SpmdMultiVectorBase< Scalar >::opSupported (  ETransp  M_trans  )  const [protected, virtual]

For complex Scalar types returns true for NOTRANS, TRANS, and CONJTRANS and for real types returns true for all values of M_trans. Implements Thyra::SingleScalarEuclideanLinearOpBase< Scalar >. Definition at line 542 of file Thyra_SpmdMultiVectorBase.hpp.

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

Uses GEMM() and Teuchos::reduceAll() to implement. ToDo: Finish documentation! Implements Thyra::SingleScalarEuclideanLinearOpBase< Scalar >. Definition at line 273 of file Thyra_SpmdMultiVectorBase.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 549 of file Thyra_SpmdMultiVectorBase.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 569 of file Thyra_SpmdMultiVectorBase.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 584 of file Thyra_SpmdMultiVectorBase.hpp.

---

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

• Thyra_SpmdMultiVectorBaseDecl.hpp
• Thyra_SpmdMultiVectorBase.hpp

---