warp.optim.linear.KrylovSolve#

class warp.optim.linear.KrylovSolve(
A,
nrhs=1,
*,
method,
M=None,
tol=None,
atol=0.0,
maxiter=1000,
restart=None,
working_dtype=None,
algorithm='auto',
residual='recurrence',
)[source]#

Prepared Krylov solves of one system for several right-hand sides.

Bind a square real system once, then call solve() with new RHS/output arrays. The existing functional solver selected by method supplies the recurrence and device stopping decisions, so every option of cg(), cr(), bicgstab() and gmres() behaves as documented there. Several RHSs iterate together as independent systems with a shared operator, so each reports the batch’s scheduled iteration count, including iterations after it individually converged. This is not a coupled block method.

Each solve starts from zero unless given an initial guess. Acceptance compares the selected residual with the effective tolerance of the functional solver, max(tol * ||b||, atol), where atol is first raised to an arithmetic safety floor that depends on working_dtype: 1e-18 for float32 and 1e-36 for float64. atol=0.0 therefore means a relative tolerance only, except for a zero RHS, and the reported tolerance includes the floor. Restarted methods may exceed maxiter by less than one cycle.

Prepare and warm up outside capture. With graph-compatible operators, CUDA replay has no allocations or host convergence checks. Coefficients in existing buffers may change on replay; topology/address changes require recapture and preconditioner updates remain explicit. Eager calls issued from different CUDA streams are ordered with an event, but simultaneously executing graphs that share this state or its smaller capacities require caller ordering. Without conditional graph nodes (CUDA Toolkit and driver 12.4+), CUDA solves run whole cycles up to maxiter and iterations counts them. Reverse-mode differentiation is not supported.

Parameters:
  • A – Square real sparse matrix or LinearOperator, float32 or float64. A one-dimensional vector-valued diagonal counts every component.

  • nrhs (int) – Positive number of RHSs prepared for solve().

  • method (Literal['cg', 'cr', 'bicgstab', 'gmres']) –

    Iterative method to run:

    • "cg": conjugate gradient, cg(). Requires a symmetric positive definite system and preconditioner.

    • "cr": conjugate residual, cr(). Requires a symmetric system and a symmetric positive definite preconditioner.

    • "bicgstab": biconjugate gradient stabilized, bicgstab(). Handles nonsymmetric systems.

    • "gmres": restarted generalized minimal residual, gmres(). Handles nonsymmetric and indefinite systems.

  • M – Optional fixed linear preconditioner: a single-system operator, or for nrhs > 1 a prepared operator with nrhs equal partitions of length n, such as a MultiRHSOperator. Its arithmetic must use working_dtype.

  • tol (float | None) – Nonnegative relative tolerance. Defaults to 1e-6 for a float32 working_dtype and 1e-12 for float64.

  • atol (float) – Nonnegative absolute tolerance, raised to the safety floor above. Unlike the functional solvers, an omitted atol is 0.0 rather than the value of tol, and None is rejected. At least one tolerance must be positive.

  • maxiter (int) – Positive iteration budget; truncation is allowed.

  • restart (int | None) – Krylov restart dimension for method="gmres", clipped to the system size. Defaults to 64. Other methods reject it.

  • working_dtype (type | None) – float32 or float64 inner arithmetic for a sparse A; defaults to A’s scalar type. RHSs and solutions keep A’s type. Every solve refreshes the converted matrix values on device.

  • algorithm (Literal['auto', 'loop', 'rows', 'columns']) – Batched product strategy for a sparse A, resolved once at construction as in MultiRHSOperator, which counts stored entries; explicit strategies pin a kernel.

  • residual (Literal['recurrence', 'fresh']) – Residual reported and used for acceptance. "recurrence" uses the iterative solver’s own estimate in working precision, at no extra cost. "fresh" recomputes ||A x - b|| with the source system and precision after every solve, at the cost of one operator application.

iterations#

Device array of scheduled iterations per RHS from the latest call that recorded diagnostics; likewise for the per-RHS arrays below.

absolute_residual#

Device array of residual norms from the latest call. Nonfinite norms are reported as infinity.

relative_residual#

Device array of residual norms relative to ||b||. A zero RHS gives zero for a zero residual and infinity otherwise. With residual="recurrence", ||b|| is the norm the solver computed in working_dtype, so a float32 working precision reports an infinite relative residual for an RHS whose squared norm underflows.

tolerance#

Device array of effective absolute tolerances from the latest call.

converged#

Device array of per-RHS acceptance flags, one for success.

stats#

Device array of cumulative iterations summed over RHSs, maximum iterations, failed RHSs and solved RHSs since the last reset_stats().

residual_maxima#

Device array of the maximum absolute and relative residuals since the last reset_stats().

Methods

reset_stats()

Clear cumulative stats and residual_maxima on device.

solve(rhs, out[, x0, diagnostics])

Solve into caller-owned storage, optionally refreshing device diagnostics.

update()

Copy current source matrix values into the working-precision matrix.

with_nrhs(nrhs, *[, M])

Prepare a smaller capacity sharing system storage and staging buffers.

with_nrhs(nrhs, *, M=None)[source]#

Prepare a smaller capacity sharing system storage and staging buffers.

The returned action owns its Krylov workspace and diagnostics but shares stream ordering, so it must not run concurrently with this action.

Parameters:
  • nrhs (int) – Positive capacity no greater than this action’s nrhs.

  • M – Preconditioner for the smaller capacity. Required when the original preconditioner was a prepared partitioned operator; otherwise the original single-system preconditioner is reused by default.

Returns:

A KrylovSolve that solves nrhs right-hand sides.

Return type:

KrylovSolve

update()[source]#

Copy current source matrix values into the working-precision matrix.

solve() also does this on every call, so explicit calls are only needed by solver-agnostic code. Operators that are not sparse matrices are read directly, so this is a no-op for them. It is graph capturable.

Raises:

ValueError – If the source matrix’s offsets, columns, row_counts or values array was replaced or reallocated after preparation.

solve(rhs, out, x0=None, *, diagnostics=True)[source]#

Solve into caller-owned storage, optionally refreshing device diagnostics.

In-place and aliased arrays are safe because all RHSs and initial guesses are staged before any output is written. Passing out as x0 warm starts from the previous solution.

Parameters:
  • rhs (array) – Contiguous array of shape (nrhs, n), or (n,) for one RHS, with the source scalar dtype and device.

  • out (array) – Matching output. Exact in-place aliasing is supported, but shifted overlapping views are rejected before any output mutation.

  • x0 (array | None) – Optional matching initial guess; the solve starts from zero when omitted. It may alias rhs or out. The tolerance stays relative to ||b||, not to the initial residual.

  • diagnostics (bool) – Whether to refresh the per-RHS diagnostic attributes, stats and residual_maxima. False skips that bookkeeping for short, frequent solves; it requires residual="recurrence".

Returns:

Device arrays of the scheduled iteration count shared by the batch, the squared residual norm of each RHS used for acceptance, and the squared effective tolerance of each RHS. Tolerances use working_dtype, and so do residuals with residual="recurrence". With residual="fresh", residuals use float64 if either the source or the working dtype is float64, so their dtype can differ from the tolerances’. The arrays belong to this action and are overwritten by its next solve.

Raises:

ValueError – If arrays do not match, if diagnostics is False with residual="fresh", or if a source matrix storage array was replaced or reallocated after preparation.

Return type:

tuple[array, array, array]