#include <Thyra_MultiVectorBaseDecl.hpp>
Inheritance diagram for Thyra::MultiVectorBase< Scalar >:
Provide access to the columns as VectorBase objects | |
virtual RCP< const VectorBase< Scalar > > | col (Index j) const |
Return a non-changeable view of a constituent column vector. | |
virtual RCP< VectorBase< Scalar > > | col (Index j)=0 |
Return a changeable view of a constituent column vector. | |
Multi-vector sub-views | |
virtual RCP< 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 RCP< MultiVectorBase< Scalar > > | subView (const Range1D &colRng)=0 |
Return a changeable sub-view of a contiguous set of columns of the this multi-vector. | |
virtual RCP< 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 RCP< 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 | |
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 |
Temporary NVI function. | |
virtual void | mvMultiReductApplyOpImpl (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. | |
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 |
Temporary NVI function. | |
virtual void | mvSingleReductApplyOpImpl (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 | |
void | acquireDetachedView (const Range1D &rowRng, const Range1D &colRng, RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const |
Temporary NVI function. | |
virtual void | acquireDetachedMultiVectorViewImpl (const Range1D &rowRng, const Range1D &colRng, RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const =0 |
Get a non-changeable explicit view of a sub-multi-vector. | |
void | releaseDetachedView (RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const |
Temporary NVI function. | |
virtual void | releaseDetachedMultiVectorViewImpl (RTOpPack::ConstSubMultiVectorView< Scalar > *sub_mv) const =0 |
Free a non-changeable explicit view of a sub-multi-vector. | |
void | acquireDetachedView (const Range1D &rowRng, const Range1D &colRng, RTOpPack::SubMultiVectorView< Scalar > *sub_mv) |
Temporary NVI function. | |
virtual void | acquireNonconstDetachedMultiVectorViewImpl (const Range1D &rowRng, const Range1D &colRng, RTOpPack::SubMultiVectorView< Scalar > *sub_mv)=0 |
Get a changeable explicit view of a sub-multi-vector. | |
void | commitDetachedView (RTOpPack::SubMultiVectorView< Scalar > *sub_mv) |
Temporary NVI function. | |
virtual void | commitNonconstDetachedMultiVectorViewImpl (RTOpPack::SubMultiVectorView< Scalar > *sub_mv)=0 |
Commit changes for a changeable explicit view of a sub-multi-vector. | |
Cloning | |
virtual RCP< MultiVectorBase< Scalar > > | clone_mv () const =0 |
Clone the multi-vector object (if supported). | |
Overridden functions from LinearOpBase | |
RCP< const LinearOpBase< Scalar > > | clone () const |
This function is simply overridden to return this->clone_mv() . | |
Related Functions | |
(Note that these are not member functions.) | |
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=0, const Index primary_sub_dim=-1, const Index primary_global_offset=0, const Index secondary_first_ele_offset=0, const Index secondary_sub_dim=-1) |
Apply a reduction/transformation operator column by column and return an array of the reduction objects. | |
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=0, const Index primary_sub_dim=-1, const Index primary_global_offset=0, const Index secondary_first_ele_offset=0, const Index secondary_sub_dim=-1) |
Apply a reduction/transformation operator column by column and reduce the intermediate reduction objects into one reduction object. |
VectorBase
and MultiVectorBase
views of single and multiple columns of *this
multi-vector, respectively. These two views are described separately in the next two subsections. The behavior of the vector and multi-vector views is very similar and the common behavior is described in the subsection Common behavior of vector and multi-vector views.col()
function. For example, the individual columns of one multi-vector can be copied to another as follows
template<class Scalar> void copyOneColumnAtATime( const Thyra::MultiVectorBase<Scalar> &X ,Thyra::MultiVectorBase<Scalar> *Y ) { for( int j = =; j < X.domain()->dim(); ++j ) assign( &*Y->col(j), *X.col(j) ); }
In the above code fragment, the expression X.col(j)
returns a smart-pointer to a non-changeable column of X
while the expression Y->col(j)
returns a smart-pointer to a changeable column of Y
which is being modified.
Note: A modification to Y
is not guaranteed to be committed back to Y
until the smart pointer returned from Y.col(j)
is deleted.
MultiVectorBase
views of columns of a parent MultiVectorBase
object. These sub-views are created with one of the overloaded subView()
functions of which there are two general forms.
The first form provides views of contiguous columns through the functions subView(const Range1D&)
and subView(const Range1D&)const
. For example, the following function shows how to copy the first three columns of one multi-vector to the last three columns of another multi-vector.
template<class Scalar> void copyThreeColumns( const Thyra::MultiVectorBase<Scalar> &X ,Thyra::MultiVectorBase<Scalar> *Y ) { const int m = Y->domain()->dim(); assign( &*Y->subView(Range1D(m-3,m-1)), *X.subView(Range1D(0,2)) ); }
Note: In the above example *Y
can be the same multi-vector as X
.
Note: In the above example *Y
is not guaranteed to be updated until the view returned from Y->subView(Range1D(m-3,m-1)
is destroyed (which occurs at the end of the statement in which it occurs in this case).
The second form provides views of non-contiguous columns through the functions subView(const int numCols, const int cols[])
and subView(const int numCols, const int cols[]) const
. For example, the following function copies columns 1, 3, and 5 from one multi-vector to columns 2, 4, and 6 of another multi-vector.
template<class Scalar> void copyThreeStaggeredColumns( const Thyra::MultiVectorBase<Scalar> &X ,Thyra::MultiVectorBase<Scalar> *Y ) { using Teuchos::arrayArg; assign( &*Y->subView(3,arrayArg<int>(2,4,6)()), ,*X.subView(3,arrayArg<int>(1,3,5)()) ); }
Note: In the above example *Y
can be the same multi-vector as X
.
Note: In the above example *Y
is not guaranteed to be updated until the view returned from Y->subView(3,arrayArg<int>(2,4,6)())
is destroyed (which occurs at the end of the statement in which it occurs in this case).
In general, the first contiguous form of views will be more efficient that the second non-contiguous form. Therefore, user's should try to structure their ANAs to use the contiguous form of multi-vector views if possible and only result to the non-contiguous form of views when absolutely needed.
If X_view
is some view of a parent multi-vector X
the following restrictions apply:
The client should not attempt to change the parent multi-vector X
while any view is active. The behavior of doing so is undefined. For example, the value returned from the following function and the final state of the parent multi-vector *X
are undefined:
template<class Scalar> Scalar undefinedBehaviorFromChangingParent( Thyra::MultiVectorBase<Scalar> *X ) { // Create the view RCP< Thyra::MultiVectorBase<Scalar> > X_view = X->subView(Teuchos::Range1D(0,0)); // Change the parent while the view is still active Teuchos::assign( X, Teuchos::ScalarTraits<Scalar>::one() ); // Above, changing the parent multi-vector may or may not change the subview return Teuchos::norm_1(*X_view); // The value returned is undefined // When the RCP X_view goes out of scope here, the state of the // parent multi-vector *X is undefined! }
The client should not attempt to change the view X_view
and then access the parent multi-vector X
while the view is still active. The behavior of doing so is undefined. For example, the value returned from the following function is undefined:
template<class Scalar> Scalar undefinedBehaviorFromChaningViewAndAccessingParent( Thyra::MultiVectorBase<Scalar> *X ) { // Create the view RCP< Thyra::MultiVectorBase<Scalar> > X_view = X->subView(Teuchos::Range1D(0,0)); // Change the view Teuchos::assign( *&X_view, Teuchos::ScalarTraits<Scalar>::one() ); // Above, changing the view may or may not immediately update the parent multi-vector return Teuchos::norm_1(*X); // The value returned from the parent is undefined at this point // When the RCP X_view goes out of scope here, the parent multi-vector // *X is guaranteed to be updated }
The client should not attempt to create overlapping changeable views. If any of these changeable views is modified, the the behavior of the parent multi-vector is undefined. For example, the state of the parent multi-vector *X
is undefined after the following function returns:
template<class Scalar> Scalar undefinedBehaviorOfOverlappingViews( Thyra::MultiVectorBase<Scalar> *X ) { // Create two overlapping views RCP< Thyra::MultiVectorBase<Scalar> > X_view1 = X->subView(Teuchos::Range1D(0,0)), X_view2 = X->subView(Teuchos::Range1D(0,0)); // Change one of the views but not the other Teuchos::assign( *&X_view2, Teuchos::ScalarTraits<Scalar>::one() ); // Once the RCPs X_view1 and X_view2 go out of scope here, // the state of the parent multi-vector *X is undefined! In some cases, // the intial view in X_view1 will be relected in X and in other // cases the view in X_view2 will be written to the parent X. }
Note that overlapping non-changeable views of a multi-vector are just fine since they do not change the state of the parent multi-vector.
In general, to stay out of trouble with multi-vector views:
Note, however, that creating simultaneous non-overlapping non-changeable or changeable views is just fine as long as the parent multi-vector is not modified while the views are active. For example, the final state of *X
is well defined after the following function finishes executing:
template<class Scalar> Scalar wellDefinedBehaviorOfNonOverlappingViews( Thyra::MultiVectorBase<Scalar> *X ) { // Create two non-overlapping views RCP< Thyra::MultiVectorBase<Scalar> > X_view1 = X->subView(Teuchos::Range1D(0,0)), X_view2 = X->subView(Teuchos::Range1D(1,1)); // Change the two views Teuchos::assign( *&X_view1, Teuchos::ScalarTraits<Scalar>::zero() ); Teuchos::assign( *&X_view2, Teuchos::ScalarTraits<Scalar>::one() ); // When the RCPs X_view1 and X_view2 go out of scope here, // the state of the parent multi-vector *X will be guaranteed to be // updated to the values changed in these views. }
MultiVectorBase
interface is derived from the LinearOpBase
interface and therefore every MultiVectorBase
object can be used as a linear operator which has some interesting implications. Since a linear operator can apply itself to vectors and multi-vectors and a multi-vector is a linear operator, this means that a multi-vector can apply itself to other vectors and multi-vectors. There are several different use cases that this functionality is useful. Two of the more important use cases are block updates and block inner products.V
and Y
be multi-vector objects with the same vector space with a very large number of rows m
and a moderate number of columns n
. Now, consider the block update of the form
Y = Y + V * B
where the multi-vector B
is of dimension n x b
.
The following function shows how this block update might be performed.
template<class Scalar> void myBlockUpdate( const Thyra::MultiVectorBase<Scalar> &V ,const int b ,Thyra::MultiVectorBase<Scalar> *Y ) { typedef Teuchos::ScalarTraits<Scalar> ST; // Create the multi-vector B used for the update RCP<Thyra::MultiVectorBase<Scalar> > B = createMembers(V.domain(),b); // Fill up B for the update ... // Do the update Y = V*B + Y V.apply(Thyra::NONCONJ_ELE,*B,Y,ST::one(),ST::one()); }
In a block update, as demonstrated above, level-3 BLAS can be used to provide a very high level of performance. Note that in an SPMD program, that B
would be a locally replicated multi-vector and V
and Y
would be distributed-memory multi-vectors. In an SPMD environment, there would be no global communication in a block update.
LinearOpBase::applyTranspose()
function is the block inner product which takes the form
B = adjoint(V)*X
where V
and X
are tall, thin multi-vectors and B
is a small multi-vector. In an SPMD environment, V
and X
would be distributed-memory objects while B
would be locally replicated in each process. The following function shows how block inner product would be performed:
template<class Scalar> RCP<Thyra::MultiVectorBase<Scalar> > void myBlockInnerProd( const Thyra::MultiVectorBase<Scalar> &V ,const Thyra::MultiVectorBase<Scalar> &X ) { // Create the multi-vector B used for the result RCP<Thyra::MultiVectorBase<Scalar> > B = createMembers(V.domain(),X.domain()->dim()); // Do the inner product B = adjoint(V)*X V.applyTranspose(Thyra::CONJ_ELE,X,&*B); // Return the result return B; }
In an SPMD program, the above block inner product will use level-3 BLAS to multiply the local elements of V
and X
and will then do a single global reduction to assemble the product B
in all of the processes.
applyOp()
functions. The behavior is identical to the client extracting each column in a set of multi-vectors and calling VectorBase::applyOp()
individually on these columns. However, the advantage of using the multi-vector apply functions is that there may be greater opportunities for increased performance in a number of respects. Also, the intermediate reduction objects over a set of columns can be reduced by a secondary reduction object.applyOp()
. See the Operator/Vector Support Software collection for these.RTOpPack::ConstSubMultiVectorView
objects or changeable RTOpPack::SubMultiVectorView
objects using the acquireDetachedView()
functions. In general, this is a very bad thing to do and should be avoided. However, there are some situations where this is needed, just as is the case for vectors (see Explicit vector coefficient access). The default implementation of these explicit access functions use sophisticated reduction/transformation operators with the applyOp()
function in order to extract and set the needed elements. Therefore, all MultiVectorBase
subclasses automatically support these operations (even if it is a bad idea to use them).ConstDetachedMultiVectorView
and DetachedMultiVectorView
since these are easier to use and safer in the event that an exception is thrown. These classes are documented in the Operator/Vector Support Software collection.MultiVectorDefaultBase
(contained in the Operator/Vector Support Software collection) uses a default multi-vector implementation to provide overrides of many of the functions and should be the first choice for subclasses implementations to derive their implementations from rather than starting from scratch.
Definition at line 476 of file Thyra_MultiVectorBaseDecl.hpp.
RCP< const VectorBase< Scalar > > Thyra::MultiVectorBase< Scalar >::col | ( | Index | j | ) | const [virtual] |
Return a non-changeable view of a constituent column vector.
j | [in] zero-based index of the column to return a view for |
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 Accessing the individual columns as vector views and Common behavior of vector and multi-vector views 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.
virtual RCP<VectorBase<Scalar> > Thyra::MultiVectorBase< Scalar >::col | ( | Index | j | ) | [pure virtual] |
Return a changeable view of a constituent column vector.
j | [in] zero-based index of the column to return a view for |
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 Accessing the individual columns as vector views and Common behavior of vector and multi-vector views for the behavior of this view.
Note: *this
is not guaranteed to be modified until the smart pointer returned by this function is destroyed.
virtual RCP<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.
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. |
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 Accessing collections of columns as multi-vector views and Common behavior of vector and multi-vector views for the behavior of this view.
virtual RCP<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.
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. |
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 Accessing collections of columns as multi-vector views and Common behavior of vector and multi-vector views for the behavior of this view.
virtual RCP<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.
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. |
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 Accessing collections of columns as multi-vector views and Common behavior of vector and multi-vector views for the behavior of this view.
virtual RCP<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.
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. |
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 Accessing collections of columns as multi-vector views and Common behavior of vector and multi-vector views for the behavior of this view.
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 [inline] |
virtual void Thyra::MultiVectorBase< Scalar >::mvMultiReductApplyOpImpl | ( | 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:
this->domain().get()!=NULL && this->range().get()!=NULL
(throw std::logic_error
) Thyra::applyOp()
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
.
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 [inline] |
virtual void Thyra::MultiVectorBase< Scalar >::mvSingleReductApplyOpImpl | ( | 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:
this->domain().get()!=NULL && this->range().get()!=NULL
(throw std::logic_error
) Thyra::applyOp()
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.
void Thyra::MultiVectorBase< Scalar >::acquireDetachedView | ( | const Range1D & | rowRng, | |
const Range1D & | colRng, | |||
RTOpPack::ConstSubMultiVectorView< Scalar > * | sub_mv | |||
) | const [inline] |
virtual void Thyra::MultiVectorBase< Scalar >::acquireDetachedMultiVectorViewImpl | ( | 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.
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) . |
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.
void Thyra::MultiVectorBase< Scalar >::releaseDetachedView | ( | RTOpPack::ConstSubMultiVectorView< Scalar > * | sub_mv | ) | const [inline] |
virtual void Thyra::MultiVectorBase< Scalar >::releaseDetachedMultiVectorViewImpl | ( | RTOpPack::ConstSubMultiVectorView< Scalar > * | sub_mv | ) | const [pure virtual] |
Free a non-changeable explicit view of a sub-multi-vector.
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() . |
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:
RTOpPack::ConstSubMultiVectorView::set_uninitialized()
for sub_mv
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!
void Thyra::MultiVectorBase< Scalar >::acquireDetachedView | ( | const Range1D & | rowRng, | |
const Range1D & | colRng, | |||
RTOpPack::SubMultiVectorView< Scalar > * | sub_mv | |||
) | [inline] |
virtual void Thyra::MultiVectorBase< Scalar >::acquireNonconstDetachedMultiVectorViewImpl | ( | const Range1D & | rowRng, | |
const Range1D & | colRng, | |||
RTOpPack::SubMultiVectorView< Scalar > * | sub_mv | |||
) | [pure virtual] |
Get a changeable explicit view of a sub-multi-vector.
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) . |
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.
void Thyra::MultiVectorBase< Scalar >::commitDetachedView | ( | RTOpPack::SubMultiVectorView< Scalar > * | sub_mv | ) | [inline] |
virtual void Thyra::MultiVectorBase< Scalar >::commitNonconstDetachedMultiVectorViewImpl | ( | RTOpPack::SubMultiVectorView< Scalar > * | sub_mv | ) | [pure virtual] |
Commit changes for a changeable explicit view of a sub-multi-vector.
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() . |
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:
RTOpPack::SubMultiVectorView::set_uninitialized()
for sub_mv
*this
will be updated according the the changes made to sub_mv
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!
virtual RCP<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.
RCP< 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.
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 = 0 , |
|||
const Index | primary_sub_dim = -1 , |
|||
const Index | primary_global_offset = 0 , |
|||
const Index | secondary_first_ele_offset = 0 , |
|||
const Index | secondary_sub_dim = -1 | |||
) | [related] |
Apply a reduction/transformation operator column by column and return an array of the reduction objects.
ToDo: Finish documentation!
Definition at line 1052 of file Thyra_MultiVectorBaseDecl.hpp.
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 = 0 , |
|||
const Index | primary_sub_dim = -1 , |
|||
const Index | primary_global_offset = 0 , |
|||
const Index | secondary_first_ele_offset = 0 , |
|||
const Index | secondary_sub_dim = -1 | |||
) | [related] |
Apply a reduction/transformation operator column by column and reduce the intermediate reduction objects into one reduction object.
ToDo: Finish documentation!
Definition at line 1091 of file Thyra_MultiVectorBaseDecl.hpp.