arrays-stencils.texi

A C++ class library for scientific computing

@item backward42(A,dimension)
4th derivative, 2nd order accurate.  Factor: @math{h^4}
@include stencils/backward42.texi
@end table

Note that the above are available in normalized versions @code{backward11n},
@code{backward21n}, ..., @code{backward42n} which have factors of @math{h},
@math{h^2}, @math{h^3}, or @math{h^4} as appropriate.  

These are available in multicomponent versions: for example,
@code{backward42(A,component,dimension)} gives the backward42 operator for
the specified component (Components are numbered 0, 1, ... N-1).

@subsection Laplacian (@math{@nabla ^2}) operators
@cindex Laplacian operators

@table @code
@item Laplacian2D(A)
2nd order accurate, 2-dimensional laplacian.  Factor: @math{h^2}
@include stencils/Laplacian2D.texi

@item Laplacian3D(A)
2nd order accurate, 3-dimensional laplacian.  Factor: @math{h^2}

@item Laplacian2D4(A)
4th order accurate, 2-dimensional laplacian.  Factor: @math{12h^2}
@include stencils/Laplacian2D4.texi

@item Laplacian3D4(A)
4th order accurate, 3-dimensional laplacian.  Factor: @math{12h^2}
@end table

Note that the above are available in normalized versions
@code{Laplacian2D4n}, @code{Laplacian3D4n} which have factors @math{h^2}.

@subsection Gradient (@math{@nabla}) operators
@cindex gradient operators

These return @code{TinyVector}s of the appropriate numeric type and length:

@table @code

@item grad2D(A)
2nd order, 2-dimensional gradient (vector of first derivatives), generated
using the central12 operator.  Factor: @math{2h}

@item grad2D4(A)
4th order, 2-dimensional gradient, using central14 operator.  Factor: @math{12h}

@item grad3D(A)
2nd order, 3-dimensional gradient, using central12 operator.  Factor: @math{2h}

@item grad3D4(A)
4th order, 3-dimensional gradient, using central14 operator.  Factor: @math{12h}
@end table

These are available in normalized versions @code{grad2Dn}, @code{grad2D4n},
@code{grad3Dn} and @code{grad3D4n} which have factors @math{h}.

@subsection Jacobian operators
@cindex Jacobian operators

The Jacobian operators are defined over 3D vector fields only (e.g.
@code{Array<TinyVector<double,3>,3>}).  They return a
@code{TinyMatrix<T,3,3>} where T is the numeric type of the vector field.

@table @code
@item Jacobian3D(A)
2nd order, 3-dimensional Jacobian using the central12 operator.  Factor:
@math{2h}.

@item Jacobian3D4(A)
4th order, 3-dimensional Jacobian using the central14 operator.  Factor:
@math{12h}.
@end table

These are also available in normalized versions @code{Jacobian3Dn} and
@code{Jacobain3D4n} which have factors @math{h}.

@subsection Grad-squared operators
@cindex Grad-squared operators

There are also grad-squared operators, which return @code{TinyVector}s of
second derivatives:

@table @code
@item gradSqr2D(A)
2nd order, 2-dimensional grad-squared (vector of second derivatives),
generated using the central22 operator.  Factor: @math{h^2}

@item gradSqr2D4(A)
4th order, 2-dimensional grad-squared, using central24 operator.  Factor:
@math{12h^2}

@item gradSqr3D(A)
2nd order, 3-dimensional grad-squared, using the central22 operator.
Factor: @math{h^2}

@item gradSqr3D4(A)
4th order, 3-dimensional grad-squared, using central24 operator.  Factor:
@math{12h^2}
@end table

Note that the above are available in normalized versions @code{gradSqr2Dn},
@code{gradSqr2D4n}, @code{gradSqr3Dn}, @code{gradSqr3D4n} which have factors
@math{h^2}.

@subsection Curl (@math{@nabla @times}) operators
@cindex curl operator

These curl operators return scalar values:

@table @code
@item curl(Vx,Vy)
2nd order curl operator using the central12 operator.  Factor: @math{2h}

@item curl4(Vx,Vy)
4th order curl operator using the central14 operator.  Factor: @math{12h}

@item curl2D(V)
2nd order curl operator on a 2D vector field (e.g.@:
@code{Array<TinyVector<float,2>,2>}), using the central12 operator.  Factor:
@math{2h}

@item curl2D4(V)
4th order curl operator on a 2D vector field, using the central12 operator.
Factor: @math{12h}
@end table

Available in normalized forms @code{curln}, @code{curl4n}, @code{curl2Dn},
@code{curl2D4n}.

These curl operators return three-dimensional @code{TinyVector}s of the 
appropriate numeric type:

