AbstractLinAlgPack::VectorMutable Class Reference

Abstract interface for mutable coordinate vectors {abstract}. More...

#include <AbstractLinAlgPack_VectorMutable.hpp>

Inheritance diagram for AbstractLinAlgPack::VectorMutable:

[legend]List of all members.

Virtual methods with default implementations
virtual VectorMutable &	operator= (value_type alpha)
	Assign the elements of this vector to a scalar.
virtual VectorMutable &	operator= (const Vector &v)
	Assign the elements of a vector to this.
virtual VectorMutable &	operator= (const VectorMutable &v)
	Default implementation calls operator=((const &Vector)v).
virtual void	set_ele (index_type i, value_type val)
	Set a specific element of a vector.
virtual vec_mut_ptr_t	sub_view (const Range1D &rng)
	Create a mutable abstract view of a vector object.
vec_mut_ptr_t	sub_view (const index_type &l, const index_type &u)
	Inline member function that simply calls this->sub_view(Range1D(l,u)).
virtual void	zero ()
	Zeros this vector.
virtual void	axpy (value_type alpha, const Vector &x)
	Adds a linear combination of another vector to this vector object.
virtual void	get_sub_vector (const Range1D &rng, RTOpPack::MutableSubVector *sub_vec)
	Get a mutable explicit view of a sub-vector.
virtual void	commit_sub_vector (RTOpPack::MutableSubVector *sub_vec)
	Free a mutable explicit view of a sub-vector.
virtual void	set_sub_vector (const RTOpPack::SparseSubVector &sub_vec)
	Set a specific sub-vector.
virtual void	Vp_StMtV (value_type alpha, const GenPermMatrixSlice &P, BLAS_Cpp::Transp P_trans, const Vector &x, value_type beta)
	Perform a gather or scatter operation with a vector.
Overridden from Vector
vec_ptr_t	sub_view (const Range1D &rng) const
	Default implementation calls this->sub_view() (non-const) and then performs an cast to vec_ptr_t.
Public Member Functions
virtual void	get_sub_vector (const Range1D &rng, RTOpPack::SubVector *sub_vec) const
virtual void	free_sub_vector (RTOpPack::SubVector *sub_vec) const

---

Detailed Description

Abstract interface for mutable coordinate vectors {abstract}.

Objects of this type can act as a target vector of a transformation operation. Similarly to Vector this interface contains very few (only one extra) pure virtual methods that must be overridden. However, more efficient and more general implementations will choose to override more methods.

In addition to being able to create non-mutable (const) abstract sub-views of a vector object thorugh the Vector interface, this interface allows the creation of mutable (non-const) sub-views using sub_view(). Also, in addition to being able to extract an explicit non-mutable view of some (small?) sub-set of elements, this interface allows a client to either extract a explicit mutable sub-views using get_sub_vector() or to set sub-vectors using set_sub_vector(). As much as possible, abstract views should be preferred (i.e. sub_view()) over explict views (i.e. get_sub_vector() and set_sub_vector()).

There are only two pure virtual methods that a concreate VectorMutable subclass must override. The space() and apply_op() methods from the Vector base class inteface must be defined.

The non-mutable (const) sub_view(...) method from the Vector interface has a default implementation defined here that will be adequate for most subclasses.

Definition at line 59 of file AbstractLinAlgPack_VectorMutable.hpp.

---

Member Function Documentation

VectorMutable & AbstractLinAlgPack::VectorMutable::operator= (  value_type  alpha  )  [virtual]

Assign the elements of this vector to a scalar. The default implementation of this function uses a transforamtion operator class (see RTOp_TOp_assign_scalar.h) and calls this->apply_op(). Reimplemented in AbstractLinAlgPack::VectorMutableBlocked, and AbstractLinAlgPack::VectorMutableDense. Definition at line 79 of file AbstractLinAlgPack_VectorMutable.cpp.

VectorMutable & AbstractLinAlgPack::VectorMutable::operator= (  const Vector &  v  )  [virtual]

Assign the elements of a vector to this. The default implementation of this function uses a transforamtion operator class (see RTOp_TOp_assign_vectors.h) and calls this->apply_op(). Reimplemented in AbstractLinAlgPack::VectorMutableBlocked, and AbstractLinAlgPack::VectorMutableDense. Definition at line 87 of file AbstractLinAlgPack_VectorMutable.cpp.

