Thyra::MultiVectorBase< Scalar > Class Template Reference

#include <Thyra_MultiVectorBaseDecl.hpp>

Inheritance diagram for Thyra::MultiVectorBase< Scalar >:

[legend]
List of all members.

Provide access to the columns as VectorBase objects

virtual Teuchos::RefCountPtr<
const VectorBase< Scalar > > 
col (Index j) const
 Return a non-changeable view of a constituent column vector.
virtual Teuchos::RefCountPtr<
VectorBase< Scalar > > 
col (Index j)=0
 Return a changeable view of a constituent column vector.

Multi-vector sub-views

virtual Teuchos::RefCountPtr<
const MultiVectorBase< Scalar > > 
subView (const Range1D &colRng) const =0
 Return a non-changeable sub-view of a contiguous set of columns of the this multi-vector.
virtual Teuchos::RefCountPtr<
MultiVectorBase< Scalar > > 
subView (const Range1D &colRng)=0
 Return a changeable sub-view of a contiguous set of columns of the this multi-vector.
virtual Teuchos::RefCountPtr<
const MultiVectorBase< Scalar > > 
subView (const int numCols, const int cols[]) const =0
 Return a non-changeable sub-view of a non-contiguous set of columns of this multi-vector.
virtual Teuchos::RefCountPtr<
MultiVectorBase< Scalar > > 
subView (const int numCols, const int cols[])=0
 Return a changeable sub-view of a non-contiguous set of columns of this multi-vector.

Collective reduction/transformation operator apply functions

virtual void applyOp (const RTOpPack::RTOpT< Scalar > &primary_op, const int num_multi_vecs, const MultiVectorBase< Scalar > *const multi_vecs[], const int num_targ_multi_vecs, MultiVectorBase< Scalar > *const targ_multi_vecs[], RTOpPack::ReductTarget *const reduct_objs[], const Index primary_first_ele_offset, const Index primary_sub_dim, const Index primary_global_offset, const Index secondary_first_ele_offset, const Index secondary_sub_dim) const =0
 Apply a reduction/transformation operator column by column and return an array of the reduction objects.
virtual void applyOp (const RTOpPack::RTOpT< Scalar > &primary_op, const RTOpPack::RTOpT< Scalar > &secondary_op, const int num_multi_vecs, const MultiVectorBase< Scalar > *const multi_vecs[], const int num_targ_multi_vecs, MultiVectorBase< Scalar > *const targ_multi_vecs[], RTOpPack::ReductTarget *reduct_obj, const Index primary_first_ele_offset, const Index primary_sub_dim, const Index primary_global_offset, const Index secondary_first_ele_offset, const Index secondary_sub_dim) const =0
 Apply a reduction/transformation operator column by column and reduce the intermediate reduction objects into a single reduction object.

Explicit sub-multi-vector access

virtual void acquireDetachedView (const Range1D &rowRng, const Range1D &colRng, RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const =0
 Get a non-changeable explicit view of a sub-multi-vector.
virtual void releaseDetachedView (RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const =0
 Free a non-changeable explicit view of a sub-multi-vector.
virtual void acquireDetachedView (const Range1D &rowRng, const Range1D &colRng, RTOpPack::SubMultiVectorView< Scalar > *sub_mv)=0
 Get a changeable explicit view of a sub-multi-vector.
virtual void commitDetachedView (RTOpPack::SubMultiVectorView< Scalar > *sub_mv)=0
 Commit changes for a changeable explicit view of a sub-multi-vector.

Cloning

virtual Teuchos::RefCountPtr<
MultiVectorBase< Scalar > > 
clone_mv () const =0
 Clone the multi-vector object (if supported).

Overridden functions from LinearOpBase

Teuchos::RefCountPtr< const
LinearOpBase< Scalar > > 
clone () const
 This function is simply overridden to return this->clone_mv().

Private Attributes

VectorBase< Scalar > * columns

template<class Scalar>
class Thyra::MultiVectorBase< Scalar >


Member Function Documentation

template<class Scalar>
Teuchos::RefCountPtr< const VectorBase< Scalar > > Thyra::MultiVectorBase< Scalar >::col Index  j  )  const [virtual]
 

Return a non-changeable view of a constituent column vector.

Parameters:
j [in] zero-based index of the column to return a view for
Preconditions:
  • this->domain().get()!=NULL && this->range().get()!=NULL (throw std::logic_error)
  • 0 <= j && j < this->domain()->dim() (throw std::invalid_argument)

Postconditions:

  • return.get() != NULL
  • this->range()->isCompatible(*return->space()) == true

See Thyra_MVB_col_access_sec and Thyra_MVB_view_behavior_sec for the behavior of this view.

The default implementation of this function (which is the only implementation needed by most subclasses) is based on the non-const version col().

Definition at line 41 of file Thyra_MultiVectorBase.hpp.

template<class Scalar>
virtual Teuchos::RefCountPtr<VectorBase<Scalar> > Thyra::MultiVectorBase< Scalar >::col Index  j  )  [pure virtual]
 

