zoomy_core.symsolver.hooks

Function hooks: a model’s operators call an opaque function hook("name") (a SymPy function the derivation keeps opaque, never an aux field); the solver setting functions={"name": callable} implements it on the Python backends (NumPy, JAX). The C++ backends (foam, AMReX) refuse a hook at setup.

A derivative the pipeline takes of a hook (source Jacobians, the flux’s quasilinear matrix) appears as Derivative(f(...), arg) or Subs(Derivative(...)); HookFunction.derivative says how it is printed: HookDerivative.zero, the user’s partial derivatives (printed like the function), or HookDerivative.auto (a SymPy Lambda: SymPy differentiates it on every Python backend; a callable: JAX AD, so JAX only).

Module Contents

Classes

HookDerivative	How the derivative of a hook is printed.
HookFunction	A hook’s implementation function (a callable of the backend’s arrays, or a SymPy Lambda) and its derivative: a HookDerivative, a sequence of callables (one partial per argument), or one callable returning all partials.
FunctionsParam	functions: hook name (an identifier) -> callable, sp.Lambda or HookFunction.
Hooks	A backend’s hooks: lower(expr) replaces hook derivatives (and inlines SymPy hooks); module holds the callables the lowered expressions call. grad(f, i) differentiates a callable (JAX: jax.grad); None: HookDerivative.auto of a callable is refused.

Functions

hook	The opaque function name for a model’s operators (real valued); the solver’s functions[name] implements it.
hook_function	Decorator: @hook_function(derivative=...) makes a HookFunction.
hook_names	The names of the hooks expr calls.
check_functions	Every hook the operators of systems (NSMs) call has a function and every function is called; raises ValueError (with “did you mean”).
refuse_hooks	The C++ backends: raise NotImplementedError for a hook the kernels of systems (NSMs) call, or any functions set.
refuse_used	Raise the HookError of a refused kernel ({slot: error}) the printed source calls as owner.slot.

Data

HOOKS_KEY

API

zoomy_core.symsolver.hooks.HOOKS_KEY

‘zoomy_hooks’

zoomy_core.symsolver.hooks.hook(name)

The opaque function name for a model’s operators (real valued); the solver’s functions[name] implements it.

class zoomy_core.symsolver.hooks.HookDerivative

Bases: zoomy_core.misc.options.Option

How the derivative of a hook is printed.

Initialization

Initialize self. See help(type(self)) for accurate signature.

zero

‘zero’

auto

‘auto’

class zoomy_core.symsolver.hooks.HookFunction(function, derivative=HookDerivative.auto)

A hook’s implementation function (a callable of the backend’s arrays, or a SymPy Lambda) and its derivative: a HookDerivative, a sequence of callables (one partial per argument), or one callable returning all partials.

Initialization

Validate function and derivative.

property symbolic

Whether the function is a SymPy Lambda (inlined, differentiated by SymPy).

zoomy_core.symsolver.hooks.hook_function(derivative=HookDerivative.auto)

Decorator: @hook_function(derivative=...) makes a HookFunction.

class zoomy_core.symsolver.hooks.FunctionsParam(default: dict[Any, Any] | None = t.cast('dict[t.Any, t.Any] | None', Undefined), *, allow_None: bool = t.cast('bool', Undefined), **params: typing_extensions.Unpack[param.parameters._ClassSelectorKwargs])

Bases: param.Dict

functions: hook name (an identifier) -> callable, sp.Lambda or HookFunction.

Initialization

Initialize a new :class:Parameter object with the specified attributes.

Parameters

• default (Any, optional): The owning class’s value for the attribute represented by this parameter, which can be overridden in an instance. Default is None.

• default_factory (callable, optional): A callable used to generate the attribute value. It can be provided directly (in which case it is invoked with no arguments) or wrapped in a :class:DefaultFactory for more advanced behavior (in which case it receives cls, self, and parameter as arguments). When specified, default_factory takes precedence over default. The factory is invoked once the :class:Parameterized instance is initialized.

  .. versionadded:: 2.3.0

• doc (str | None, optional): A documentation string describing the purpose of the parameter. Default is None.

• label (str | None, optional): An optional text label used when displaying this parameter, such as in a listing. If not specified, the parameter’s attribute name in the owning :class:Parameterized object is used.

