cubie.outputhandling.output_sizes

Array sizing classes for output buffer and array management.

This module provides classes for calculating and managing the sizes of various arrays used in CUDA batch solving, including buffers for intermediate calculations and output arrays for results. All classes inherit from ArraySizingClass which provides utilities for memory allocation.

Classes

ArraySizingClass()	Base class for array sizing with memory allocation utilities.
BatchInputSizes([initial_values, ...])	Input array sizes for batch integration runs.
BatchOutputSizes([state, observables, ...])	Output array sizes for batch integration runs.
LoopBufferSizes([state_summaries, ...])	Buffer sizes for integrator inner loop calculations.
OutputArrayHeights([state, observables, ...])	Heights of output arrays for different variable types.
SingleRunOutputSizes([state, observables, ...])	Output array sizes for a single integration run.
SummariesBufferSizes([state, observables, ...])	Buffer sizes for summary metric calculations.

class cubie.outputhandling.output_sizes.ArraySizingClass

Bases: ABC

Base class for array sizing with memory allocation utilities.

This abstract base class provides common functionality for all array sizing classes, including a method to ensure minimum array sizes for memory allocation purposes.

Notes

All derived classes inherit the nonzero property which is useful for allocating memory where zero-sized arrays would cause issues.

property nonzero: ArraySizingClass

Return a copy with all sizes having a minimum of one element.

Returns:

Copy of the object with all integer and tuple sizes ensured to be at least 1, useful for memory allocation.

Return type:

ArraySizingClass

Notes

This method creates a new object instance with modified size values to prevent zero-sized array allocations which can cause issues in CUDA memory management.

class cubie.outputhandling.output_sizes.BatchInputSizes(initial_values: Tuple[int, int] = (1, 1), parameters: Tuple[int, int] = (1, 1), forcing_vectors: Tuple[int, int | None] = (1, None), stride_order: Tuple[str, ...] = ('run', 'variable'))

Bases: ArraySizingClass

Input array sizes for batch integration runs.

This class specifies the sizes of input arrays needed for batch processing, including initial conditions, parameters, and forcing terms.

initial_values

Shape of initial values array as (n_runs, n_states).

Type:

tuple[int, int], default (1, 1)

parameters

Shape of parameters array as (n_runs, n_parameters).

Type:

tuple[int, int], default (1, 1)

forcing_vectors

Shape of forcing vectors array as (n_drivers, time_steps).

Type:

tuple[int, int or None], default (1, None)

stride_order

Order of dimensions in the input arrays.

Type:

tuple[str, …], default (“run”, “variable”)

forcing_vectors: Tuple[int, int | None]

classmethod from_solver(solver_instance: BatchSolverKernel) → BatchInputSizes

Create input array sizes from a BatchSolverKernel object.

Parameters:

solver_instance (BatchSolverKernel) – Solver instance containing batch and system configuration.

Returns:

Input array sizes for the batch run.

Return type:

BatchInputSizes

initial_values: Tuple[int, int]

parameters: Tuple[int, int]

stride_order: Tuple[str, ...]

class cubie.outputhandling.output_sizes.BatchOutputSizes(state: Tuple[int, int, int] = (1, 1, 1), observables: Tuple[int, int, int] = (1, 1, 1), state_summaries: Tuple[int, int, int] = (1, 1, 1), observable_summaries: Tuple[int, int, int] = (1, 1, 1), stride_order: Tuple[str, ...] = ('time', 'run', 'variable'))

Bases: ArraySizingClass

Output array sizes for batch integration runs.

This class provides 3D array sizes (time × run × variable) for output arrays from batch integration runs.

state

Shape of state output array as (time_samples, n_runs,

n_variables).

Type:

tuple[int, int, int], default (1, 1, 1)

observables

Shape of observable output array as (time_samples, n_runs, n_variables).

Type:

tuple[int, int, int], default (1, 1, 1)

state_summaries

Shape of state summary array as (summary_samples, n_runs, n_summaries).

Type:

tuple[int, int, int], default (1, 1, 1)

observable_summaries

Shape of observable summary array as (summary_samples, n_runs, n_summaries).

Type:

tuple[int, int, int], default (1, 1, 1)

stride_order

Order of dimensions in the output arrays.

Type:

tuple[str, …], default (“time”, “run”, “variable”)

classmethod from_solver(solver_instance: BatchSolverKernel) → BatchOutputSizes

Create batch output sizes from a BatchSolverKernel object.

Parameters:

solver_instance (BatchSolverKernel) – Solver instance containing batch and output configuration.

Returns:

Output array sizes for the batch run.

Return type:

BatchOutputSizes

Notes

Constructs 3D array sizes by combining single run sizes with the number of runs in the batch.

observable_summaries: Tuple[int, int, int]

observables: Tuple[int, int, int]

state: Tuple[int, int, int]

state_summaries: Tuple[int, int, int]

stride_order: Tuple[str, ...]

class cubie.outputhandling.output_sizes.LoopBufferSizes(state_summaries: int | None = 1, observable_summaries: int | None = 1, state: int | None = 1, observables: int | None = 1, dxdt: int | None = 1, parameters: int | None = 1, drivers: int | None = 1)

Bases: ArraySizingClass

Buffer sizes for integrator inner loop calculations.

This class holds the sizes of all buffers used in the main integration loop, including system state buffers and summary calculation buffers.

state_summaries

Buffer size for state summary calculations.

Type:

int, default 1

observable_summaries

Buffer size for observable summary calculations.

Type:

int, default 1

state

Buffer size for current state values.

