Algorithms

cubie.integrators.algorithms

Factories in cubie.integrators.algorithms assemble explicit and implicit step implementations that plug into the CUDA-based integrator loop. Explicit steps wrap direct right-hand-side evaluations, while implicit steps couple user-supplied device callbacks with matrix-free Newton–Krylov helpers to satisfy nonlinear solves. Precision handling is central: every factory propagates the configured precision through compiled device helpers and the shared linear and nonlinear solver stack.

Default settings

Each algorithm ships with a default scheme and a default step controller. Requesting an algorithm by family name (algorithm="erk") uses the defaults below; requesting a specific tableau alias (algorithm="radau") selects that scheme within the same family.

Name	Default scheme	Order	Default step control
euler	Forward Euler (explicit, single stage)	1	Fixed step
backwards_euler	Backward Euler (implicit, single stage)	1	Fixed step
backwards_euler_pc	Backward Euler with a forward-Euler predictor	1	Fixed step
crank_nicolson	Crank–Nicolson with an embedded backward-Euler error estimate	2	Gustafsson predictive: step-ratio clamp 0.2–8.0
erk	dormand-prince-54 (explicit, seven stages)	5(4)	Integral: integral_gain=1.2, step-ratio clamp 0.2–10.0
dirk	l_stable_dirk_3 (diagonally implicit, three stages)	3	Fixed step — the default tableau has no error estimate
firk	firk_gauss_legendre_2 (fully implicit, two coupled stages)	4	Fixed step — the default tableau has no error estimate
rosenbrock	ros3p (linearly implicit, three stages)	3	Gustafsson predictive: step-ratio clamp 0.2–8.0

How the step controller is chosen

Adaptive step control needs an embedded error estimate. When an algorithm or tableau is named without setting step_controller, CuBIE selects the family’s tuned controller if the scheme provides an estimate — an integral controller for explicit Runge–Kutta, the Gustafsson predictive controller for the implicit families — and a fixed-step controller if it does not. This is why dirk and firk run fixed-step out of the box: their default tableaus carry no embedded estimate. Aliases that do (radau, for example) enable the family’s adaptive defaults automatically. Explicitly pairing an adaptive controller with an estimate-free scheme falls back to fixed stepping with a UserWarning. Gains or filter_coefficients passed without a step_controller select the smallest of i/pi/pid that carries every nonzero gain given.

No family enables a step-freeze deadband by default; pass deadband_min/deadband_max to hold dt for gains inside a band. Every value can be overridden per solve — see Configuration Reference for how kwargs reach the controller and Solver Options Reference for the full parameter list.

Implicit solver defaults

Implicit algorithms (backwards_euler, backwards_euler_pc, crank_nicolson, dirk, firk) solve their stage equations with a matrix-free Newton–Krylov iteration. rosenbrock is linearly implicit: it performs one linear solve per stage, so only the Krylov and preconditioner settings below apply to it and the newton_* parameters do not.

Parameter	Default
newton_atol / newton_rtol	1e-6
newton_max_iters	8
krylov_atol / krylov_rtol	1e-6
krylov_max_iters	ceil(1.5 * solver width)
linear_correction_type	"lu" for dirk, firk, and rosenbrock; "minimal_residual" otherwise
inexact_newton / prefactored	both True for dirk and firk (frozen step-start LU factors); dropped when linear_correction_type is set explicitly
preconditioner_type	"jacobi"
preconditioner_order	the type’s default: 2 for "neumann", 0 for "jacobi"

Base infrastructure

• BaseStepConfig – attrs configuration shared by explicit and implicit steps.

• BaseAlgorithmStep – base class that wires precision and CUDA compilation helpers.

• StepCache – container storing compiled kernels and loop scratch buffers.

Explicit steps

• ExplicitStepConfig – configuration for explicit step factories.

• ExplicitEulerStep – Euler step that invokes the RHS device function.

• ERKStep – multistage explicit Runge–Kutta step with adaptive control defaults.

• ERK tableau registry – named explicit Runge–Kutta tableaus and references.

Implicit steps

• ImplicitStepConfig – configuration for implicit step factories.

• BackwardsEulerStep – backward Euler implicit algorithm.

• BackwardsEulerPCStep – predictor-corrector backward Euler variant.

• CrankNicolsonStep – Crank–Nicolson implicit algorithm.

• DIRKStep – diagonally implicit Runge–Kutta family with embedded error estimates.

• DIRK tableau registry – named diagonally implicit Runge–Kutta tableaus and references.

• FIRKStep – fully implicit Runge–Kutta family (Gauss–Legendre, Radau IIA).

• FIRK tableau registry – named fully implicit Runge–Kutta tableaus and references.

• GenericRosenbrockWStep – linearly implicit Rosenbrock-W methods.

• Rosenbrock tableau registry – named Rosenbrock-W tableaus and references.

Factory helpers

• get_algorithm_step – resolves step factories by enum or name.

Dependencies

Implicit steps depend on cubie.integrators.matrix_free_solvers for the linear and Newton–Krylov factories and reuse cubie.CUDAFactory utilities for JIT compilation and caching. All algorithms expect caller supplied device callbacks for time derivatives, operator assembly, and observable evaluation, operating on preallocated device buffers whose precision matches the configured integration precision.