BatchSolverKernel

class cubie.batchsolving.BatchSolverKernel.BatchSolverKernel(system: SymbolicODE, **settings: Any)

Bases: CUDAFactory

Factory for CUDA kernel which coordinates a batch integration.

Parameters:

• system – ODE system describing the problem to integrate.

• **settings – Loop, step, controller, algorithm, output, memory, cache and kernel settings as one flat dict; the interpolation settings and compile flags reach the driver interpolator.

resident_blocks

Blocks per SM on the GPU, set by auto_performance and Solver.optimize.

Notes

The kernel delegates integration logic to SingleIntegratorRun instances and expects upstream APIs to perform batch construction. It executes the compiled loop function against kernel-managed memory slices and distributes work across GPU threads for each input batch.

_compute_launch_geometry(blocksize: int, runs: int, resident: int | None) → tuple[int, int]

Return the geometry holding resident blocks per SM.

_default_launch(runs: int) → tuple[int, int | None]

Return the block size and resident blocks per SM of a launch with no block size requested.

Returns:

The automatic choice, or the blocksize setting (unset: DEFAULT_BLOCKSIZE) with None when none is made.

Return type:

tuple[int, int or None]

_driver_settings() → Dict[str, Any]

Return the interpolator’s evaluators and coefficient layout.

_duration_counts(duration: float) → DurationCounts

Return the event counts for duration, memoised per build.

static _dynamic_shared_for_blocks(dispatcher: Any, blocksize: int, dynamic_sharedmem: int, blocks: int) → int

Return the smallest dynamic shared pad holding blocks per SM.

_execute_run(inits: NDArray[floating], params: NDArray[floating], duration: float, blocksize: int | None, stream: Any | None, warmup: float, t0: float, transfer_outputs: bool) → None

Allocate, chunk, and launch the batch kernel.

_get_chunk_events(chunk_idx: int) → Tuple

Get the three CUDA events for a specific chunk.

Parameters:

chunk_idx (int) – Chunk index (0-based)

Returns:

(h2d_event, kernel_event, d2h_event) for the chunk

Return type:

tuple

_invalidate_cache() → None

Drop the build; flush the disk cache in flush_on_change mode.

_kernel_launch_args(chunk_run_params: RunParams) → Tuple

Return the kernel’s positional arguments for one chunk.

_launch_shape(blocksize: int, runs: int) → tuple[int, int]

Return a launch’s block size, halved until its shared footprint fits, and dynamic shared bytes.

_natural_blocks(blocksize: int, dynamic_sharedmem: int) → int

Return the blocks per SM the driver fits at this launch shape.

_on_allocation(response: ArrayResponse) → None

Update run parameters with chunking metadata from allocation.

_prepare_batch(inits: NDArray[floating], params: NDArray[floating], duration: float, warmup: float, t0: float, stream: Any | None) → None

Set run parameters, refresh settings, and queue allocations.

_resident_input(name: str) → Any

Device input name; raises ValueError after a chunked run.

_setup_cuda_events(chunks: int) → None

Provide the timing events for this run.

Parameters:

chunks (int) – Number of chunks to process

Notes

One workload event plus three per chunk. While timing is on they are kept between runs and rebuilt when the chunk count or logger verbosity changes; with timing off each run gets fresh no-op events.

_setup_memory_manager(settings: Dict[str, Any]) → MemoryManager

Register the kernel with a memory manager instance.

Parameters:

settings – Mapping of memory configuration options recognised by the memory manager.

Returns:

Memory manager configured for solver allocations.

Return type:

MemoryManager

_summaries_legend() → Dict[int, str]

Map summary output rows to labels with units and metric.

_time_domain_legend() → Dict[int, str]

Map time-domain output rows to labels with units.

_validate_timing_parameters(duration: float) → None

Validate timing parameters to prevent invalid array accesses.

Parameters:

duration – Integration duration in time units.

Raises:

ValueError – When timing parameters would result in no outputs or invalid sampling.

Notes

Uses dt_min as an absolute tolerance when comparing floating point timing parameters by adding dt_min to the requested duration. Small in-loop timing oversteps smaller than dt_min are treated as valid and do not trigger validation errors.

_variable_units() → Tuple[Dict[str, str], Dict[str, str]]

Return the system’s state and observable units by label.

property active_outputs: ActiveOutputs

Active output array flags derived from compile_flags.

property algorithm: str

Identifier of the selected integration algorithm.

property atol: float

Absolute error tolerance applied during adaptive stepping.

build() → BatchSolverCache

Compile the integration kernel and return it with its memos.

build_kernel() → None

Build and compile the CUDA integration kernel.

property chunks

Number of chunks in the most recent run.

close(shutdown_timeout: float | None = None) → None

