SymbolicODE

class cubie.odesystems.SymbolicODE(parsed_system: ParsedSystem, precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], name: str | None = None, operation_ordering: str | None = None, swept_parameters: Iterable[str] | None = None)[source]

Bases: BaseODE

Symbolic representation of an ODE system.

The system holds a ParsedSystem, with every parameter left as a symbol, and a SystemSpecialiser child that assembles it for the parameters the current batch compiles.

Parameters:

  • parsed_system – Parsed system with every parameter left as a symbol.

  • precision – Target floating-point precision used for generated kernels.

  • name – Identifier used for generated modules.

  • operation_ordering – Generated-operation ordering policy.

  • swept_parameters – Names of the parameters that vary between the runs of a batch. Every other parameter is compiled in at its default value, and when you leave this out every parameter is compiled in. A solve sets the swept parameters to match its inputs, so giving them here saves specialising the system again at the first solve, which can take 10-100 ms.

__init__(parsed_system: ParsedSystem, precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], name: str | None = None, operation_ordering: str | None = None, swept_parameters: Iterable[str] | None = None)[source]

Specialise a parsed system for a set of swept parameters.

Parameters:

  • parsed_system – Parsed system with every parameter left as a symbol.

  • precision – Target floating-point precision used for generated kernels.

  • name – Identifier used for generated modules. Defaults to unnamed_ followed by the start of a hash of the equations, which is the same whichever parameters are swept.

  • operation_ordering – Policy for ordering the generated operations. Defaults to CUBIE_OPERATION_ORDERING, read when the system is built, or liveness_auto if that is unset.

  • swept_parameters – Names of the parameters that vary between the runs of a batch. Every other parameter is compiled in at its default value, and when you leave this out every parameter is compiled in. A solve sets the swept parameters to match its inputs, so giving them here saves specialising the system again at the first solve, which can take 10-100 ms.

_device_function_injections() → dict[str, Callable][source]

Collect device callables the generated module must resolve.

Generated factories call user device functions (and their derivative helpers) by name, but the generated module is imported standalone, so those callables are injected as module attributes before the factory is compiled.

Returns:

Mapping from printed function name to device callable.

Return type:

dict[str, Callable]

build() → ODECache[source]

Compile the dxdt factory and refresh the cache.

Returns:

Cache populated with the compiled dxdt callable.

Return type:

ODECache

classmethod create(dxdt: str | Iterable[str] | Callable, precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], states: dict[str, float] | Iterable[str] | None = None, observables: Iterable[str] | None = None, parameters: dict[str, float] | Iterable[str] | None = None, drivers: Iterable[str] | dict[str, Any] | None = None, user_functions: dict[str, Callable] | None = None, user_function_derivatives: dict[str, Callable] | None = None, name: str | None = None, strict: bool = False, state_units: dict[str, str] | Iterable[str] | None = None, parameter_units: dict[str, str] | Iterable[str] | None = None, observable_units: dict[str, str] | Iterable[str] | None = None, driver_units: dict[str, str] | Iterable[str] | None = None, state_priority: dict[str, float] | None = None, irreducible: Iterable[str] | None = None, simplify_options: dict[str, Any] | None = None, operation_ordering: str | None = None, swept_parameters: Iterable[str] | None = None) → SymbolicODE[source]

Parse user inputs and instantiate a SymbolicODE.

