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

Base VectorSpaceBase class for all MPI-based vector spaces with contiguous local storage. More...

#include <Thyra_MPIVectorSpaceBaseDecl.hpp>

Inheritance diagram for Thyra::MPIVectorSpaceBase< Scalar >:

[legend]List of all members.

Pure virtual methods to be overridden by subclasses
virtual MPI_Comm	mpiComm () const =0
	Returns the MPI communicator.
virtual Index	localSubDim () const =0
	Returns the number of local elements stored on this processor.
Virtual methods with default implementations
virtual Index	localOffset () const
	Returns the offset for the local sub-vector stored on this processor.
virtual Index	mapCode () const
	Returns the code for the mapping of elements to processors.
Overridden from VectorSpaceBase
Index	dim () const
	Returns the sum of the local number of elements on every process.
bool	isInCore () const
	Returns true if all of the elements are stored on one processor.
Teuchos::RefCountPtr< const VectorSpaceFactoryBase< Scalar > >	smallVecSpcFcty () const
	Returns a MPIVectorSpaceFactoryStd object that has been given mpiComm().
bool	isCompatible (const VectorSpaceBase< Scalar > &vecSpc) const
	Checks the general compatibility of parallel (or serial on one processor) MPI-based vector spaces.
Public Member Functions
	MPIVectorSpaceBase ()
Protected Member Functions
virtual void	updateState (const Index globalDim)
	This function must be called whenever the state of this changes and some internal state must be updated.

---

Detailed Description

template<class Scalar>
class Thyra::MPIVectorSpaceBase< Scalar >

Base VectorSpaceBase class for all MPI-based vector spaces with contiguous local storage.

This interface defines a basic mechanism for the interoperability of MPI SPMD VectorBase and MultiVectorBase objects. See the base classes MPIVetorBase and MPIMultiVectorBase to demonstrate how this interface is used to achieve universal interoperability of vector and multi-vector objects.

Specifically, these classes are designed to handle three different use case:

• Serial vectors on one processor with localSubDim()==dim(). In this case, the MPI_Comm returned from mpiComm() can be MPI_COMM_NULL.
• Distributed parallel vectors on two or more processors with localSubDim() < dim(). This implementation assumes that all of the elements are stored contiguously on each processor and that there are no ghost elements as described below.
• Locally replicated vectors on one or more processor. This case is similar to serial vectors except that we have localSubDim()==dim() even if there is more than one processor. This case is checked for so that the reduction operations are performed correctly.

This interface provides all the information necessary to implement MPIVectorBase::applyOp() in all of the above described use cases. This interface returns an MPI communicator (of which all compatible vector spaces must have the same communicator obviously) through the method mpiComm().

VectorBase data layout:

For the case of a distributed parallel vector, this interface base class assumes that vector data is partitioned to processors in contiguous chunks of dense subvectors. To spell this out, let v be the local vector that is sorted on this processor and let g be the global vector. Then these two vectors are related (using one-based indexing) as:

    v(k) == g(k + this->localOffset()), for k = 1...this->localSubDim()

 

Any type of mapping of vector data to processors that can not be interpreted in this way can not rely on this base class for interoperability. Note that as long as the elements in a processor are partitioned to unique processors and no ghost elements are present, the actual indexes used by the application with these vectors is immaterial. The indexes associated with this set of interfaces, however, are only meaningful to abstract numerical algorithms and provide an arbitrary label for certain types of coordinate-dependent operations (like required in an active-set method for optimization). Therefore, as long as the underlying vector represents a unique partitioning of elements, these classes can be used. There is a default implementation of localOffset() that automatically assumes this contiguous mapping of elements to processors and in general this should not be changed.

Notes to subclass developers:

The pure virtual methods mpiComm() and localSubDim() defined in this interface along with the pure virtual methods dim() and createMember() are the only methods that must be overridden.

If this this is in an uninitialized state then localSubDim() should return 0.

It should never be necessary to override the virtual functions mapCode() and isCompatible() as these functions have very good and very general implementations. do.

If optimized implementations of multi-vectors can be supported, then the createMembers() method should also be overridden.

This class defines a very general default implementation for smallVecSpcFcty() that returns a MPIVectorSpaceFactoryStd object. This returned object creates MPIVectorSpaceStd objects. MPIVectorSpaceStd creates MPIVectorStd and MPIMultiVectorStd. This implementation is very general should be very appropriate for many different concrete implementations.

Note: It is very important that subclasses call the updateState() function whenever the state of *this changes in a way that might affect the behavior of any of the public member functions. For example, if a different value of localSubDim() will be returned the next time it is called by a client, then updateState() needs to be called by the subclass. External clients should never need to worry about this function and that is why updateState() is declared protected.

Definition at line 140 of file Thyra_MPIVectorSpaceBaseDecl.hpp.

---

Constructor & Destructor Documentation

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

Definition at line 43 of file Thyra_MPIVectorSpaceBase.hpp.

---

Member Function Documentation

template<class Scalar> virtual MPI_Comm Thyra::MPIVectorSpaceBase< Scalar >::mpiComm (   )  const [pure virtual]

Returns the MPI communicator. Implemented in Thyra::MPIVectorSpaceStd< Scalar >.

