RTOpPack::RTOpT< Scalar > Class Template Reference
[Templated interfaces for generalized vector reduction/transformation operators in C++.]

Templated interface to vector reduction/transformation operators {abstract}. More...

#include <RTOpPack_RTOpTDecl.hpp>

Inheritance diagram for RTOpPack::RTOpT< Scalar >:

[legend]
List of all members.

public types

typedef Teuchos::PrimitiveTypeTraits<
Scalar >::primitiveType 
primitive_value_type
 

Reduction object functions

virtual void get_reduct_type_num_entries (int *num_values, int *num_indexes, int *num_chars) const
 Get the number of entries of each basic data type in the externalized state for a reduction object for this operator.
virtual Teuchos::RefCountPtr<
ReductTarget
reduct_obj_create () const
 Creates a new reduction target object initialized and ready to be used in a reduction.
virtual void reduce_reduct_objs (const ReductTarget &in_reduct_obj, ReductTarget *inout_reduct_obj) const
 Reduce intermediate reduction target objects.
virtual void reduct_obj_reinit (ReductTarget *reduct_obj) const
 Reinitialize an already created reduction object.
virtual void extract_reduct_obj_state (const ReductTarget &reduct_obj, int num_values, primitive_value_type value_data[], int num_indexes, index_type index_data[], int num_chars, char_type char_data[]) const
 Extract the state of an already created reduction object.
virtual void load_reduct_obj_state (int num_values, const primitive_value_type value_data[], int num_indexes, const index_type index_data[], int num_chars, const char_type char_data[], ReductTarget *reduct_obj) const
 Load the state of an already created reduction object given arrays of primitive objects.

Operator functions

virtual ~RTOpT ()
 Mandatory virtual destructor.
virtual const char * op_name () const
 Return the name (as a null-terminated C-style string) of the operator.
virtual RTOpT< Scalar > & operator= (const RTOpT< Scalar > &op)
 Copy the state of another operator object into this one.
virtual void get_op_type_num_entries (int *num_values, int *num_indexes, int *num_chars) const
 Return the number of entries of each type of basic data type in the externalized state for the operator object.
virtual void extract_op_state (int num_values, primitive_value_type value_data[], int num_indexes, index_type index_data[], int num_chars, char_type char_data[]) const
 Extract the state of the object in a portable format.
virtual void load_op_state (int num_values, const primitive_value_type value_data[], int num_indexes, const index_type index_data[], int num_chars, const char_type char_data[])
 Load the state of the object from a portable format.
virtual bool coord_invariant () const
 Returns true if this operator is coordinate invariant.
virtual void apply_op (const int num_vecs, const SubVectorT< Scalar > sub_vecs[], const int num_targ_vecs, const MutableSubVectorT< Scalar > targ_sub_vecs[], ReductTarget *reduct_obj) const =0
 Apply the reduction/transformation operator to a set of sub-vectors.

Public Member Functions

 RTOpT (const std::string &op_name_base)
 Constructor that creates an operator name appended with the type.

Detailed Description

template<class Scalar>
class RTOpPack::RTOpT< Scalar >

Templated interface to vector reduction/transformation operators {abstract}.

The purpose of this base class is to allow users to specify arbitrary reduction/transformation operations on vectors without requiring the vectors to reveal their implementation details. The design is motivated partly by the "Visitor" patter (Gamma, 1995).

This interface is designed to allow implementation of a distributed parallel application without the explicit knowledge by the application.

In the following discussion, v[k], x, y and z are some abstract vector objects of dimension n. Users can define operators to perform reduction and/or transformation operations. Reduction operations applied over all of the elements of a vector require communication between nodes in a parallel environment but do not change any of the vectors involved. Transformation operations don't require communication between nodes in a parallel environment. The targets of a transformation operation is a set of one or more vectors which are mutated in some way.

The idea is that the user may want to perform reduction operations of the form:


 op(v[0]...v[*],z[0]...z[*]) -> reduct_obj
 

where reduct_obj is a single object based on a reduction over all the elements of the vector arguments, or transformation operations of the form:


 op(v[0](i)...v[*](i),z[0](i)...z[*](i)) -> z[0](i)...z[*](i), for i = 1...n
 

Operators can also be defined that perform reduction and transformation operations.

