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

#include <AbstractLinAlgPack_VectorSpace.hpp>

Inheritance diagram for AbstractLinAlgPack::VectorSpace:

Classes
class	IncompatibleVectorSpaces
	Thrown if vector spaces are incompatible. More...

Public Types
typedef Teuchos::RCP< const InnerProduct >	inner_prod_ptr_t

typedef Teuchos::RCP< const VectorSpace >	space_ptr_t

typedef Teuchos::RCP< const VectorSpaceFactory >	space_fcty_ptr_t

typedef Teuchos::RCP < VectorMutable >	vec_mut_ptr_t

typedef Teuchos::RCP < MultiVectorMutable >	multi_vec_mut_ptr_t

Public Member Functions
virtual space_ptr_t	sub_space (const Range1D &rng) const
	Create a transient sub-space of the current vector space. More...

space_ptr_t	sub_space (const index_type il, const index_type iu) const
	Inlined to call `this->sub_space(Range1D(il,iu))`. More...

virtual space_ptr_t	space (const GenPermMatrixSlice &P, BLAS_Cpp::Transp P_trans) const
	Create a vector space for vector to gather the elements into. More...

Constructors / initializers
	VectorSpace (const inner_prod_ptr_t &inner_prod=Teuchos::null)
	Calls `inner_prod()` More...

virtual void	inner_prod (const inner_prod_ptr_t &inner_prod)
	Initialize with an inner product object. More...

virtual const inner_prod_ptr_t	inner_prod () const
	Return the smart pointer to the inner product strategy object. More...

Pure virtual functions that must be overridden
virtual space_ptr_t	clone () const =0
	Create a clone of `this` vector space object. More...

virtual bool	is_compatible (const VectorSpace &vec_spc) const =0
	Compare the compatibility of two vector spaces. More...

virtual index_type	dim () const =0
	Return the dimmension of the vector space. More...

virtual vec_mut_ptr_t	create_member () const =0
	Create a vector member from the vector space. More...

Virtual functions with default implementations
virtual bool	is_in_core () const
	Returns true if the vectors are in core. More...

virtual space_fcty_ptr_t	small_vec_spc_fcty () const
	Return a `VectorSpaceFactory` object for the creation of vector spaces with a small dimension. More...

virtual vec_mut_ptr_t	create_member (const value_type &alpha) const
	Create a vector member from the vector space initialized to a scalar. More...

virtual multi_vec_mut_ptr_t	create_members (size_type num_vecs) const
	Create a set of vector members (a `MultiVectorMutable`) from the vector space. More...

Overridden from AbstractFactory
obj_ptr_t	create () const
	Just calls `this->create_member()` by default! More...

Detailed Description

Abstract interface for objects that represent a space for mutable coordinate vectors.

This interface acts primarily as an "Abstract Factory" interface for creating VectorMutable objects using the create_member() method. A VectorSpace object may also be able to create MultiVectorMutable objects which represent a compact collection of vectors. Every application area should be able to define a MultiVectorMutable subclass if it can define a VectorMutable subclass. A secondary role for VectorSpace objects is to test for compatibility of vector spaces (and the vectors and matrix using those spaces) objects using the is_compatible() method.

Given a VectorSpace object it may also be possible to create sub-spaces using the sub_space() method. This subspace is not a sub-space in the mathematical sense but instead referese to a sub-range of vector elements.

Any VectorSpace object can be copied using the clone() method. Therefore, clients have complete control over the lifetime of VectorSpace objects.

A VectorSpace object can exist independent from any individual VectorMutable (or MutiVectorMutable) object; Or, a VectorSpace object can have a lifetime that is dependent on a single Vector ( or MultiVector) object. The same interface can serve both roles.

