BaseAlgorithmStep

class cubie.integrators.algorithms.base_algorithm_step.BaseAlgorithmStep(config: BaseStepConfig, _defaults: AlgorithmDefaults)

Bases: CUDAFactory

Base class implementing cache and configuration handling for steps.

The class exposes properties and an update helper shared by concrete explicit and implicit algorithms. Concrete subclasses implement build to compile device helpers and provide metadata about resource usage.

__init__(config: BaseStepConfig, _defaults: AlgorithmDefaults) → None

Initialise the algorithm step with its configuration object and its family default settings.

Parameters:

• config – Configuration describing the algorithm step.

• _defaults – Algorithm family (e.g. FIRK or DIRK) default settings for other solver components.

_apply_updates(updates: Dict[str, object]) → Set[str]

Apply the step settings and buffer locations.

Parameters:

updates – Setting names to new values.

Returns:

Names the settings and the buffer registry took.

Return type:

set[str]

Raises:

ValueError – A tableau or n_states other than this step’s.

_update(updates: Dict[str, object], silent: bool) → Set[str]

Apply the updates, then accept other algorithms’ parameters.

Parameters:

• updates – Setting names to new values.

• silent – Suppress the other-algorithm parameter warning.

Returns:

Recognised names, including other algorithms’ parameters.

Return type:

set[str]

Notes

After _apply_updates(), unapplied names in ALL_ALGORITHM_STEP_PARAMETERS count as recognised and warn.

property accumulates_error: bool

Return whether the compiled step sums the error over stages.

property accumulates_output: bool

Whether the tableau accumulates its output over the stages.

property algorithm_defaults: Dict[str, Any]

Return the family defaults overlaid with the tableau’s.

property algorithm_order: int

Return the order of accuracy used for step-size control.

build() → StepCache

Compile the step and record its sizes, order and flags.

Returns:

The compiled step with its products filled in.

Return type:

StepCache

property can_reuse_accepted_start: bool

Return True when the accepted state seeds the next proposal.

Returns False when the algorithm is not tableau-based.

abstractmethod compile_step() → StepCache

Compile the step’s device functions.

Returns:

The compiled step and any nonlinear solver.

Return type:

StepCache

property controller_default_settings: Dict[str, Any]

Return the default settings that apply to the controller.

copy() → BaseAlgorithmStep

Return a new step with these settings and the helper factory.

default_tableau = None

Tableau a bare family alias builds on; None for fixed schemes.

property dxdt_fn: Callable | None

Return the compiled device derivative function.

property error_row: int | None

Return the a row the step captures as its error solution.

property error_weights: ndarray | None

Return the error weights in run precision; zeros when unused.

classmethod family_defaults(tableau: ButcherTableau | None = None) → AlgorithmDefaults

Return the family’s controller and solver defaults.

property first_same_as_last: bool

Return True when the first and last stages align.

Returns False when the algorithm is not tableau-based.

property get_solver_helper_fn: Callable | None

Return the helper factory used to build solver device functions.

Returns:

Callable that yields device helpers for solver construction when available.

Return type:

Callable or None

abstract property has_error_estimate: bool

Return whether the algorithm produces an embedded error estimate.

property is_adaptive: bool

Return whether the step controller is adaptive.

abstract property is_implicit: bool

is_linear = False

Linearly-implicit steps own their linear solver directly.

abstract property is_multistage: bool

property local_elements: int

Elements the step’s buffers would take with every one local.

property n_drivers: int

Return the configured number of external drivers.

property n_error: int

n_states while the step writes an error estimate, else 0.

property n_states: int

Return the number of state variables advanced per step.

property newton_solves_per_step: int

Return the Newton solves one step runs.

property observables_fn: Callable | None

Return the compiled device observables function.

property optimisation_candidates: Tuple[Dict[str, Any], ...]

Return the setting combinations Solver.optimize times.

abstract property order: int

Return the classical order of accuracy of the algorithm.

performance_defaults(hardware: Any = None) → Dict[str, Any]

Return the placements auto_performance sets for this step.

register_buffers() → None

Register buffers required by the algorithm step.

settings_keys: frozenset | None = frozenset({'accumulator_location', 'algorithm', 'attempt_dense_prediction', 'base_state_placeholder_location', 'cached_auxiliaries_location', 'dae_initialisation', 'delta_location', 'driver_derivative_fn', 'drivers_fn', 'dxdt_fn', 'dxdt_location', 'error_atol', 'error_max_iters', 'error_residual_floor', 'error_residual_reduction', 'error_rtol', 'get_solver_helper_fn', 'increment_cache_location', 'inexact_newton', 'krylov_atol', 'krylov_iters_local_location', 'krylov_iters_out_location', 'krylov_max_iters', 'krylov_residual_floor', 'krylov_residual_reduction', 'krylov_rtol', 'linear_correction_type', 'lu_factor_location', 'mass_flags', 'n_drivers', 'n_states', 'newton_atol', 'newton_max_iters', 'newton_rtol', 'observables_fn', 'operator_beta', 'operator_gamma', 'p_location', 'precision', 'preconditioned_vec_location', 'preconditioner_order', 'preconditioner_type', 'predictor_previous_values_location', 'predictor_transform_location', 'prefactored', 'prev_theta_location', 'previous_step_size_location', 'r0_hat_location', 'residual_location', 's_hat_location', 'stage_accumulator_location', 'stage_base_location', 'stage_driver_stack_location', 'stage_increment_history_location', 'stage_increment_location', 'stage_rhs_location', 'stage_state_location', 'stage_store_location', 'temp_location', 'tmp_location', 'use_smoothed_error', 'v_location'})

Loose keys the factory accepts; None accepts every field.

shared_keeps_occupancy(elements: int, fraction: int = 1, hardware: Any = None) → bool

Whether elements shared per run plus the kernel’s skew keep 1 / fraction of the register-limited threads.

property smooth_error: bool

Return whether error smoothing compiles into the step.

property smoothed_error_weights: ndarray | None

Return the tableau’s smoothed weights while smoothing, else None.

property solver_diagnostics: Dict[str, Any]

Return the solver settings reported when runs fail.

property stage_count: int

Return the number of stages described by the tableau.

property step_default_settings: Dict[str, Any]

Return the default settings that apply to the step itself.

property step_fn: Callable

Return the cached device function that advances the solution.

property step_operation_count: int

Return the operator count of one fully unrolled step.

classmethod system_inputs(system: Any, drivers_fn: Callable | None, driver_derivative_fn: Callable | None, is_adaptive: bool) → Dict[str, Any]

Return step settings from a system object and driver functions.

property tableau: ButcherTableau | None

Return the configured tableau; None on tableau-less steps.

abstract property threads_per_step: int

property uses_direct_solver: bool

Return whether the step solves its stages with a direct LU.

property uses_error: bool

Return whether the compiled step writes an error estimate.