Parameters:

  • dxdt – System equations defined as a single string, an iterable of equation strings in lhs = rhs form, or a Python callable with a (t, y, ...) signature.

  • states – State labels either as an iterable or as a mapping to default initial values.

  • observables – Observable variable labels to expose from the generated system.

  • parameters – Parameter labels either as an iterable or as a mapping to default values.

  • drivers – Names of the drivers you supply at solve time, as a list, or as a dict whose keys are the names. create reads only the keys.

  • user_functions – Custom callables referenced within dxdt expressions.

  • user_function_derivatives – Mapping of user-function names to callables evaluating their analytic derivatives, used when generating Jacobian-based solver helpers. A value may also be a list of callables evaluating the first, second, … derivatives; the order-n callable takes the function’s arguments followed by n argument indices.

  • name – Identifier used for generated files. Defaults to unnamed_ followed by the start of a hash of the equations.

  • precision – Target floating-point precision used when compiling the system.

  • strict – When True require every symbol to be explicitly categorised.

  • state_units – Optional units for states. Defaults to “dimensionless”.

  • parameter_units – Optional units for parameters. Defaults to “dimensionless”.

  • observable_units – Optional units for observables. Defaults to “dimensionless”.

  • driver_units – Optional units for drivers. Defaults to “dimensionless”.

  • state_priority – Per-unknown state-selection priorities (higher values are preferred as solver states).

  • irreducible – Unknowns that must not be eliminated.

  • simplify_options – Extra keyword arguments forwarded to structural_simplify().

  • operation_ordering – Generated-operation ordering policy: "liveness_auto", "kahn", "greedy", or "dfs". Defaults to CUBIE_OPERATION_ORDERING.

  • swept_parameters – Names of the parameters that vary between the runs of a batch. Every other parameter is compiled in at its default value, and when you leave this out every parameter is compiled in. A solve sets the swept parameters to match its inputs, so giving them here saves specialising the system again at the first solve, which can take 10-100 ms.

Returns:

Fully constructed symbolic system ready for compilation.

Return type:

SymbolicODE

property driver_units: dict[str, str]

Return units for drivers.

property equations

The equations with every fixed value folded in.

property fn_hash: str

Hash of every value the generated source embeds.

get_parameters_info() → list[dict][source]

Return information about all parameters.

Returns:

Each dict contains ‘name’, ‘value’, and ‘unit’ keys.

Return type:

list of dict

get_solver_helper(role: str, **request_kwargs: Any) → HelperResult[source]

Return the bound helper member for one role and variant.

Parameters:

  • role – Registered role name ("linear_operator", "residual", …) or preconditioner type name ("neumann", "jacobi").

  • **request_kwargs – Remaining SolverHelperRequest fields: jacobian_at, prefactored, stacked, operator_beta, operator_gamma, preconditioner_order, and stage data.

Returns:

The bound device callable and its typed metadata. Cached Jacobian-carrying members carry prepare_jac and cached_auxiliary_count.

Return type:

HelperResult

Notes

Mass-consuming helpers read mass. A repeated request returns the same member; bindings sharing source reuse one generated factory.

get_states_info() → list[dict][source]

Return information about all state variables.

Returns:

Each dict contains ‘name’, ‘value’, and ‘unit’ keys.

Return type:

list of dict

property observable_units: dict[str, str]

Return units for observables.

property parameter_units: dict[str, str]

Return units for parameters.

parameters_gui(blocking: bool = True) → None[source]

Launch a Qt GUI for editing parameter values.

The GUI displays every parameter with its value and unit.

Parameters:

blocking – If True (default), block until the dialog is closed. If False, return immediately with the dialog still open.

Notes

Requires a Qt binding (PyQt6, PyQt5, PySide6, or PySide2).

Example

>>> ode = load_cellml_model("model.cellml")
>>> ode.parameters_gui()  # Opens editor dialog
property state_units: dict[str, str]

Return units for state variables.

states_gui(blocking: bool = True) → None[source]

Launch a Qt GUI for editing initial state values.

The GUI displays all state variables with their initial values and units. Users can edit the initial values directly.

Parameters:

blocking – If True (default), block until the dialog is closed. If False, return immediately with the dialog still open.

Notes

Requires a Qt binding (PyQt6, PyQt5, PySide6, or PySide2).

Example

>>> ode = load_cellml_model("model.cellml")
>>> ode.states_gui()  # Opens editor dialog
property user_functions: dict[str, Callable]

Every callable the generated code may call, by name.