The tricky part though, is that the reduct_obj object of the reduction operation may be more complex than a single scalar value. For instance, it could be a double and an int pair such as in the reduction operation:


 min{ |x(i)|, i = 1...n } -> [ x(j_min), j_min ]
 

or it could perform several reductions at once and store several scalar values such as in:


 min_max_sum{ x(i), i = 1...n } -> [ x(j_min), j_min, x(j_max), j_max, x_sum ]
 

Transformation operations are much simpler to think about and to deal with. Some off-the-wall examples of transformation operations that this design will support are:


 max{ |x(i)|, |y(i)| } + |z(i)| -> z(i), for i = 1...n
 
 alpha * |z(i)| / x(i) -> z(i), for i = 1...n
 
 alpha * x(i) * y(i) + beta * z(i) -> z(i), for i = 1...n
 

Reduction operations present the more difficult technical challenge since they require information gathered from all of the elements to arrive at the final result. This design allows operator classes to be defined that can simultaneously perform reduction and transformation operations:


   op(v[0](i)...v[*](i),z[0](i)...z[*](i)) -> z[0](i)...z[*](i),reduct_obj
      , for i = 1...n
 

This design is based on a few assumptions about the reduction and transformation operations and vector implementations themselves. First, we will assume that vectors are stored and manipulated as chunks of sub-vectors (of dimension subDim) where each sub-vector is sufficiently large. This design supports dense strided sub-vectors (see SubVectorT and MutableSubVectorT) and is relatively flexible.

It is strictly the responsibilities of the vector implementations to determine how these operators are applied. For instance, if we are performing a transformation operation of the form:


 op( x(i), y(i), z(i) ) -> z(i), for i = 1...n
 

where x, y, and z are distributed parallel vectors, then we would assume that the elements would be partitioned onto the various processors with the same local elements stored on each processor so as not to require any communication between processors.

Definition at line 158 of file RTOpPack_RTOpTDecl.hpp.


Member Typedef Documentation

template<class Scalar>
typedef Teuchos::PrimitiveTypeTraits<Scalar>::primitiveType RTOpPack::RTOpT< Scalar >::primitive_value_type
 

Reimplemented in RTOpPack::ROpScalarReductionBase< Scalar >, RTOpPack::ROpScalarIndexReductionBase< Scalar >, RTOpPack::ROpIndexReductionBase< Scalar >, RTOpPack::ROpScalarTransformationBase< Scalar >, RTOpPack::ROpScalarScalarTransformationBase< Scalar >, RTOpPack::ROpGetSubVector< Scalar >, RTOpPack::TOpSetSubVector< Scalar >, and RTOpPack::ROpScalarReductionBase< Teuchos::ScalarTraits< Scalar >::magnitudeType >.

Definition at line 165 of file RTOpPack_RTOpTDecl.hpp.


Constructor & Destructor Documentation

template<class Scalar>
RTOpPack::RTOpT< Scalar >::RTOpT const std::string &  op_name_base  ) 
 

Constructor that creates an operator name appended with the type.

Definition at line 40 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
RTOpPack::RTOpT< Scalar >::~RTOpT  )  [virtual]
 

Mandatory virtual destructor.

Definition at line 115 of file RTOpPack_RTOpT.hpp.


Member Function Documentation

template<class Scalar>
void RTOpPack::RTOpT< Scalar >::get_reduct_type_num_entries int *  num_values,
int *  num_indexes,
int *  num_chars
const [virtual]
 

Get the number of entries of each basic data type in the externalized state for a reduction object for this operator.

Note that a specific reduction object is not passed in as an argument. This is because the structure of a reduction object is completely determined by its associated operator object and this structure can not change as a result of a reduction operation (this is needed to simplify global communication code when used * with MPI).

The default implementation returns zeros for *num_values, *num_indexes and *num_chars (i.e. by default there is no reduction operation performed).

Reimplemented in RTOpPack::ROpScalarReductionBase< Scalar >, RTOpPack::ROpScalarIndexReductionBase< Scalar >, RTOpPack::ROpIndexReductionBase< Scalar >, RTOpPack::ROpGetSubVector< Scalar >, and RTOpPack::ROpScalarReductionBase< Teuchos::ScalarTraits< Scalar >::magnitudeType >.

Definition at line 47 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
Teuchos::RefCountPtr< ReductTarget > RTOpPack::RTOpT< Scalar >::reduct_obj_create  )  const [virtual]
 

