zoomy_core.kernel.kernel module

zoomy_core.kernel.kernel module#

Kernel — SymbolicRegistrar for backend-agnostic helper functions.

The Kernel holds basefunctions (safe_denominator, clamp_positive, etc.) that model and numerics expressions reference symbolically. Each backend (numpy, jax, C, UFL) provides concrete implementations during code transformation, using the same NumpyRuntimeSymbolic / JaxRuntimeSymbolic machinery that compiles Model and Numerics functions.

After code transformation the user gets three compiled artifacts:

  1. Model — physics (flux, source, eigenvalues)

  2. Numerics — Riemann solver (numerical flux, fluctuations)

  3. Kernel — helper functions shared by both

Usage:

kernel = Kernel(model)
runtime_kernel = NumpyRuntimeSymbolic(kernel)
# merge kernel functions into the module dict used by model/numerics
class zoomy_core.kernel.kernel.Kernel(model=None, **params)#

Bases: Parameterized, SymbolicRegistrar

Backend-agnostic registry of numerical helper functions.

Mirrors the Model/Numerics pattern: each function is a Function basefunction registered via register_symbolic_function. The symbolic definitions serve as blueprints; actual implementations are provided by the backend during compilation.

var(name)#

Get a model variable symbol by name.

Parameters:

name (str) –

Return type:

Symbol

par(name)#

Get a model parameter symbol by name.

Parameters:

name (str) –

Return type:

Symbol

safe_denominator()#

safe_denominator(x) → x regularized to avoid 1/0.

clamp_positive()#

clamp_positive(x) → max(x, 0).

clamp_momentum()#

clamp_momentum(hu, h, u_max) → sign(hu) * min(|hu|, h * u_max).

conditional()#

conditional(c, t, f) → t if c else f.

positive_variables()#

Return list of model variable symbols declared positive.

static find_singular_denominators(expr, positive_vars)#

Find Pow(v, negative_exp) subexpressions for positive variables.

Walks the expression tree and collects every Pow(v, e) where v is a positive variable and e < 0. These are the terms that produce NaN when v → 0 (e.g. at dry cells).

This is the detection function — swap this out to try different strategies (e.g. numerical probing, limit analysis).

Return type:

list of (Pow_subexpr, variable) pairs

name = 'Kernel'#
regularize(obj)#

Regularize function definitions in-place (targeted).

Works on any object with a functions Zstruct (Model, Numerics). For each function definition, finds Pow(v, -n) where v is a positive variable and replaces v → v + eps in that denominator only. Other occurrences of v (e.g. in g*h) are untouched.