VectorMutable & AbstractLinAlgPack::VectorMutable::operator= (  const VectorMutable &  v  )  [virtual]

Default implementation calls operator=((const &Vector)v). Reimplemented in AbstractLinAlgPack::VectorMutableDense. Definition at line 97 of file AbstractLinAlgPack_VectorMutable.cpp.

void AbstractLinAlgPack::VectorMutable::set_ele (  index_type  i, value_type  val )  [virtual]

Set a specific element of a vector. Preconditions: 1 <= i <= this->dim() (throw std::out_of_range) Postconditions: this->get(i) == val The default implementation uses a transforamtion operator class (see RTOp_TOp_set_ele.h) and calls this->apply_op(). Parameters: i  [in] Index of the element value to set. val  [in] Value of the element to set. Reimplemented in AbstractLinAlgPack::VectorMutableSubView, AbstractLinAlgPack::VectorMutableBlocked, and AbstractLinAlgPack::VectorMutableDense. Definition at line 102 of file AbstractLinAlgPack_VectorMutable.cpp.

VectorMutable::vec_mut_ptr_t AbstractLinAlgPack::VectorMutable::sub_view (  const Range1D &  rng  )  [virtual]

Create a mutable abstract view of a vector object. This is only a transient view of a sub-vector that is to be immediately used and then released by RefCountPtr<>. This function is declared as non-constant because the object returned has the capacity to alter this object. The compatibility of sub-views goes along with the compatibility of sub-spaces (see VectorSpace). For example, given the vector objects where x.space().is_compatible(y.space()) == true then if x.space().sub_space(rng1)->is_compatible(*y.space().sub_space(rng2)) == true then the sub-vector views *x.sub_view(rng1) and *y.sub_view(rng2) should be compatible and can be combined in vector operations. Preconditions: rng.in_range(this->dim()) == true (throw std::out_of_range) Parameters: rng  [in] The range of the elements to extract the sub-vector view. Returns: Returns a smart reference counted pointer to a view of the requested vector elements. It is allowed for the vector implementation to refuse to create arbitrary views in which case this function will return return.get() == NULL. In most applications, only specific views are every required. The default implementation uses the subclass VectorSubView to represent any arbitrary sub-view but this can be inefficient if the sub-view is very small compared this this full vector space but not necessarily. Note that the underlying vector this is not guarrenteed to show the changes made the sub-view *return .get() until the smart reference counted pointer return is destroyed. Reimplemented in AbstractLinAlgPack::VectorMutableSubView, AbstractLinAlgPack::VectorMutableBlocked, and AbstractLinAlgPack::VectorMutableDense. Definition at line 113 of file AbstractLinAlgPack_VectorMutable.cpp.

VectorMutable::vec_mut_ptr_t AbstractLinAlgPack::VectorMutable::sub_view (  const index_type &  l, const index_type &  u )  [inline]

Inline member function that simply calls this->sub_view(Range1D(l,u)). Definition at line 294 of file AbstractLinAlgPack_VectorMutable.hpp.

void AbstractLinAlgPack::VectorMutable::zero (   )  [virtual]

Zeros this vector. Calls operator=(0.0). Definition at line 135 of file AbstractLinAlgPack_VectorMutable.cpp.

void AbstractLinAlgPack::VectorMutable::axpy (  value_type  alpha, const Vector &  x )  [virtual]

Adds a linear combination of another vector to this vector object. Calls this->apply_op() with an operator class (see RTOp_TOp_axpy.h). Reimplemented in AbstractLinAlgPack::VectorMutableBlocked. Definition at line 140 of file AbstractLinAlgPack_VectorMutable.cpp.

void AbstractLinAlgPack::VectorMutable::get_sub_vector (  const Range1D &  rng, RTOpPack::MutableSubVector *  sub_vec )  [virtual]