Release resources after pending transfers finish.

Parameters:

shutdown_timeout – Maximum seconds to wait. None waits until transfers finish.

property coefficients_shape: tuple[int, int, int]

Expected driver-coefficient layout for input validation.

A BatchSolverConfig compile setting the owning Solver keeps aligned with ArrayInterpolator.coefficients_shape — the exact (num_segments, num_drivers, order + 1) layout baked into the compiled driver evaluators — so supplied coefficient arrays are checked against the shape the kernel was compiled for. Update via update(coefficients_shape=...).

compile(inits: NDArray[floating], params: NDArray[floating], duration: float, warmup: float = 0.0, t0: float = 0.0) → None

Compile the batch kernel for these inputs without launching.

property compile_flags: OutputCompileFlags

Boolean compile-time controls for which output features are enabled.

configure_drivers(drivers: Dict[str, Any]) → None

Update the owned driver interpolator and dependent settings.

Parameters:

drivers – Driver samples plus interpolation settings, as accepted by ArrayInterpolator.update_from_dict().

property device_driver_coefficients: NDArray[floating] | None

Device-resident driver coefficients.

property device_function

Return the compiled CUDA device function.

Returns:

Compiled CUDA device function.

Return type:

callable

property device_initial_values: Any

Device initial values of the last single-chunk run.

property device_iteration_counters: Any

Device buffer of iteration counters at each save point.

property device_observable_summaries: Any

Device buffer of observable summary reductions.

property device_observables: Any

Device buffer of saved observable trajectories.

property device_parameters: Any

Device parameters of the last single-chunk run.

property device_state: Any

Device buffer of saved state trajectories.

property device_state_summaries: Any

Device buffer of state summary reductions.

property device_status_codes: Any

Device buffer of integration status codes.

property driver_coefficients: NDArray[floating] | None

Horner-ordered driver coefficients on the host.

driver_inputs() → Dict[str, Any] | None

Drivers as passed to configure_drivers; None when unset.

property dt: float | None

Current integrator step size when available.

property dt_max: float

Maximum allowable step size from the controller.

property dt_min: float

Minimum allowable step size from the controller.

property duration: float

Requested integration duration.

property initial_values: Any

Initial state values used in the last run.

A host view, or the caller’s device array when initial values were supplied on device.

property iteration_counters: Any

Host view of iteration counters at each save point.

property kernel: Callable

Compiled integration kernel callable.

kernel_is_cached() → bool

Whether the disk cache holds this configuration’s kernel; False when caching is off.

property kernel_name: str

Name the compiled kernel is given on the device.

Returns:

The configured name, or {algorithm}_{system name} when unset, with the LTO state appended and illegal identifier characters replaced.

Return type:

str

launch_geometry(blocksize: int | None = None) → tuple[int, int]

Return the block size and dynamic shared bytes of a launch.

Parameters:

blocksize – Requested CUDA block size; None uses the blocksize setting, or the automatic launch when that is unset.

Returns:

Block size and dynamic shared bytes, padded to hold the resident block count.

Return type:

tuple[int, int]

launchable_shapes(blocksizes: Sequence[int] = (32, 64, 128, 256), runs: int | None = None) → Dict[int, Tuple[int, int]]

Dynamic shared bytes and blocks per SM per launchable block size.

runs types the shapes; None uses the staged batch.

limit_blocksize(blocksize: int, dynamic_sharedmem: int, bytes_per_run: int, numruns: int) → tuple[int, int]

Halve the block size until dynamic shared memory is launchable.

Parameters:

• blocksize – Requested CUDA block size.

• dynamic_sharedmem – Shared-memory footprint per block at the current block size.

• bytes_per_run – Shared-memory requirement per run.

• numruns – Total number of runs queued for the launch.

Returns:

Adjusted block size and shared-memory footprint per block, within the device’s opt-in per-block limit.

Return type:

tuple[int, int]

Raises:

ValueError – If a single run’s shared-memory demand exceeds the device’s per-block limit, so no block size can launch.

property mem_proportion: float | None

Fraction of managed memory reserved for this kernel.

property memory_manager: MemoryManager

Registered memory manager for this kernel.

property n_drivers: int

Number of interpolated driver inputs for the system.

property num_runs: int

Number of runs scheduled for the batch integration.

property observable_summaries: Any

Host view of observable summary reductions.

property observables: Any

Host view of saved observable trajectories.

property output_array_heights: OutputArrayHeights

Height metadata for the batched output arrays.

property output_length: int

Number of saved trajectory samples in the main run.

property output_types: Any

Active output type identifiers configured for the run.

property parameters: Any

Parameter tables used in the last run.

A host view, or the caller’s device array when parameters were supplied on device.

property persistent_local_elements: int

