FIRKStep

FIRKStep provides a fully implicit Runge–Kutta integrator that solves coupled stage systems with the cached Newton–Krylov helpers supplied by cubie.integrators.matrix_free_solvers. The factory consumes FIRKTableau instances, exposing high-order Gauss–Legendre and Radau IIA schemes for stiff problems while preserving adaptive error control through embedded weights.

class cubie.integrators.algorithms.FIRKStep(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], n: int, evaluate_f: Callable | None = None, evaluate_observables: Callable | None = None, evaluate_driver_at_t: Callable | None = None, get_solver_helper_fn: Callable | None = None, tableau: FIRKTableau = FIRKTableau(a=((0.25, -0.038675134594812866), (0.5386751345948129, 0.25)), b=(0.5, 0.5), c=(0.21132486540518713, 0.7886751345948129), order=4, b_hat=None), n_drivers: int = 0, **kwargs)[source]

Bases: ODEImplicitStep

Fully implicit Runge–Kutta step with an embedded error estimate.

__init__(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], n: int, evaluate_f: Callable | None = None, evaluate_observables: Callable | None = None, evaluate_driver_at_t: Callable | None = None, get_solver_helper_fn: Callable | None = None, tableau: FIRKTableau = FIRKTableau(a=((0.25, -0.038675134594812866), (0.5386751345948129, 0.25)), b=(0.5, 0.5), c=(0.21132486540518713, 0.7886751345948129), order=4, b_hat=None), n_drivers: int = 0, **kwargs) → None[source]

Initialise the FIRK step configuration.

This constructor creates a FIRK step object and automatically selects appropriate default step controller settings based on whether the tableau has an embedded error estimate. Tableaus with error estimates default to adaptive stepping (PI controller), while errorless tableaus default to fixed stepping.

Parameters:

  • precision – Floating-point precision for CUDA computations.

  • n – Number of state variables in the ODE system.

  • evaluate_f – Device function for evaluating f(t, y) right-hand side.

  • evaluate_observables – Device function computing system observables.

  • evaluate_driver_at_t – Optional device function evaluating drivers at arbitrary times.

  • get_solver_helper_fn – Factory function returning solver helper for Jacobian operations.

  • tableau – FIRK tableau describing the coefficients. Defaults to DEFAULT_FIRK_TABLEAU.

  • n_drivers – Number of driver variables in the system.

  • **kwargs – Optional parameters passed to config classes. See FIRKStepConfig, ImplicitStepConfig, and solver config classes for available parameters. None values are ignored.

Notes

The step controller defaults are selected dynamically:

  • If tableau.has_error_estimate is True: Uses FIRK_ADAPTIVE_DEFAULTS (PI controller)

  • If tableau.has_error_estimate is False: Uses FIRK_FIXED_DEFAULTS (fixed-step controller)

This automatic selection prevents incompatible configurations where an adaptive controller is paired with an errorless tableau.

FIRK methods require solving a coupled system of all stages simultaneously, which is more computationally expensive than DIRK methods but can achieve higher orders of accuracy for stiff systems.

build_implicit_helpers() → None[source]

Construct the nonlinear solver chain used by implicit methods.

build_step(evaluate_f: Callable, evaluate_observables: Callable, evaluate_driver_at_t: Callable | None, solver_function: Callable, numba_precision: type, n: int, n_drivers: int) → StepCache[source]

Compile the FIRK device step.

property is_adaptive: bool

Return True when the tableau supplies an error estimate.

property is_implicit: bool

Return True because the method solves nonlinear systems.

property is_multistage: bool

Return True as the method has multiple stages.

property order: int

Return the classical order of accuracy.

register_buffers() → None[source]

Register buffers according to locations in compile settings.

property stage_count: int

Return the number of stages described by the tableau.

property threads_per_step: int

Return the number of CUDA threads that advance one state.

class cubie.integrators.algorithms.generic_firk.FIRKStepConfig(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], n: int = 1, n_drivers: int = 0, evaluate_f: Callable | None = None, evaluate_observables: Callable | None = None, evaluate_driver_at_t: Callable | None = None, get_solver_helper_fn: Callable | None = None, beta: float = 1.0, gamma: float = 1.0, M: ndarray | MutableDenseMatrix = Matrix([[1]]), preconditioner_order: int = 2, solver_function=None, tableau: FIRKTableau = FIRKTableau(a=((0.25, -0.038675134594812866), (0.5386751345948129, 0.25)), b=(0.5, 0.5), c=(0.21132486540518713, 0.7886751345948129), order=4, b_hat=None), stage_increment_location: str = 'local', stage_driver_stack_location: str = 'local', stage_state_location: str = 'local')[source]

Bases: ImplicitStepConfig

Configuration describing the FIRK integrator.

property all_stages_n: int

Return the flattened dimension covering all stage increments.

property stage_count: int

Return the number of stages described by the tableau.

stage_driver_stack_location: str
stage_increment_location: str
stage_state_location: str
tableau: FIRKTableau