Get a mutable explicit view of a sub-vector. This is only a transient view of a sub-vector that is to be immediately used and then released with a call to release_sub_vector(). Note that calling this operation might require some internal allocations and temporary memory. Therefore, it is critical that this->release_sub_vector(sub_vec) is called to clean up memory and avoid memory leaks after the sub-vector is used. If this->get_sub_vector(...,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->get_sub_vector(...,sub_vec) before this->release_sub_vector(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. Changes to the underlying sub-vector are not guarrenteed to become permanent until this->get_sub_vector(...,sub_vec) or this->commit_sub_vector(sub_vec) is called. Preconditions: [!rng.full_range()] (rng.ubound() <= this->dim()) == true (throw std::out_of_range) This method has a default implementation based on a vector reduction operator class (see RTOp_ROp_get_sub_vector.h) and calls apply_op(). Note that the footprint of the reduction object (both internal and external state) will be O(rng.size()). For serial applications this is faily adequate and will not be a major performance penalty. For parallel applications, this will be a terrible implementation and must be overridden if rng.size() is large at all. If a subclass does override this method, it must also override release_sub_vector() which has a default implementation which is a companion to this method's default implementation. 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 RTOp_mutable_sub_vector_null(sub_vec) must have been called for the correct behavior. Technically *sub_vec owns the memory but this memory can be freed only by calling this->commit_sub_vector(sub_vec). Reimplemented in AbstractLinAlgPack::VectorMutableSubView, and AbstractLinAlgPack::VectorMutableDense. Definition at line 148 of file AbstractLinAlgPack_VectorMutable.cpp.

void AbstractLinAlgPack::VectorMutable::commit_sub_vector (  RTOpPack::MutableSubVector *  sub_vec  )  [virtual]

Free a mutable explicit view of a sub-vector. The sub-vector view must have been allocated by this->get_sub_vector() first. This method has a default implementation which is a companion to the default implementation for get_sub_vector(...). If get_sub_vector(...) is overridden by a subclass then this method must be overridden also! Parameters: sub_vec  [in/out] The memory refered to by sub_vec->values and sub_vec->indices will be released if it was allocated and *sub_vec will be zeroed out using RTOp_mutable_sub_vector_null(sub_vec). Reimplemented in AbstractLinAlgPack::VectorMutableSubView, and AbstractLinAlgPack::VectorMutableDense. Definition at line 165 of file AbstractLinAlgPack_VectorMutable.cpp.

void AbstractLinAlgPack::VectorMutable::set_sub_vector (  const RTOpPack::SparseSubVector &  sub_vec  )  [virtual]

Set a specific sub-vector. After this function returns, the corresponding elements in this vector object will be set equal to those in the input vector (the post conditions are obvious). Preconditions: sub_vec.global_offset + sub_dim <= this->dim() (throw std::out_of_range) The default implementation of this operation uses a transformation operator class (see RTOp_TOp_set_sub_vector.h) and calls apply_op(). Be forewarned however, that the operator objects state data (both internal and external) will be O(sub_vec.sub_nz). For serial applications, this is entirely adequate. For parallel applications this will be very bad! Parameters: sub_vec  [in] Represents the elements in the subvector to be set. Reimplemented in AbstractLinAlgPack::VectorMutableSubView, AbstractLinAlgPack::VectorMutableBlocked, and AbstractLinAlgPack::VectorMutableDense. Definition at line 177 of file AbstractLinAlgPack_VectorMutable.cpp.

void AbstractLinAlgPack::VectorMutable::Vp_StMtV (  value_type  alpha, const GenPermMatrixSlice &  P, BLAS_Cpp::Transp  P_trans, const Vector &  x, value_type  beta )  [virtual]

Perform a gather or scatter operation with a vector. this = alpha * op(P) * x + beta * this The default implementation is based on a transformation or reduction operator (depending if a gather or scatter is being performed). Reimplemented in AbstractLinAlgPack::VectorMutableDense. Definition at line 205 of file AbstractLinAlgPack_VectorMutable.cpp.

Vector::vec_ptr_t AbstractLinAlgPack::VectorMutable::sub_view (  const Range1D &  rng  )  const [virtual]

Default implementation calls this->sub_view() (non-const) and then performs an cast to vec_ptr_t. This function override is actually needed here for another reason. Without, the override, the non-const version defined in this interface hides the const version defined in Vector. Reimplemented from AbstractLinAlgPack::Vector. Reimplemented in AbstractLinAlgPack::VectorMutableSubView. Definition at line 226 of file AbstractLinAlgPack_VectorMutable.cpp.

virtual void AbstractLinAlgPack::Vector::get_sub_vector (  const Range1D &  rng, RTOpPack::SubVector *  sub_vec )  const

virtual void AbstractLinAlgPack::Vector::free_sub_vector (  RTOpPack::SubVector *  sub_vec  )  const

---

The documentation for this class was generated from the following files:

• AbstractLinAlgPack_VectorMutable.hpp
• AbstractLinAlgPack_VectorMutable.cpp

---