cubie.integrators.algorithms

Integration algorithm implementations and registry.

This module provides concrete implementations of numerical integration algorithms for CUDA-based ODE solving, along with a registry system for accessing available algorithms. It includes the base algorithm framework and specific implementations like the Euler method.

class cubie.integrators.algorithms.Euler(precision, dxdt_function, buffer_sizes, loop_step_config, save_state_func, update_summaries_func, save_summaries_func, compile_flags=None, **kwargs)

Bases: GenericIntegratorAlgorithm

Euler integrator algorithm for fixed-step integration.

This class implements the simple, first-order Euler method for updating the state of dynamical systems. It uses a fixed time step and is suitable for systems where the dynamics are not too stiff and where high accuracy is not required.

Parameters:

• precision (type) – Numerical precision type (float32, float64, etc.).

• dxdt_function (callable) – Function that computes the time derivative of the state.

• buffer_sizes (object) – Configuration object specifying buffer sizes for integration.

• loop_step_config (object) – Configuration object for loop step parameters.

• save_state_func (callable) – Function for saving state values during integration.

• update_summaries_func (callable) – Function for updating summary statistics.

• save_summaries_func (callable) – Function for saving summary statistics.

• compile_flags (object, optional) – Compilation flags for CUDA device function generation.

• **kwargs – Additional keyword arguments passed to parent class.

Notes

The Euler method approximates the solution to the differential equation dy/dt = f(t, y) using the update rule:

y_{n+1} = y_n + h * f(t_n, y_n)

where h is the step size. This is a first-order method with local truncation error O(h²) and global error O(h).

See also

GenericIntegratorAlgorithm

Base class for integration algorithms

build_loop(precision, dxdt_function, save_state_func, update_summaries_func, save_summaries_func)

Build the CUDA device function for the Euler integration loop.

This method constructs a numba-compiled CUDA device function that implements the Euler integration algorithm with output handling.

Parameters:

• precision (type) – Numerical precision type for the integration.

• dxdt_function (callable) – Function that computes time derivatives.

• save_state_func (callable) – Function for saving state values.

• update_summaries_func (callable) – Function for updating summary statistics.

• save_summaries_func (callable) – Function for saving summary statistics.

Returns:

Compiled CUDA device function for Euler integration.

Return type:

callable

Notes

The generated function handles memory allocation, state initialization, the main integration loop, and output generation according to the configured step sizes and buffer requirements.

property shared_memory_required

Calculate the number of shared memory elements required for the loop.

Returns:

Number of elements in shared memory required for state, derivatives, observables, drivers, and summary buffers. Does not include summary arrays as they are handled outside the loop and are common to all algorithms.

Return type:

int

class cubie.integrators.algorithms.GenericIntegratorAlgorithm(precision, dxdt_function, buffer_sizes, loop_step_config, save_state_func, update_summaries_func, save_summaries_func, compile_flags)

Bases: CUDAFactory

Base class for the inner “loop” algorithm for ODE solving algorithms.

This class handles building and caching of the algorithm function, which is incorporated into a CUDA kernel for GPU execution. All integration algorithms (e.g. Euler, Runge-Kutta) should subclass this class and override specific attributes and methods.

Parameters:

• precision (type) – Numerical precision type for computations.

• dxdt_function (CUDA device function) – Function that computes time derivatives of the state.

• buffer_sizes (LoopBufferSizes) – Configuration object specifying buffer sizes.

• loop_step_config (LoopStepConfig) – Configuration object for loop step parameters.

• save_state_func (CUDA device function) – Function for saving state values during integration.

• update_summaries_func (CUDA device function) – Function for updating summary statistics.

• save_summaries_func (CUDA device function) – Function for saving summary statistics.

• compile_flags (OutputCompileFlags) – Compilation flags for device function generation.

Notes

Subclasses must override:

• _threads_per_loop : Number of threads the algorithm uses

• build_loop() : Factory method that builds the CUDA device function

• shared_memory_required : Amount of shared memory the device allocates

Data used in compiling and controlling the loop is handled by the IntegratorLoopSettings class. This class presents relevant attributes of the data class to higher-level components as properties.

See also

IntegratorLoopSettings

Configuration data for loop compilation

CUDAFactory

Base factory class for CUDA device functions

build()

Build the integrator loop, unpacking config for local scope.

Returns:

The compiled integrator loop device function.

Return type:

callable

build_loop(precision, dxdt_function, save_state_func, update_summaries_func, save_summaries_func)

Build the CUDA device function for the integration loop.

This is a template method that provides a dummy implementation. Subclasses should override this method to implement specific integration algorithms.

Parameters:

• precision (type) – Numerical precision type for the integration.

• dxdt_function (callable) – Function that computes time derivatives.

• save_state_func (callable) – Function for saving state values.

• update_summaries_func (callable) – Function for updating summary statistics.

• save_summaries_func (callable) – Function for saving summary statistics.

Returns:

Compiled CUDA device function implementing the integration algorithm.

Return type:

callable

Notes

This base implementation provides a dummy loop that can be used for testing but does not perform actual integration. Real algorithms should override this method with their specific implementation.

property fixed_step_size

Get the fixed step size used in the integration loop.

Returns:

The fixed step size from the compile settings.

Return type:

float

classmethod from_single_integrator_run(run_object)

Create an instance of the integrator algorithm from a SingleIntegratorRun object.

Parameters:

run_object (SingleIntegratorRun) – The SingleIntegratorRun object containing configuration parameters.

Returns:

New instance of the integrator algorithm configured with parameters from the run object.

Return type:

GenericIntegratorAlgorithm

property shared_memory_required

Calculate shared memory requirements for the integration algorithm.

This is a dummy implementation that returns 0. Subclasses should override this method to calculate the actual shared memory requirements based on their specific algorithm needs.

Returns:

Number of shared memory elements required (dummy implementation returns 0).

Return type:

int

property threads_per_loop

Get the number of threads required by loop algorithm.

Returns:

Number of threads required per integration loop.

Return type:

int

update(updates_dict=None, silent=False, **kwargs)

Pass updates to compile settings through the CUDAFactory interface.

This method will invalidate the cache if an update is successful. Use silent=True when doing bulk updates with other component parameters to suppress warnings about unrecognized keys.

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

class cubie.integrators.algorithms._ImplementedAlgorithms

Bases: object

Container for implemented integrator algorithms.

This class provides a registry of available integration algorithms that can be accessed by name. It supports both attribute and dictionary-style access to algorithms.

euler

Euler integration algorithm implementation.

Type:

Euler

generic

Base generic integration algorithm class.

Type:

GenericIntegratorAlgorithm

euler

alias of Euler

generic

alias of GenericIntegratorAlgorithm

Modules

IntegratorLoopSettings	Integrator configuration management with validation and adapter patterns.
LoopStepConfig	Loop step configuration for integrator timing and tolerances.
euler	Euler method implementation for numerical integration.
genericIntegratorAlgorithm	Base class for integration algorithm implementations.