Note that a VectorSpace object can create MultiVectorMutable objects with any number of column vectors, and MultiVector::space_rows() gives a vector space of the dimension. Therefore, 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 without having to create a multi-vector, the method small_vec_spc_fcty() returns a VectorSpaceFactory object that can create vector spaces of small dimension. These created vector spaces can be used by the created MultiVectorMutable objects (see create_members()). These vector spaces are also used for the default implementation of space(P,P_trans) (see below). Since a VectorSpace object is not required to create MultiVectorMutable objects using create_members() a VectorSpace object is also not required to return a VectorSpaceFactory object from small_vec_spc_fcty(). to be consistent.

A vector space is also where the inner product for the space is defined. It is anticipated that the same implementation of vectors and vector spaces will be reused over and over again with different definitions of the inner product. Therefore, the inner product is represented as a seperate strategy object. For example, the same parallel vector implementation can be used with several different inner product definitions. In some cases, the same inner product stategy object may be able to be used with diffeent vector implemenations (such as the dot product for example).

Note that the default copy constructor will transfer the inner product object correctly but the subclass must make sure to copy the inner product object in clone() operation. This is little price to pay considering what this design takes care of already for VectorSpace subclasses. However, the default copy constructor will only make a shallow copy of the inner product object but since this object may never be changed, this is perhaps the correct behavior. For any other behavior and the subbclass will have to take care of it.

A vector space may also have another advanced feature; it may be able to define other vector spaces based on a gather operation of selected vector elements given a GenPermMatrixSlice (GPMS) object. For example, suppose that a GPMS object P is defined which extracts a (relatively) small number of elements of a vector v (from the vector space *this) and gathers them into a small vector q.

q = op(P)*v

The question is, to what vector space Q does the vector q belong? The answer is returned by the method Q = this->space(P,P_trans). Theoretically, op(P) could be any GPMS object and this->space(P,P_trans) should always be able to return a non-NULL vector space object. In reality, the client should only expect this->space(P,P_trans).get() != NULL if q_dim = BLAS_Cpp::rows( P.rows(), P.cols(), P_trans ) is a relatively small number (i.e. less than a few thousand). If q_dim is small, then the vector q can always be represented as a local serial vector. This is not a terribly difficult requirement and any VectorSpace subclass should be able to comply.

The returned vector space Q must have the property that the scatter operation is also defined. In other words, it must be that:

 this->space(P,P_trans)->space(P,trans_not(P_trans))->is_compatible(*this) == true

This property insures that the gather and scatter operations can be implemented properly.

Definition at line 133 of file AbstractLinAlgPack_VectorSpace.hpp.

Member Typedef Documentation

typedef Teuchos::RCP<const InnerProduct> AbstractLinAlgPack::VectorSpace::inner_prod_ptr_t

Definition at line 142 of file AbstractLinAlgPack_VectorSpace.hpp.

typedef Teuchos::RCP<const VectorSpace> AbstractLinAlgPack::VectorSpace::space_ptr_t

Definition at line 144 of file AbstractLinAlgPack_VectorSpace.hpp.

typedef Teuchos::RCP<const VectorSpaceFactory> AbstractLinAlgPack::VectorSpace::space_fcty_ptr_t

Definition at line 146 of file AbstractLinAlgPack_VectorSpace.hpp.

typedef Teuchos::RCP<VectorMutable> AbstractLinAlgPack::VectorSpace::vec_mut_ptr_t

Definition at line 148 of file AbstractLinAlgPack_VectorSpace.hpp.

typedef Teuchos::RCP<MultiVectorMutable> AbstractLinAlgPack::VectorSpace::multi_vec_mut_ptr_t

Definition at line 150 of file AbstractLinAlgPack_VectorSpace.hpp.

Constructor & Destructor Documentation

AbstractLinAlgPack::VectorSpace::VectorSpace ( const inner_prod_ptr_t & inner_prod = Teuchos::null )

Calls inner_prod()

Definition at line 55 of file AbstractLinAlgPack_VectorSpace.cpp.

Member Function Documentation

virtual void AbstractLinAlgPack::VectorSpace::inner_prod ( const inner_prod_ptr_t & inner_prod )

