AbstractLinAlgPack: C++ Interfaces For Vectors, Matrices And Related Linear Algebra Objects Version of the Day
Classes | Public Types | Public Member Functions
AbstractLinAlgPack::VectorSpace Class Reference

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

#include <AbstractLinAlgPack_VectorSpace.hpp>

Inheritance diagram for AbstractLinAlgPack::VectorSpace:
Inheritance graph
[legend]

List of all members.

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.
space_ptr_t sub_space (const index_type il, const index_type iu) const
 Inlined to call this->sub_space(Range1D(il,iu)).
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.

Constructors / initializers

 VectorSpace (const inner_prod_ptr_t &inner_prod=Teuchos::null)
 Calls inner_prod()
virtual void inner_prod (const inner_prod_ptr_t &inner_prod)
 Initialize with an inner product object.
virtual const inner_prod_ptr_t inner_prod () const
 Return the smart pointer to the inner product strategy object.

Pure virtual functions that must be overridden

virtual space_ptr_t clone () const =0
 Create a clone of this vector space object.
virtual bool is_compatible (const VectorSpace &vec_spc) const =0
 Compare the compatibility of two vector spaces.
virtual index_type dim () const =0
 Return the dimmension of the vector space.
virtual vec_mut_ptr_t create_member () const =0
 Create a vector member from the vector space.

Virtual functions with default implementations

virtual bool is_in_core () const
 Returns true if the vectors are in core.
virtual space_fcty_ptr_t small_vec_spc_fcty () const
 Return a VectorSpaceFactory object for the creation of vector spaces with a small dimension.
virtual vec_mut_ptr_t create_member (const value_type &alpha) const
 Create a vector member from the vector space initialized to a scalar.
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.

Overridden from AbstractFactory

obj_ptr_t create () const
 Just calls this->create_member() by default!

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

Definition at line 142 of file AbstractLinAlgPack_VectorSpace.hpp.

Definition at line 144 of file AbstractLinAlgPack_VectorSpace.hpp.

Definition at line 146 of file AbstractLinAlgPack_VectorSpace.hpp.

Definition at line 148 of file AbstractLinAlgPack_VectorSpace.hpp.

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::VectorSpaceSubSpace, AbstractLinAlgPack::VectorSpaceBlocked, 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::VectorSpaceSubSpace, AbstractLinAlgPack::VectorSpaceBlocked, and AbstractLinAlgPack::VectorSpaceSerial.

virtual index_type AbstractLinAlgPack::VectorSpace::dim ( ) const [pure virtual]
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::VectorSpaceSubSpace, AbstractLinAlgPack::VectorSpaceBlocked, 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::VectorSpaceSubSpace, AbstractLinAlgPack::VectorSpaceBlocked, and AbstractLinAlgPack::VectorSpaceSerial.

Definition at line 104 of file AbstractLinAlgPack_VectorSpace.cpp.

VectorSpace::space_ptr_t AbstractLinAlgPack::VectorSpace::sub_space ( const index_type  il,
const index_type  iu 
) const [inline]

Inlined to call this->sub_space(Range1D(il,iu)).

Definition at line 407 of file AbstractLinAlgPack_VectorSpace.hpp.

VectorSpace::space_ptr_t AbstractLinAlgPack::VectorSpace::space ( const GenPermMatrixSlice P,
BLAS_Cpp::Transp  P_trans 
) const [virtual]

Create a vector space for vector to gather the elements into.

Parameters:
P[in] A GenPermMatrixSlice object specifying the map.
P_trans[in] Determines if P is transposed or not.

Preconditions:

  • ???

Postconditions:

  • [return.get()!=NULL] return->space(P,trans_not(P_trans))->is_compatible(*this) == true
Returns:
Returns a smart reference counted pointer to a dynamically allocated vector space object.

ToDo: Finish documentation!

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

Reimplemented in AbstractLinAlgPack::VectorSpaceSerial.

Definition at line 124 of file AbstractLinAlgPack_VectorSpace.cpp.

VectorSpace::obj_ptr_t AbstractLinAlgPack::VectorSpace::create ( ) const [virtual]

Just calls this->create_member() by default!

Implements Teuchos::AbstractFactory< VectorMutable >.

Definition at line 139 of file AbstractLinAlgPack_VectorSpace.cpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends