#include <AbstractLinAlgPack_VectorSpace.hpp>
Inheritance diagram for AbstractLinAlgPack::VectorSpace:
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! | |
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. | |
Private Attributes | |
const InnerProduct * | inner_prod |
Classes | |
class | IncompatibleVectorSpaces |
Thrown if vector spaces are incompatible. More... |
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
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
Definition at line 120 of file AbstractLinAlgPack_VectorSpace.hpp.
typedef Teuchos::RCP<const VectorSpace> AbstractLinAlgPack::VectorSpace::space_ptr_t |
VectorSpace::VectorSpace | ( | const inner_prod_ptr_t & | inner_prod = Teuchos::null |
) |
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. |
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, AbstractLinAlgPack::VectorSpaceSerial, and AbstractLinAlgPack::VectorSpaceThyra.
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, AbstractLinAlgPack::VectorSpaceSerial, and AbstractLinAlgPack::VectorSpaceThyra.
virtual index_type AbstractLinAlgPack::VectorSpace::dim | ( | ) | const [pure virtual] |
Return the dimmension of the vector space.
Implemented in AbstractLinAlgPack::VectorSpaceSubSpace, AbstractLinAlgPack::VectorSpaceBlocked, AbstractLinAlgPack::VectorSpaceSerial, and AbstractLinAlgPack::VectorSpaceThyra.
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, AbstractLinAlgPack::VectorSpaceSerial, and AbstractLinAlgPack::VectorSpaceThyra.
bool 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, AbstractLinAlgPack::VectorSpaceSerial, and AbstractLinAlgPack::VectorSpaceThyra.
Definition at line 64 of file AbstractLinAlgPack_VectorSpace.cpp.
VectorSpace::space_fcty_ptr_t 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, AbstractLinAlgPack::VectorSpaceSerial, and AbstractLinAlgPack::VectorSpaceThyra.
Definition at line 70 of file AbstractLinAlgPack_VectorSpace.cpp.
VectorSpace::vec_mut_ptr_t 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. |
return->get_ele(i)
are equal to alpha
. Note that &return->space()
does not have to be equal to this
.create_member()
and then assigns alpha
before returning the smart pointer object.
Definition at line 76 of file AbstractLinAlgPack_VectorSpace.cpp.
VectorSpace::multi_vec_mut_ptr_t 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 multi-vectors and can return NULL
from this method.NULL
.
Reimplemented in AbstractLinAlgPack::VectorSpaceBlocked, AbstractLinAlgPack::VectorSpaceSerial, and AbstractLinAlgPack::VectorSpaceThyra.
Definition at line 85 of file AbstractLinAlgPack_VectorSpace.cpp.
VectorSpace::space_ptr_t VectorSpace::sub_space | ( | const Range1D & | rng | ) | const [virtual] |
Create a transient sub-space of the current vector space.
rng | [in] The range of the elements to extract a vector sub-space. |
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.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 91 of file AbstractLinAlgPack_VectorSpace.cpp.
VectorSpace::space_ptr_t 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 394 of file AbstractLinAlgPack_VectorSpace.hpp.
VectorSpace::space_ptr_t 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. |
Postconditions:
return.get()!=NULL
] return->space(P,trans_not(P_trans))->is_compatible(*this) == true
The default implementation returns return.get() == NULL
.
Reimplemented in AbstractLinAlgPack::VectorSpaceSerial.
Definition at line 111 of file AbstractLinAlgPack_VectorSpace.cpp.
VectorSpace::obj_ptr_t VectorSpace::create | ( | ) | const [virtual] |
Just calls this->create_member()
by default!
Implements Teuchos::AbstractFactory< T >.
Definition at line 126 of file AbstractLinAlgPack_VectorSpace.cpp.
const VectorSpace::inner_prod_ptr_t VectorSpace::inner_prod [private] |
Definition at line 382 of file AbstractLinAlgPack_VectorSpace.hpp.