cubie.integrators.SingleIntegratorRun

Single integrator run coordination for CUDA-based ODE solving.

This module provides the SingleIntegratorRun class which coordinates the low-level CUDA machinery to create device functions for running individual ODE integration runs. It handles dependency injection to integrator loop algorithms and manages light-weight caching to ensure changes in subfunctions are properly communicated.

Classes

SingleIntegratorRun(system[, algorithm, ...])

Coordinates low-level CUDA machinery for single ODE integration runs.
class cubie.integrators.SingleIntegratorRun.SingleIntegratorRun(system, algorithm: str = 'euler', 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_state_indices: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, saved_observable_indices: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, summarised_state_indices: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, summarised_observable_indices: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None, output_types: list[str] = None)[source]

Bases: object

Coordinates low-level CUDA machinery for single ODE integration runs.

This class presents the interface to lower-level CUDA code and performs dependency injection to integrator loop algorithms. It contains light-weight cache management to ensure that changes in one subfunction are communicated to others, but does not inherit from CUDAFactory as it performs a different role than other factory classes.

Parameters:

  • system (GenericODE object) – The ODE system to integrate.

  • algorithm (str, default='euler') – Name of the integration algorithm to use.

  • dt_min (float, default=0.01) – Minimum time step size.

  • dt_max (float, default=0.1) – Maximum time step size.

  • dt_save (float, default=0.1) – Time interval between saved outputs.

  • dt_summarise (float, default=1.0) – Time interval between summary calculations.

  • atol (float, default=1e-6) – Absolute tolerance for integration.

  • rtol (float, default=1e-6) – Relative tolerance for integration.

  • saved_state_indices (ArrayLike, optional) – Indices of states to save during integration.

  • saved_observable_indices (ArrayLike, optional) – Indices of observables to save during integration.

  • summarised_state_indices (ArrayLike, optional) – Indices of states to summarise during integration.

  • summarised_observable_indices (ArrayLike, optional) – Indices of observables to summarise during integration.

  • output_types (list of str or tuple of str, optional) – Types of outputs to generate.

Notes

This class handles modifications that invalidate the currently compiled loop, including:

  • Changes to system constants (compiled-in parameters)

  • Changes to loop outputs (adding/removing output types, summary types)

  • Changes to algorithm parameters (step size, tolerances, algorithm type)

The class maintains a list of currently implemented algorithms accessible through the ImplementedAlgorithms registry. Additional algorithms can be added by subclassing GenericIntegratorAlgorithm.

This class is not typically exposed to users directly - the user-facing API is through the Solver class which handles batching and memory management.

All device functions maintain a local cache of their output functions and compile-sensitive attributes, and will invalidate and rebuild if any of these are updated.

See also

IntegratorRunSettings

Runtime configuration settings

ImplementedAlgorithms

Registry of available integration algorithms

_invalidate_cache()[source]

Invalidate the compiled loop cache.

Marks the current compiled loop as invalid, forcing a rebuild on the next access.

build()[source]

Build the complete integrator loop.

Compiles the integrator loop device function and updates the cache.

Returns:

The compiled loop device function.

Return type:

CUDA device function

property cache_valid

Check if the compiled loop is current.

Returns:

True if the cached loop is valid, False otherwise.

Return type:

bool

property compile_flags

Get the compilation flags for output functions.

Returns:

Compilation flags from the child OutputFunctions object.

Return type:

object

property device_function

Get the compiled loop function, building if necessary.

Returns:

The compiled CUDA device function for the integration loop.

Return type:

CUDA device function

property dt_save

Get the time step size for saving states and observables.

Returns:

Time interval between saved outputs.

Return type:

float

property dt_summarise

Get the time step size for summarising states and observables.

Returns:

Time interval between summary calculations.

Return type:

float

property dxdt_function

Get the derivative function from the system.

Returns:

The dxdt function from the child GenericODE object.

Return type:

callable

property fixed_step_size

Get the fixed step size for integration.

Returns:

Fixed step size from the child GenericIntegratorAlgorithm object.

Return type:

float

property loop_buffer_sizes

Get buffer sizes required for the integration loop.

Returns:

Buffer size configuration for the integration loop.

Return type:

LoopBufferSizes

property loop_step_config

Get the loop step configuration.

Returns:

Step configuration object for the integration loop.

Return type:

LoopStepConfig

property output_array_heights

Get the heights of output arrays.

Returns:

Output array height configuration from the OutputFunctions object.

Return type:

OutputArrayHeights

property output_types

Get the configured output types.

Returns:

List of output types from the child OutputFunctions object.

Return type:

list

property precision

Get the numerical precision type from the system.

Returns:

Numerical precision type (e.g., float32, float64) from the child GenericODE object.

Return type:

type

property save_state_func

Get the state saving function.

Returns:

State saving function from the child OutputFunctions object.

Return type:

callable

property save_summaries_func

Get the summary saving function.

Returns:

Summary saving function from the child OutputFunctions object.

Return type:

callable

property save_time

Get whether time values should be saved.

Returns:

True if time should be saved, from the child OutputFunctions object.

Return type:

bool

property saved_observable_indices

Get indices of observables to save.

Returns:

Indices of observables to save from the child OutputFunctions object.

Return type:

ArrayLike

property saved_state_indices

Get indices of states to save.

Returns:

Indices of states to save from the child OutputFunctions object.

Return type:

ArrayLike

property shared_memory_bytes

Get the number of bytes of dynamic shared memory required.

Returns:

Number of bytes of dynamic shared memory required for a single integrator run.

Return type:

int

property shared_memory_elements

Get the number of shared memory elements required for integration.

Returns:

Number of elements of shared memory required for a single integrator run.

Return type:

int

property summaries_buffer_sizes

Get buffer sizes for summary calculations.

Returns:

Summary buffer size configuration from the OutputFunctions object.

Return type:

SummaryBufferSizes

property summarised_observable_indices

Get indices of observables to summarise.

Returns:

Indices of observables to summarise from the child OutputFunctions object.

Return type:

ArrayLike

property summarised_state_indices

Get indices of states to summarise.

Returns:

Indices of states to summarise from the child OutputFunctions object.

Return type:

ArrayLike

property summary_legend_per_variable

Get the summary legend for each variable.

Returns:

Summary legend mapping from the child OutputFunctions object.

Return type:

object

property system

Get the ODE system object.

Returns:

The child GenericODE system object.

Return type:

object

property system_sizes: SystemSizes

Get the system size information.

Returns:

Size information from the child GenericODE object.

Return type:

SystemSizes

property threads_per_loop

Get the number of threads required by the loop algorithm.

Returns:

Number of threads per loop from the child GenericIntegratorAlgorithm object.

Return type:

int

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

Update parameters across all components.

This method sends all parameters to all child components with silent=True to avoid spurious warnings, then checks if any parameters were not recognized by any component.

Parameters:

  • updates_dict (dict, optional) – Dictionary of parameters to update.

  • silent (bool, default=False) – If True, suppress warnings about unrecognized parameters.

  • **kwargs – Parameter updates to apply as keyword arguments.

Returns:

Set of parameter names that were recognized and updated.

Return type:

set

Raises:

KeyError – If parameters are not recognized by any component and silent=False.

property update_summaries_func

Get the summary update function.

Returns:

Summary update function from the child OutputFunctions object.

Return type:

callable