Solver

class cubie.batchsolving.solver.Solver(system: BaseODE, algorithm: str = 'euler', profileCUDA: bool = False, step_control_settings: Dict[str, object] | None = None, algorithm_settings: Dict[str, object] | None = None, output_settings: Dict[str, object] | None = None, memory_settings: Dict[str, object] | None = None, loop_settings: Dict[str, object] | None = None, strict: bool = False, time_logging_level: str | None = None, cache: bool | str | Path = True, **kwargs: Any)[source]

Bases: object

User-facing interface for solving batches of ODE systems.

Parameters:

system – System model containing the ODEs to integrate.
algorithm – Integration algorithm to use. Defaults to "euler".
profileCUDA – Enable CUDA profiling. Defaults to False.
step_control_settings – Explicit controller configuration that overrides solver defaults.
algorithm_settings – Explicit algorithm configuration overriding solver defaults.
output_settings – Explicit output configuration overriding solver defaults. Individual selectors such as save_variables or index-based parameters may also be supplied as keyword arguments.
memory_settings – Explicit memory configuration overriding solver defaults. Keys like memory_manager or mem_proportion may likewise be provided as keyword arguments.
loop_settings – Explicit loop configuration overriding solver defaults. Keys such as save_every and summarise_every may also be supplied as loose keyword arguments.
strict – If True unknown keyword arguments raise KeyError.
time_logging_level (str or None, default='default') – Time logging verbosity level. Options are ‘default’, ‘verbose’, ‘debug’, None, or ‘None’ to disable timing.
**kwargs – Additional keyword arguments forwarded to internal components. See “Optional Arguments” in the docs for the possibilities.

Notes

Instances coordinate batch grid construction, kernel configuration, and driver interpolation so that solve() orchestrates a complete GPU integration run.

When specifying variables:

None means “use all” (default behavior for both states and observables)
[] (empty list) means “explicitly no variables”
When both labels and indices are provided, their union is used

property active_outputs: ActiveOutputs: Expose active output array containers.

property algorithm: Return the configured algorithm name.

property atol: float | None: Return the absolute tolerance for adaptive controllers.

Build parameter and state grids for external use.

Parameters:

initial_values – Initial state values as dictionaries mapping state names to value sequences, or arrays in (n_states, n_runs) format.
parameters – Parameter values as dictionaries mapping parameter names to value sequences, or arrays in (n_params, n_runs) format.
grid_type – Strategy for constructing the grid. "combinatorial" produces all combinations while "verbatim" preserves column-wise pairings. Default is "verbatim".

Returns:

Tuple of (initial_values, parameters) arrays in (n_vars, n_runs) format with system precision dtype. These arrays can be passed directly to solve() for fast-path execution.

Return type:

Tuple[ndarray, ndarray]

Examples

>>> inits, params = solver.build_grid(
...     {"x": [1, 2, 3]}, {"p": [0.1, 0.2]}, grid_type="combinatorial"
... )
>>> result = solver.solve(inits, params)  # Uses fast path

property cache_dir: Path | None: Custom cache directory, or None for default location.

property cache_enabled: bool: Whether file-based caching is enabled.

property cache_mode: str: Current caching mode (‘hash’ or ‘flush_on_change’).

property chunks: Return the number of chunks used in the last run.

property compile_flags: OutputCompileFlags: Expose output compile flags from the kernel.

convert_output_labels(output_settings: Dict[str, Any]) → None[source]

Convert variable labels to indices.

Parameters:: output_settings – Output configuration kwargs. Entries used are save_variables, summarise_variables, saved_state_indices, saved_observable_indices, summarised_state_indices, and summarised_observable_indices.
Returns:: Modifies output_settings in-place.
Return type:: None
Raises:: ValueError – If variable labels are not recognized by the system.

disable_profiling() → None[source]

Disable CUDA profiling for the solver.

Returns:: This method alters kernel profiling configuration in-place.
Return type:: None

property driver_coefficients: Expose driver interpolation coefficients.

property dt: float | None: Return the fixed-step size or None for adaptive controllers.

property dt_max: float | None: Return the maximum step size for adaptive controllers.

property dt_min: float | None: Return the minimum step size for adaptive controllers.

property duration: Return the requested integration duration.

enable_profiling() → None[source]

Enable CUDA profiling for the solver.

Returns:: This method alters kernel profiling configuration in-place.
Return type:: None

get_observable_indices(observable_labels: List[str] | None = None) → ndarray[source]

Return indices for the specified observables.

Parameters:: observable_labels – Labels of observables to query. None returns indices for all observables.
Returns:: Integer indices corresponding to the requested observables.
Return type:: ndarray

get_state_indices(state_labels: List[str] | None = None) → ndarray[source]

Return indices for the specified state variables.

Parameters:: state_labels – Labels of states to query. None returns indices for all states.
Returns:: Integer indices corresponding to the requested states.
Return type:: ndarray

property initial_values: Expose initial values array used in the last run.

property input_variables: List[str]: List all input variable labels.

property iteration_counters: Expose iteration counters at each save point.

property mem_proportion: Return the proportion of global memory allocated.

property memory_manager: Return the associated memory manager instance.

property num_runs: Expose the number of runs in the last solve.

