SymbolicODE

Bases: BaseODE

Symbolic representation of an ODE system.

Parameters are provided as SymPy symbols and the differential equations are supplied as (lhs, rhs) tuples where the left-hand side is a derivative or observable symbol. Right-hand sides combine states, parameters, constants, and intermediate observables.

Parameters:

equations – Parsed equations describing the system dynamics.
all_indexed_bases – Indexed base collections providing access to state, parameter, constant, and observable metadata.
all_symbols – Mapping from symbol names to their sympy.Symbol instances.
precision – Target floating-point precision used for generated kernels.
fn_hash – Precomputed system hash. When omitted it is derived from the equations and constants.
user_functions – Runtime callables referenced within the symbolic expressions.
name – Identifier used for generated modules.

Initialise the symbolic system instance.

Parameters:

equations – Parsed equations describing the system dynamics; the solver mass matrix rides on equations.mass_matrix.
all_indexed_bases – Indexed base collections providing access to state, parameter, constant, and observable metadata.
all_symbols – Mapping from symbol names to their sympy.Symbol instances.
precision – Target floating-point precision used for generated kernels.
fn_hash – Precomputed system hash. When omitted it is derived from the equations and constants.
user_functions – Runtime callables referenced within the symbolic expressions.
name – Identifier used for generated modules.
operation_ordering – Generated-operation ordering policy.
parsed_system – Constants-symbolic checkpoint from the parser; rebuilt from equations and re-specialised when omitted.

_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]

_get_jvp_exprs() → JVPEquations[source]

Return Jacobian-vector assignments for the current system.

The cache keys on the system hash and ordering policy, so a re-specialisation or ordering change recomputes on next use.

_seed_derived_mass(mass_matrix) → None[source]

Seed compile settings with the simplification-derived mass.

Parameters:: mass_matrix – None for solved systems, or the 0/1 diagonal from structural simplification (nested lists or an array).

_specialise(constant_values: dict[str, float], parsed_system: ParsedSystem) → None[source]

Derive the system’s products for one set of constant values.

Specialises the checkpoint, swaps in the derived equations, layouts, and hash, and pushes the changed compile settings in one call. parsed_system replaces the stored checkpoint on success; nothing mutates on a raise.

Parameters:

constant_values – Complete mapping of constant names to their new values.
parsed_system – Checkpoint to specialise from.

build() → ODECache[source]

Compile the dxdt factory and refresh the cache.

Returns:: Cache populated with the compiled dxdt callable.
Return type:: ODECache

property constant_units: dict[str, str]: Return units for constants.

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

Launch a Qt GUI for editing constants and parameters.

The GUI displays all constants and parameters with their values and units. Users can convert between constants and parameters using a checkbox, and edit 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.constants_gui()  # Opens editor dialog

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.
constants – Constant labels either as an iterable or as a mapping to default values.
drivers – External driver variable labels required at runtime. May be an iterable of driver labels or a dictionary describing driver defaults or driver-array samples alongside configuration entries.
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.
name – Identifier used for generated files. Defaults to the hash of the system definition.
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”.
constant_units – Optional units for constants. 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.

Returns:

Fully constructed symbolic system ready for compilation.

Return type:

SymbolicODE

property driver_units: dict[str, str]: Return units for drivers.

get_constants_info() → list[dict][source]

Return information about all constants.

Returns:: Each dict contains ‘name’, ‘value’, and ‘unit’ keys.
Return type:: list of dict

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 compile_settings.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

make_constant(name: str) → None[source]

Convert a parameter to a compile-time constant.

The parameter’s value folds into the source as a literal.

Parameters:: name – Name of the parameter to convert.
Raises:: KeyError – If the name is not found in parameters.

make_parameter(name: str) → None[source]

Convert a constant to a swept parameter.

The symbol returns to the equations in place of the folded literal; the current value becomes the parameter’s default.

Parameters:: name – Name of the constant to convert.
Raises:: KeyError – If the name is not found in constants.

property observable_units: dict[str, str]: Return units for observables.

property parameter_units: dict[str, str]: Return units for parameters.

set_constant_value(name: str, value: float) → None[source]

Set the value of a constant.

Parameters:

name – Name of the constant.
value – New value for the constant.

Raises:

KeyError – If the name is not found in constants.

set_constants(updates_dict: dict[str, float] | None = None, silent: bool = False, **kwargs: float) → Set[str][source]

Update constant values, re-specialising the system.

Parameters:

updates_dict – Mapping from constant names to replacement values.
silent – When True suppress warnings for unknown labels.
**kwargs – Additional constant overrides supplied as keyword arguments.

Returns:

Labels that were recognised and updated.

Return type:

set[str]

Notes

A value change re-runs constant specialisation, so system structure follows the new values.

set_initial_value(name: str, value: float) → None[source]

Set the initial value of a state variable.

Parameters:

name – Name of the state variable.
value – New initial value.

Raises:

KeyError – If the name is not found in states.

set_parameter_value(name: str, value: float) → None[source]

Set the default value of a parameter.

Parameters:

name – Name of the parameter.
value – New default value for the parameter.

Raises:

KeyError – If the name is not found in parameters.

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