Creates a new reduction target object initialized and ready to be used in a reduction.

To delete this object simply let the returned RefCountPtr<> object go out of scope.

The default implementation returns return.get()==NULL (i.e. by default there is no reduction operation performed).

Reimplemented in RTOpPack::ROpScalarReductionBase< Scalar >, RTOpPack::ROpScalarIndexReductionBase< Scalar >, RTOpPack::ROpIndexReductionBase< Scalar >, RTOpPack::ROpGetSubVector< Scalar >, and RTOpPack::ROpScalarReductionBase< Teuchos::ScalarTraits< Scalar >::magnitudeType >.

Definition at line 65 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
void RTOpPack::RTOpT< Scalar >::reduce_reduct_objs const ReductTarget in_reduct_obj,
ReductTarget inout_reduct_obj
const [virtual]
 

Reduce intermediate reduction target objects.

The default implementation does not do anything (i.e. by default there is no reduction operation performed).

Reimplemented in RTOpPack::ROpScalarReductionBase< Scalar >, RTOpPack::ROpIndexReductionBase< Scalar >, RTOpPack::ROpGetSubVector< Scalar >, RTOpPack::ROpMax< Scalar >, RTOpPack::ROpMaxIndex< Scalar >, RTOpPack::ROpMaxIndexLessThanBound< Scalar >, RTOpPack::ROpMin< Scalar >, RTOpPack::ROpMinIndex< Scalar >, RTOpPack::ROpMinIndexGreaterThanBound< Scalar >, RTOpPack::ROpNormInf< Scalar >, and RTOpPack::ROpScalarReductionBase< Teuchos::ScalarTraits< Scalar >::magnitudeType >.

Definition at line 71 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
void RTOpPack::RTOpT< Scalar >::reduct_obj_reinit ReductTarget reduct_obj  )  const [virtual]
 

Reinitialize an already created reduction object.

The default implementation does nothing (i.e. by default there is no reduction operation performed).

Parameters:
reduct_obj [in/out] Reduction object is reinitialized on output.

Reimplemented in RTOpPack::ROpScalarReductionBase< Scalar >, RTOpPack::ROpScalarIndexReductionBase< Scalar >, RTOpPack::ROpIndexReductionBase< Scalar >, RTOpPack::ROpGetSubVector< Scalar >, and RTOpPack::ROpScalarReductionBase< Teuchos::ScalarTraits< Scalar >::magnitudeType >.

Definition at line 79 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
void RTOpPack::RTOpT< Scalar >::extract_reduct_obj_state const ReductTarget reduct_obj,
int  num_values,
primitive_value_type  value_data[],
int  num_indexes,
index_type  index_data[],
int  num_chars,
char_type  char_data[]
const [virtual]
 

Extract the state of an already created reduction object.

This method allows the state of a reduction target object to be externalized so that it can be passed over a heterogeneous network of computers.

The default implementation does nothing (i.e. by default there is no reduction operation performed).

Reimplemented in RTOpPack::ROpScalarReductionBase< Scalar >, RTOpPack::ROpScalarIndexReductionBase< Scalar >, RTOpPack::ROpIndexReductionBase< Scalar >, and RTOpPack::ROpScalarReductionBase< Teuchos::ScalarTraits< Scalar >::magnitudeType >.

Definition at line 85 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
void RTOpPack::RTOpT< Scalar >::load_reduct_obj_state int  num_values,
const primitive_value_type  value_data[],
int  num_indexes,
const index_type  index_data[],
int  num_chars,
const char_type  char_data[],
ReductTarget reduct_obj
const [virtual]
 

Load the state of an already created reduction object given arrays of primitive objects.

The default implementation does nothing.

Reimplemented in RTOpPack::ROpScalarReductionBase< Scalar >, RTOpPack::ROpScalarIndexReductionBase< Scalar >, RTOpPack::ROpIndexReductionBase< Scalar >, and RTOpPack::ROpScalarReductionBase< Teuchos::ScalarTraits< Scalar >::magnitudeType >.

Definition at line 99 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
const char * RTOpPack::RTOpT< Scalar >::op_name  )  const [virtual]
 

Return the name (as a null-terminated C-style string) of the operator.

This name is used to differentiate an operator subclass from all other operator subclasses. This is an important property needed for a client/server or master/slave runtime configuration.

The default implementation uses the value created in the constructor RTOpT().