Number of elements in the per-thread persistent local array.

property rtol: float

Relative error tolerance applied during adaptive stepping.

run(inits: NDArray[floating], params: NDArray[floating], duration: float, blocksize: int | None = None, warmup: float = 0.0, t0: float = 0.0, transfer_outputs: bool = True) → None

Execute the solver kernel for batch integration.

Chunking is performed along the run axis when memory constraints require splitting the batch.

Parameters:

• inits – Initial conditions with shape (n_states, n_runs). Host or device arrays are accepted; device arrays are used in place with no host-to-device transfer.

• params – Parameter table with shape (n_params, n_runs). Host or device arrays are accepted, as for inits.

• duration – Duration of the simulation window.

• blocksize – CUDA block size for this launch; None uses the blocksize setting, or the automatic launch when that is unset.

• warmup – Warmup time before the main simulation.

• t0 – Initial integration time.

• transfer_outputs – When True (default), output arrays are copied device-to-host after each chunk. False skips the copy so results stay in the device output buffers; the run must fit in a single chunk.

Notes

The kernel prepares array views, queues allocations, and executes the device loop on each chunked workload. Shared-memory demand may reduce the block size automatically, emitting a warning when the limit drops below a warp. Every launch and transfer runs on this kernel’s memory-manager stream (stream); there is no per-run stream selection.

Raises:

• RuntimeError – If the kernel has been closed.

• ValueError – Drivers declared but no evaluator wired; chunked batch with transfer_outputs=False or device inputs.

property sample_summaries_every: float

Interval between summary metric samples from the loop.

property save_counters: bool

Whether iteration counters are saved at each save point.

property save_every: float | None

Interval between saved samples from the loop, or None if save_last only.

property save_time: bool

Whether time samples are saved alongside states.

property saved_observable_indices: Any

Indices of saved observable variables.

property saved_state_indices: Any

Indices of saved state variables.

set_cache_dir(path: str | Path) → None

Set a custom cache directory for compiled kernels.

Parameters:

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

property settings_dict: Dict[str, Any]

Return the settings of this kernel and its run.

settings_keys: frozenset | None = frozenset({'auto_performance', 'blocksize', 'cache', 'cache_dir', 'cache_enabled', 'cache_mode', 'kernel_name', 'max_cache_entries', 'max_registers'})

Loose keys the factory accepts; None accepts every field.

property shared_memory_bytes: int

Shared-memory footprint per run for the compiled kernel.

property shared_memory_elements: int

Number of precision elements required in shared memory per run.

property shared_memory_needs_padding: bool

Indicate whether shared-memory padding is required.

Returns:

True when a four-byte skew reduces bank conflicts for single precision.

Return type:

bool

Notes

Shared memory load instructions for float64 require eight-byte alignment. Padding in that scenario would misalign alternate runs and trigger misaligned-access faults, so padding only applies to single precision workloads where the skew preserves alignment.

property state: Any

Host view of saved state trajectories.

property state_summaries: Any

Host view of state summary reductions.

property status_codes: Any

Host view of integration status codes.

property stream: Any

CUDA stream used for kernel launches.

property stream_group: str

Stream group label assigned by the memory manager.

property summaries_legend: Dict[int, str]

Labels of the summary output rows, from the build.

property summaries_length: int

Number of complete summary intervals in the integration window.

property summarise_every: float | None

Interval between summary reductions from the loop

property summarised_observable_indices: Any

Indices of summarised observable variables.

property summarised_state_indices: Any

Indices of summarised state variables.

property summary_legend_per_variable: Any

Legend entries describing each summarised variable.

property summary_unit_modifications: Any

Unit modifications for each summarised variable.

synchronize() → None

Wait for this kernel’s last run stream.

property system: BaseODE

Underlying ODE system handled by the kernel.

property system_config_stale: bool

True when the system changed outside the update chain.

property system_sizes: Any

Structured size metadata for the system.

property t0: float

Configured initial integration time.

property threads_per_loop: int

CUDA threads consumed by each run in the loop.

property time_domain_legend: Dict[int, str]

Labels of the time-domain output rows, from the build.

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

Update solver configuration parameters.

Parameters:

• updates_dict – Mapping of parameter updates forwarded to the single integrator and compile settings.

• silent – Flag suppressing errors when unrecognised parameters remain.

• **kwargs – Additional parameter overrides merged into updates_dict.

Returns:

Names of parameters successfully applied.

Return type:

set[str]

Raises:

KeyError – Raised when unknown parameters persist and silent is False.

Notes

Order: memory manager, interpolator, run, then this kernel’s settings with the run’s loop_fn and compile flags.

wait_for_writeback(timeout: float | None = None) → None

Wait for pending staging-buffer work.

property warmup: float

Configured warmup duration.