vector interfaces]

Abstract interface for objects that represent a space for vectors. More...

#include <Thyra_VectorSpaceBaseDecl.hpp>

Inheritance diagram for Thyra::VectorSpaceBase< Scalar >:


Public pure virtual functions that must be overridden
virtual Index	dim () const =0
	Return the dimension of the vector space.
virtual bool	isCompatible (const VectorSpaceBase< Scalar > &vecSpc) const =0
	Compare the compatibility of two vector spaces.
virtual Teuchos::RefCountPtr< const VectorSpaceFactoryBase< Scalar > >	smallVecSpcFcty () const =0
	Return a `VectorSpaceFactoryBase` object for the creation of (serial) vector spaces with a small dimension.
virtual Scalar	scalarProd (const VectorBase< Scalar > &x, const VectorBase< Scalar > &y) const =0
	Return the scalar product of two vectors in the vector space.
virtual void	scalarProds (const MultiVectorBase< Scalar > &X, const MultiVectorBase< Scalar > &Y, Scalar scalar_prods[]) const =0
	Return the scalar product of each column in two multi-vectors in the vector space.
Public virtual functions with default implementations
virtual bool	isInCore () const
	Returns if all of the vector elements are cheaply accessible on this processor.
virtual Teuchos::RefCountPtr< const VectorSpaceBase< Scalar > >	clone () const
	Clone this object (if supported).
Protected pure virtual functions that must be overridden
virtual Teuchos::RefCountPtr< VectorBase< Scalar > >	createMember () const =0
	Create a vector member from the vector space.
virtual Teuchos::RefCountPtr< MultiVectorBase< Scalar > >	createMembers (int numMembers) const =0
	Create a set of vector members (a `MultiVectorBase`) from the vector space.
virtual Teuchos::RefCountPtr< VectorBase< Scalar > >	createMemberView (const RTOpPack::MutableSubVectorT< Scalar > &raw_v) const =0
	Create a vector member that is a non-`const` view of raw vector data.
virtual Teuchos::RefCountPtr< const VectorBase< Scalar > >	createMemberView (const RTOpPack::SubVectorT< Scalar > &raw_v) const =0
	Create a vector member that is a `const` view of raw vector data.
virtual Teuchos::RefCountPtr< MultiVectorBase< Scalar > >	createMembersView (const RTOpPack::MutableSubMultiVectorT< Scalar > &raw_mv) const =0
	Create a multi-vector member that is a non-`const` view of raw multi-vector data.
virtual Teuchos::RefCountPtr< const MultiVectorBase< Scalar > >	createMembersView (const RTOpPack::SubMultiVectorT< Scalar > &raw_mv) const =0
	Create a multi-vector member that is a `const` view of raw multi-vector data.

Detailed Description

template<class Scalar>
class Thyra::VectorSpaceBase< Scalar >

Abstract interface for objects that represent a space for vectors.

This interface acts primarily as an "Abstract Factory" interface for creating VectorBase objects using the Thyra::createMember(). A VectorSpaceBase can also create MultiVectorBase objects which represent a compact collection of vectors. A secondary role for VectorSpaceBase objects is to test for compatibility of vector spaces (and the vectors and linear operators using those spaces) objects using the isCompatible() method.

Clients can not directly create VectorBase and MultiVectorBase objects using the member functions createMember(), createMembers(), createMemberView(), and createMembersView() but instead must use the non-member User callable creational functions for VectorBase and MultiVectorBase..

Note that a VectorSpaceBase object must also be able to create MultiVectorBase objects with any number of column vectors using the Thyra::createMembers() function. Once created, the LinearOpBase::domain() function supported by the created MultiVectorBase objects returns a vector space of that dimension. An interesting implication of this design is that the creation of a multi-vector provides a way for clients to create vector spaces of any arbitrary (although small usually) dimension. In order to give the client the same ability to create smaller vector spaces without having to create a dummy multi-vector object first, the method smallVecSpcFcty() is included. The method smallVecSpcFcty() returns a VectorSpaceFactoryBase object that can create (serial) vector spaces of any small dimension that are compatible with the domain spaces of so created MultiVectorBase objects.

