cubie.batchsolving.solver

High level batch-solver interface.

This module exposes the user-facing Solver class and a convenience wrapper solve_ivp() for solving batches of initial value problems on the GPU.

Functions

solve_ivp(system, y0, parameters, ...[, ...])

Solve a batch initial value problem.

Classes

Solver(system, algorithm, duration, warmup, ...)

User-facing interface for solving batches of ODE systems.
class cubie.batchsolving.solver.Solver(system, algorithm: str = 'euler', duration: float = 1.0, warmup: float = 0.0, dt_min: float = 0.01, dt_max: float = 0.1, dt_save: float = 0.1, dt_summarise: float = 1.0, atol: float = 1e-06, rtol: float = 1e-06, saved_states: ~typing.List[str | int] | None = None, saved_observables: ~typing.List[str | int] | None = None, summarised_states: ~typing.List[str | int] | None = None, summarised_observables: ~typing.List[str | int] | None = None, output_types: list[str] = None, precision: type = <class 'numpy.float64'>, profileCUDA: bool = False, memory_manager=MemoryManager(totalmem=8589934592, registry={}, stream_groups=StreamGroups(groups={}, streams={}), _mode='passive', _allocator=<class 'cubie.cudasim_utils.FakeNumbaCUDAMemoryManager'>, _auto_pool=[], _manual_pool=[], _stride_order=('time', 'run', 'variable'), _queued_allocations={}), stream_group='solver', mem_proportion=None, **kwargs)[source]

Bases: object

User-facing interface for solving batches of ODE systems.

Parameters:

  • system (GenericODE) – System model containing the ODEs to integrate.

  • algorithm (str, optional) – Integration algorithm to use. Defaults to "euler".

  • duration (float, optional) – Total integration time. Defaults to 1.0.

  • warmup (float, optional) – Warm-up period before outputs are stored. Defaults to 0.0.

  • dt_min (float, optional) – Minimum and maximum timestep sizes. Defaults are 0.01 and 0.1.

  • dt_max (float, optional) – Minimum and maximum timestep sizes. Defaults are 0.01 and 0.1.

  • dt_save (float, optional) – Sampling interval for storing state values. Default is 0.1.

  • dt_summarise (float, optional) – Interval for computing summary outputs. Default is 1.0.

  • atol (float, optional) – Absolute and relative error tolerances. Defaults are 1e-6.

  • rtol (float, optional) – Absolute and relative error tolerances. Defaults are 1e-6.

  • saved_states (list of str or int, optional) – Variables to save verbatim at each output step.

  • saved_observables (list of str or int, optional) – Variables to save verbatim at each output step.

  • summarised_states (list of str or int, optional) – Variables for which summary statistics are computed.

  • summarised_observables (list of str or int, optional) – Variables for which summary statistics are computed.

  • output_types (list of str, optional) – Output arrays to generate (e.g. ["state"]).

  • precision (type, optional) – Floating point precision. Defaults to numpy.float64.

  • profileCUDA (bool, optional) – Enable CUDA profiling. Defaults to False.

  • memory_manager (MemoryManager, optional) – Manager responsible for CUDA memory allocations.

  • stream_group (str, optional) – Name of the CUDA stream group used by the solver. Defaults to "solver".

  • mem_proportion (float, optional) – Proportion of GPU memory reserved for the solver.

  • **kwargs – Additional keyword arguments forwarded to internal components.

system_interface

Object translating between user-world and GPU-world variables.

Type:

SystemInterface

grid_builder

Helper that constructs integration grids from user inputs.

Type:

BatchGridBuilder

kernel

Low-level component that executes integrations on the GPU.

Type:

BatchSolverKernel

_variable_indices_from_list(saved_states, saved_observables, summarised_states, summarised_observables)[source]

Translate variable labels into index arrays.

Parameters:

  • saved_states

  • saved_observables

  • summarised_states

:param : :param summarised_observables: Lists of variable labels. None leaves the corresponding

selection unchanged.

Returns:

Index arrays for each variable list in the order provided.

Return type:

tuple of ndarray or None

property active_output_arrays: ActiveOutputs

Exposes active_output_arrays from the child BatchSolverKernel object.

property chunk_axis: str

Exposes chunk_axis from the child BatchSolverKernel object.

property chunks

Exposes chunks from the child BatchSolverKernel object.

disable_profiling()[source]

Disable CUDA profiling for the solver.

This reverts the effect of enable_profiling() and returns the solver to normal execution speed.

enable_profiling()[source]

Enable CUDA profiling for the solver.

Profiling collects detailed performance information but can slow down execution considerably.

property forcing_vectors

Exposes forcing_vectors from the child BatchSolverKernel object.

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

Return indices for the specified observables.

Parameters:

observable_labels (list[str], optional) – 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)[source]

Return indices for the specified state variables.

Parameters:

state_labels (list[str], optional) – 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

Exposes initial_values from the child BatchSolverKernel object.

property input_variables: List[str]

`~cubie.batchsolving.BatchSolverKernel.input_variables ` from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property mem_proportion

Returns the memory proportion the solver is assigned.

property memory_manager

Returns the memory manager the solver is registered with.

property num_runs

Exposes num_runs from the child BatchSolverKernel object.

property observable_summaries

~cubie.batchsolving.BatchSolverKernel. observable_summaries from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property observables

