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, 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, 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.float64.

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

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

Notes

‘Precision’ is the root for all other precisions in the package. If left unset, it will make everything float32.

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

Override the config hash fetcher to add and hash the current constant values. When labels change, we need to re-codegen, but when values change, we need to rebuild.

property constants

Constant values configured for the system.

correct_answer_python(states: ndarray[Any, dtype[floating[Any]]], parameters: ndarray[Any, dtype[floating[Any]]], drivers: ndarray[Any, dtype[floating[Any]]]) → Tuple[ndarray[Any, dtype[floating[Any]]], ndarray[Any, dtype[floating[Any]]]][source]

Python reference dxdt for testing.

Parameters:

  • states – Current state values.

  • parameters – Parameter values.

  • drivers – Driver or forcing values.

Returns:

Tuple containing the state derivatives and observable outputs.

Return type:

tuple of numpy.ndarray

property evaluate_f

Compiled CUDA device function for evaluating f(t, y).

property evaluate_observables: Callable

Return the compiled observables device function.

Returns:

CUDA device function that computes observables without updating the derivative buffer.

Return type:

Callable

get_solver_helper(func_name: str, beta: float = 1.0, gamma: float = 1.0, mass: Any = 1.0, preconditioner_order: int = 0) → Callable[source]

Retrieve a cached solver helper function.

Parameters:

  • func_name – Identifier for the helper function.

  • beta – Shift parameter for the linear operator. Defaults to 1.0.

  • gamma – Weight of the Jacobian term in the linear operator. Defaults to 1.0.

  • preconditioner_order – Polynomial order of the preconditioner. Defaults to 0. Unused when generating the linear operator.

  • mass – Mass matrix used by the linear operator. Defaults to identity.

Returns:

Cached device function corresponding to func_name.

Return type:

Callable

Notes

Returns NotImplementedError if the ODESystem lacks generated code for the requested helper.

property initial_values

Alias for states.

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

Observable definitions configured for the system.

property parameters

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

Initial state values configured for the system.

update(updates_dict: Dict[str, float] | 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.