Optional Arguments Reference

CuBIE uses a cascading configuration system where optional parameters flow through to underlying components. When you call solver.solve() or create integration components directly, you can customize behaviour by passing optional keyword arguments.

How Optional Arguments Work

When you pass an optional argument, it flows down through the configuration hierarchy:

1. Algorithm level: Parameters like preconditioner_order control how implicit algorithms solve their internal equations.

2. Controller level: Parameters like atol and rtol control how the step size adapts to maintain accuracy.

3. Loop level: Parameters like dt_save control output timing.

4. Output level: Parameters like output_types control what data is saved.

Any parameter you don’t specify uses a sensible default from the component’s configuration class. Passing None for any optional parameter means “use the default” — it does not set the parameter to None.

Algorithm Options

Algorithm parameters control how integration steps are computed. Implicit algorithms (Backwards Euler, DIRK, FIRK, Rosenbrock-W, Crank-Nicolson) use internal solvers that have their own tuning parameters.

Implicit Solver Parameters

These parameters control the Newton-Krylov solver used by implicit methods. The solver works in two layers: an outer Newton loop that handles nonlinearity, and an inner Krylov loop that solves the linear system at each Newton step.

newton_atol

The absolute tolerance for the Newton solver convergence check. Together with newton_rtol, this defines when the Newton loop exits. The scaled norm of the residual must fall below 1 (where the norm uses these tolerances for scaling) for convergence. Use tighter tolerances for more accurate implicit solves.

• Default: 1e-6

• Type: float or ndarray (must be positive)

newton_rtol

The relative tolerance for the Newton solver convergence check. Works together with newton_atol to scale the residual norm. The relative tolerance scales based on the magnitude of the current solution.

• Default: 1e-6

• Type: float or ndarray (must be positive)

max_newton_iters

Maximum number of Newton iterations before the solver gives up. If the Newton loop hasn’t converged after this many iterations, the step is marked as failed. Increase this if you have a very stiff system that converges slowly but eventually succeeds.

• Default: 100

• Type: int (1 to 32767)

newton_damping

The fraction by which the step is shrunk during backtracking. When a Newton step doesn’t reduce the residual, the solver backtracks by multiplying the step by this factor and trying again. Values closer to 1.0 try smaller corrections first, while values closer to 0 make more aggressive corrections.

• Default: 0.5

• Type: float (0 to 1)

newton_max_backtracks

Maximum number of backtracking attempts per Newton step. If the solver cannot find a step that reduces the residual after this many attempts, it accepts the current step anyway and continues. Increase this for systems where finding good descent directions is difficult.

• Default: 8

• Type: int (1 to 32767)

krylov_atol

The absolute tolerance for the linear solver convergence check. Together with krylov_rtol, this defines when the Krylov loop exits. The inner Krylov loop solves a linear system at each Newton step and exits when the scaled residual norm falls below 1.

• Default: 1e-6

• Type: float or ndarray (must be positive)

krylov_rtol

The relative tolerance for the linear solver convergence check. Works together with krylov_atol to scale the residual norm.

• Default: 1e-6

• Type: float or ndarray (must be positive)

max_linear_iters

Maximum number of linear solver iterations per Newton step. If the Krylov loop hasn’t converged after this many iterations, it returns with its current best estimate. Increase for ill-conditioned systems.

• Default: 100

• Type: int (1 to 32767)

linear_correction_type

The line search strategy used within the linear solver. Choose between:

• "steepest_descent": Moves in the direction of steepest decrease. Robust but can be slow for ill-conditioned problems.

• "minimal_residual": Minimises the residual along the search direction. Often converges faster but may be less stable.

• Default: "minimal_residual"

• Type: str

preconditioner_order

Order of the truncated Neumann series preconditioner. Higher orders give better preconditioning (faster convergence) but cost more per iteration. For most problems, order 1-3 works well.

• Default: 1

• Type: int (1 to 32)

Implicit Algorithm Applicability

