Thyra Operator/Vector Support : Thyra::ConstDetachedVectorView< Scalar

List of all members.


Public Member Functions
	ConstDetachedVectorView (const Teuchos::RefCountPtr< const VectorBase< Scalar > > &v, const Range1D &rng=Range1D(), const bool forceUnitStride=false)
	Construct an explicit non-mutable (const) view of a subset of elements.
	ConstDetachedVectorView (const VectorBase< Scalar > &v, const Range1D &rng=Range1D(), const bool forceUnitStride=false)
	Construct an explicit non-mutable (const) view of a subset of elements.
	~ConstDetachedVectorView ()
	Free the explicit view on the `VectorBase` object `v` passed to `ConstDetachedVectorView()`.
const RTOpPack::ConstSubVectorView< Scalar > &	sv () const
	Returns the explicit view as an `RTOpPack::ConstSubVectorView<Scalar>` object.
Teuchos_Index	globalOffset () const
	Returns the global offset for the explicit view.
Teuchos_Index	subDim () const
	Returns the dimension of the explicit view.
const Scalar *	values () const
	Return a pointer to a `Scalar` array containing the explicit view.
ptrdiff_t	stride () const
	Return the stride between elements in the array returned from `this->values()`.
const Scalar &	operator[] (Teuchos_Index i) const
	Zero-based indexing: Preconditions: `values()!=NULL && (0 <= i < subDim()-1)`.
const Scalar &	operator() (Teuchos_Index i) const
	Zero-based indexing: Preconditions: `values()!=NULL && (0 <= i < subDim()-1)`.

Detailed Description

template<class Scalar>
class Thyra::ConstDetachedVectorView< Scalar >

This utility class makes it easy to explicitly access a contiguous subset of elements in any const VectorBase object.

Warning! Creating an explicit view of an arbitrary VectorBase object may be a very expensive operation (such as with distributed-memory vectors) and should only be done in special cases (such as when the vector is an in-core vector). There several specialized use cases where creating these types of explicit views are necessary but in most cases this should not be done.

The following functions show four different ways to extract a range of elements from in any const VectorBase object and copy then into a raw C++ array:

 //
 // Copy using unit-strided pointer access
 //
 template<class Scalar>
 void copyToArrayPointerUnit(
   const Thyra::VectorBase<Scalar>   &v
   ,const Thyra::Range1D             &rng
   ,Scalar                           x[]   // Size == rng.size()
   )
 {
    Thyra::ConstDetachedVectorView<Scalar> v_ev(v,rng,true);  // Force unit stride
    const Scalar *v_ptr = v_ev.values();                 // Get pointer to unit-stride data
    for( int k = 0; k < n; ++k )                         // For each element in view:
      x[k] = v_ptr[k];                                   //   Copy elements
    // When this function returns then v_ev will be destroyed and the view will be freed
 }

 //
 // Copy using non-unit-strided pointer access
 //
 template<class Scalar>
 void copyToArrayPointerNonunit(
   const Thyra::VectorBase<Scalar>   &v
   ,const Thyra::Range1D             &rng
   ,Scalar                           x[]   // Size == rng.size()
   )
 {
    Thyra::ConstDetachedVectorView<Scalar> v_ev(v,rng);           // Allow non-unit stride
    const Scalar        *v_ptr    = v_ev.values();           // Get pointer to non-unit-stride data
    const Thyra::Index  *v_stride = v_ev.stride();           // Get stride between vector data
    for( int k = 0; k < rng.size(); ++k, v_ptr += v_stride ) // For each element in view:
      x[k] = *v_ptr;                                         //   Copy elements
    // When this function returns then v_ev will be destroyed and the view will be freed
 }

 //
 // Copy using possibly non-unit stride with zero-based overloaded function operator[]()
 //
 template<class Scalar>
 void copyToArrayZeroBasedOperator(
   const Thyra::VectorBase<Scalar>   &v
   ,const Thyra::Range1D             &rng
   ,Scalar                           x[]   // Size == rng.size()
   )
 {
    Thyra::ConstDetachedVectorView<Scalar> v_ev(v,rng);       // Allow non-unit stride 
    for( int k = 0; k < rng.size(); ++k )                // For each element in view:
      x[k] = v_ev[k];                                    //   Copy elements using operator[]()
    // When this function returns then v_ev will be destroyed and the view will be freed
 }

 //
 // Copy using possibly non-unit stride with zero-based overloaded function operator()()
 //
 template<class Scalar>
 void copyToArrayOneBasedOperator(
   const Thyra::VectorBase<Scalar>   &v
   ,const Thyra::Range1D             &rng
   ,Scalar                           x[]   // Size == rng.size()
   )
 {
    Thyra::ConstDetachedVectorView<Scalar> v_ev(v,rng);       // Allow non-unit stride 
    for( int k = 0; k < rng.size(); ++k )                // For each element in view:
      x[k] = v_ev(k);                                    //   Copy elements using operator()()
    // When this function returns then v_ev will be destroyed and the view will be freed
 }

