API reference

Diff(v)   (alias ∂)

"With respect to" functor: ∂(v)(e) == differentiate(e, v). v may be a Slot (the result is a spatial Stencil) or a Symbolic (the result is an AbstractTerm coefficient — a per-cell broadcast).

Fill{T} <: AbstractTerm{T}

Broadcast-to-grid bridge from scalar-land to term-land: wraps a single value (a literal or an AbstractScalar) and presents it as a spatially- invariant AbstractTerm. The element type follows the wrapped value: for a literal T it is T; for an AbstractScalar it is eltype(scalar) (recursive), so e.g. Fill(Symbolic{:τ, Float64}()) has eltype Float64 and arithmetic with a Slot{:f, Float64} promotes cleanly.

FwdDiff{D} / BwdDiff{D} / FwdSum{D} / BwdSum{D}   (aliases δ₊, δ₋, σ₊, σ₋)

Non-local first-order operators along mesh axis D, applied by calling the type on a term:

Each builds a Term over a Shifted leaf (e.g. δ₊{1}(f) == f[ê₁] - f); on a Number they collapse to the local closed form (0, 0, 2x, 2x). Dimension-polymorphic — only the axis D is fixed.

LazyArray{T, N, F, Args<:NamedTuple} <: AbstractArray{T, N}

Read-only array view of a materialized term: fn(args, I...) computes the element at I, where fn is a generated per-cell kernel and args is the substitution NamedTuple. axes is the term's valid index box (each substituted array's axes shrunk inward by the term's shift footprint).

Shifted(shift::StaticShift, term) / Shifted(term, shift::StaticShift)

A term read at the lattice offset shift. The element type is unchanged (eltype(term)); the zero shift ô is the identity (returns term).

Slot{S, T}()

Placeholder for a discrete field named S (a Symbol) whose cells hold values of the concrete type T (default Float64). Substituted with an AbstractArray at materialize and indexed per cell. Term-side analogue of Symbolic.

Term(fn, args::Tuple{Vararg{AbstractTerm}})

Internal node applying fn to args component-wise. The element type T = Base.promote_op(fn, eltype.(args)...) is computed at construction; a Union{} result (e.g. genuine SVector inhomogeneity) is an unconstructable term and throws.

Zero{T}() / One{T}()

Type-level additive / multiplicative identities (structure, not data): they let differentiation collapse and simplify rewrite by dispatch. Lower to zero(T) / one(T). Scalar-side analogues: Null / Unity.

build_stencil(sst::Stencil, pairs::NamedTuple = (;); size = nothing)

Lower a (typically differentiate-produced) Stencil to an assemblable LinearStencil / StarStencil{ColumnAccess} with a concrete coefficient:

1. convert RowAccess → ColumnAccess (shift each per-offset coefficient by −offset);
2. optionally densify (pad = true) to fill single-axis offset gaps with Zero so a gappy result still narrows to LinearStencil;
3. narrow the offset pattern (as_linear / as_star), which switches the structure-of-arrays terms to the array-of-structs SVector coefficient;
4. materialize that coefficient against pairs (variable coefficients) — for a constant coefficient pass the mesh size.

The result is ready for StencilAssembly.build / assemble.

code_string(term::AbstractTerm; name = :kernel, ndims = <hint>) -> String

Render the per-cell kernel for term as Julia source — the same Expr materialize compiles, wrapped in a named function definition. ndims defaults to the largest shifted axis (≥ 1). For inspection / dumping to a file.

densify(sst::Stencil) -> Stencil

Pad a single-axis Stencil to a contiguous offset range by inserting type-level Zero coefficients at the missing offsets, so a gappy differentiation result (e.g. offsets {-2, 0}) can narrow to LinearStencil. A no-op (returns sst) for patterns that are already contiguous, multi-axis, or pure-diagonal (ambiguous axis) — those go to as_star or stay as is.

differentiate(t::AbstractTerm, ::Slot{S}) -> StencilCore.Stencil{RowAccess}

Differentiate t with respect to the field named S (matched on the symbol only). Returns a row-anchored Stencil in structure-of-arrays form: reverse- lex-ordered offsets shifts and a parallel tuple terms whose k-th entry is the coefficient ∂t/∂(f[σ_k]). Throws if t does not depend on S (identically-zero derivative).

differentiate(t::AbstractTerm, ::Symbolic{S}) -> AbstractTerm

Differentiate t with respect to the named scalar parameter S. A Symbolic appears in t only inside a Fill, so the derivative is a per-cell broadcast coefficient (a single AbstractTerm, not a Stencil). Throws if t does not depend on S.

materialize(term::AbstractTerm, pairs::NamedTuple) -> LazyArray

Substitute the slots/symbolics named in pairs into term and lower it to a compiled LazyArray. The grid rank N is the substituted arrays' ndims (which must agree); the result's axes are their axes intersected and shrunk inward by the term's shift footprint (no implicit broadcasting). Shifts become index arithmetic in the generated kernel. Method on the same generic as StencilCore.materialize for AbstractScalar.