Type:

int, default 1

observables

Buffer size for current observable values.

Type:

int, default 1

dxdt

Buffer size for state derivatives.

Type:

int, default 1

parameters

Buffer size for system parameters.

Type:

int, default 1

drivers

Buffer size for external driving forces.

Type:

int, default 1

Notes

Combines system-based buffer sizes (state, dxdt, parameters) with output-derived buffer sizes (summaries) to provide a complete view of memory requirements for the integration loop.

drivers: int | None

dxdt: int | None

classmethod from_solver(solver_instance: BatchSolverKernel) → LoopBufferSizes

Create buffer sizes from a BatchSolverKernel object.

Parameters:

solver_instance (BatchSolverKernel) – Solver instance containing system and output configuration.

Returns:

Buffer sizes extracted from the solver configuration.

Return type:

LoopBufferSizes

classmethod from_system_and_output_fns(system: GenericODE, output_fns: OutputFunctions) → LoopBufferSizes

Create buffer sizes from system and output function objects.

Parameters:

• system (GenericODE) – System model containing state and parameter dimensions.

• output_fns (OutputFunctions) – Output functions containing summary buffer requirements.

Returns:

Combined buffer sizes for the integration loop.

Return type:

LoopBufferSizes

observable_summaries: int | None

observables: int | None

parameters: int | None

state: int | None

state_summaries: int | None

class cubie.outputhandling.output_sizes.OutputArrayHeights(state: int = 1, observables: int = 1, state_summaries: int = 1, observable_summaries: int = 1, per_variable: int = 1)

Bases: ArraySizingClass

Heights of output arrays for different variable types.

This class specifies the height (number of elements) required for output arrays storing results from batch integrations.

state

Height of state variable output arrays.

Type:

int, default 1

observables

Height of observable variable output arrays.

Type:

int, default 1

state_summaries

Height of state summary output arrays.

Type:

int, default 1

observable_summaries

Height of observable summary output arrays.

Type:

int, default 1

per_variable

Height per variable for summary outputs.

Type:

int, default 1

classmethod from_output_fns(output_fns: OutputFunctions) → OutputArrayHeights

Create output array heights from an OutputFunctions object.

Parameters:

output_fns (OutputFunctions) – Output functions object containing configuration information.

Returns:

Array heights calculated from the output configuration.

Return type:

OutputArrayHeights

Notes

The state height includes an extra element if time saving is enabled.

observable_summaries: int

observables: int

per_variable: int

state: int

state_summaries: int

class cubie.outputhandling.output_sizes.SingleRunOutputSizes(state: Tuple[int, int] = (1, 1), observables: Tuple[int, int] = (1, 1), state_summaries: Tuple[int, int] = (1, 1), observable_summaries: Tuple[int, int] = (1, 1), stride_order: Tuple[str, ...] = ('time', 'variable'))

Bases: ArraySizingClass

Output array sizes for a single integration run.

This class provides 2D array sizes (time × variable) for output arrays from a single integration run.

state

Shape of state output array as (time_samples, n_variables).

Type:

tuple[int, int], default (1, 1)

observables

Shape of observable output array as (time_samples, n_variables).

Type:

tuple[int, int], default (1, 1)

state_summaries

Shape of state summary array as (summary_samples, n_summaries).

Type:

tuple[int, int], default (1, 1)

observable_summaries

Shape of observable summary array as (summary_samples, n_summaries).

Type:

tuple[int, int], default (1, 1)

stride_order

Order of dimensions in the arrays.

Type:

tuple[str, …], default (“time”, “variable”)

classmethod from_output_fns_and_run_settings(output_fns, run_settings)

Create output sizes from output functions and run settings.

Parameters:

• output_fns (OutputFunctions) – Output functions containing variable configuration.

• run_settings (IntegratorRunSettings) – Run settings containing timing information.

Returns:

Output array sizes for a single run.

Return type:

SingleRunOutputSizes

Notes

This method is primarily used for testing. In normal operation, the from_solver method is preferred.

classmethod from_solver(solver_instance: BatchSolverKernel) → SingleRunOutputSizes

Create output sizes from a BatchSolverKernel object.

Parameters:

solver_instance (BatchSolverKernel) – Solver instance containing timing and output configuration.

Returns:

Output array sizes for a single run.

Return type:

SingleRunOutputSizes

observable_summaries: Tuple[int, int]

observables: Tuple[int, int]

state: Tuple[int, int]

state_summaries: Tuple[int, int]

stride_order: Tuple[str, ...]

class cubie.outputhandling.output_sizes.SummariesBufferSizes(state: int | None = 1, observables: int | None = 1, per_variable: int | None = 1)

Bases: ArraySizingClass

Buffer sizes for summary metric calculations.

This class provides a clean interface for accessing summary buffer sizes with descriptive names rather than accessing them through more complex object hierarchies.

state

Buffer size required for state variable summaries.

Type:

int, default 1

observables

Buffer size required for observable variable summaries.

Type:

int, default 1

per_variable

Buffer size required per individual variable for summaries.

Type:

int, default 1

Notes

Most commonly used via the from_output_fns class method which extracts the relevant sizes from an OutputFunctions object.

classmethod from_output_fns(output_fns: OutputFunctions) → SummariesBufferSizes

Create buffer sizes from an OutputFunctions object.

Parameters:

output_fns (OutputFunctions) – Output functions object containing buffer size information.

Returns:

Buffer sizes extracted from the output functions configuration.

Return type:

SummariesBufferSizes

observables: int | None

per_variable: int | None

state: int | None