#include <Thyra_VectorBase.hpp>
Inheritance diagram for Thyra::VectorBase< Scalar >:
Space membership | |
virtual RCP< const VectorSpaceBase< Scalar > > | space () const =0 |
Return a smart pointer to the vector space that this vector belongs to. | |
Reduction/Transformation operator support | |
void | applyOp (const RTOpPack::RTOpT< Scalar > &op, const ArrayView< const Ptr< const VectorBase< Scalar > > > &vecs, const ArrayView< const Ptr< VectorBase< Scalar > > > &targ_vecs, const Ptr< RTOpPack::ReductTarget > &reduct_obj, const Ordinal first_ele_offset, const Ordinal sub_dim, const Ordinal global_offset) const |
Calls applyOpImpl(). | |
Vector Cloning | |
virtual RCP< VectorBase< Scalar > > | clone_v () const =0 |
Returns a cloned copy of *this vector. | |
Explicit sub-vector access | |
void | acquireDetachedView (const Range1D &rng, RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const |
Calls acquireDetachedVectorViewImpl(). | |
void | releaseDetachedView (RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const |
Calls releaseDetachedVectorViewImpl(). | |
void | acquireDetachedView (const Range1D &rng, RTOpPack::SubVectorView< Scalar > *sub_vec) |
Calls acquireNonconstDetachedVectorViewImpl(). | |
void | commitDetachedView (RTOpPack::SubVectorView< Scalar > *sub_vec) |
Calls commitDetachedView(). | |
void | setSubVector (const RTOpPack::SparseSubVectorT< Scalar > &sub_vec) |
Calls setSubVectorImpl(). | |
Protected virtual functions to be overridden by subclasses | |
virtual void | applyOpImpl (const RTOpPack::RTOpT< Scalar > &op, const ArrayView< const Ptr< const VectorBase< Scalar > > > &vecs, const ArrayView< const Ptr< VectorBase< Scalar > > > &targ_vecs, const Ptr< RTOpPack::ReductTarget > &reduct_obj, const Ordinal first_ele_offset, const Ordinal sub_dim, const Ordinal global_offset) const =0 |
Apply a reduction/transformation operator over a set of vectors: op(op(v[0]...v[nv-1],z[0]...z[nz-1]),(*reduct_obj)) -> z[0]...z[nz-1],(*reduct_obj) . | |
virtual void | acquireDetachedVectorViewImpl (const Range1D &rng, RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const =0 |
Get a non-mutable explicit view of a sub-vector. | |
virtual void | releaseDetachedVectorViewImpl (RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const =0 |
Free an explicit view of a sub-vector. | |
virtual void | acquireNonconstDetachedVectorViewImpl (const Range1D &rng, RTOpPack::SubVectorView< Scalar > *sub_vec)=0 |
Get a mutable explicit view of a sub-vector. | |
virtual void | commitNonconstDetachedVectorViewImpl (RTOpPack::SubVectorView< Scalar > *sub_vec)=0 |
Commit changes for a mutable explicit view of a sub-vector. | |
virtual void | setSubVectorImpl (const RTOpPack::SparseSubVectorT< Scalar > &sub_vec)=0 |
Set a specific sub-vector. | |
Related Functions | |
(Note that these are not member functions.) | |
void | applyOp (const RTOpPack::RTOpT< Scalar > &op, const ArrayView< const Ptr< const VectorBase< Scalar > > > &vecs, const ArrayView< const Ptr< VectorBase< Scalar > > > &targ_vecs, const Ptr< RTOpPack::ReductTarget > &reduct_obj, const Ordinal first_ele_offset=0, const Ordinal sub_dim=-1, const Ordinal global_offset=0) |
Apply a reduction/transformation operator over a set of vectors: op(op(v[0]...v[nv-1],z[0]...z[nz-1]),(*reduct_obj)) -> z[0]...z[nz-1],(*reduct_obj) . | |
void | applyOp (const RTOpPack::RTOpT< Scalar > &op, const int num_vecs, const VectorBase< Scalar > *const vecs_in[], const int num_targ_vecs, VectorBase< Scalar > *const targ_vecs_inout[], RTOpPack::ReductTarget *reduct_obj, const Ordinal first_ele_offset=0, const Ordinal sub_dim=-1, const Ordinal global_offset=0) |
Deprecated. |
This interface contains the minimal set of operations needed to define an abstract vector.
applyOp()
which is used to implement all types of vector reduction and transformation operations (RTOp) through RTOp operators . Every standard (i.e. BLAS) and nearly every non-standard element-wise operation that can be performed on a set of vectors can be performed efficiently through reduction/transformation operators. More standard vector operations could be included in this interface and allow for specialized implementations but, in general, assuming the sub-vectors are large enough, such implementations would not be significantly faster than those implemented through reduction/transformation operators. There are some operations however that can not always be efficiently implemented with reduction/transformation operators and a few of these important operations are included in this interface. The applyOp()
function allows to client to specify a sub-set of the vector elements to include in reduction/transformation operation. This greatly increases the generality of this vector interface as vector objects can be used as sub objects in larger composite vectors and sub-views of a vector can be created.applyOp()
. These wrapper functions can be found hereRTOpPack::ConstSubVectorView
or mutable RTOpPack::SubVectorView
objects using the acquireDetachedView()
functions. In general, this is a very inefficient thing to do and should be avoided. However, there are some situations where getting explicit access to the coefficients of a vector is a very reasonable and efficient thing to do (i.e. for vectors in the domain of a multi-vector for instance) and therefore this functionality is supported. These views and the parent vector follow the state behavior outlined here.ConstDetachedVectorView
and DetachedVectorView
instead since these are easier an safer in the event that an exception is thrown.setSubVector()
.VectorBase
interface class also inherits from MultiVectorBase
so that every VectorBase
object is also a MultiVectorBase
object. This allows any piece of code that accepts MultiVectorBase
objects to automatically accept VectorBase
objects as well. In addition, since MultiVectorBase
inherits from LinearOpBase
, then this means that every vector is also a linear operator.VectorDefaultBase
provides default implementations for as many functions as possible and should be considered a first choice for creating concrete subclasses.
Definition at line 133 of file Thyra_VectorBase.hpp.
virtual RCP< const VectorSpaceBase<Scalar> > Thyra::VectorBase< Scalar >::space | ( | ) | const [pure virtual] |
Return a smart pointer to the vector space that this vector belongs to.
A return value of space().get()==NULL
is a flag that *this
is not fully initialized.
If return.get()!=NULL
, then it is required that the object referenced by *return.get()
must have lifetime that extends past the lifetime of the returned smart pointer object. However, the object referenced by *return.get()
may change if *this
is modified so this reference should not be maintained for too long.
New Behavior! It is required that the VectorSpaceBase
object embedded in return
must be valid past the lifetime of *this
vector object.
void Thyra::VectorBase< Scalar >::applyOp | ( | const RTOpPack::RTOpT< Scalar > & | op, | |
const ArrayView< const Ptr< const VectorBase< Scalar > > > & | vecs, | |||
const ArrayView< const Ptr< VectorBase< Scalar > > > & | targ_vecs, | |||
const Ptr< RTOpPack::ReductTarget > & | reduct_obj, | |||
const Ordinal | first_ele_offset, | |||
const Ordinal | sub_dim, | |||
const Ordinal | global_offset | |||
) | const [inline] |
virtual RCP<VectorBase<Scalar> > Thyra::VectorBase< Scalar >::clone_v | ( | ) | const [pure virtual] |
Returns a cloned copy of *this
vector.
This function exists to be consistent with the clone functions clone()
which creates a LinearOpBase
object and clone_mv()
which creates a MultiVectorBase
object. However, this function is not really necessary because this capability is already present by using the VectorSpaceBase
returned from this->space()
.
Subclasses should only consider overriding this function if there they want to be very sophisticated and implement some form of lazy evaluation in case the created object might not actually be modified before it is destroyed. However, this is not advised.
void Thyra::VectorBase< Scalar >::acquireDetachedView | ( | const Range1D & | rng, | |
RTOpPack::ConstSubVectorView< Scalar > * | sub_vec | |||
) | const [inline] |
Calls acquireDetachedVectorViewImpl().
Temporary NVI function.
Definition at line 213 of file Thyra_VectorBase.hpp.
void Thyra::VectorBase< Scalar >::releaseDetachedView | ( | RTOpPack::ConstSubVectorView< Scalar > * | sub_vec | ) | const [inline] |
Calls releaseDetachedVectorViewImpl().
Temporary NVI function.
Definition at line 222 of file Thyra_VectorBase.hpp.
void Thyra::VectorBase< Scalar >::acquireDetachedView | ( | const Range1D & | rng, | |
RTOpPack::SubVectorView< Scalar > * | sub_vec | |||
) | [inline] |
Calls acquireNonconstDetachedVectorViewImpl().
Temporary NVI function.
Definition at line 231 of file Thyra_VectorBase.hpp.
void Thyra::VectorBase< Scalar >::commitDetachedView | ( | RTOpPack::SubVectorView< Scalar > * | sub_vec | ) | [inline] |
Calls commitDetachedView().
Temporary NVI function.
Definition at line 240 of file Thyra_VectorBase.hpp.
void Thyra::VectorBase< Scalar >::setSubVector | ( | const RTOpPack::SparseSubVectorT< Scalar > & | sub_vec | ) | [inline] |
Calls setSubVectorImpl().
Temporary NVI function.
Definition at line 249 of file Thyra_VectorBase.hpp.
virtual void Thyra::VectorBase< Scalar >::applyOpImpl | ( | const RTOpPack::RTOpT< Scalar > & | op, | |
const ArrayView< const Ptr< const VectorBase< Scalar > > > & | vecs, | |||
const ArrayView< const Ptr< VectorBase< Scalar > > > & | targ_vecs, | |||
const Ptr< RTOpPack::ReductTarget > & | reduct_obj, | |||
const Ordinal | first_ele_offset, | |||
const Ordinal | sub_dim, | |||
const Ordinal | global_offset | |||
) | const [protected, pure virtual] |
Apply a reduction/transformation operator over a set of vectors: op(op(v[0]...v[nv-1],z[0]...z[nz-1]),(*reduct_obj)) -> z[0]...z[nz-1],(*reduct_obj)
.
Preconditions:
this->space().get()!=NULL
(throw std::logic_error
)
The vector *this
that this function is called on is assumed to be one of the vectors in v[0]...v[nv-1],z[0]...z[nz-1]
. This function is generally should not called directly by a client but instead the client should call the nonmember function Thyra::applyOp()
.
See the documentation for the nonmember function Thyra::applyOp()
for a description of what this function does.
virtual void Thyra::VectorBase< Scalar >::acquireDetachedVectorViewImpl | ( | const Range1D & | rng, | |
RTOpPack::ConstSubVectorView< Scalar > * | sub_vec | |||
) | const [protected, pure virtual] |
Get a non-mutable explicit view of a sub-vector.
rng | [in] The range of the elements to extract the sub-vector view. | |
sub_vec | [in/out] View of the sub-vector. Prior to the first call to this function, sub_vec->set_uninitialized() must be called. Technically *sub_vec owns the memory but this memory can be freed only by calling this->releaseDetachedView(sub_vec) . |
this->space().get()!=NULL
(throw std::logic_error
) !rng.full_range()
] (rng.ubound() < this->space()->dim()) == true
(throw std::out_of_range
) Postconditions:
*sub_vec
contains an explicit non-mutable view to the elements in the range full_range(rng,0,this->space()->dim()-1)
This is only a transient view of a sub-vector that is to be immediately used and then released with a call to releaseDetachedView()
.
Note that calling this function might require some dynamic memory allocations and temporary memory. Therefore, it is critical that this->releaseDetachedView(sub_vec)
is called to clean up memory and avoid memory leaks after the sub-vector is used.
Heads Up! Note that client code in general should not directly call this function but should instead use the utility class ConstDetachedVectorView
which will also take care of calling releaseDetachedView()
.
If this->acquireDetachedView(...,sub_vec)
was previously called on sub_vec
then it may be possible to reuse this memory if it is sufficiently sized. The user is encouraged to make multiple calls to this->acquireDetachedView(...,sub_vec)
before this->releaseDetachedView(sub_vec)
to finally clean up all of the memory. Of course, the same sub_vec
object must be passed to the same vector object for this to work correctly.
virtual void Thyra::VectorBase< Scalar >::releaseDetachedVectorViewImpl | ( | RTOpPack::ConstSubVectorView< Scalar > * | sub_vec | ) | const [protected, pure virtual] |
Free an explicit view of a sub-vector.
sub_vec | [in/out] The memory referred to by sub_vec->values() will be released if it was allocated and *sub_vec will be zeroed out using sub_vec->set_uninitialized() . |
this->space().get()!=NULL
(throw std::logic_error
) sub_vec
must have been passed through a call to this->acquireDetachedView(...,sub_vec)
Postconditions:
RTOpPack::ConstSubVectorView::set_uninitialized()
for sub_vec
The sub-vector view must have been allocated by this->acquireDetachedView()
first.
virtual void Thyra::VectorBase< Scalar >::acquireNonconstDetachedVectorViewImpl | ( | const Range1D & | rng, | |
RTOpPack::SubVectorView< Scalar > * | sub_vec | |||
) | [protected, pure virtual] |
Get a mutable explicit view of a sub-vector.
rng | [in] The range of the elements to extract the sub-vector view. | |
sub_vec | [in/out] Mutable view of the sub-vector. Prior to the first call to this function sub_vec->set_uninitialized() must have been called for the correct behavior. Technically *sub_vec owns the memory but this memory must be committed and freed by calling this->commitDetachedView(sub_vec) after the client is finished modifying the view. |
this->space().get()!=NULL
(throw std::logic_error
) !rng.full_range()
] rng.ubound() < this->space()->dim()
(throw std::out_of_range
) Postconditions:
*sub_vec
contains an explicit mutable view to the elements in the range full_range(rng,0,this->space()->dim()-1)
This is only a transient view of a sub-vector that is to be immediately used and then committed back with a call to commitDetachedView()
.
Note that calling this function might require some internal allocations and temporary memory. Therefore, it is critical that this->commitDetachedView(sub_vec)
is called to commit the changed entries, clean up memory, and avoid memory leaks after the sub-vector is modified.
Heads Up! Note that client code in general should not directly call this function but should instead use the utility class DetachedVectorView
which will also take care of calling commitDetachedView()
.
If this->acquireDetachedView(...,sub_vec)
was previously called on sub_vec
then it may be possible to reuse this memory if it is sufficiently sized. The user is encouraged to make multiple calls to this->acquireDetachedView(...,sub_vec)
before this->commitDetachedView(sub_vec)
is called to finally clean up all of the memory. Of course the same sub_vec
object must be passed to the same vector object for this to work correctly.
Changes to the underlying sub-vector are not guaranteed to become permanent until this->acquireDetachedView(...,sub_vec)
is called again, or this->commitDetachedView(sub_vec)
is called.
virtual void Thyra::VectorBase< Scalar >::commitNonconstDetachedVectorViewImpl | ( | RTOpPack::SubVectorView< Scalar > * | sub_vec | ) | [protected, pure virtual] |
Commit changes for a mutable explicit view of a sub-vector.
sub_vec | [in/out] The data in sub_vec->values() will be written back internal storage and the memory referred to by sub_vec->values() will be released if it was allocated and *sub_vec will be zeroed out using sub_vec->set_uninitialized() . |
this->space().get()!=NULL
(throw std::logic_error
) sub_vec
must have been passed through a call to this->acquireDetachedView(...,sub_vec)
Postconditions:
RTOpPack::SubVectorView::set_uninitialized()
for sub_vec
*this
will be updated according the the changes made to sub_vec
The sub-vector view must have been allocated by this->acquireDetachedView()
first.
virtual void Thyra::VectorBase< Scalar >::setSubVectorImpl | ( | const RTOpPack::SparseSubVectorT< Scalar > & | sub_vec | ) | [protected, pure virtual] |
Set a specific sub-vector.
sub_vec | [in] Represents the elements in the sub-vector to be set. |
this->space().get()!=NULL
(throw std::logic_error
) sub_vec.globalOffset() + sub_vec.subDim() < this->space()->dim()
(throw std::out_of_range
) Postconditions:
[sub_vec.globalOffset(),sub_vec.globalOffset()+sub_vec.subDim()-1]
in *this
are set to 0.0 except for those that have that have entries in sub_vec
which are set to the values specified by (*this)(sub_vec.globalOffset()+vec.localOffset()+sub_vec.indices()[sub_vec.indicesStride()*k]) = vec.values[vec.valueStride()*k]
, for k = 0..sub_vec.subNz()-1
After this function returns, the corresponding elements in *this
vector object will be set equal to those in the input view sub_vec
.
void applyOp | ( | const RTOpPack::RTOpT< Scalar > & | op, | |
const ArrayView< const Ptr< const VectorBase< Scalar > > > & | vecs, | |||
const ArrayView< const Ptr< VectorBase< Scalar > > > & | targ_vecs, | |||
const Ptr< RTOpPack::ReductTarget > & | reduct_obj, | |||
const Ordinal | first_ele_offset = 0 , |
|||
const Ordinal | sub_dim = -1 , |
|||
const Ordinal | global_offset = 0 | |||
) | [related] |
Apply a reduction/transformation operator over a set of vectors: op(op(v[0]...v[nv-1],z[0]...z[nz-1]),(*reduct_obj)) -> z[0]...z[nz-1],(*reduct_obj)
.
op | [in] Reduction/transformation operator to apply over each sub-vector and assemble the intermediate targets into reduct_obj (if reduct_obj != RTOp_REDUCT_OBJ_NULL ). | |
vecs | [in] Array (length num_vecs ) of a set of pointers to non-mutable vectors to include in the operation. The order of these vectors is significant to op . If vecs.size()==0 , then op is called with no non-mutable vectors. | |
targ_vecs | [in] Array (length num_targ_vecs ) of a set of pointers to mutable vectors to include in the operation. The order of these vectors is significant to op . If targ_vecs.size()==0 , then op is called with no mutable vectors. | |
reduct_obj | [in/out] Target object of the reduction operation. This object must have been created by the op.reduct_obj_create_raw() function first. The reduction operation will be added to *reduct_obj if *reduct_obj has already been through a reduction. By allowing the info in *reduct_obj to be added to the reduction over all of these vectors, the reduction operation can be accumulated over a set of abstract vectors which can be useful for implementing composite vectors for instance. If op.get_reduct_type_num_entries(...) returns num_values == 0 , num_indexes == 0 and num_chars == 0 then reduct_obj must be set to null and no reduction will be performed. | |
first_ele_offset | [in] (default = 0) The index of the first element in this to be included. | |
sub_dim | [in] (default = -1) The number of elements in these vectors to include in the reduction/transformation operation. The value of sub_dim < 0 means to include all available elements. The value of sub_dim == 0 means to include none of the elements of the vector. This last value is somewhat undefined but has meaning in some specialized contexts (such as for SPMD vectors). | |
global_offset | [in] (default = 0) The offset applied to the included vector elements. |
vecs.size() > 0
] vecs[k]->space()->isCompatible(*this->space()) == true
, for k = 0...vecs.size()-1
(throw Exceptions::IncompatibleVectorSpaces
) targ_vecs.size() > 0
] targ_vecs[k]->space()->isCompatible(*this->space()) == true
, for k = 0...targ_vecs.size()-1
(throw Exceptions::IncompatibleVectorSpaces
) targ_vecs.size() > 0
] The vectors pointed to by targ_vecs[k]
, for k = 0...targ_vecs.size()-1
must not alias each other or any of the vectors vecs[k]
, for k = 0...vecs.size()-1
. You have be warned!!!! 0 <= first_ele_offset < this->space()->dim()
(throw std::out_of_range
) global_offset >= 0
(throw std::invalid_argument
) sub_dim - first_ele_offset <= this->space()->dim()
(throw std::length_error
). Postconditions:
targ_vecs[]
may be modified as determined by the definition of op
. reduct_obj!=null
] The reduction object reduct_obj
contains the combined reduction from the input state of reduct_obj
and the reductions that where accumulated during this this function invocation.
The logical vector passed to the op.apply_op(...)
function is:
v(k + global_offset) = this->get_ele(first_ele_offset + k) , for k = 0 ... sub_dim-1
where v
represents any one of the input or input/output vectors. The situation where first_ele_offset == 0
and global_offset > 1
corresponds to the case where the vectors represent constituent vectors in a larger aggregate vector. The situation where first_ele_offset > 0
and global_offset == 0
is for when a sub-view of the vectors are being treated as full vectors. Other combinations of these arguments are also possible.
Definition at line 587 of file Thyra_VectorBase.hpp.
void applyOp | ( | const RTOpPack::RTOpT< Scalar > & | op, | |
const int | num_vecs, | |||
const VectorBase< Scalar > *const | vecs_in[], | |||
const int | num_targ_vecs, | |||
VectorBase< Scalar > *const | targ_vecs_inout[], | |||
RTOpPack::ReductTarget * | reduct_obj, | |||
const Ordinal | first_ele_offset = 0 , |
|||
const Ordinal | sub_dim = -1 , |
|||
const Ordinal | global_offset = 0 | |||
) | [related] |