Return a changeable view of a constituent column vector.

Parameters:
j [in] zero-based index of the column to return a view for
Preconditions:
  • this->domain().get()!=NULL && this->range().get()!=NULL (throw std::logic_error)
  • 0 <= j && j < this->domain()->dim() (throw std::invalid_argument)

Postconditions:

  • return.get() != NULL
  • this->range()->isCompatible(*return->space()) == true

See Thyra_MVB_col_access_sec and Thyra_MVB_view_behavior_sec for the behavior of this view.

Note: *this is not guaranteed to be modified until the smart pointer returned by this function is destroyed.

Implemented in Thyra::DefaultColumnwiseMultiVector< Scalar >, Thyra::DefaultSpmdMultiVector< Scalar >, Thyra::DefaultVectorMultiVector< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual Teuchos::RefCountPtr<const MultiVectorBase<Scalar> > Thyra::MultiVectorBase< Scalar >::subView const Range1D colRng  )  const [pure virtual]
 

Return a non-changeable sub-view of a contiguous set of columns of the this multi-vector.

Parameters:
colRng [in] zero-based range of columns to create a view of. Note that it is valid for colRng.full_range()==true in which case the view of the entire multi-vector is taken.
Preconditions:
  • this->domain().get()!=NULL && this->range().get()!=NULL (throw std::logic_error)
  • [!colRng.full_range()] colRng.ubound() < this->domain()->dim() (throw std::invalid_argument)

Postconditions:

  • this->range()->isCompatible(*return->range()) == true
  • return->domain()->dim() == Teuchos::full_range(colRng,0,this->domain()->dim()-1).size()
  • *return->col(k) represents the same column vector as this->col(colRng.lbound()+k), for k=0...Teuchos::full_range(colRng,0,this->domain()->dim()).ubound()-1

See Thyra_MVB_subviews_sec and Thyra_MVB_view_behavior_sec for the behavior of this view.

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

template<class Scalar>
virtual Teuchos::RefCountPtr<MultiVectorBase<Scalar> > Thyra::MultiVectorBase< Scalar >::subView const Range1D colRng  )  [pure virtual]
 

Return a changeable sub-view of a contiguous set of columns of the this multi-vector.

Parameters:
colRng [in] zero-based range of columns to create a view of. Note that it is valid for colRng.full_range()==true in which case the view of the entire multi-vector is taken.
Preconditions:
  • this->domain().get()!=NULL && this->range().get()!=NULL (throw std::logic_error)
  • [!colRng.full_range()] colRng.ubound() < this->domain()->dim() (throw std::invalid_argument)

Postconditions:

  • this->range()->isCompatible(*return->range()) == true
  • return->domain()->dim() == Teuchos::full_range(colRng,0,this->domain()->dim()-1).size()
  • *return->col(k) represents the same column vector as this->col(colRng.lbound()+k), for k=0...Teuchos::full_range(colRng,0,this->domain()->dim()).ubound()-1

See Thyra_MVB_subviews_sec and Thyra_MVB_view_behavior_sec for the behavior of this view.

Implemented in Thyra::DefaultColumnwiseMultiVector< Scalar >, Thyra::DefaultSpmdMultiVector< Scalar >, Thyra::DefaultVectorMultiVector< Scalar >, Thyra::MultiVectorDefaultBase< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual Teuchos::RefCountPtr<const MultiVectorBase<Scalar> > Thyra::MultiVectorBase< Scalar >::subView const int  numCols,
const int  cols[]
const [pure virtual]
 

Return a non-changeable sub-view of a non-contiguous set of columns of this multi-vector.