@table @code
@item curl(Vx,Vy,Vz)
2nd order curl operator using the central12 operator.  Factor: @math{2h}

@item curl4(Vx,Vy,Vz)
4th order curl operator using the central14 operator.  Factor: @math{12h}

@item curl(V)
2nd order curl operator on a 3D vector field (e.g.@:
@code{Array<TinyVector<double,3>,3>}, using the central12 operator.  Factor:
@math{2h}

@item curl4(V)
4th order curl operator on a 3D vector field, using the central14 operator.
Factor: @math{12h}
@end table

Note that the above are available in normalized versions @code{curln} and
@code{curl4n}, which have factors of @code{h}.

@subsection Divergence (@math{@nabla @cdot}) operators
@cindex divergence operator

The divergence operators return a scalar value.

@table @code
@item div(Vx,Vy)
2nd order div operator using the central12 operator.  Factor: @math{2h}

@item div4(Vx,Vy)
4th order div operator using the central14 operator.  Factor: @math{12h}

@item div(Vx,Vy,Vz)
2nd order div operator using the central12 operator.  Factor: @math{2h}

@item div4(Vx,Vy,Vz)
4th order div operator using the central14 operator.  Factor: @math{12h}

@item div2D(V)
2nd order div operator on a 2D vector field, using the central12 operator.
Factor: @math{2h}

@item div2D4(V)
2nd order div operator on a 2D vector field, using the central14 operator.
Factor: @math{12h}

@item div3D(V)
2nd order div operator on a 3D vector field, using the central12 operator.
Factor: @math{2h}

@item div3D4(V)
2nd order div operator on a 3D vector field using the central14 operator.
Factor: @math{12h}
@end table

These are available in normalized versions
@code{divn}, @code{div4n}, @code{div2Dn}, @code{div2D4n}, @code{div3Dn}, and
@code{div3D4n} which have factors of @math{h}.

@subsection Mixed partial derivatives
@cindex mixed partial operators

@table @code
@item mixed22(A,dim1,dim2)
2nd order accurate, 2nd mixed partial derivative.  Factor: @math{4h^2}

@item mixed24(A,dim1,dim2)
4th order accurate, 2nd mixed partial derivative.  Factor: @math{144h^2}
@end table

There are also normalized versions of the above, @code{mixed22n} and
@code{mixed24n} which have factors @math{h^2}.

@section Declaring your own stencil operators
@cindex stencil operators declaring your own

You can declare your own stencil operators using the macro
@code{BZ_DECLARE_STENCIL_OPERATOR1}.  For example, here is the declaration
of @code{Laplacian2D}:

@example
BZ_DECLARE_STENCIL_OPERATOR1(Laplacian2D, A)
    return -4*A(0,0) + A(-1,0) + A(1,0) + A(0,-1) + A(0,1);
BZ_END_STENCIL_OPERATOR
@end example

To declare a stencil operator on 3 operands, use the macro
@code{BZ_DECLARE_STENCIL_OPERATOR3}.  Here is the declaration of @code{div}:

@example
BZ_DECLARE_STENCIL_OPERATOR3(div,vx,vy,vz)
  return central12(vx,firstDim) + central12(vy,secondDim)
    + central12(vz,thirdDim);
BZ_END_STENCIL_OPERATOR
@end example

The macros aren't magical; they just declare an inline template function
with the names and arguments you specify.  For example, the declaration of
@code{div} could also be written

@example
template<class T>                              
inline typename T::T_numtype div(T& vx, T& vy, T& vz)   
@{
  return central12(vx,firstDim) + central12(vy,secondDim)
                                + central12(vz,thirdDim);
@}
@end example

The template parameter @code{T} is an iterator type for arrays.

You are encouraged to use the macros when possible, because it is possible
the implementation could be changed in the future.

To declare a difference operator, use this syntax:

@example
BZ_DECLARE_DIFF(central12,A) @{
  return A.shift(1,dim) - A.shift(-1,dim);
@}
@end example

The method @code{shift(offset,dim)} retrieves the element at
@code{offset} in dimension @code{dim}.

Stencil operator declarations cannot occur inside a function.  If
declared inside a class, they are scoped by the class.

@section Applying a stencil
@cindex stencil objects applying

The syntax for applying a stencil is:

@example
applyStencil(stencilname(),A,B,C...,F);
@end example

Where @code{stencilname} is the name of the stencil, and @code{A,B,C,...,F}
are the arrays on which the stencil operates.

For examples, see @file{examples/stencil.cpp} and @file{examples/stencil2.cpp}.

Blitz++ interrogates the stencil object to find out how large its footprint
is.  It only applies the stencil over the region of the arrays where it
won't overrun the boundaries.