A vector space is also where the scalar product for the space is defined which is computed by the scalarProd() method. A scalar product allows the vector space to introduce scaling into many different types of numerical algorithms.

If the underlying object is not initialized, then dim()==0 will be true and none of the other methods should be called or exceptions will be thrown.

Notes for subclass developers

This is a fairly bare-bones interface class without much in the way of default function implementations. The subclass VectorSpaceDefaultBase provides a default multi-vector implementation and should the the first choice for subclasses implementations.

Examples:: silly1DFFT_serial.cpp.

Definition at line 215 of file Thyra_VectorSpaceBaseDecl.hpp.

Member Function Documentation

template<class Scalar>

virtual Index Thyra::VectorSpaceBase< Scalar >::dim ( ) const [pure virtual]

Return the dimension of the vector space.
If the underlying object is not initialized, then dim()==0 will be true and none of the other methods should be called.
Implemented in Thyra::MPIVectorSpaceBase< Scalar >, Thyra::SerialVectorSpaceStd< Scalar >, and Thyra::ProductVectorSpace< Scalar >.

template<class Scalar>

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

Compare the compatibility of two vector spaces.
If this function returns true, then vectors created from either of the vector spaces will be compatible and can be combined in vector operations.
Preconditions:

this->dim() > 0

Postconditions:

[this->dim() != vecSpc.dim()] return == false

Invariants:

[this->isCompatible(vecSpc) == true] vecSpc.isCompatible(*this) == true

Implemented in Thyra::MPIVectorSpaceBase< Scalar >, Thyra::SerialVectorSpaceBase< Scalar >, and Thyra::ProductVectorSpace< Scalar >.

template<class Scalar>

virtual Teuchos::RefCountPtr< const VectorSpaceFactoryBase<Scalar> > Thyra::VectorSpaceBase< Scalar >::smallVecSpcFcty ( ) const [pure virtual]

Return a VectorSpaceFactoryBase object for the creation of (serial) vector spaces with a small dimension.
Preconditions:

this->dim() > 0

Implemented in Thyra::MPIVectorSpaceBase< Scalar >, Thyra::VectorSpaceDefaultBase< Scalar >, and Thyra::ProductVectorSpace< Scalar >.

template<class Scalar>

virtual Scalar Thyra::VectorSpaceBase< Scalar >::scalarProd ( const VectorBase< Scalar > & x,

const VectorBase< Scalar > & y

) const [pure virtual]

Return the scalar product of two vectors in the vector space.
Preconditions:

x.space()->isCompatible(*this) (throw Exceptions::IncompatibleVectorSpaces)

y.space()->isCompatible(*this) (throw Exceptions::IncompatibleVectorSpaces)

Postconditions:

The scalar product is returned.

Implemented in Thyra::ScalarProdVectorSpaceBase< Scalar >, and Thyra::ProductVectorSpace< Scalar >.

template<class Scalar>

virtual void Thyra::VectorSpaceBase< Scalar >::scalarProds ( const MultiVectorBase< Scalar > & X,

const MultiVectorBase< Scalar > & Y,

Scalar scalar_prods[]

) const [pure virtual]

Return the scalar product of each column in two multi-vectors in the vector space.

Parameters:

X [in] Multi-vector.

Y [in] Multi-vector.

scalar_prod [out] Array (length X.domain()->dim()) containing the scalar products scalar_prod[j-1] = this->scalarProd(*X.col(j),*Y.col(j)), for j = 1 ... X.domain()->dim().

Preconditions:

X.range()->isCompatible(*this) (throw Exceptions::IncompatibleVectorSpaces)

Y.range()->isCompatible(*this) (throw Exceptions::IncompatibleVectorSpaces)

X.domain()->isCompatible(*Y.domain()) (throw Exceptions::IncompatibleVectorSpaces)

Postconditions:

scalar_prod[j-1] = this->scalarProd(*X.col(j),*Y.col(j)), for j = 1 ... X.domain()->dim()

Implemented in Thyra::ScalarProdVectorSpaceBase< Scalar >, and Thyra::ProductVectorSpace< Scalar >.