Exposes observables from the child BatchSolverKernel object.

property output_array_heights

Exposes output_array_heights from the child BatchSolverKernel object.

property output_length

Exposes output_length from the child BatchSolverKernel object.

property output_stride_order: List[str]

`~cubie.batchsolving.BatchSolverKernel.output_stride_order ` from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property output_types: list[str]

Exposes output_types from the child BatchSolverKernel object.

property output_variables: List[str]

~cubie.batchsolving.BatchSolverKernel .output_variables from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property parameters

Exposes parameters from the child BatchSolverKernel object.

property precision: type

Exposes precision from the child BatchSolverKernel object.

property save_time: bool

Exposes save_time from the child BatchSolverKernel object.

property saved_observable_indices

~cubie.batchsolving.BatchSolverKernel .saved_observable_indices from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property saved_observables

Returns a list of observable labels for the saved observables.

property saved_state_indices

~cubie.batchsolving.BatchSolverKernel .saved_state_indices from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property saved_states

Returns a list of state labels for the saved states.

solve(initial_values, parameters, forcing_vectors=None, duration=1.0, settling_time=0.0, blocksize=256, stream=None, chunk_axis='run', grid_type: str = 'combinatorial', results_type: str = 'full', **kwargs)[source]

Solve a batch initial value problem.

Parameters:

  • initial_values (array-like or dict) – Initial state values for each integration run.

  • parameters (array-like or dict) – Parameter values for each run.

  • forcing_vectors (array-like, optional) – External forcing applied during integration.

  • duration (float, optional) – Total integration time. Default is 1.0.

  • settling_time (float, optional) – Warm-up period before recording outputs. Default 0.0.

  • blocksize (int, optional) – CUDA block size used for kernel launch. Default 256.

  • stream (cuda.stream or None, optional) – Stream on which to execute the kernel. None uses the solver’s default stream.

  • chunk_axis ({'run', 'time'}, optional) – Dimension along which to chunk when memory is limited. Default 'run'.

  • grid_type ({'combinatorial', 'verbatim'}, optional) – Strategy for constructing the integration grid from inputs.

  • results_type ({'full', 'numpy', 'numpy_per_summary', 'pandas'}, optional) – Format of returned results. Default 'full'.

  • **kwargs – Additional options forwarded to update().

Returns:

Collected results from the integration run.

Return type:

SolveResult

property solve_info

Returns a SolveSpec object with details of the solver run.

property state

~cubie.batchsolving.BatchSolverKernel.state from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property state_summaries

~cubie.batchsolving.BatchSolverKernel .state_summaries from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property stream_group

Returns the stream_group the solver is in.

property summaries_buffer_sizes

~cubie.batchsolving.BatchSolverKernel .summaries_buffer_sizes from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property summaries_length

Exposes summaries_length from the child BatchSolverKernel object.

property summarised_observable_indices

~cubie.batchsolving.BatchSolverKernel .summarised_observable_indices from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property summarised_observables

Returns a list of observable labels for the summarised observables.

property summarised_state_indices

~cubie.batchsolving.BatchSolverKernel .summarised_state_indices from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property summarised_states

Returns a list of state labels for the summarised states.

property summary_legend_per_variable: dict[int, str]

~cubie.batchsolving.BatchSolverKernel .summary_legend_per_variable from the child BatchSolverKernel object.

Type:

Exposes

Type:

attr

property system_sizes

Exposes system_sizes from the child BatchSolverKernel object.

update(updates_dict, silent=False, **kwargs)[source]

Update solver, integrator and system settings.

Parameters:

  • updates_dict (dict) – Mapping of attribute names to new values.

  • silent (bool, optional) – If True unknown keys are ignored instead of raising KeyError. Defaults to False.

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

Returns:

Set of keys that were successfully updated.

Return type:

set

update_memory_settings(updates_dict=None, silent=False, **kwargs)[source]

Update memory manager parameters.

Parameters:

  • updates_dict (dict, optional) – Mapping of settings to update.

  • silent (bool, optional) – If True unknown keys are ignored. Default False.

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

Returns:

Set of keys that were successfully updated.

Return type:

set

update_saved_variables(updates_dict)[source]

Interpret label lists and insert resolved indices.

Parameters:

updates_dict (dict) – Dictionary potentially containing saved_states, saved_observables, summarised_states or summarised_observables entries as labels.

Returns:

Updated dictionary with label lists replaced by index arrays.

Return type:

dict

cubie.batchsolving.solver.solve_ivp(system, y0, parameters, forcing_vectors, dt_eval, method='euler', duration=1.0, settling_time=0.0, **options) → SolveResult[source]

Solve a batch initial value problem.

Parameters:

  • system (object) – System model defining the differential equations.

  • y0 (array-like) – Initial state values for each run.

  • parameters (array-like or dict) – Parameter values for each run.

  • forcing_vectors (array-like) – External forcing values to apply during integration.

  • dt_eval (float) – Interval at which solution values are stored.

  • method (str, optional) – Integration algorithm to use. Default is "euler".

  • duration (float, optional) – Total integration time. Default is 1.0.

  • settling_time (float, optional) – Warm-up period prior to storing outputs. Default is 0.0.

  • **options – Additional keyword arguments passed to Solver.

Returns:

Results returned from Solver.solve().

Return type:

SolveResult