simplify(t::AbstractTerm, rules = DEFAULT_RULES; maxsteps = 64)

Rewrite t to a normal form by post-walking and applying rules to a fixed point. The default rules push shifts down to leaves (merging nested shifts), apply additive/multiplicative identities, and collapse all-Fill Terms into a single Fill(Scalar(…)) (the scalar-precedence rule). Method on the same generic as StencilCore.simplify for AbstractScalar.

@slot name [T = Float64]

Bind name to Slot{:name, T}(), taking the variable name as the field symbol. @slot f ≡ f = Slot{:f, Float64}(); @slot f Float32 ≡ f = Slot{:f, Float32}(). Scalar-side analogue: @symbolic.

AbstractTerm{T}

Supertype of every symbolic grid expression. An AbstractTerm{T} behaves like a dimension- and size-less array whose eltype is T: its grid rank N is unknown until it is materialized against concrete arrays, but its element type T (the value each cell will hold once materialized) is fixed at construction.

eltype(::AbstractTerm{T}) === T. Concrete subtypes are provided by the StencilCalculus package.

AbstractScalar{T}

Supertype for cell-level scalar expressions. Reaches a single value of type T at materialize time (no axes). Concrete subtypes: Symbolic, Const, Scalar, Null, Unity. Sibling of, not subtype of, AbstractTerm.

Symbolic{S, T}()

Named, runtime-substituted scalar parameter S (a Symbol) of concrete type T (default Float64). Materializes to the value supplied at the keyword S of the pairs NamedTuple — like Slot but without per-cell indexing.

Const(value) / Const{T}(value)

Literal scalar leaf carrying its value in a runtime field. The element type is typeof(value) (always concrete).

Null{T}()

Type-level additive identity / structural zero for AbstractScalar: the scalar-side analogue of AbstractTerm Zero. Materializes to zero(T); lets the scalar simplify and differentiate rules collapse by dispatch.

Unity{T}()

Type-level multiplicative identity for AbstractScalar: the scalar-side analogue of AbstractTerm One. Materializes to one(T).

Scalar(fn, args::Tuple{Vararg{AbstractScalar}})

Interior node of a scalar-tree: applies fn to scalar args component-wise. The element type T = Base.promote_op(fn, eltype.(args)...) is computed at construction; a Union{} result throws (the node is unconstructable). Term-side analogue: AbstractTerm Term.

StaticPair{D, O}

A single offset of magnitude O along mesh dimension D (both compile-time Ints). Singleton. Alias: SPair.

SPair

Alias for StaticPair.

StaticShift{P<:Tuple{Vararg{StaticPair}}}

A lattice offset: a normalized collection of StaticPairs. Invariants (enforced by the constructor): pairs are sorted ascending by dimension, no two pairs share a dimension (same-dimension pairs are summed), and no pair has zero offset (dropped). The empty shift StaticShift{Tuple{}} is the identity.

Construct from pairs, or via the basis symbols ê₁ … ê₉ and the +/-/*Int algebra:

3ê₁ + ê₂            # StaticShift{Tuple{StaticPair{1,3}, StaticPair{2,1}}}

Alias: SShift.

SShift

Alias for StaticShift.

ô, ê₁ … ê₉

Predefined StaticShift constants: ô is the zero shift (identity), and êᵢ is the unit offset along axis i. Combine them with the +/-/*Int algebra to write lattice offsets, e.g. -2ê₁, 3ê₁ + ê₂.

Stencil{M, C<:NTuple{M,StaticShift}, A<:NTuple{M,ArrayOrTermLike}, S<:AccessStyle}
    <: AbstractStencil{S}

General offset-list stencil in structure-of-arrays form: M offsets shifts (reverse-lexicographically ordered) and a parallel M-tuple terms of per-offset coefficients (terms[k] is the coefficient at offset shifts[k]). Each coefficient is an ArrayOrTermLike — a concrete array or a symbolic term — with a scalar element type.

The form produced by symbolic differentiation; not assembled directly — narrowed to a LinearStencil / StarStencil via as_linear / as_star, which is where the layout switches to array-of-structs (one SVector{M}-valued coefficient) by _interlaceing terms.

as_linear(st::Stencil{…,S}) -> LinearStencil{D, …, S}

Narrow a Stencil whose offsets are single-axis (same axis D) and contiguous to the equivalent LinearStencil{D}, interlacing terms into the single SVector{D}-valued coefficient. Throws if the offsets are multi-axis, span several axes, or are not contiguous-ascending.

as_star(st::Stencil{…,S}) -> StarStencil{L, …, S}

Narrow a Stencil whose offsets form the canonical reverse-lex star pattern (every axis 1..N with symmetric reach −L..L, plus the diagonal) to the equivalent StarStencil{L}, interlacing terms into the single SVector{M}- valued coefficient. Throws otherwise.