warp.optim.linear.gmres#
- warp.optim.linear.gmres(
- A,
- b,
- x,
- tol=None,
- atol=None,
- restart=31,
- maxiter=0,
- M=None,
- callback=None,
- check_every=31,
- use_graph=None,
- is_left_preconditioner=False,
- run=True,
- *,
- use_cuda_graph=_DEPRECATED_NONE,
Compute an approximate solution to a linear system using the restarted Generalized Minimum Residual method (GMRES[k]).
Supports batched systems when
Ais aLinearOperatorwithbatch_offsetsset; all subproblems iterate together and convergence uses the worst-case residual.- Parameters:
A (array | BsrMatrix | LinearOperator) – the linear system’s left-hand-side
b (array) – the linear system’s right-hand-side
x (array) – initial guess and solution vector
tol (float | None) – relative tolerance for the residual, as a ratio of the right-hand-side norm
atol (float | None) – absolute tolerance for the residual
restart – The restart parameter, i.e, the k in GMRES[k]. In general, increasing this parameter reduces the number of iterations but increases memory consumption.
maxiter (float | None) – maximum number of iterations to perform before aborting. Defaults to the system size. Note that the current implementation always perform restart iterations at a time, and as a result may exceed the specified maximum number of iterations by
restart-1.M (array | BsrMatrix | LinearOperator | None) – optional left- or right-preconditioner, ideally chosen such that
M A(respA M) is close to identity.callback (Callable | None) – function to be called every check_every iteration with the current iteration number, residual and tolerance. If check_every is 0, the callback should be a Warp kernel.
check_every – number of iterations every which to call callback, check the residual against the tolerance and possibility terminate the algorithm. Setting
check_everyto 0 disables host-side residual checks, allowing CPU and CUDA graph capture. Running during graph capture requirescheck_every=0. On CPU, the solver stops once converged. On CUDA withuse_graphand conditional graph support, it also stops once converged. Otherwise, it runs whole cycles until the iteration count reachesmaxiter, which restarted solvers can exceed by less than one cycle.use_graph (bool | None) – Whether to capture the solver iterations in a graph and replay it, reducing launch overhead.
Nonecaptures on CUDA devices only.Truealso captures on CPU, using experimental CPU graph capture. Withcheck_every=0, a captured solve stops once converged; on CUDA, this needs conditional graph support. CPU capture is process-wide, so don’t run captured CPU solves from several threads at once. When capturing, the linear operator and preconditioner must only perform graph-friendly operations.is_left_preconditioner – whether M should be used as a left- or right- preconditioner.
run (bool) – If
True(default), allocate temporary buffers and immediately run the solver. IfFalse, return a pre-allocatedGMRESfunctor. The functor can be called repeatedly without reallocating temporary buffers when replacement operands match the construction-time shape, dtype, device, and batch layout. For batchedLinearOperatorinputs, replacement operators must use the samebatch_offsetsarray andmax_batch_lengthvalue.use_cuda_graph (bool | None) – Deprecated since Warp 1.20 and scheduled for removal in Warp 1.24. Pass the same value as
use_graphinstead.
- Returns:
- Tuple (final_iteration, residual_norm, absolute_tolerance)
final_iteration: The number of iterations performed before convergence or reaching maxiter
residual_norm: The final residual norm ||b - Ax||
absolute_tolerance: The absolute tolerance used for convergence checking
- If
runisTrueandcheck_everyis 0: Tuple (final_iteration_array, residual_norm_squared_array, absolute_tolerance_squared_array) final_iteration_array: Device array containing the number of iterations performed
residual_norm_squared_array: Device array containing the squared residual norm ||b - Ax||²
absolute_tolerance_squared_array: Device array containing the squared absolute tolerance
If
runisFalse: aGMRESfunctor with all temporary buffers pre-allocated.- Return type:
If
runisTrueandcheck_every> 0- Raises:
TypeError – If
use_cuda_graphis passed with ause_graphother thanNone.RuntimeError – If
runisTrueduring graph capture withcheck_every> 0.
If both tol and atol are provided, the absolute tolerance used as the termination criterion for the residual norm is
max(atol, tol * norm(b)).