virtual

Initialize with an inner product object.

Parameters

inner_prod [in] Smart pointer to inner product strategy object. If inner_prod.get()==NULL then an InnerProductDot object will be used instead.

Postconditions:

[inner_prod.get() != NULL] this->inner_prod().get() == inner_prod.get()
[inner_prod.get() == NULL] dynamic_cast<InnerProductDot*>(this->inner_prod().get()) != NULL

virtual const inner_prod_ptr_t AbstractLinAlgPack::VectorSpace::inner_prod ( ) const

virtual

Return the smart pointer to the inner product strategy object.

Postconditions:

return.get() != NULL

virtual space_ptr_t AbstractLinAlgPack::VectorSpace::clone ( ) const

pure virtual

Create a clone of this vector space object.

The returned vector space object is expected to be independent from this and have a lifetime that extends beyond this. This makes a vector space class a little hander to implement by makes for much better flexibility for the client. A complete implementation of VectorSpace is not allowed to return NULL from this method.

Postconditions:

return.get() != NULL

Implemented in AbstractLinAlgPack::VectorSpaceBlocked, AbstractLinAlgPack::VectorSpaceSubSpace, and AbstractLinAlgPack::VectorSpaceSerial.

virtual bool AbstractLinAlgPack::VectorSpace::is_compatible ( const VectorSpace & vec_spc ) 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.

Invariants:

[this->is_compatible(vec_spc) == true] vec_spc.is_compatible(*this) == true

Postconditions:

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

Implemented in AbstractLinAlgPack::VectorSpaceBlocked, AbstractLinAlgPack::VectorSpaceSubSpace, and AbstractLinAlgPack::VectorSpaceSerial.

virtual index_type AbstractLinAlgPack::VectorSpace::dim ( ) const

pure virtual

Return the dimmension of the vector space.

Implemented in AbstractLinAlgPack::VectorSpaceBlocked, AbstractLinAlgPack::VectorSpaceSubSpace, and AbstractLinAlgPack::VectorSpaceSerial.

virtual vec_mut_ptr_t AbstractLinAlgPack::VectorSpace::create_member ( ) const

pure virtual

Create a vector member from the vector space.

Postconditions:

return.get() != NULL
return->dim() == this->dim()
return->space().is_compatible(*this) == true

Returns: Returns a smart reference counted pointer to a dynamically allocated vector object. After construction the values returnd by return->get_ele(i) are unspecified (uninitialized). This allows for faster execution times. Note that &return->space() does not have to be equal to this.

Implemented in AbstractLinAlgPack::VectorSpaceBlocked, AbstractLinAlgPack::VectorSpaceSubSpace, and AbstractLinAlgPack::VectorSpaceSerial.

bool AbstractLinAlgPack::VectorSpace::is_in_core ( ) const

virtual

Returns true if the vectors are in core.

If this function returns true then it means that the vector access functions Vector::get_sub_vector() and VectorMutable::get_sub_vector() can be safely called and can be expected to be fairly efficient. If this function does return true then the functions Vector::get_sub_vector(), Vector::free_sub_vector(), VectorMutable::get_sub_vector() and VectorMutable::commit_sub_vector() had better be overridden and had better not call Vector::apply_op(...).

The default implementation returns false

Reimplemented in AbstractLinAlgPack::VectorSpaceSubSpace, and AbstractLinAlgPack::VectorSpaceSerial.

Definition at line 77 of file AbstractLinAlgPack_VectorSpace.cpp.

VectorSpace::space_fcty_ptr_t AbstractLinAlgPack::VectorSpace::small_vec_spc_fcty ( ) const

virtual

Return a VectorSpaceFactory object for the creation of vector spaces with a small dimension.

ToDo: Finish documentation!

The default implementation returns return.get() == NULL.

Reimplemented in AbstractLinAlgPack::VectorSpaceBlocked, and AbstractLinAlgPack::VectorSpaceSerial.