Parameter	Backwards Euler	Crank-Nicolson	DIRK	FIRK	Rosenbrock-W
newton_atol	✓	✓	✓	✓	✗
newton_rtol	✓	✓	✓	✓	✗
max_newton_iters	✓	✓	✓	✓	✗
newton_damping	✓	✓	✓	✓	✗
newton_max_backtracks	✓	✓	✓	✓	✗
krylov_atol	✓	✓	✓	✓	✓
krylov_rtol	✓	✓	✓	✓	✓
max_linear_iters	✓	✓	✓	✓	✓
linear_correction_type	✓	✓	✓	✓	✓
preconditioner_order	✓	✓	✓	✓	✓

Tableau Selection

Multi-stage algorithms (ERK, DIRK, FIRK, Rosenbrock-W) use Butcher tableaus that define the coefficients for each stage. CuBIE provides several built-in tableaus, and you can also define custom ones.

tableau

The Butcher tableau defining the Runge-Kutta method. Different tableaus offer different trade-offs between accuracy, stability, and computational cost. Tableaus with embedded error estimates enable adaptive stepping; tableaus without them require fixed stepping.

• ERK defaults: DOPRI54 (Dormand-Prince 5(4), adaptive)

• DIRK defaults: ESDIRK32 (3rd order, adaptive)

• FIRK defaults: RadauIIA (5th order, stiff problems)

• Rosenbrock-W defaults: ROS34PW2 (4th order, stiff problems)

Controller Options

Step controllers determine how the integration proceeds: whether to accept or reject a step, and how to adjust the step size for the next attempt. CuBIE provides several controllers for different use cases.

Common Adaptive Parameters

These parameters apply to all adaptive step controllers (I, PI, PID, Gustafsson).

atol

Absolute tolerance for error control. The error at each step is compared against atol + rtol * |state|. Absolute tolerance dominates when state values are small. Can be a scalar (same for all variables) or an array (one per state variable).

• Default: 1e-6

• Type: float or array of float

rtol

Relative tolerance for error control. Scales with the magnitude of the state, so larger values have proportionally larger acceptable errors. Can be a scalar or array.

• Default: 1e-6

• Type: float or array of float

dt_min

Minimum allowable step size. The controller will not shrink the step below this limit. If the error is still too large at the minimum step, the integration will continue but flag this condition.

• Default: 1e-6

• Type: float (must be positive)

dt_max

Maximum allowable step size. The controller will not grow the step beyond this limit, even if the error estimate suggests a larger step would be acceptable. Set this to prevent jumping over important dynamics.

• Default: dt_min * 100 (if not specified)

• Type: float (must be greater than dt_min)

algorithm_order

Order of the integration algorithm, used to calculate optimal step size adjustment. Usually determined automatically from the algorithm, but can be overridden if needed.

• Default: determined by algorithm

• Type: int (must be at least 1)

min_gain

Minimum factor by which the step size can shrink in one adjustment. Prevents overly aggressive step reduction. A value of 0.3 means the step can shrink to at most 30% of its previous size.

• Default: 0.3

• Type: float (0 to 1)

max_gain

Maximum factor by which the step size can grow in one adjustment. Prevents overly aggressive step growth. A value of 2.0 means the step can at most double.

• Default: 2.0

• Type: float (must be at least 1)

safety

Safety factor applied to step size predictions. A value less than 1.0 makes the controller more conservative, preferring smaller steps than the error estimate suggests. Helps prevent rejected steps due to optimistic predictions.

• Default: 0.9

• Type: float (0 to 1)

deadband_min / deadband_max

Range within which step size changes are suppressed. If the calculated gain falls between deadband_min and deadband_max, the step size is left unchanged. This prevents small oscillations in step size when the error is near the tolerance. Set both to 1.0 to disable the deadband.

• Default: deadband_min=1.0, deadband_max=1.2

• Type: float

PI Controller Parameters

The PI (proportional-integral) controller uses both current and previous error estimates to calculate step size adjustments.

kp

Proportional gain coefficient. Controls how strongly the current error estimate affects the step size. Higher values react more aggressively to the current error.

• Default: 1/18

• Type: float

ki

Integral gain coefficient. Controls how strongly the accumulated error history affects the step size. Higher values provide more smoothing but slower response.

• Default: 1/9

• Type: float

PID Controller Parameters

The PID controller adds a derivative term to the PI controller for faster response to rapidly changing errors.

kp

Proportional gain coefficient (same as PI controller).

• Default: 1/18

• Type: float

ki

Integral gain coefficient (same as PI controller).