template<class Scalar> virtual Index Thyra::MPIVectorSpaceBase< Scalar >::localSubDim (   )  const [pure virtual]

Returns the number of local elements stored on this processor. If this this is uninitialized then localSubDim() returns 0. Implemented in Thyra::MPIVectorSpaceStd< Scalar >.

template<class Scalar> Index Thyra::MPIVectorSpaceBase< Scalar >::localOffset (   )  const [virtual]

Returns the offset for the local sub-vector stored on this processor. This method has a default implementation which just assigns this offset based on counting up localSubDim() on each processor and then setting localOffset() by the rank of the processor. For example, if there are 5 elements in process 0 and 4 elements in process rank, then localOffset on each of these processors will be set as: localOffset=0 on process 0, localOffset=5 on process 1, localOffset=9 on process 2 and so on. Definition at line 50 of file Thyra_MPIVectorSpaceBase.hpp.

template<class Scalar> Index Thyra::MPIVectorSpaceBase< Scalar >::mapCode (   )  const [virtual]

Returns the code for the mapping of elements to processors. Postconditions: [this->localSubDim() > 0] this->mapCode() > 0. [this->localSubDim() <= 0] this->mapCode() <= 0. This method takes the data mpiComm(), numProc (where numProc is returned from MPI_Comm_size(this->mpiComm(),&numProc), localOffset() or localSubDim() on each processor and then uses it to compute a value for mapCode (using a single global reduction if numProc > 1) which is returned from this function. The value returned from this default implementation of this method must not be changed or this approach breaks down. The only reason for overriding this method is for the subclass to be alerted of when this method is called but not what is returned from this method. If a subclass developer does not understand what this means then don't override this method! The default implementation will always return return > 0 (unless this is uninitialized) so that if this method is overridden to return return <= then this is a flag that the underlying vector map does not satisfy the assumptions of this vector space interface and vectors that are in *this vector space can not collaborate with other MPI-based vector implementations. Definition at line 56 of file Thyra_MPIVectorSpaceBase.hpp.

template<class Scalar> Index Thyra::MPIVectorSpaceBase< Scalar >::dim (   )  const [virtual]

Returns the sum of the local number of elements on every process. Implements Thyra::VectorSpaceBase< Scalar >. Definition at line 64 of file Thyra_MPIVectorSpaceBase.hpp.

template<class Scalar> bool Thyra::MPIVectorSpaceBase< Scalar >::isInCore (   )  const [virtual]

Returns true if all of the elements are stored on one processor. Postconditions: return == (dim()==localSubDim()). Reimplemented from Thyra::VectorSpaceBase< Scalar >. Definition at line 70 of file Thyra_MPIVectorSpaceBase.hpp.

template<class Scalar> Teuchos::RefCountPtr< const VectorSpaceFactoryBase< Scalar > > Thyra::MPIVectorSpaceBase< Scalar >::smallVecSpcFcty (   )  const [virtual]

Returns a MPIVectorSpaceFactoryStd object that has been given mpiComm(). Reimplemented from Thyra::VectorSpaceDefaultBase< Scalar >. Definition at line 77 of file Thyra_MPIVectorSpaceBase.hpp.

template<class Scalar> bool Thyra::MPIVectorSpaceBase< Scalar >::isCompatible (  const VectorSpaceBase< Scalar > &  vecSpc  )  const [virtual]

Checks the general compatibility of parallel (or serial on one processor) MPI-based vector spaces. Returns: Returns true if *this and vecSpace are both serial in-core vectors or if vecSpc is of type MPIVectorSpaceBase<Scalar> and both *this and vecSpc have the same MPI communicators and the same mapping of elements to processors. Postconditions: return = ( this->isInCore() && vecSpc->isInCore() ) || ( (mpiVecSpc = dynamic_cast<const MPIVectorSpaceBase<Scalar>*>(&vecSpc)) && this->mpiComm() == mpiVecSpc->mpiComm() && this->mapCode() == mpiVecSpc->mpiComm()). If the mapping of vector elements to processors is not as described above then this method should be overridden in a way that is specific to the vector implementation. Implements Thyra::VectorSpaceBase< Scalar >. Definition at line 83 of file Thyra_MPIVectorSpaceBase.hpp.

template<class Scalar> void Thyra::MPIVectorSpaceBase< Scalar >::updateState (  const Index  globalDim  )  [protected, virtual]

This function must be called whenever the state of this changes and some internal state must be updated. Parameters: globalDim  [in] If globalDim > 0 then this determines the global dimension of the vector space. If globalDim==this->localSubDim() then this is a locally replicated vector space. If globalDim < 0 then the global dimension is computed using a global reduction. If MPI_Comm_size(this->mpiComm(),&numProc) returns numProc==1 then this argument is ignored. Note that calling this function will involve one or more global reductions being called if this is parallel vector space so it should only be called when needed by subclasses. Usually, this operation only needs to be called once for every *new* parallel vector space constructed and very few parallel vector spaces will be created per application usually. Definition at line 97 of file Thyra_MPIVectorSpaceBase.hpp.

---

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

• Thyra_MPIVectorSpaceBaseDecl.hpp
• Thyra_MPIVectorSpaceBase.hpp

---