Definition at line 83 of file AbstractLinAlgPack_VectorSpace.cpp.

VectorSpace::vec_mut_ptr_t AbstractLinAlgPack::VectorSpace::create_member ( const value_type & alpha ) const

virtual

Create a vector member from the vector space initialized to a scalar.

Parameters

alpha [in] Scalar that all elements of allocated vector are initialized to.

Postconditions:

return.get() != NULL
return->dim() == this->dim()
return->space().is_compatible(*this) == true

Returns: Returns a smart reference counted pointer to a dynamically allocated vector object. After construction the values returnd by return->get_ele(i) are equal to alpha. Note that &return->space() does not have to be equal to this.

The default implementation just calls create_member() and then assigns alpha before returning the smart pointer object.

Definition at line 89 of file AbstractLinAlgPack_VectorSpace.cpp.

VectorSpace::multi_vec_mut_ptr_t AbstractLinAlgPack::VectorSpace::create_members ( size_type num_vecs ) const

virtual

Create a set of vector members (a MultiVectorMutable) from the vector space.

Preconditions:

num_vecs >= 1 (throw ???)

Postconditions:

[return.get() != NULL] return->space_cols().is_compatible(*this) == true
[return.get() != NULL] return->space_rows().dim() == num_vecs
[return.get() != NULL] (return->access_by() & MultiVector::COL_ACCESS) == true

Returns: Returns a smart reference counted pointer to a dynamically allocated multi-vector object. After construction the values returnd by return->col(j)->get_ele(i) are unspecified (uninitialized). This allows for faster execution times. Note that &return->space_cols() does not have to be equal to this. It is allowed for a vector space implementation to refuse to create multi-vectors and can return NULL from this method.

The default implementation just returns NULL.

Reimplemented in AbstractLinAlgPack::VectorSpaceBlocked, and AbstractLinAlgPack::VectorSpaceSerial.

Definition at line 98 of file AbstractLinAlgPack_VectorSpace.cpp.

VectorSpace::space_ptr_t AbstractLinAlgPack::VectorSpace::sub_space ( const Range1D & rng ) const

virtual

Create a transient sub-space of the current vector space.

Parameters

rng	[in] The range of the elements to extract a vector sub-space.

Preconditions:

rng.ubound() <= this->dim() (throw std::out_of_range)

Postconditions:

[return.get() != NULL] return->dim() == rng->size()

Returns: Returns a smart reference counted pointer to a dynamically allocated vector space object. Note that the vector object returned by this->sub_space(rng).create_member() should be exactly equivalent to the vector returned by this->create_member()->sub_view(rng)->space()->create_member(). It is allowed for the implementation to return return->get() == NULL for arbitrary values of rng. Only some rng ranges may be allowed but they will be appropriate for the application at hand. However, a very good implementation should be able to accomidate any valid rng that meets the basic preconditions.

Note that if two vector space objects X and Y are compatible (i.e. X.is_compatible(Y) == true, then it is also expected that X.sub_space(rng)->is_compatible(*Y.sub_space(rng)) will also be true. However, in general it can not be expected that X.sub_space(rng1)->is_compatible(*X.sub_space(rng2)) == true, even if rng1.size() == rng2.size(). For serial vectors, it may be but for parallel vectors it will most certainly not be. Therefore, in general, don't assume that arbitrary subsets of the vector spaces will be compatible, even if the sizes of these subspaces are the same.

The default implementation uses the subclass VectorSpaceSubSpace to represent any arbitrary sub-space but this can be very inefficient if the sub-space is very small compared this this full vector space.

Reimplemented in AbstractLinAlgPack::VectorSpaceBlocked, AbstractLinAlgPack::VectorSpaceSubSpace, and AbstractLinAlgPack::VectorSpaceSerial.

Definition at line 104 of file AbstractLinAlgPack_VectorSpace.cpp.