[Templated interfaces for generalized vector reduction/transformation operators in C++.]

`#include <RTOpPack_RTOpTDecl.hpp>`

Inheritance diagram for RTOpPack::RTOpT< Scalar >:

## 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::RCP< 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 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 ConstSubVectorView< Scalar > sub_vecs[], const int num_targ_vecs, const SubVectorView< 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. |

class RTOpPack::RTOpT< Scalar >

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

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 = 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. This design supports dense strided sub-vectors (see `ConstSubVectorView`

and `SubVectorView`

) 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 = 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 158 of file RTOpPack_RTOpTDecl.hpp.

The documentation for this class was generated from the following files:

Generated on Tue Oct 20 12:46:12 2009 for Fundamental Vector Reduction/Transformation Operator (RTOp) Interfaces by 1.4.7