template<class Scalar>

bool Thyra::VectorSpaceBase< Scalar >::isInCore ( ) const [virtual]

Returns if all of the vector elements are cheaply accessible on this processor.
Preconditions:

this->dim() > 0

The default implementation returns false.
Reimplemented in Thyra::MPIVectorSpaceBase< Scalar >, Thyra::SerialVectorSpaceBase< Scalar >, and Thyra::ProductVectorSpace< Scalar >.
Definition at line 41 of file Thyra_VectorSpaceBase.hpp.

template<class Scalar>

Teuchos::RefCountPtr< const VectorSpaceBase< Scalar > > Thyra::VectorSpaceBase< Scalar >::clone ( ) const [virtual]

Clone this object (if supported).
It is allowed for return.get()==NULL which means that this capability is optional.
Preconditions:

this->dim() > 0

The default implementation returns return.get()==NULL.
Reimplemented in Thyra::MPIVectorSpaceStd< Scalar >, Thyra::SerialVectorSpaceStd< Scalar >, and Thyra::ProductVectorSpace< Scalar >.
Definition at line 48 of file Thyra_VectorSpaceBase.hpp.

template<class Scalar>

virtual Teuchos::RefCountPtr< VectorBase<Scalar> > Thyra::VectorSpaceBase< Scalar >::createMember ( ) const [protected, pure virtual]

Create a vector member from the vector space.
Preconditions:

this->dim() > 0

Postconditions:

return.get() != NULL

return->dim() == this->dim()

return->space()->isCompatible(*this) == true

Note: This function is not to be called directly since it is protected! See the User callable creational functions for VectorBase and MultiVectorBase..

Returns:
Returns a smart reference counted pointer to a dynamically allocated vector object. After construction the values in the vector *return are unspecified (uninitialized). This allows for faster execution times. Note that return->space().get() == this need not be true.

Implemented in Thyra::MPIVectorSpaceStd< Scalar >, Thyra::SerialVectorSpaceStd< Scalar >, and Thyra::ProductVectorSpace< Scalar >.

template<class Scalar>

virtual Teuchos::RefCountPtr< MultiVectorBase<Scalar> > Thyra::VectorSpaceBase< Scalar >::createMembers ( int numMembers ) const [protected, pure virtual]

Create a set of vector members (a MultiVectorBase) from the vector space.
Preconditions:

this->dim() > 0

num_vecs >= 1

Postconditions:

return->range()->isCompatible(*this) == true

return->domain()->dim() == numMembers

Returns:
This method returns a smart reference-counted pointer to a dynamically allocated multi-vector object. After construction, the values in *return are unspecified (uninitialized). This allows for faster execution times. Note that return->range().get()==this does not have to be true but will be in may cases.

Implemented in Thyra::MPIVectorSpaceStd< Scalar >, Thyra::SerialVectorSpaceStd< Scalar >, Thyra::VectorSpaceDefaultBase< Scalar >, and Thyra::ProductVectorSpace< Scalar >.

template<class Scalar>

virtual Teuchos::RefCountPtr<VectorBase<Scalar> > Thyra::VectorSpaceBase< Scalar >::createMemberView ( const RTOpPack::MutableSubVectorT< Scalar > & raw_v ) const [protected, pure virtual]

Create a vector member that is a non-const view of raw vector data.

Parameters:

raw_v [in] On input contains pointer (i.e. raw_v.values()) to array that the returned VectorBase will be a view of. The data pointed to by raw_v.values() must remain valid until the returned VectorBase object is destroyed.

Preconditions:

raw_v has been initialized to memory (i.e. raw_v.subDim()!=0 && raw_v.values()!=NULL).

raw_v is consistent with the local storage of this vector spaces vector data. This precondition is purposefully vague since this function can be used an variety of specialized use-cases.

Postconditions:

See this->createMember()

It is stated here that the client can not expect that the values pointed to by raw_v.values() to be changed until the smart pointer return goes out of scope. This is to allow an implementation that temporarily copies data into and out of a VectorBase object using explicit vector access.
Implemented in Thyra::MPIVectorSpaceStd< Scalar >, and Thyra::VectorSpaceDefaultBase< Scalar >.