Parameters:
numCols [in] The number of columns to extract a view for.
cols [in] Array (length numCols) of the zero-based column indexes to use in the returned view.
Preconditions:
  • this->domain().get()!=NULL && this->range().get()!=NULL (throw std::logic_error)
  • numCols <= this->domain()->dim() (throw std::invalid_argument)
  • 0 <= cols[k] < this->domain()->dim(), for k=0...numCols-1 (throw std::invalid_argument)
  • col[k1] != col[k2], for all k1 != k2 in the range [0,numCols-1]

Postconditions:

  • this->range()->isCompatible(*return->range()) == true
  • return->domain()->dim() == numCols
  • *return->col(k) represents the same column vector as this->col(cols[k]), for k=0...numCols-1

See Thyra_MVB_subviews_sec and Thyra_MVB_view_behavior_sec for the behavior of this view.

Implemented in Thyra::DefaultSpmdMultiVector< Scalar >, Thyra::DefaultVectorMultiVector< Scalar >, Thyra::MultiVectorDefaultBase< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual Teuchos::RefCountPtr<MultiVectorBase<Scalar> > Thyra::MultiVectorBase< Scalar >::subView const int  numCols,
const int  cols[]
[pure virtual]
 

Return a changeable sub-view of a non-contiguous set of columns of this multi-vector.

Parameters:
numCols [in] The number of columns to extract a view for.
cols [in] Array (length numCols) of the zero-based column indexes to use in the returned view.
Preconditions:
  • this->domain().get()!=NULL && this->range().get()!=NULL (throw std::logic_error)
  • numCols <= this->domain()->dim() (throw std::invalid_argument)
  • 0 <= cols[k] < this->domain()->dim(), for k=0...numCols-1 (throw std::invalid_argument)
  • col[k1] != col[k2], for all k1 != k2 in the range [0,numCols-1]

Postconditions:

  • this->range()->isCompatible(*return->range()) == true
  • return->domain()->dim() == numCols
  • *return->col(k) represents the same column vector as this->col(cols[k]), for k=0...numCols-1

See Thyra_MVB_subviews_sec and Thyra_MVB_view_behavior_sec for the behavior of this view.

Implemented in Thyra::DefaultSpmdMultiVector< Scalar >, Thyra::DefaultVectorMultiVector< Scalar >, Thyra::MultiVectorDefaultBase< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::MultiVectorBase< Scalar >::applyOp const RTOpPack::RTOpT< Scalar > &  primary_op,
const int  num_multi_vecs,
const MultiVectorBase< Scalar > *const   multi_vecs[],
const int  num_targ_multi_vecs,
MultiVectorBase< Scalar > *const   targ_multi_vecs[],
RTOpPack::ReductTarget *const   reduct_objs[],
const Index  primary_first_ele_offset,
const Index  primary_sub_dim,
const Index  primary_global_offset,
const Index  secondary_first_ele_offset,
const Index  secondary_sub_dim
const [pure virtual]
 

Apply a reduction/transformation operator column by column and return an array of the reduction objects.

Preconditions:

See the documentation for the function Thyra::applyOp() for a description of the arguments.

This function is not to be called directly by the client but instead through the nonmember function Thyra::applyOp().

It is expected that this will be one of the multi-vector objects in multi_vecs[] or targ_multi_vecs[].

The default implementation calls VectorBase::applyOp() on each column this->col(j) for j = 0 ... this->range()->dim()-1.

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdMultiVectorBase< Scalar >, and Thyra::MultiVectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::MultiVectorBase< Scalar >::applyOp const RTOpPack::RTOpT< Scalar > &  primary_op,
const RTOpPack::RTOpT< Scalar > &  secondary_op,
const int  num_multi_vecs,
const MultiVectorBase< Scalar > *const   multi_vecs[],
const int  num_targ_multi_vecs,
MultiVectorBase< Scalar > *const   targ_multi_vecs[],
RTOpPack::ReductTarget reduct_obj,
const Index  primary_first_ele_offset,
const Index  primary_sub_dim,
const Index  primary_global_offset,
const Index  secondary_first_ele_offset,
const Index  secondary_sub_dim
const [pure virtual]
 

Apply a reduction/transformation operator column by column and reduce the intermediate reduction objects into a single reduction object.

Preconditions:

See the documentation for the function Thyra::applyOp() for a description of the arguments.