property observable_summaries: Expose observable summary outputs.

property observables: Expose latest observable outputs.

property output_array_heights: Expose output array heights from the kernel.

property output_length: Expose the flattened output length.

property output_types: List[str]: List active output types.

property output_variables: List[str]: List all output variable labels.

property parameters: Expose parameter array used in the last run.

property precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64]: Expose the kernel precision.

property rtol: float | None: Return the relative tolerance for adaptive controllers.

property sample_summaries_every: float | None: Return the interval between summary metric samples.

property save_every: float | None: Return the interval between saved time-domain outputs.

property save_time: bool: Return whether time points are saved.

property saved_observable_indices: Expose saved observable indices.

property saved_observables: List saved observable labels.

property saved_state_indices: Expose saved state indices.

property saved_states: List saved state labels.

set_cache_dir(path: str | Path) → None[source]

Set a custom cache directory for compiled kernels.

Parameters:: path – New cache directory path. Can be absolute or relative.

Notes

Invalidates the current cache, causing a rebuild on next access.

set_verbosity(verbosity: str | None) → None[source]

Set the time logging verbosity level.

Parameters:: verbosity (str or None) – New verbosity level. Options are ‘default’, ‘verbose’, ‘debug’, None, or ‘None’.

Notes

Updates the global time logger verbosity. This affects all timing events across the entire CuBIE package.

solve(initial_values: ndarray | Dict[str, float | ndarray], parameters: ndarray | Dict[str, float | ndarray], drivers: Dict[str, Any] | None = None, duration: float = 1.0, settling_time: float = 0.0, t0: float = 0.0, blocksize: int = 256, stream: Any = None, grid_type: str = 'verbatim', results_type: str = 'full', nan_error_trajectories: bool = True, **kwargs: Any) → SolveResult[source]

Solve a batch initial value problem.

Parameters:

initial_values – Initial state values for each integration run. Accepts dictionaries mapping state names to values for grid construction, or pre-built arrays in (n_states, n_runs) format for fast-path execution.
parameters – Parameter values for each run. Accepts dictionaries mapping parameter names to values, or pre-built arrays in (n_params, n_runs) format.
drivers – Driver samples or configuration matching cubie.integrators.array_interpolator.ArrayInterpolator.
duration – Total integration time. Default is 1.0.
settling_time – Warm-up period before recording outputs. Default 0.0.
t0 – Initial integration time. Default 0.0.
blocksize – CUDA block size used for kernel launch. Default 256.
stream – Stream on which to execute the kernel. None uses the solver’s default stream.
grid_type – Strategy for constructing the integration grid from inputs. Only used when dict inputs trigger grid construction.
results_type – Format of returned results, for example "full" or "numpy".
nan_error_trajectories – When True (default), trajectories with nonzero status codes are automatically set to NaN, making failed runs easy to identify and exclude from analysis. When False, all trajectories are returned unchanged. Ignored when results_type is "raw".
**kwargs – Additional options forwarded to update(). See “Optional Arguments” in the docs for possibilities.

Returns:

Collected results from the integration run.

Return type:

SolveResult

Notes

Input type detection determines the processing path:

Dictionary inputs trigger grid construction via BatchInputHandler
Pre-built numpy arrays with correct shapes skip grid construction for improved performance
Device arrays receive minimal processing before kernel execution

When GPU memory is insufficient for the full batch, arrays are automatically chunked along the run axis.

property solve_info: SolveSpec: Construct a SolveSpec describing the current configuration.

property state: Expose latest state outputs.

property state_summaries: Expose state summary outputs.

property status_codes: Expose integration status codes.

property stream: Return the CUDA stream used by this solver.

property stream_group: Return the CUDA stream group assigned to this solver.

property summaries_buffer_sizes: Expose summary buffer sizes.

property summaries_length: Expose the flattened summary length.

property summarise_every: float | None: Return the interval between summary computations.

property summarised_observable_indices: Expose summarised observable indices.

property summarised_observables: List summarised observable labels.

property summarised_state_indices: Expose summarised state indices.

property summarised_states: List summarised state labels.

property summary_legend_per_variable: dict[int, str]: Expose summary legends keyed by variable index.

property summary_unit_modifications: dict[int, str]: Expose summary unit modifications keyed by variable index.

property system: BaseODE: Return the underlying ODE system instance.

property system_sizes: Expose cached system size metadata.

property t0: float: Return the starting integration time.

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

Update solver, integrator, and system settings.

Parameters:

updates_dict – Mapping of attribute names to new values.
silent – If True unknown keys are ignored instead of raising KeyError.
**kwargs – Additional updates supplied as keyword arguments.

Returns:

Set of keys that were successfully updated.

Return type:

Set[str]

Raises:

KeyError – If silent is False and unknown settings are supplied.

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

Update memory manager parameters.

Parameters:

updates_dict – Mapping of memory manager settings to update.
silent – If True unknown keys are ignored instead of raising KeyError.
**kwargs – Additional updates supplied as keyword arguments.

Returns:

Set of keys that were successfully updated.

Return type:

Set[str]

Raises:

KeyError – If silent is False and unknown settings are supplied.

property warmup: Return the warm-up period length.