SymbolicODE

class cubie.odesystems.SymbolicODE(equations: ParsedEquations, precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], all_indexed_bases: IndexedBases, all_symbols: dict[str, Symbol] | None = None, fn_hash: str | None = None, user_functions: dict[str, Callable] | None = None, name: str | None = None)[source]

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.

__init__(equations: ParsedEquations, precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], all_indexed_bases: IndexedBases, all_symbols: dict[str, Symbol] | None = None, fn_hash: str | None = None, user_functions: dict[str, Callable] | None = None, name: str | None = None)[source]

Initialise the symbolic system instance.

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.

Returns:

None.

Return type:

None

_get_jvp_exprs() → JVPEquations[source]

Return cached Jacobian-vector assignments.

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.

classmethod create(dxdt: str | Iterable[str], 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, constants: dict[str, float] | Iterable[str] | None = None, drivers: Iterable[str] | dict[str, Any] | None = None, user_functions: 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, constant_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) → SymbolicODE[source]

Parse user inputs and instantiate a SymbolicODE.

Parameters:

  • dxdt – System equations defined as either a single string or an iterable of equation strings in lhs = rhs form.

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

  • 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”.

Returns:

Fully constructed symbolic system ready for compilation.

Return type:

SymbolicODE

property driver_units: dict[str, str]

Return units for drivers.

get_solver_helper(func_type: str, beta: float = 1.0, gamma: float = 1.0, preconditioner_order: int = 2, mass: ndarray | MutableDenseMatrix | None = None, stage_coefficients: Sequence[Sequence[float | Expr]] | None = None, stage_nodes: Sequence[float | Expr] | None = None) → Callable | int[source]

Return a generated solver helper device function.

Parameters:

  • func_type – Helper identifier. Supported values are "linear_operator", "linear_operator_cached", "neumann_preconditioner", "neumann_preconditioner_cached", "stage_residual", "n_stage_residual", "n_stage_linear_operator"`, ``"n_stage_neumann_preconditioner", "prepare_jac"`, ``"cached_aux_count" and "calculate_cached_jvp".

  • beta – Shift parameter for the linear operator.

  • gamma – Weight applied to the Jacobian term in the linear operator.

  • preconditioner_order – Polynomial order of the Neumann preconditioner.

  • mass – Mass matrix applied by the linear operator. When omitted the identity matrix is assumed.

  • stage_coefficients – FIRK tableau coefficients used to evaluate stage states. Required for flattened helpers.

  • stage_nodes – FIRK stage nodes expressed as timestep fractions. The stage count is inferred from len(stage_nodes).

Returns:

CUDA device function implementing the requested helper or the cached auxiliary count for "cached_aux_count".

Return type:

Callable or int

Raises:

NotImplementedError – Raised when func_type does not correspond to a supported helper.

property jacobian_aux_count: int | None

Return the number of cached Jacobian auxiliary values.

property observable_units: dict[str, str]

Return units for observables.

property parameter_units: dict[str, str]

Return units for parameters.

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

Update constant values in-place.

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

Constants are first updated in the indexed base map before delegating to BaseODE.set_constants() for cache management.

property state_units: dict[str, str]

Return units for state variables.