LinearSolver

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

Bases: MatrixFreeSolver

Factory for linear solver device functions.

Implements steepest-descent or minimal-residual iterations for solving linear systems without forming Jacobian matrices.

Parameters:

• precision (PrecisionDType) – Numerical precision for computations.

• n (int) – Length of residual and search-direction vectors.

• **kwargs – Forwarded to LinearSolverConfig and the norm factory. Includes prefixed tolerance parameters (krylov_atol, krylov_rtol).

See also

LinearSolverConfig

Configuration container for this factory.

MatrixFreeSolver

Parent class providing norm and tolerance management.

NewtonKrylov

Newton–Krylov solver that owns a LinearSolver.

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

Initialize LinearSolver with parameters.

Parameters:

• precision (PrecisionDType) – Numerical precision for computations.

• n (int) – Length of residual and search-direction vectors.

• **kwargs – Optional parameters passed to LinearSolverConfig. See LinearSolverConfig for available parameters. Tolerance parameters (krylov_atol, krylov_rtol) are passed to the norm factory. None values are ignored.

build() → LinearSolverCache

Compile linear solver device function.

Returns:

Container with compiled linear_solver device function.

Return type:

LinearSolverCache

Raises:

ValueError – If operator_apply is None when build() is called.

property device_function: Callable

Return cached linear solver device function.

property krylov_atol: ndarray

Return absolute tolerance array.

property krylov_max_iters: int

Return maximum iterations.

property krylov_rtol: ndarray

Return relative tolerance array.

property linear_correction_type: str

Return correction strategy.

register_buffers() → None

Register device buffers with buffer_registry.

property settings_dict: Dict[str, Any]

Return linear solver configuration as dictionary.

Combines config settings with tolerance arrays from norm factory.

Returns:

Configuration dictionary including krylov_atol and krylov_rtol from the norm factory.

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

property use_cached_auxiliaries: bool

Return whether cached auxiliaries are used.

class cubie.integrators.matrix_free_solvers.LinearSolverConfig(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, operator_apply: Callable | None = None, preconditioner: Callable | None = None, linear_correction_type: str = 'minimal_residual', preconditioned_vec_location: str = 'local', temp_location: str = 'local', use_cached_auxiliaries: bool = False)

Bases: MatrixFreeSolverConfig

Configuration for LinearSolver compilation.

precision

Numerical precision for computations.

Type:

PrecisionDType

n

Length of residual and search-direction vectors.

Type:

int

max_iters

Maximum solver iterations permitted.

Type:

int

norm_device_function

Compiled norm function for convergence checks.

Type:

Optional[Callable]

operator_apply

Device function applying operator F @ v.

Type:

Optional[Callable]

preconditioner

Device function for approximate inverse preconditioner.

Type:

Optional[Callable]

linear_correction_type

Line-search strategy (‘steepest_descent’ or ‘minimal_residual’).

Type:

str

preconditioned_vec_location

Memory location for preconditioned_vec buffer (‘local’ or ‘shared’).

Type:

str

temp_location

Memory location for temp buffer (‘local’ or ‘shared’).

Type:

str

use_cached_auxiliaries

Whether to use cached auxiliary arrays (determines signature).

Type:

bool

Notes

Tolerance arrays (krylov_atol, krylov_rtol) are managed by the solver’s norm factory and accessed via LinearSolver.krylov_atol/krylov_rtol properties.

linear_correction_type: str

operator_apply: Callable | None

preconditioned_vec_location: str

preconditioner: Callable | None

property settings_dict: Dict[str, Any]

Return linear solver configuration as dictionary.

Returns:

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

Return type:

dict

temp_location: str

use_cached_auxiliaries: bool

class cubie.integrators.matrix_free_solvers.LinearSolverCache(linear_solver: Callable)

Bases: CUDADispatcherCache

Cache container for LinearSolver outputs.

linear_solver

Compiled CUDA device function for linear solving.

Type:

Callable

linear_solver: Callable