This function is not to be called directly by the client but instead through the nonmember function Thyra::applyOp().

It is expected that this will be one of the multi-vector objects in multi_vecs[] or targ_multi_vecs[].

The default implementation calls applyOp() where an array of reduction objects is taken.

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, and Thyra::MultiVectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::MultiVectorBase< Scalar >::acquireDetachedView const Range1D rowRng,
const Range1D colRng,
RTOpPack::ConstSubMultiVectorView< Scalar > *  sub_mv
const [pure virtual]
 

Get a non-changeable explicit view of a sub-multi-vector.

Parameters:
rowRng [in] The range of the rows to extract the sub-multi-vector view.
colRng [in] The range of the columns to extract the sub-multi-vector view.
sub_mv [in/out] View of the sub-multi_vector. Prior to the first call to this function, sub_mv->set_uninitialized() must be called. Technically *sub_mv owns the memory but this memory can be freed only by calling this->releaseDetachedView(sub_mv).
Preconditions:
  • this->range().get()!=NULL && this->domain().get()!=NULL (throw std::logic_error)
  • [!rowRng.full_range()] rowRng.ubound() < this->range()->dim() (throw std::out_of_range)
  • [!colRng.full_range()] colRng.ubound() < this->domain()->dim() (throw std::out_of_range)

Postconditions:

  • *sub_mv contains an explicit non-changeable view to the elements in the row and column ranges Teuchos::full_range(rowRng,0,this->range()->dim()-1) and Teuchos::full_range(colRng,0,this->domain()->dim()-1) respectively.

Note: This view is to be used immediately and then released with a call to releaseDetachedView().

Note that calling this operation might require some dynamic memory allocations and temporary memory. Therefore, it is critical that this->releaseDetachedView(sub_mv) be called by client in order to clean up memory and avoid memory leaks after the sub-multi-vector view is finished being used.

Heads Up! Note that client code in general should not directly call this function but should instead use the utility class ConstDetachedMultiVectorView which will also take care of calling releaseDetachedView().

If this->acquireDetachedView(...,sub_mv) was previously called on sub_mv 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_mv) before this->releaseDetachedView(sub_mv) to finally clean up all of the memory. Of course, the same sub_mv object must be passed to the same multi-vector object for this to work correctly.

This function has a default implementation based on the vector operation VectorBase::acquireDetachedView() called on the non-changeable vector objects returned from col(). Note that the footprint of the reduction object (both internal and external state) will be O(rowRng.size()*colRng.size()). For serial applications this is fairly reasonable and will not be a major performance penalty. For parallel applications, however, this is a terrible implementation and must be overridden if rowRng.size() is large at all. Although, this function should not even be used in cases where the multi-vector is very large. If a subclass does override this function, it must also override releaseDetachedView() which has a default implementation which is a companion to this function's default implementation.

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdMultiVectorBase< Scalar >, Thyra::MultiVectorDefaultBase< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::MultiVectorBase< Scalar >::releaseDetachedView RTOpPack::ConstSubMultiVectorView< Scalar > *  sub_mv  )  const [pure virtual]
 

Free a non-changeable explicit view of a sub-multi-vector.

Parameters:
sub_mv [in/out] The memory referred to by sub_mv->values() will be released if it was allocated and *sub_mv will be zeroed out using sub_mv->set_uninitialized().
Preconditions:
  • this->range().get()!=NULL && this->domain().get()!=NULL (throw std::logic_error)
  • sub_mv must have been passed through a call to this->acquireDetachedView(...,sub_mv)

Postconditions:

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

This function has a default implementation which is a companion to the default implementation for acquireDetachedView(). If acquireDetachedView() is overridden by a subclass then this function must be overridden also!

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdMultiVectorBase< Scalar >, Thyra::MultiVectorDefaultBase< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::MultiVectorBase< Scalar >::acquireDetachedView const Range1D rowRng,
const Range1D colRng,
RTOpPack::SubMultiVectorView< Scalar > *  sub_mv
[pure virtual]
 

Get a changeable explicit view of a sub-multi-vector.

