Skip to content
XFELPP

Stencil

Stencil

Section titled “Stencil”
#include <ncarray/expression/stencil.hh>
template<int NDIM>
class Stencil

Defined in src/lib/ncarray/expression/stencil.hh:59

A Stencil for defining expressions over an array with determined offsets.

A Stencil holds the offsets and set of operations for reducing the host-time cost of constructing the expression evaluation infrastructure each time that an expression is evaluated. If the same operation(s) is(are) being performed many times with solely the underlying pointers being changed, then the Stencil can reduce the overall execution time significantly.

A Stencil can only be created to evaluate operations that run on a single array. Examples include convolutions, or reductions that can be expressed in terms of arithmetic operations on sub-views of the array.

Template Parameters

Section titled “Template Parameters”
  • NDIM The number of dimensions of the array operands.

List of all members

Section titled “List of all members”
Name Kind Owner
Stencil function Declared here
apply function Declared here
create function Declared here
m_kernel variable Declared here
m_instrs variable Declared here
m_offsets variable Declared here
m_constants_buf variable Declared here
m_constants_offsets variable Declared here
m_work_dtype variable Declared here
m_expr_dtype variable Declared here

Public Methods

Section titled “Public Methods”
Return Name Description
Stencil Defaulted constructor.
void apply inline Apply the stencil.

Stencil

Section titled “Stencil”
Stencil() = default

Defined in src/lib/ncarray/expression/stencil.hh:61

Defaulted constructor.

apply

Section titled “apply”

inline

template<ViewArrayLike Src, OwningArrayLike Dest, typename... Args> inline void apply(const Src & src, Dest & dest, std::optional< cudaStream_t > stream = std::nullopt, Args &&... extra_args)

Defined in src/lib/ncarray/expression/stencil.hh:182

Apply the stencil.

Run the pre-constructed kernel on an input array and a pre-created output array. The input must match the input used for creation of the kernel in the number and location of pointer axes as well as the dimensionality. A CUDA stream may be provided to run the execution on, if desired.

NOTE: If a stream is provided for running the kernel on, this function will NOT synchronize. This constrasts with other APIs which always do before returning control the host caller. This is because if a stream is passed in order to record the kernel as part of a graph, synchronization is NOT permitted in the capture. Since it is not possible to know whether the stream is provided in order to construct a graph, or not, all synchronization is the caller’s responsibility when providing a stream.

Parameters

Section titled “Parameters”
Parameter Type Description
src const Src & The input array.
dest Dest & The output array.
stream std::optional< cudaStream_t > Optionally, provide a stream to launch the kernel on.

Public Static Methods

Section titled “Public Static Methods”
Return Name Description
Stencil< NDIM > create static inline Create a stencil from a set of relative offsets and a math function.

create

Section titled “create”

static inline

template<typename SrcT, typename Func> static inline Stencil< NDIM > create(const std::vector< StaticCoords< NDIM > > & offsets_in, const std::vector< std::uint8_t > & is_pointer_axis, Func && op_func, const device::StencilJITExtensions & ext = {}, bool is_soarr = false)

Defined in src/lib/ncarray/expression/stencil.hh:77

Create a stencil from a set of relative offsets and a math function.

Parameters

Section titled “Parameters”
Parameter Type Description
offsets_in const std::vector< [StaticCoords](api-ncarray-StaticCoords.md#staticcoords)< NDIM > > & List of StaticCoords representing the window (e.g. {0,0}, {0,1}…)
is_pointer_axis const std::vector< std::uint8_t > & A vector of flags for whether each dimension is a pointer dim. The compiled kernel will only work for arrays that have the same kinds of pointer dimensions (although shape and stride can vary freely).
op_func Func && A lambda that takes a vector of views and returns an expression.
ext const [device::StencilJITExtensions](api-ncarray-device-StencilJITExtensions.md#stenciljitextensions) & Optionally provide code to run before/after the main expression.
is_soarr bool A boolean flag as to whether SOArrayPolicy traversal is needed.

Private Attributes

Section titled “Private Attributes”
Return Name Description
CUfunction m_kernel
std::vector< Instruction > m_instrs
std::vector< StaticCoords< NDIM > > m_offsets
std::vector< std::uint8_t > m_constants_buf
std::vector< std::uint16_t > m_constants_offsets
DType m_work_dtype
DType m_expr_dtype

m_kernel

Section titled “m_kernel”
CUfunction m_kernel

Defined in src/lib/ncarray/expression/stencil.hh:246

m_instrs

Section titled “m_instrs”
std::vector< Instruction > m_instrs

Defined in src/lib/ncarray/expression/stencil.hh:247

m_offsets

Section titled “m_offsets”
std::vector< StaticCoords< NDIM > > m_offsets

Defined in src/lib/ncarray/expression/stencil.hh:248

m_constants_buf

Section titled “m_constants_buf”
std::vector< std::uint8_t > m_constants_buf

Defined in src/lib/ncarray/expression/stencil.hh:250

m_constants_offsets

Section titled “m_constants_offsets”
std::vector< std::uint16_t > m_constants_offsets

Defined in src/lib/ncarray/expression/stencil.hh:251

m_work_dtype

Section titled “m_work_dtype”
DType m_work_dtype

Defined in src/lib/ncarray/expression/stencil.hh:253

m_expr_dtype

Section titled “m_expr_dtype”
DType m_expr_dtype

Defined in src/lib/ncarray/expression/stencil.hh:254