If one wants to modify the elements in a VectorBase object then one should use the utility class DetachedVectorView.

The default constructor, copy constructor and assignment operators are not allowed.

Constructor & Destructor Documentation

template<class Scalar>
Thyra::ConstDetachedVectorView< Scalar >::ConstDetachedVectorView	(	const Teuchos::RefCountPtr< const VectorBase< Scalar > > &	v,
		const Range1D &	rng = `Range1D()`,
		const bool	forceUnitStride = `false`
	)	`[inline]`

Construct an explicit non-mutable (const) view of a subset of elements.

Parameters:

	v	[in] The vector that a view will be taken. This object must be maintained until `*this` is destroyed.
	rng	[in] the range of element indices that the explicit view will be taken.
	forceUnitStride	[in] If `true` then the view will have unit stride.

Preconditions:

[rng.full_range()==false] rng.ubound() < v.space()->dim()

Postconditions:

this->sv() returns the created view
this->globalOffset()==rng.lbound()
this->subDim()==rng.size()
this->values() returns a pointer to a Scalar array
this->stride() returns the stride between the elements pointed it in this->values()
[forceUnitStride==true] this->stride()==1

Definition at line 157 of file Thyra_DetachedVectorView.hpp.

template<class Scalar>
Thyra::ConstDetachedVectorView< Scalar >::ConstDetachedVectorView	(	const VectorBase< Scalar > &	v,
		const Range1D &	rng = `Range1D()`,
		const bool	forceUnitStride = `false`
	)	`[inline]`

Construct an explicit non-mutable (const) view of a subset of elements.

Parameters:

	v	[in] The vector that a view will be taken. This object must be maintained until `*this` is destroyed.
	rng	[in] the range of element indices that the explicit view will be taken.
	forceUnitStride	[in] If `true` then the view will have unit stride.

Preconditions:

[rng.full_range()==false] rng.ubound() < v.space()->dim()

Postconditions:

this->sv() returns the created view
this->globalOffset()==rng.lbound()
this->subDim()==rng.size()
this->values() returns a pointer to a Scalar array
this->stride() returns the stride between the elements pointed it in this->values()
[forceUnitStride==true] this->stride()==1

Definition at line 185 of file Thyra_DetachedVectorView.hpp.

Thyra::ConstDetachedVectorView< Scalar > Class Template Reference
[Development of linear Abstract Numerical Algorithms (ANAs)]

Public Member Functions

Detailed Description

template<class Scalar>
class Thyra::ConstDetachedVectorView< Scalar >

Constructor & Destructor Documentation

Member Function Documentation

Thyra::ConstDetachedVectorView< Scalar > Class Template Reference [Development of linear Abstract Numerical Algorithms (ANAs)]

Public Member Functions

Detailed Description

template<class Scalar> class Thyra::ConstDetachedVectorView< Scalar >

Constructor & Destructor Documentation

Member Function Documentation

Thyra::ConstDetachedVectorView< Scalar > Class Template Reference
[Development of linear Abstract Numerical Algorithms (ANAs)]

template<class Scalar>
class Thyra::ConstDetachedVectorView< Scalar >