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.

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.

_auto_defaults(settings: Dict[str, Any]) → Dict[str, Any]

Apply and return the built step’s values for the placement and unroll keys settings leaves None.

_compile_specialization(args: Tuple | None = None) → Callable

Compile the selected specialization and return the kernel.

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

Return the geometry holding resident blocks per SM.

_configured_launch(blocks: int, threads: Tuple[int, int], stream: Any, dynamic_sharedmem: int) → Callable

Return the kernel configured for one launch geometry.

Parameters:

• blocks – Blocks in the grid.

• threads – Threads per run and runs per block.

• stream – Stream to launch on.

• dynamic_sharedmem – Dynamic shared memory per block, in bytes.

Returns:

The configured launch; call it with the kernel arguments.

Return type:

Callable

_default_launch(runs: int | None) → 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, signature: Tuple | None = None) → 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

_kernel_launch_args(chunk_run_params: RunParams) → Tuple

Return the kernel’s positional arguments for one chunk.

_launch_shape(blocksize: int, runs: int | None) → 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, transfer_outputs: bool = True) → 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. The kernel keeps them between runs and rebuilds them when the chunk count or logger verbosity changes.

_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

_specialization_args() → Tuple

Return arguments for kernel compilation.

_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.

_update(updates: Dict[str, Any], silent: bool) → Set[str]

Update the memory manager, interpolator, run and kernel.

Parameters:

• updates – Setting names to new values; gains the derived driver settings after an interpolator change.

• silent – Whether update() ignores unrecognised names.

Returns:

Names the memory manager, interpolator, run and kernel settings recognised.

Return type:

set[str]

Notes

The kernel settings take the run’s loop_fn and output compile flags last.

_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() → None

Compile the kernel; RuntimeError once closed.

property compile_flags: OutputCompileFlags

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

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.

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, runs: 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.

• runs – Runs in the launch; None sizes a full block.

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.

Parameters:

• blocksizes – Block sizes to consider.

• runs – Runs in the launch; None sizes a full block.

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 – Runs the launch places in one block.

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

Length of the drivers buffer the system reads.

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.

performance_defaults() → Dict[str, Any]

Return the placements and unroll flags the built step picks.

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 leaves results in the device output buffers and touches no host output buffer; 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_dir', 'cache_enabled', '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 signature: Tuple

Signature used for launch sizing and resource queries.

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.

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

Wait for pending staging-buffer work.

property warmup: float

Configured warmup duration.