AbstractLinAlgPack: C++ Interfaces For Vectors, Matrices And Related Linear Algebra Objects Version of the Day

Abstract interface for objects that represent a space for mutable coordinate vectors. More...
#include <AbstractLinAlgPack_VectorSpace.hpp>
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 subspace 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! 
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 subspaces using the sub_space()
method. This subspace is not a subspace in the mathematical sense but instead referese to a subrange 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 multivector 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 multivector, 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 nonNULL 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.
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.
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.
AbstractLinAlgPack::VectorSpace::VectorSpace  (  const inner_prod_ptr_t &  inner_prod = Teuchos::null  ) 
Calls inner_prod()
Definition at line 55 of file AbstractLinAlgPack_VectorSpace.cpp.
virtual void AbstractLinAlgPack::VectorSpace::inner_prod  (  const inner_prod_ptr_t &  inner_prod  )  [virtual] 
Initialize with an inner product object.
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] 
Return the dimmension of the vector space.
Implemented in AbstractLinAlgPack::VectorSpaceSubSpace, AbstractLinAlgPack::VectorSpaceBlocked, 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_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.
alpha  [in] Scalar that all elements of allocated vector are initialized to. 
Postconditions:
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
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 multivectors 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 subspace of the current vector space.
rng  [in] The range of the elements to extract a vector subspace. 
Preconditions:
rng.ubound() <= this>dim()
(throw std::out_of_range
) Postconditions:
return.get() != NULL
] return>dim() == rng>size()
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 subspace but this can be very inefficient if the subspace 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.
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 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.