Stencil.h File Reference

Stencil objects are a way to build an object which applies a stencil to an array, and returns a new Array for the expression. More...

#include "Domain/Interval.h"
#include "Evaluator/EngineTraits.h"
#include "Engine/Engine.h"
#include "Engine/Intersector.h"
#include "Engine/IntersectEngine.h"
#include "Engine/EngineFunctor.h"
#include "PETE/ErrorType.h"
#include "Pooma/View.h"
#include "Pooma/FunctorResult.h"
#include "Engine/ViewEngine.h"
#include "Utilities/WrappedInt.h"

Include dependency graph for Stencil.h:

This graph shows which files directly or indirectly include this file:


Classes

struct  StencilEngine< Function, Expression >
 This is just a tag class for the stencil engine. More...
class  Engine< D, T, StencilEngine< Function, Expression > >
 A specialization of Engine for StencilEngine. More...
struct  View1< Stencil< Function >, Array< D, T, E > >
struct  View2< Stencil< Function >, ArrayIn, Interval< Dim > >
struct  View2< Stencil< Function >, ArrayIn, Dom >
class  Stencil< Function >
 Stencil. More...
struct  NewEngine< Engine< Dim, T, StencilEngine< S, E > >, Interval< Dim > >
 Specializations of NewEngine for subsetting a StencilEngine with an arbitrary domain. More...
struct  NewEngine< Engine< Dim, T, StencilEngine< S, E > >, INode< Dim > >
struct  NewEngine< Engine< Dim, T, StencilEngine< S, E > >, Range< Dim > >
struct  NewEngine< Engine< Dim, T, StencilEngine< S, E > >, SliceInterval< Dim, SliceDim > >
struct  NewEngine< Engine< Dim, T, StencilEngine< S, E > >, SliceRange< Dim, SliceDim > >
struct  EvaluatorEngineTraits< StencilEngine< UserFunction, Expression > >
 Specializations for selecting the appropriate evaluator for the Stencil engine. More...
class  StencilIntersector< Dim, Intersect >
struct  LeafFunctor< Engine< D, T, StencilEngine< S, E > >, ExpressionApply< IntersectorTag< Intersect > > >
struct  EngineFunctor< Engine< D, T, StencilEngine< S, E > >, DataObjectRequest< RequestType > >
struct  LeafFunctor< Engine< D, T, StencilEngine< S, E > >, EngineView< Tag > >
struct  LeafFunctor< Engine< D, T, StencilEngine< S, E > >, ExpressionApply< Tag > >

Functions

template<class Function , int D>
Interval< D > insetDomain (const Function &f, const Interval< D > &domain)
 insetDomain() computes the insetDomain domain of the stencil for users (it's not zero-based).

Detailed Description

Stencil objects are a way to build an object which applies a stencil to an array, and returns a new Array for the expression.

There are several reasons one might want to do this:

  1. Abstraction. Once a stencil like Laplace is constructed, you can say things like Laplace(A) to take the laplacian of A. That way the definition of the laplacian can be abstracted out and put in one place.
  2. Polymorphism. The Laplace object above can take different actions depending on the type of A, giving it compile-time polymorphism.
  3. Run-time efficiency. Because the stencil object directly represents what happens in the inner loop, more optimizations are available. Two particular ones are of greatest importance. When an array appears several times in a stencil, it can recognize that the pointers are the same, saving registers, and the values of the integer offsets from those pointers are visible and can be put in the instruction stream instead of registers. Together, these two optimizations allow a third, reusing values from the stencil from one loop iteration to the next.
  4. Compile-time efficiency. Stencil objects are much easier to compile than expression templates, so compilation goes much faster.

Stencil

A base class from which users would inherit to produce a specific stencil. This mainly implements operator()(expr), which constructs the expression with the stencil applied to the expression.

StencilEngine<D,T2,Expression>

An engine for Arrays which applies a stencil. This takes another engine as a template argument and applies the stencil to that engine.

NewEngine

Defines the type of StencilEngine you get when you subset it. It just subsets the engine inside of it.

Stencil Concepts:

A stencil is a pattern repeatedly applied to elements in an input domain to yield elements in the output domain. For example, the simplest stencil copies each element in the input domain to exactly the same element in the output domain. A second-order difference stencil can be represented by the formula

out(i) = 2 in(i-1) + in(i) + in(i+1)

where in(i) and out(i) indicate the ith input and output elements, respectively. This stencil illustrates that a stencil can use more than one input element, but that all input elements must be contiguous.

A StencilEngine is an engine applying a stencil to an input array. When invoked, the result is an array filled with values from applying the stencil to the input array. We explain the engine's data members and assumptions. Even though a StencilEngine stores the data for its computation, actually performing the computation only when requested, we use the slang of its "output" to avoid writing "its output when the computation is invoked." Also, in the explanation below, we use one-dimensional terminology. The only supported domains and ranges are Cartesian products so the one-dimensional terminology is easily generalized.

When created, engines frequently are given the desired array output range indices, e.g., -3, ..., 5. Any such range can be shifted so the leftmost element's index is zero, i.e., zero-based. For example, 0, ..., 8 with an offset of -3. To return to the "original," desired range, add the offset to each index. The `domain_m' variable records the number of output elements.

Assume the engine's stencil uses input array elements with indices lowerExtent, lowerExtent+1, ..., 0, ..., upperExtent. Thus, to produce out(0) requires knowing in(lowerExtent), ..., in(upperExtent). The input domain to consisting of the values used to compute the zero-based output range is in(lowerExtent), ..., in(domain_m + upperExtent).

The StencilEngine's data members are

  1. function_m representing the stencil
  2. expression_m which is approximately the input
  3. domain_m representing the indices for the output
  4. offset_m representing the 'shift' to yield zero-based output indices

Note all members concern output, not input.

When reading the source code below, "domain" is used for both input and output indices. The reader must decide the meaning of each occurrence.


Function Documentation

template<class Function , int D>
Interval<D> insetDomain ( const Function &  f,
const Interval< D > &  domain 
) [inline]

insetDomain() computes the insetDomain domain of the stencil for users (it's not zero-based).

If you just got a random stencil from who knows where and want to apply it to another array, you could say:

b(st.insetDomain(a.domain())) = st(a);

Note that you can always just say:

b(range) = st(a,range);

because that version doesn't inset.

In other words, given a stencil and an input domain, return the resulting output indices.

Referenced by Engine< D, T, StencilEngine< Function, Expression > >::Engine(), View2< Stencil< Function >, ArrayIn, Dom >::make(), and View1< Stencil< Function >, Array< D, T, E > >::make().


Generated on Wed Mar 16 06:19:13 2011 for FreePOOMA by  doxygen 1.5.9