BaseODE

class cubie.odesystems.BaseODE(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64] = <class 'numpy.float32'>, initial_values: Dict[str, float] | None=None, parameters: Dict[str, float] | None=None, constants: Dict[str, float] | None=None, observables: Dict[str, float] | None=None, default_initial_values: Dict[str, float] | None=None, default_parameters: Dict[str, float] | None=None, default_constants: Dict[str, float] | None=None, default_observable_names: Dict[str, float] | None=None, num_drivers: int = 1, operation_ordering: str = 'liveness_auto', name: str | None = None)[source]

Bases: CUDAFactory

Abstract base for CUDA-backed ordinary differential equation systems.

Subclasses override build() to compile a CUDA device function that advances the system state and, optionally, provide analytic helpers via get_solver_helper(). The base class handles value management, precision selection, and caching through CUDAFactory.

Notes

Only functions cached during build() (typically dxdt) are available on this base class. Solver helper functions such as the linear operator or preconditioner are generated only by subclasses like SymbolicODE.

__init__(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64] = <class 'numpy.float32'>, initial_values: Dict[str, float] | None=None, parameters: Dict[str, float] | None=None, constants: Dict[str, float] | None=None, observables: Dict[str, float] | None=None, default_initial_values: Dict[str, float] | None=None, default_parameters: Dict[str, float] | None=None, default_constants: Dict[str, float] | None=None, default_observable_names: Dict[str, float] | None=None, num_drivers: int = 1, operation_ordering: str = 'liveness_auto', name: str | None = None) → None[source]

Initialize the ODE system.

Parameters:

  • initial_values – Initial values for state variables.

  • parameters – Parameter values for the system.

  • constants – Constants that are not expected to change between simulations.

  • observables – Observable values to track.

  • default_initial_values – Default initial values if initial_values omits entries.

  • default_parameters – Default parameter values if parameters omits entries.

  • default_constants – Default constant values if constants omits entries.

  • default_observable_names – Default observable names if observables omits entries.

  • precision – Precision factory used for calculations. Defaults to numpy.float32.

  • num_drivers – Number of driver or forcing functions. Defaults to 1.

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

  • name – Printable identifier for the system. Defaults to None.

abstractmethod build() → ODECache[source]

Compile the dxdt system as a CUDA device function.

Returns:

Cache containing the built dxdt function. Subclasses may add further solver helpers to this cache as needed.

Return type:

ODECache

Notes

Bring constants into local (outer) scope before defining dxdt because CUDA device functions cannot reference self.

property config_hash

Configuration hash incorporating constant values.

property constants: SystemValues

Constant values configured for the system.

copy() → BaseODE[source]

Return an independent system with these values and no build.

property dxdt_fn

Compiled dxdt(state, parameters, drivers, observables, out, t) device function.

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

Return the bound helper member for one role and variant.

Mass-consuming helpers read the system’s own mass.

Parameters:

  • role – Registered role name or preconditioner type name.

  • **request_kwargs – Remaining SolverHelperRequest fields.

Returns:

The bound device callable and its typed metadata.

Return type:

HelperResult

Raises:

NotImplementedError – Always; only SymbolicODE generates helpers.

property initial_values: SystemValues

Alias for states.

property mass: Any

Return the system’s mass matrix.

None implies identity, otherwise a diagonal 0/1 matrix produced in structural simplification.

property mass_diagonal_flags: tuple

Return per-state mass flags, True for a differential row.

property num_constants: int

Number of constants.

property num_drivers: int

Number of driver variables.

property num_observables: int

Number of observable variables.

property num_parameters: int

Number of parameters.

property num_states: int

Number of state variables.

property observables: SystemValues

Observable definitions configured for the system.

property observables_fn: Callable

Compiled get_observables(state, parameters, drivers, observables, t) device function.

property operation_count: int

Binary-operator count of the dxdt and observables sources.

property operation_ordering: str

Return the generated-operation ordering policy.

property parameters: SystemValues

Parameter values configured for the system.

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

Update constant values in the system.

Parameters:

  • updates_dict – Mapping from constant names to their new values.

  • silent – Set to True to suppress warnings about missing keys.

  • **kwargs – Additional constant updates provided as keyword arguments. These override entries in updates_dict.

Returns:

Labels that were recognized and updated.

Return type:

set of str

property sizes

System component sizes cached for solvers.

property states: SystemValues

Initial state values configured for the system.

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

Update compile settings through the CUDAFactory interface.

Pass updates through the compile-settings interface, which invalidates caches when an update succeeds.

Parameters:

  • updates_dict – Dictionary of updates to apply.

  • silent – Set to True to suppress warnings about missing keys.

  • **kwargs – Additional updates specified as keyword arguments.

Returns:

Labels that were recognized and updated.

Return type:

set of str

Notes

Pass silent=True when performing bulk updates that may include values for other components to suppress warnings about missing keys.