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_RTOpT_decl.hpp>

Inheritance diagram for RTOpPack::RTOpT< Scalar >:

Inheritance graph
[legend]
List of all members.

public types

typedef PrimitiveTypeTraits<
Scalar, Scalar >::primitiveType 
primitive_value_type
 

Reduction object functions (NVI)

void get_reduct_type_num_entries (const Ptr< int > &num_values, const Ptr< int > &num_indexes, const Ptr< 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.
Teuchos::RCP< ReductTargetreduct_obj_create () const
 Creates a new reduction target object initialized and ready to be used in a reduction.
void reduce_reduct_objs (const ReductTarget &in_reduct_obj, const Ptr< ReductTarget > &inout_reduct_obj) const
 Reduce intermediate reduction target objects.
void reduct_obj_reinit (const Ptr< ReductTarget > &reduct_obj) const
 Reinitialize an already created reduction object.
void extract_reduct_obj_state (const ReductTarget &reduct_obj, const ArrayView< primitive_value_type > &value_data, const ArrayView< index_type > &index_data, const ArrayView< char_type > &char_data) const
 Extract the state of an already created reduction object.
void load_reduct_obj_state (const ArrayView< const primitive_value_type > &value_data, const ArrayView< const index_type > &index_data, const ArrayView< const char_type > &char_data, const Ptr< ReductTarget > &reduct_obj) const
 Load the state of an already created reduction object given arrays of primitive objects.

Operator functions (NIV)

const std::string op_name () const
 Return the name (as a null-terminated C-style string) of the operator.
bool coord_invariant () const
 Returns true if this operator is coordinate invariant.
void apply_op (const ArrayView< const ConstSubVectorView< Scalar > > &sub_vecs, const ArrayView< const SubVectorView< Scalar > > &targ_sub_vecs, const Ptr< ReductTarget > &reduct_obj) const
 Apply the reduction/transformation operator to a set of sub-vectors.

Deprecated (NVI)

void get_reduct_type_num_entries (int *num_values, int *num_indexes, int *num_chars) const
 Deprecated.
void reduce_reduct_objs (const ReductTarget &in_reduct_obj, ReductTarget *inout_reduct_obj) const
 Deprecated.
void reduct_obj_reinit (ReductTarget *reduct_obj) const
 Deprecated.
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
 Deprecated.
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
 Deprecated.
void apply_op (const int num_vecs, const ConstSubVectorView< Scalar > sub_vecs[], const int num_targ_vecs, const SubVectorView< Scalar > targ_sub_vecs[], ReductTarget *reduct_obj) const
 Deprecated.
virtual void get_reduct_type_num_entries_impl (const Ptr< int > &num_values, const Ptr< int > &num_indexes, const Ptr< int > &num_chars) const
 Protected virtual functions to be overridden by subclasses. .
virtual Teuchos::RCP< ReductTargetreduct_obj_create_impl () const
 
virtual void reduce_reduct_objs_impl (const ReductTarget &in_reduct_obj, const Ptr< ReductTarget > &inout_reduct_obj) const
 
virtual void reduct_obj_reinit_impl (const Ptr< ReductTarget > &reduct_obj) const
 
virtual void extract_reduct_obj_state_impl (const ReductTarget &reduct_obj, const ArrayView< primitive_value_type > &value_data, const ArrayView< index_type > &index_data, const ArrayView< char_type > &char_data) const
 
virtual void load_reduct_obj_state_impl (const ArrayView< const primitive_value_type > &value_data, const ArrayView< const index_type > &index_data, const ArrayView< const char_type > &char_data, const Ptr< ReductTarget > &reduct_obj) const
 
virtual const std::string op_name_impl () const
 
virtual bool coord_invariant_impl () const
 
virtual void apply_op_impl (const ArrayView< const ConstSubVectorView< Scalar > > &sub_vecs, const ArrayView< const SubVectorView< Scalar > > &targ_sub_vecs, const Ptr< ReductTarget > &reduct_obj) const =0
 
 RTOpT (const std::string &op_name_base="")
 Nonvirtual protected functions. Constructor that creates an operator name appended with the type.
void setOpNameBase (const std::string &op_name_base)
 Just set the opeator name.

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 abstract numerical algorithm without the explicit knowledge of the algorithm.

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 changed 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 = 0...n-1
 

Operators can also be defined that perform reduction and transformation operations on the same vectors that that should only be done for efficiency reasons.

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 = 0...n-1 } -> [ 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 = 0...n-1 } -> [ 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 = 0...n-1
 
 alpha * |z(i)| / x(i) -> z(i), for i = 0...n-1
 
 alpha * x(i) * y(i) + beta * z(i) -> z(i), for i = 0...n-1
 

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 = 0...n-1
 

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 to overcome the inherent overhead of this design. This design supports dense strided sub-vectors (see ConstSubVectorView and SubVectorView) but is relatively flexible.

It is strictly the responsibility 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 = 0...n-1
 

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 161 of file RTOpPack_RTOpT_decl.hpp.


The documentation for this class was generated from the following files:
Generated on Wed May 12 21:41:16 2010 for Fundamental Vector Reduction/Transformation Operator (RTOp) Interfaces by  doxygen 1.4.7