• Default: 1/9

• Type: float

kd

Derivative gain coefficient. Controls how the rate of change of error affects step size. Helps anticipate changes but can amplify noise.

• Default: 0.0 (derivative term disabled)

• Type: float

Gustafsson Controller Parameters

The Gustafsson controller is designed for implicit methods, incorporating information about Newton iteration convergence.

gamma

Damping factor applied to the gain calculation. Lower values produce more conservative step size changes.

• Default: 0.9

• Type: float (0 to 1)

max_newton_iters

Expected maximum Newton iterations, used to scale the step size prediction. Should match or slightly exceed your actual Newton iteration limit.

• Default: 20

• Type: int

Fixed Step Controller

The fixed step controller maintains a constant step size throughout integration.

dt

The fixed step size to use. Required parameter for fixed stepping.

• No default (must be specified)

• Type: float (must be positive)

Controller Applicability

Parameter	Fixed	I	PI	PID	Gustafsson
dt	✓	✗	✗	✗	✗
atol	✗	✓	✓	✓	✓
rtol	✗	✓	✓	✓	✓
dt_min	✗	✓	✓	✓	✓
dt_max	✗	✓	✓	✓	✓
min_gain	✗	✓	✓	✓	✓
max_gain	✗	✓	✓	✓	✓
safety	✗	✓	✓	✓	✓
deadband_min/max	✗	✓	✓	✓	✓
kp	✗	✗	✓	✓	✗
ki	✗	✗	✓	✓	✗
kd	✗	✗	✗	✓	✗
gamma	✗	✗	✗	✗	✓
max_newton_iters (ctrl)	✗	✗	✗	✗	✓

Loop Options

Loop parameters control the overall integration process, including timing, initial conditions, and output cadence.

Timing Parameters

dt0

Initial step size at the start of integration. For adaptive controllers, this is used only for the first step; subsequent steps are determined by the controller. For fixed stepping, this is ignored (dt is used).

• Default: computed as sqrt(dt_min * dt_max) for adaptive

• Type: float (must be positive)

dt_save

Time interval between saved output samples. Determines how often state and observable values are recorded to the output arrays. Smaller values give higher resolution output but require more memory.

• Default: 0.1

• Type: float (must be positive)

dt_summarise

Time interval between summary statistic calculations. Summary metrics (mean, max, RMS, etc.) are accumulated over this interval before being written to output. Should be at least as large as dt_save.

• Default: 1.0

• Type: float (must be positive)

Output Options

Output parameters control what data is saved during integration.

Output Type Selection

output_types

List of output types to save. Valid options include:

• "state": Save state variable time series

• "observables": Save observable time series

• "time": Save time stamps for each output sample

• "iteration_counters": Save Newton and Krylov iteration counts

Summary metrics can also be specified:

• "mean": Arithmetic mean over summary interval

• "max": Maximum value over summary interval

• "min": Minimum value over summary interval

• "rms": Root-mean-square over summary interval

• "std": Standard deviation over summary interval

• "var": Variance over summary interval

• Default: ["state"]

• Type: list of str

Index Selection

saved_state_indices

Indices of state variables to include in time-domain output. Use this to save only the variables you need, reducing memory requirements. If not specified, all state variables are saved.

• Default: all states

• Type: list or array of int

saved_observable_indices

Indices of observable variables to include in time-domain output.

• Default: all observables

• Type: list or array of int

summarised_state_indices

Indices of state variables to include in summary calculations. Defaults to the same as saved_state_indices if not specified.

• Default: same as saved indices

• Type: list or array of int

summarised_observable_indices

Indices of observable variables to include in summary calculations.

• Default: same as saved indices

• Type: list or array of int

Memory Location Options

Advanced users can control where intermediate buffers are allocated in GPU memory. These options affect performance but not correctness.

Buffer location parameters (e.g., state_location, preconditioned_vec_location, etc.)

Control whether a buffer is allocated in local memory ("local") or shared memory ("shared"). Local memory is private to each thread and larger; shared memory is faster but limited and shared across a thread block. The defaults are tuned for typical use cases.

• Default: "local" for most buffers

• Type: str ("local" or "shared")

These parameters are primarily useful for performance tuning on specific GPU architectures and can generally be left at their defaults.