template<class Scalar>

virtual Teuchos::RefCountPtr<const VectorBase<Scalar> > Thyra::VectorSpaceBase< Scalar >::createMemberView ( const RTOpPack::SubVectorT< Scalar > & raw_v ) const [protected, pure virtual]

Create a vector member that is a const view of raw vector data.

Parameters:

raw_v [in] On input contains pointer (i.e. raw_v.values()) to array that the returned VectorBase will be a view of. The data pointed to by raw_v.values() must remain valid until the returned VectorBase object is destroyed.

This function works exactly the same as the previous version that takes a RTOpPack::MutableSubVectorT object except that this version takes a RTOpPack::SubVectorT and returns a smart pointer to a const VectorBase object.
Preconditions:

See the previous RTOpPack::MutableSubVectorT version of this function.

Postconditions:

See this->createMember()

Implemented in Thyra::MPIVectorSpaceStd< Scalar >, and Thyra::VectorSpaceDefaultBase< Scalar >.

template<class Scalar>

virtual Teuchos::RefCountPtr<MultiVectorBase<Scalar> > Thyra::VectorSpaceBase< Scalar >::createMembersView ( const RTOpPack::MutableSubMultiVectorT< Scalar > & raw_mv ) const [protected, pure virtual]

Create a multi-vector member that is a non-const view of raw multi-vector data.

Parameters:

raw_mv [in] On input contains pointer (i.e. raw_mv.values()) to array that the returned MultiVectorBase will be a view of.

Preconditions:

raw_mv has been initialized to memory (i.e. raw_mv.subDim()!=0 && raw_mv.values()!=NULL).

raw_mv is consistent with the local storage of this spaces vector data. This precondition is purposefully vague since this function can be used an variety of specialized use-cases.

Postconditions:

See this->createMembers() where numMembers==raw_mv.numSubCols()

It is stated here that the client can not expect that the values pointed to by raw_mv.values() to be changed until the smart pointer return goes out of scope. This is to allow for an implementation that temporarily copies data into and out of a MultiVectorBase object using explicit vector access.
Implemented in Thyra::MPIVectorSpaceStd< Scalar >, and Thyra::VectorSpaceDefaultBase< Scalar >.

template<class Scalar>

virtual Teuchos::RefCountPtr<const MultiVectorBase<Scalar> > Thyra::VectorSpaceBase< Scalar >::createMembersView ( const RTOpPack::SubMultiVectorT< Scalar > & raw_mv ) const [protected, pure virtual]

Create a multi-vector member that is a const view of raw multi-vector data.

Parameters:

raw_mv [in] On input contains pointer (i.e. raw_mv.values()) to array that the returned MultiVectorBase will be a view of. The data pointed to by raw_mv.values() must remain valid until the returned MultiVectorBase object is destroyed.

This function works exactly the same as the previous version that takes a RTOpPack::MutableSubMultiVectorT object except that this version takes a RTOpPack::SubMultiVectorT object and returns a smart pointer to a const MultiVectorBase object.
Preconditions:

See the previous RTOpPack::MutableSubMultiVectorT version of this function.

Postconditions:

See this->createMember()

Implemented in Thyra::MPIVectorSpaceStd< Scalar >, and Thyra::VectorSpaceDefaultBase< Scalar >.

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

Generated on Thu Sep 18 12:39:53 2008 for Thyra ANA Operator/VectorBase Interfaces and Related Software by

1.3.9.1

Thyra::VectorSpaceBase< Scalar > Class Template Reference [C++ code for foundational Thyra operator/vector interfaces]

Public pure virtual functions that must be overridden

Public virtual functions with default implementations

Protected pure virtual functions that must be overridden

Detailed Description

template<class Scalar> class Thyra::VectorSpaceBase< Scalar >

Member Function Documentation

Thyra::VectorSpaceBase< Scalar > Class Template Reference
[C++ code for foundational Thyra operator/vector interfaces]

template<class Scalar>
class Thyra::VectorSpaceBase< Scalar >