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',
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 bymethodsupplies the recurrence and device stopping decisions, so every option ofcg(),cr(),bicgstab()andgmres()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), whereatolis first raised to an arithmetic safety floor that depends onworking_dtype: 1e-18 for float32 and 1e-36 for float64.atol=0.0therefore means a relative tolerance only, except for a zero RHS, and the reportedtoleranceincludes the floor. Restarted methods may exceedmaxiterby 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
maxiteranditerationscounts 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.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 > 1a prepared operator withnrhsequal partitions of lengthn, such as aMultiRHSOperator. Its arithmetic must useworking_dtype.tol (float | None) – Nonnegative relative tolerance. Defaults to 1e-6 for a float32
working_dtypeand 1e-12 for float64.atol (float) – Nonnegative absolute tolerance, raised to the safety floor above. Unlike the functional solvers, an omitted
atolis0.0rather than the value oftol, andNoneis 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 toA’s scalar type. RHSs and solutions keepA’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 inMultiRHSOperator, 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. Withresidual="recurrence",||b||is the norm the solver computed inworking_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
statsandresidual_maximaon 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
KrylovSolvethat solvesnrhsright-hand sides.- Return type:
- 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_countsorvaluesarray 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
outasx0warm 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
rhsorout. The tolerance stays relative to||b||, not to the initial residual.diagnostics (bool) – Whether to refresh the per-RHS diagnostic attributes,
statsandresidual_maxima.Falseskips that bookkeeping for short, frequent solves; it requiresresidual="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 withresidual="recurrence". Withresidual="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
diagnosticsisFalsewithresidual="fresh", or if a source matrix storage array was replaced or reallocated after preparation.- Return type: