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

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

#include <Thyra_MPIMultiVectorBaseDecl.hpp>

Inheritance diagram for Thyra::MPIMultiVectorBase< Scalar >:

[legend]List of all members.

Constructors / initializers / accessors
	MPIMultiVectorBase ()
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 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 mpiSpace.
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 > *multi_vecs[], const int num_targ_multi_vecs, MultiVectorBase< Scalar > *targ_multi_vecs[], RTOpPack::ReductTarget *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	getSubMultiVector (const Range1D &rowRng, const Range1D &colRng, RTOpPack::SubMultiVectorT< Scalar > *sub_mv) const
void	freeSubMultiVector (RTOpPack::SubMultiVectorT< Scalar > *sub_mv) const
void	getSubMultiVector (const Range1D &rowRng, const Range1D &colRng, RTOpPack::MutableSubMultiVectorT< Scalar > *sub_mv)
void	commitSubMultiVector (RTOpPack::MutableSubMultiVectorT< 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 MPI_Allreduce(...) to implement.
Protected functions for subclasses to call.
virtual void	updateMpiSpace ()
	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::MPIMultiVectorBase< Scalar >

Base class for MPI-based SPMD multi-vectors.

By inheriting from this base class, multi-vector implementations allow their multi-vector objects to be seamlessly combined with other MPI-based 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 MPIVectorSpaceBase object through the virtual function mpiSpace().

This base class contains an implementation of applyOp() that relies on implementations of the methods (const) getSubMultiVector(), freeSubMultiVector(), (non-const) getSubMultiVector() and commitSubMultiVector() (which all have default implementations in this subclass). In essence, this implementation will only call the getSubMultiVector() 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 five functions: mpiSpace(), getLocalData(const Scalar**,Index*), freeLocalData(const Scalar**,Index*), getLocalData(Scalar**,Index*), commitLocalData(Scalar**,Index*). Note that overriding the mpiSpace() function requires implementing or using a pre-implemented concrete MPIVectorSpace object.

If the getSubMultiVector() methods are ever called with index ranges outside of those of the local processor, then the default implementations in MultiVectorBase of all of the methods (const) MultiVectorBase::getSubMultiVector(), MultiVectorBase::freeSubMultiVector(), (non-const) MultiVectorBase::getSubMultiVector() and MultiVectorBase::commitSubMultiVector() are called in 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 that the explicit subvector access methods 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 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. As long as ghost data is not included this should never be an issue.

Note that multi-vector subclass derived from this base class must only be directly used in SPMD mode for this to work properly.

Definition at line 109 of file Thyra_MPIMultiVectorBaseDecl.hpp.

---

Constructor & Destructor Documentation

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

Definition at line 52 of file Thyra_MPIMultiVectorBase.hpp.

---

Member Function Documentation

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

Returns the MPI-based vector space object for the range of *this multi-vector. Implemented in Thyra::MPIMultiVectorStd< Scalar >.

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

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

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

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

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

Returns mpiSpace. Implements Thyra::EuclideanLinearOpBase< Scalar >. Definition at line 64 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> void Thyra::MPIMultiVectorBase< 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_MPIMultiVectorBase.hpp.

template<class Scalar> void Thyra::MPIMultiVectorBase< Scalar >::applyOp (  const RTOpPack::RTOpT< Scalar > &  primary_op, const int  num_multi_vecs, const MultiVectorBase< Scalar > *  multi_vecs[], const int  num_targ_multi_vecs, MultiVectorBase< Scalar > *  targ_multi_vecs[], RTOpPack::ReductTarget *  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

Definition at line 86 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> void Thyra::MPIMultiVectorBase< Scalar >::getSubMultiVector (  const Range1D &  rowRng, const Range1D &  colRng, RTOpPack::SubMultiVectorT< Scalar > *  sub_mv )  const

Definition at line 184 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> void Thyra::MPIMultiVectorBase< Scalar >::freeSubMultiVector (  RTOpPack::SubMultiVectorT< Scalar > *  sub_mv  )  const

Definition at line 214 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> void Thyra::MPIMultiVectorBase< Scalar >::getSubMultiVector (  const Range1D &  rowRng, const Range1D &  colRng, RTOpPack::MutableSubMultiVectorT< Scalar > *  sub_mv )

Definition at line 228 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> void Thyra::MPIMultiVectorBase< Scalar >::commitSubMultiVector (  RTOpPack::MutableSubMultiVectorT< Scalar > *  sub_mv  )

Definition at line 258 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> bool Thyra::MPIMultiVectorBase< 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 547 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> void Thyra::MPIMultiVectorBase< 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 MPI_Allreduce(...) to implement. ToDo: Finish documentation! Implements Thyra::SingleScalarEuclideanLinearOpBase< Scalar >. Definition at line 274 of file Thyra_MPIMultiVectorBase.hpp.

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

Subclasses should call whenever the structure of the VectorSpaceBase changes. This function can be overridden by subclasses but this particular function implementation must be called from within any override. Definition at line 554 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> Range1D Thyra::MPIMultiVectorBase< 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 574 of file Thyra_MPIMultiVectorBase.hpp.

template<class Scalar> Range1D Thyra::MPIMultiVectorBase< 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 589 of file Thyra_MPIMultiVectorBase.hpp.

---

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

• Thyra_MPIMultiVectorBaseDecl.hpp
• Thyra_MPIMultiVectorBase.hpp

---