Parameters:
rowRng [in] The range of the rows to extract the sub-multi-vector view.
colRng [in] The range of the columns to extract the sub-multi-vector view.
sub_mv [in/out] Changeable view of the sub-multi-vector. Prior to the first call sub_mv->set_uninitialized() must have been called for the correct behavior. Technically *sub_mv owns the memory but this memory must be committed and freed only by calling this->commitDetachedView(sub_mv).
Preconditions:
  • this->range().get()!=NULL && this->domain().get()!=NULL (throw std::logic_error)
  • [!rowRng.full_range()] rowRng.ubound() < this->range()->dim() (throw std::out_of_range)
  • [!colRng.full_range()] colRng.ubound() < this->domain()->dim() (throw std::out_of_range)

Postconditions:

  • *sub_mv contains an explicit changeable view to the elements in the row and column ranges full_range(rowRng,0,this->range()->dim()-1) and full_range(colRng,0,this->domain()->dim()-1) respectively.

Note: This view is to be used immediately and then committed back with a call to commitDetachedView().

Note that calling this operation might require some internal allocations and temporary memory. Therefore, it is critical that this->commitDetachedView(sub_mv) is called to commit the changed entries and clean up memory and avoid memory leaks after the sub-multi-vector is modified.

Heads Up! Note that client code in general should not directly call this function but should instead use the utility class DetachedMultiVectorView which will also take care of calling commitDetachedView.

If this->acquireDetachedView(...,sub_mv) was previously called on sub_mv 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_mv) before this->commitDetachedView(sub_mv) to finally clean up all of the memory. Of course the same sub_mv object must be passed to the same multi-vector object for this to work correctly.

Changes to the underlying sub-multi-vector are not guaranteed to become permanent until this->acquireDetachedView(...,sub_mv) is called again, or this->commitDetachedView(sub_mv) is called.

This function has a default implementation based on the vector operation VectorBase::acquireDetachedView() called on the changeable vector objects returned from col(). Note that the footprint of the reduction object (both internal and external state) will be O(rowRng.size()*colRng.size()). For serial applications this is fairly reasonable and will not be a major performance penalty. For parallel applications, however, this is a terrible implementation and must be overridden if rowRng.size() is large at all. Although, this function should not even be used in case where the multi-vector is very large. If a subclass does override this function, it must also override commitDetachedView() which has a default implementation which is a companion to this function's default implementation.

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdMultiVectorBase< Scalar >, Thyra::MultiVectorDefaultBase< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual void Thyra::MultiVectorBase< Scalar >::commitDetachedView RTOpPack::SubMultiVectorView< Scalar > *  sub_mv  )  [pure virtual]
 

Commit changes for a changeable explicit view of a sub-multi-vector.

Parameters:
sub_mv [in/out] The data in sub_mv->values() will be written back to internal storage and the memory referred to by sub_mv->values() will be released if it was allocated and *sub_mv will be zeroed out using sub_mv->set_uninitialized().
Preconditions:
  • this->range().get()!=NULL && this->domain().get()!=NULL (throw std::logic_error)
  • sub_mv must have been passed through a call to this->acquireDetachedView(...,sub_mv)

Postconditions:

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

This function has a default implementation which is a companion to the default implementation for acquireDetachedView(). If acquireDetachedView() is overridden by a subclass then this function must be overridden also!

Implemented in Thyra::DefaultVectorMultiVector< Scalar >, Thyra::SpmdMultiVectorBase< Scalar >, Thyra::MultiVectorDefaultBase< Scalar >, and Thyra::VectorDefaultBase< Scalar >.

template<class Scalar>
virtual Teuchos::RefCountPtr<MultiVectorBase<Scalar> > Thyra::MultiVectorBase< Scalar >::clone_mv  )  const [pure virtual]
 

Clone the multi-vector object (if supported).

The default implementation uses the vector space to create a new multi-vector object and then uses a transformation operator to assign the vector elements. A subclass should only override this function if it can do something more sophisticated (i.e. lazy evaluation) but in general, this is not needed.

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

template<class Scalar>
Teuchos::RefCountPtr< const LinearOpBase< Scalar > > Thyra::MultiVectorBase< Scalar >::clone  )  const [virtual]
 

This function is simply overridden to return this->clone_mv().

Reimplemented from Thyra::LinearOpBase< Scalar >.

Definition at line 50 of file Thyra_MultiVectorBase.hpp.


Member Data Documentation

template<class Scalar>
VectorBase<Scalar>* Thyra::MultiVectorBase< Scalar >::columns [private]
 

Definition at line 946 of file Thyra_MultiVectorBaseDecl.hpp.


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