Reimplemented in RTOpPack::TOpUnaryFuncPtr< Scalar >.

Definition at line 119 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
RTOpT< Scalar > & RTOpPack::RTOpT< Scalar >::operator= const RTOpT< Scalar > &  op  )  [virtual]
 

Copy the state of another operator object into this one.

This default version uses op->ref extract_op_state() and this->load_op_state() to perform the copy. No override should be needed by subclasses (unless a slightly more efficient implementation is desired).

Definition at line 125 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
void RTOpPack::RTOpT< Scalar >::get_op_type_num_entries int *  num_values,
int *  num_indexes,
int *  num_chars
const [virtual]
 

Return the number of entries of each type of basic data type in the externalized state for the operator object.

The default implementation returns zeros for *num_values, *num_indexes and *num_chars (i.e. the default reduction/transformation operator has no state).

Reimplemented in RTOpPack::ROpScalarTransformationBase< Scalar >, RTOpPack::ROpScalarScalarTransformationBase< Scalar >, RTOpPack::ROpGetSubVector< Scalar >, and RTOpPack::TOpSetSubVector< Scalar >.

Definition at line 148 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
void RTOpPack::RTOpT< Scalar >::extract_op_state int  num_values,
primitive_value_type  value_data[],
int  num_indexes,
index_type  index_data[],
int  num_chars,
char_type  char_data[]
const [virtual]
 

Extract the state of the object in a portable format.

This method allows the state of a reduction/transformation operator to be externalized so that it can be passed over a heterogeneous network of computers.

The default implementation does nothing (i.e. the default reduction/transformation operator has no state).

Parameters:
num_values [in] Value returned from this->get_op_type_num_entries().
value_data [out] Array (size num_values) of floating point data.
num_indexes [in] Value returned from this->get_op_type_num_entries().
index_data [out] Array (size num_indexes) of integral data.
num_chars [in] Value returned from this->get_op_type_num_entries().
char_data [out] Array (size num_chars) of character data.

Reimplemented in RTOpPack::ROpScalarTransformationBase< Scalar >, RTOpPack::ROpScalarScalarTransformationBase< Scalar >, and RTOpPack::TOpSetSubVector< Scalar >.

Definition at line 165 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
void RTOpPack::RTOpT< Scalar >::load_op_state int  num_values,
const primitive_value_type  value_data[],
int  num_indexes,
const index_type  index_data[],
int  num_chars,
const char_type  char_data[]
[virtual]
 

Load the state of the object from a portable format.

This method allows the state of the operator object to be set given an the externalized state as extracted using extract_op_state(...) called on a compatible operator object (possibly on a different heterogeneous computer).

The default implementation does nothing (i.e. the default reduction/transformation operator has no state).

Parameters:
num_values [in] Value returned from this->get_op_type_num_entries().
value_data [out] Array (size num_values) of floating point data.
num_indexes [in] Value returned from this->get_op_type_num_entries().
index_data [out] Array (size num_indexes) of integral data.
num_chars [in] Value returned from this->get_op_type_num_entries().
char_data [out] Array (size num_chars) of character data.

Reimplemented in RTOpPack::ROpScalarTransformationBase< Scalar >, RTOpPack::ROpScalarScalarTransformationBase< Scalar >, and RTOpPack::TOpSetSubVector< Scalar >.

Definition at line 178 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
bool RTOpPack::RTOpT< Scalar >::coord_invariant  )  const [virtual]
 

Returns true if this operator is coordinate invariant.

The default implementation returns true as most vector operators are coordinate invariant.

Reimplemented in RTOpPack::ROpGetSubVector< Scalar >, RTOpPack::ROpMaxIndex< Scalar >, RTOpPack::ROpMaxIndexLessThanBound< Scalar >, RTOpPack::ROpMinIndex< Scalar >, RTOpPack::ROpMinIndexGreaterThanBound< Scalar >, and RTOpPack::TOpSetSubVector< Scalar >.

Definition at line 191 of file RTOpPack_RTOpT.hpp.

template<class Scalar>
virtual void RTOpPack::RTOpT< Scalar >::apply_op const int  num_vecs,
const SubVectorT< Scalar >  sub_vecs[],
const int  num_targ_vecs,
const MutableSubVectorT< Scalar >  targ_sub_vecs[],
ReductTarget reduct_obj
const [pure virtual]
 

