Thyra::VectorBase< Scalar > Class Template Reference

#include <Thyra_VectorBaseDecl.hpp>

Inheritance diagram for Thyra::VectorBase< Scalar >:

[legend]
List of all members.

Space membership

virtual Teuchos::RefCountPtr<
const VectorSpaceBase< Scalar > > 
space () const =0
 Return a smart pointer to the vector space that this vector belongs to.

Reduction/Transformation operator support

virtual void applyOp (const RTOpPack::RTOpT< Scalar > &op, const int num_vecs, const VectorBase< Scalar > *const vecs[], const int num_targ_vecs, VectorBase< Scalar > *const targ_vecs[], RTOpPack::ReductTarget *reduct_obj, const Index first_ele_offset, const Index sub_dim, const Index 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).

Vector Cloning

virtual Teuchos::RefCountPtr<
VectorBase< Scalar > > 
clone_v () const =0
 Returns a cloned copy of *this vector.

Explicit sub-vector access

virtual void acquireDetachedView (const Range1D &rng, RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const =0
 Get a non-mutable explicit view of a sub-vector.
virtual void releaseDetachedView (RTOpPack::ConstSubVectorView< Scalar > *sub_vec) const =0
 Free an explicit view of a sub-vector.
virtual void acquireDetachedView (const Range1D &rng, RTOpPack::SubVectorView< Scalar > *sub_vec)=0
 Get a mutable explicit view of a sub-vector.
virtual void commitDetachedView (RTOpPack::SubVectorView< Scalar > *sub_vec)=0
 Commit changes for a mutable explicit view of a sub-vector.
virtual void setSubVector (const RTOpPack::SparseSubVectorT< Scalar > &sub_vec)=0
 Set a specific sub-vector.

template<class Scalar>
class Thyra::VectorBase< Scalar >


Member Function Documentation

template<class Scalar>
virtual Teuchos::RefCountPtr< 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.

Implemented in Thyra::DefaultClusteredSpmdProductVector< Scalar >, Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdVectorBase< Scalar >, and Thyra::DefaultProductVector< Scalar >.

template<class Scalar>
virtual void Thyra::VectorBase< Scalar >::applyOp const RTOpPack::RTOpT< Scalar > &  op,
const int  num_vecs,
const VectorBase< Scalar > *const   vecs[],
const int  num_targ_vecs,
VectorBase< Scalar > *const   targ_vecs[],
RTOpPack::ReductTarget reduct_obj,
const Index  first_ele_offset,
const Index  sub_dim,
const Index  global_offset
const [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.

Implemented in Thyra::DefaultClusteredSpmdProductVector< Scalar >, Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdVectorBase< Scalar >, and Thyra::DefaultProductVector< Scalar >.

template<class Scalar>
virtual Teuchos::RefCountPtr<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.

Implemented in Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::VectorBase< Scalar >::acquireDetachedView const Range1D rng,
RTOpPack::ConstSubVectorView< Scalar > *  sub_vec
const [pure virtual]
 

Get a non-mutable explicit view of a sub-vector.

Parameters:
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).
Preconditions:
  • 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.

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdVectorBase< Scalar >, Thyra::DefaultProductVector< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::VectorBase< Scalar >::releaseDetachedView RTOpPack::ConstSubVectorView< Scalar > *  sub_vec  )  const [pure virtual]
 

Free an explicit view of a sub-vector.

Parameters:
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().
Preconditions:
  • this->space().get()!=NULL (throw std::logic_error)
  • sub_vec must have been passed through a call to this->acquireDetachedView(...,sub_vec)

Postconditions:

The sub-vector view must have been allocated by this->acquireDetachedView() first.

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdVectorBase< Scalar >, Thyra::DefaultProductVector< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::VectorBase< Scalar >::acquireDetachedView const Range1D rng,
RTOpPack::SubVectorView< Scalar > *  sub_vec
[pure virtual]
 

Get a mutable explicit view of a sub-vector.

Parameters:
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.
Preconditions:
  • 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 Thyra::full_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.

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdVectorBase< Scalar >, Thyra::DefaultProductVector< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::VectorBase< Scalar >::commitDetachedView RTOpPack::SubVectorView< Scalar > *  sub_vec  )  [pure virtual]
 

Commit changes for a mutable explicit view of a sub-vector.

Parameters:
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().
Preconditions:
  • this->space().get()!=NULL (throw std::logic_error)
  • sub_vec must have been passed through a call to this->acquireDetachedView(...,sub_vec)

Postconditions:

The sub-vector view must have been allocated by this->acquireDetachedView() first.

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdVectorBase< Scalar >, Thyra::DefaultProductVector< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::VectorBase< Scalar >::setSubVector const RTOpPack::SparseSubVectorT< Scalar > &  sub_vec  )  [pure virtual]
 

Set a specific sub-vector.

Parameters:
sub_vec [in] Represents the elements in the sub-vector to be set.
Preconditions:
  • this->space().get()!=NULL (throw std::logic_error)
  • sub_vec.globalOffset() + sub_vec.subDim() < this->space()->dim() (throw std::out_of_range)

Postconditions:

  • All of the elements in the range [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.

Implemented in Thyra::DefaultProductVector< Scalar >, and Thyra::VectorDefaultBase< Scalar >.


The documentation for this class was generated from the following file:
Generated on Thu Sep 18 12:33:11 2008 for Thyra Package Browser (Single Doxygen Collection) by doxygen 1.3.9.1