NewtonKrylov

class cubie.integrators.matrix_free_solvers.NewtonKrylov(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], n: int, linear_solver: LinearSolver, **kwargs)

Bases: MatrixFreeSolver

Factory for Newton–Krylov solver device functions.

Implements damped Newton iteration using a matrix-free linear solver for the correction equation.

Parameters:

• precision (PrecisionDType) – Numerical precision for computations.

• n (int) – Size of state vectors.

• linear_solver (LinearSolver) – LinearSolver instance for solving linear systems.

• **kwargs – Forwarded to NewtonKrylovConfig and the norm factory. Includes prefixed tolerance parameters (newton_atol, newton_rtol).

See also

NewtonKrylovConfig

Configuration container for this factory.

MatrixFreeSolver

Parent class providing norm and tolerance management.

LinearSolver

Inner linear solver used for the Newton correction equation.

__init__(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], n: int, linear_solver: LinearSolver, **kwargs) → None

Initialize NewtonKrylov with parameters.

Parameters:

• precision (PrecisionDType) – Numerical precision for computations.

• n (int) – Size of state vectors.

• linear_solver (LinearSolver) – LinearSolver instance for solving linear systems.

• **kwargs – Optional parameters passed to NewtonKrylovConfig. See NewtonKrylovConfig for available parameters. Tolerance parameters (newton_atol, newton_rtol) are passed to the norm factory. None values are ignored.

build() → NewtonKrylovCache

Compile Newton-Krylov solver device function.

Returns:

Container with compiled newton_krylov_solver device function.

Return type:

NewtonKrylovCache

Raises:

ValueError – If residual_function or linear_solver is None when build() is called.

property device_function: Callable

Return cached Newton-Krylov solver device function.

property krylov_atol: ndarray

Return the Krylov absolute tolerance array from nested LinearSolver.

property krylov_max_iters: int

Return max linear iterations from nested linear solver.

property krylov_rtol: ndarray

Return the Krylov relative tolerance array from nested LinearSolver.

property linear_correction_type: str

Return correction type from nested linear solver.

property newton_atol: ndarray

Return absolute tolerance array.

property newton_damping: float

Return damping factor.

property newton_max_backtracks: int

Return maximum backtracking steps.

property newton_max_iters: int

Return maximum Newton iterations.

property newton_rtol: ndarray

Return relative tolerance array.

register_buffers() → None

Register buffers according to locations in compile settings.

property settings_dict: Dict[str, Any]

Return merged Newton and linear solver configuration.

Combines Newton-level settings from compile_settings with linear solver settings from nested linear_solver instance, plus tolerance arrays from the norm factory.

Returns:

Merged configuration dictionary containing both Newton parameters, linear solver parameters, and tolerance arrays.

Return type:

dict

update(updates_dict: Dict[str, Any] | None = None, silent: bool = False, **kwargs) → Set[str]

Update compile settings and invalidate cache if changed.

Parameters:

• updates_dict (dict, optional) – Dictionary of settings to update.

• silent (bool, default False) – If True, suppress warnings about unrecognized keys.

• **kwargs – Additional settings as keyword arguments.

Returns:

Set of recognized parameter names that were updated.

Return type:

set

class cubie.integrators.matrix_free_solvers.NewtonKrylovConfig(precision: type[float16] | type[float32] | type[float64] | dtype[float16] | dtype[float32] | dtype[float64], instance_label: str = '', prefixed_attributes: Set[str] = NOTHING, n: int = 0, max_iters: int = 100, norm_device_function: Callable | None = None, residual_function: Callable | None = None, linear_solver_function: Callable | None = None, newton_damping: float = 0.5, newton_max_backtracks: int = 8, delta_location: str = 'local', residual_location: str = 'local', residual_temp_location: str = 'local', stage_base_bt_location: str = 'local', krylov_iters_local_location: str = 'local')

Bases: MatrixFreeSolverConfig

Configuration for NewtonKrylov solver compilation.

precision

Numerical precision for computations.

Type:

PrecisionDType

n

Size of state vectors.

Type:

int

max_iters

Maximum solver iterations permitted.

Type:

int

norm_device_function

Compiled norm function for convergence checks.

Type:

Optional[Callable]

residual_function

Device function evaluating residuals.

Type:

Optional[Callable]

linear_solver_function

Device function for solving linear systems.

Type:

Optional[Callable]

newton_damping

Step shrink factor for backtracking.

Type:

float

newton_max_backtracks

Maximum damping attempts per Newton step.

Type:

int

delta_location

Memory location for delta buffer.

Type:

str

residual_location

Memory location for residual buffer.

Type:

str

residual_temp_location

Memory location for residual_temp buffer.

Type:

str

stage_base_bt_location

Memory location for stage_base_bt buffer.

Type:

str

krylov_iters_local_location

Memory location for the single-element Krylov iteration counter buffer.

Type:

str

Notes

Tolerance arrays (newton_atol, newton_rtol) are managed by the solver’s norm factory and accessed via NewtonKrylov.newton_atol/newton_rtol properties.

delta_location: str

krylov_iters_local_location: str

linear_solver_function: Callable | None

property newton_damping: float

Return damping factor in configured precision.

newton_max_backtracks: int

residual_function: Callable | None

residual_location: str

residual_temp_location: str

property settings_dict: Dict[str, Any]

Return Newton-Krylov configuration as dictionary.

Returns:

Configuration dictionary. Note: newton_atol and newton_rtol are not included here; access them via solver.newton_atol and solver.newton_rtol properties which delegate to the norm factory.

Return type:

dict

stage_base_bt_location: str

class cubie.integrators.matrix_free_solvers.NewtonKrylovCache(newton_krylov_solver: Callable)

Bases: CUDADispatcherCache

Cache container for NewtonKrylov outputs.

newton_krylov_solver

Compiled CUDA device function for Newton-Krylov solving.

Type:

Callable

newton_krylov_solver: Callable