Apply the reduction/transformation operator to a set of sub-vectors.

op(sub_vecs[],targ_sub_vecs[]),reduct_obj) -> targ_sub_vecs[],reduct_obj.

This is the bread and butter of the whole design. Through this method, a vector implementation applies a reduction/transformation operator to a set of sub-vectors.

Parameters:
num_vecs [in] Number of non-mutable sub-vectors in sub_vec[].
sub_vecs [in] Array (length num_vecs) of non-mutable vectors to apply the operator over. The ordering of these sub-vectors sub_vecs[k], for k = 0...num_vecs-1, is significant to the this operator object. If num_vecs == 0 then sub_vecs can be NULL.
num_targ_vecs [in] Number of mutable sub-vectors in targ_sub_vec[].
targ_sub_vecs [in/out] Array (length num_targ_vecs) of mutable vectors to apply the operator over and be mutated. The ordering of these sub-vectors targ_sub_vecs[k], for k = 0...num_targ_vecs-1, is significant to this operator object. If num_targ_vecs == 0 then targ_sub_vecs can be NULL.
reduct_obj [in/out] This reduction object must have been created by a this->reduct_obj_create() call and it may have already passed through one or more other reduction operations (accumulating the reductions along the way). If this->get_reduct_type_num_entries() returns num_values==0, num_indexes==0 and num_chars==0, then reduct_obj should be set to NULL as no reduction will be performed.
Preconditions:
  • num_vecs > 0 || num_targ_vecs > 0
  • [num_vecs > 0] sub_vecs != NULL
  • [num_targ_vecs > 0] targ_sub_vecs != NULL
  • [num_vecs > 0] globalOffset==sub_vecs[k].globalOffset , for k = 0,...,num_vecs-1
  • [num_targ_vecs > 0] globalOffset==targ_sub_vecs[k].globalOffset , for k = 0,...,num_targ_vecs-1
  • [num_vecs > 0] sub_dim==sub_vecs[k].subDim() , for k = 0,...,num_vecs-1
  • [num_targ_vecs > 0] sub_dim==targ_sub_vecs[k].subDim() , for k = 0,...,num_targ_vecs-1

If reduct_obj != NULL then the reduction operation will be accumulated as:

     op(op(sub_vecs[],targ_sub_vecs[]),reduct_obj) -> reduct_obj
   

By allowing an in/out reduct_obj and an accumulation of the reduction, the maximum reuse of memory is achieved. If this->reduct_obj_create() or this->reduct_obj_reinit() (passing in reduct_obj) was called immediately before this function, then on return, reduct_obj will contain only the reduction from this function call.

If num_vecs is incompatible with the underlying operator object then InvalidNumVecs is thrown. If the sub-vectors are not compatible (i.e. global_offset and/or sub_dim not the same) then IncompatibleVecs is thrown.

Implemented in RTOpPack::TOpUnaryFuncPtr< Scalar >, RTOpPack::ROpCountNanInf< Scalar >, RTOpPack::ROpDotProd< Scalar >, RTOpPack::ROpGetSubVector< Scalar >, RTOpPack::ROpMax< Scalar >, RTOpPack::ROpMaxIndex< Scalar >, RTOpPack::ROpMaxIndexLessThanBound< Scalar >, RTOpPack::ROpMin< Scalar >, RTOpPack::ROpMinIndex< Scalar >, RTOpPack::ROpMinIndexGreaterThanBound< Scalar >, RTOpPack::ROpNorm2< Scalar >, RTOpPack::ROpSum< Scalar >, RTOpPack::ROpWeightedNorm2< Scalar >, RTOpPack::TOpAbs< Scalar >, RTOpPack::TOpAddScalar< Scalar >, RTOpPack::TOpAssignScalar< Scalar >, RTOpPack::TOpAssignVectors< Scalar >, RTOpPack::TOpAXPY< Scalar >, RTOpPack::TOpEleWiseDivide< Scalar >, RTOpPack::TOpEleWiseProd< Scalar >, RTOpPack::TOpLinearCombination< Scalar >, RTOpPack::TOpRandomize< Scalar >, RTOpPack::TOpReciprocal< Scalar >, RTOpPack::TOpScaleVector< Scalar >, and RTOpPack::TOpSetSubVector< Scalar >.


The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:39:44 2008 for RTOp : Vector Reduction/Transformation Operators by doxygen 1.3.9.1