• precedence (float | None, optional): A numeric value, usually in the range 0.0 to 1.0, that determines the order of the parameter in a listing or user interface. A negative precedence indicates a parameter that should be hidden in such listings. Default is None.

• instantiate (bool, optional): Whether the default value of this parameter will be deepcopied when a :class:Parameterized object is instantiated (True), or if the single default value will be shared by all Parameterized instances (False, the default). For an immutable Parameter value, it is best to leave instantiate at the default of False, so that a user can choose to change the value at the Parameterized instance level (affecting only that instance) or at the :class:Parameterized class or superclass level (affecting all existing and future instances of that class or superclass). For a mutable Parameter value, the default of False is also appropriate if you want all instances to share the same value state, e.g. if they are each simply referring to a single global object like a singleton. If instead each Parameterized should have its own independently mutable value, instantiate should be set to True, but note that there is then no simple way to change the value of this parameter at the class or superclass level, because each instance, once created, will then have an independently deepcopied value. Default is False.

• constant (bool, optional): If True, the parameter value can only be set at the class level or in a :class:Parameterized constructor call. The value is otherwise constant on the Parameterized instance, once it has been constructed. Default is False.

• readonly (bool, optional): If True, the parameter value cannot be modified at the class or instance level. Default is False.

• pickle_default_value (bool, optional): Whether the default value should be pickled. Set to False in rare cases, such as system-specific file paths.

  .. deprecated:: 2.3.0

• allow_None (bool, optional): If True, allows None as a valid parameter value. If the default value is None, this is automatically set to True. Default is False.

• per_instance (bool, optional): Whether to create a separate Parameter object for each instance of the Parameterized class (True), or share the same Parameter object across all instances (False). See also instantiate, which is conceptually similar but affects the parameter value rather than the parameter object. Default is True.

• allow_refs (bool, optional): If True, allows linking parameter references to this parameter, meaning the value will automatically reflect the current value of the reference that is passed in. Default is False.

• nested_refs (bool, optional): If True and allow_refs=True, inspects nested objects (e.g., dictionaries, lists, slices, tuples) for references and resolves them automatically. Default is False.

• metadata (Mapping, optional): An arbitrary mapping, to be used to store additional metadata than cannot be declared with the other attributes. Useful for third-party libraries to extend Param. Default is None.

  .. versionadded:: 2.3.0

Examples

Define a parameter with a default value:

import param class MyClass(param.Parameterized): … my_param = param.Parameter(default=10, doc=”An example parameter.”) instance = MyClass() instance.my_param 10

Use a constant parameter:

class ConstantExample(param.Parameterized): … my_param = param.Parameter(default=5, constant=True) instance = ConstantExample() instance.my_param = 10 # Raises an error … TypeError: Constant parameter ‘my_param’ cannot be modified.

exception zoomy_core.symsolver.hooks.HookError

Bases: NotImplementedError

A hook (or its derivative) a backend cannot print.

Initialization

Initialize self. See help(type(self)) for accurate signature.

zoomy_core.symsolver.hooks.hook_names(expr)

The names of the hooks expr calls.

class zoomy_core.symsolver.hooks.Hooks(functions, grad=None)

A backend’s hooks: lower(expr) replaces hook derivatives (and inlines SymPy hooks); module holds the callables the lowered expressions call. grad(f, i) differentiates a callable (JAX: jax.grad); None: HookDerivative.auto of a callable is refused.

Initialization

Wrap every plain callable as a HookFunction (HookDerivative.auto).

lower(expr)

expr with the hook derivatives printable and SymPy hooks inlined (unchanged when it calls no hook).

zoomy_core.symsolver.hooks.check_functions(functions, systems)

Every hook the operators of systems (NSMs) call has a function and every function is called; raises ValueError (with “did you mean”).

zoomy_core.symsolver.hooks.refuse_hooks(systems, backend, functions=None)

The C++ backends: raise NotImplementedError for a hook the kernels of systems (NSMs) call, or any functions set.

zoomy_core.symsolver.hooks.refuse_used(refused, owner, source)

Raise the HookError of a refused kernel ({slot: error}) the printed source calls as owner.slot.