zoomy_core.model.kernel_functions module

Custom SymPy functions for numerical models.

These are opaque to SymPy (never simplified away) but have concrete implementations in each backend (NumPy, JAX, C).

Each function must be registered in the backend’s module dict:

• NumPy: to_numpy.py → NumpyRuntimeModel.module

• JAX: to_jax.py

• C: generic_c.py

class zoomy_core.model.kernel_functions.clamp_positive(x)

Bases: Function

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

Opaque to SymPy — never simplified, even if x has positive=True. At runtime: np.maximum(x, 0).

nargs = {1}

is_commutative: bool | None = True

classmethod eval(x)

Returns a canonical form of cls applied to arguments args.

The eval() method is called when the class cls is about to be instantiated and it should return either some simplified instance (possible of some other class), or if the class cls should be unmodified, return None.

Examples of eval() for the function “sign”

@classmethod
def eval(cls, arg):
    if arg is S.NaN:
        return S.NaN
    if arg.is_zero: return S.Zero
    if arg.is_positive: return S.One
    if arg.is_negative: return S.NegativeOne
    if isinstance(arg, Mul):
        coeff, terms = arg.as_coeff_Mul(rational=True)
        if coeff is not S.One:
            return cls(coeff) * cls(terms)

default_assumptions: ClassVar[StdFactKB] = {'commutative': True}

class zoomy_core.model.kernel_functions.clamp_momentum(hu, h, u_max)

Bases: Function

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

Caps momentum so that |u| = |hu/h| <= u_max. Opaque to SymPy. At runtime: np.clip(hu, -h*u_max, h*u_max).

nargs = {3}

is_commutative: bool | None = True

classmethod eval(hu, h, u_max)

Returns a canonical form of cls applied to arguments args.

The eval() method is called when the class cls is about to be instantiated and it should return either some simplified instance (possible of some other class), or if the class cls should be unmodified, return None.

Examples of eval() for the function “sign”

@classmethod
def eval(cls, arg):
    if arg is S.NaN:
        return S.NaN
    if arg.is_zero: return S.Zero
    if arg.is_positive: return S.One
    if arg.is_negative: return S.NegativeOne
    if isinstance(arg, Mul):
        coeff, terms = arg.as_coeff_Mul(rational=True)
        if coeff is not S.One:
            return cls(coeff) * cls(terms)

default_assumptions: ClassVar[StdFactKB] = {'commutative': True}

class zoomy_core.model.kernel_functions.max_wavespeed(*args)

Bases: Function

max_wavespeed(Q, Qaux, p, n) — maximum absolute wave speed.

Opaque to SymPy. Used in Rusanov dissipation and CFL computation. Backend implementations:

• NumPy: provided by NumericalModel (symbolic eigenvalues compiled,

  or np.linalg.eigvals on quasilinear matrix)

• JAX: same

• C: compiled from symbolic eigenvalue expressions

is_commutative: bool | None = True

is_real: bool | None = True

is_nonnegative: bool | None = True

classmethod eval(*args)

Returns a canonical form of cls applied to arguments args.

The eval() method is called when the class cls is about to be instantiated and it should return either some simplified instance (possible of some other class), or if the class cls should be unmodified, return None.

Examples of eval() for the function “sign”

@classmethod
def eval(cls, arg):
    if arg is S.NaN:
        return S.NaN
    if arg.is_zero: return S.Zero
    if arg.is_positive: return S.One
    if arg.is_negative: return S.NegativeOne
    if isinstance(arg, Mul):
        coeff, terms = arg.as_coeff_Mul(rational=True)
        if coeff is not S.One:
            return cls(coeff) * cls(terms)

default_assumptions: ClassVar[StdFactKB] = {'commutative': True, 'complex': True, 'extended_negative': False, 'extended_nonnegative': True, 'extended_real': True, 'finite': True, 'hermitian': True, 'imaginary': False, 'infinite': False, 'negative': False, 'nonnegative': True, 'real': True}

is_complex: bool | None = True

is_extended_negative: bool | None = False

is_extended_nonnegative: bool | None = True

is_extended_real: bool | None = True

is_finite: bool | None = True

is_hermitian: bool | None = True

is_imaginary: bool | None = False

is_infinite: bool | None = False

is_negative: bool | None = False

class zoomy_core.model.kernel_functions.conditional(*args)

Bases: Function

A Vector-Aware, Differentiable Conditional Function.

Usage:

conditional(c, t, f)

Behavior:

• If inputs are Scalars: Returns a symbolic conditional object.

• If inputs are Vectors: Returns a ZArray of symbolic conditional objects.

Differentiation:

• Implements the ‘Active Branch’ rule: d/dx conditional(c, t, f) = conditional(c, dt/dx, df/dx)

nargs = {3}

is_commutative: bool | None = True

default_assumptions: ClassVar[StdFactKB] = {'commutative': True}