warp.optim.linear.cg#

warp.optim.linear.cg(
A,
b,
x,
tol=None,
atol=None,
maxiter=0,
M=None,
callback=None,
check_every=10,
use_graph=None,
run=True,
*,
restart=None,
use_cuda_graph=_DEPRECATED_NONE,
)[source]#

Compute an approximate solution to a symmetric, positive-definite linear system using the Conjugate Gradient algorithm.

Supports batched systems when A is a LinearOperator with batch_offsets set; 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

  • maxiter (float | None) – maximum number of iterations to perform before aborting. Defaults to the system size. When restart is enabled, CG performs complete restart cycles and may exceed maxiter by up to restart - 1 iterations.

  • M (array | BsrMatrix | LinearOperator | None) – optional left-preconditioner, ideally chosen such that M A 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_every to 0 disables host-side residual checks, allowing CPU and CUDA graph capture. Running during graph capture requires check_every=0. On CPU, the solver stops once converged. On CUDA with use_graph and conditional graph support, it also stops once converged. Otherwise, it runs whole cycles until the iteration count reaches maxiter, 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. None captures on CUDA devices only. True also captures on CPU, using experimental CPU graph capture. With check_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.

  • run (bool) – If True (default), allocate temporary buffers and immediately run the solver, returning the iteration count, residual norm, and absolute tolerance. If False, return a pre-allocated CG functor. The functor can be called repeatedly without reallocating temporary buffers when replacement operands match the construction-time shape, dtype, device, and batch layout. For batched LinearOperator inputs, replacement operators must use the same batch_offsets array and max_batch_length value.

  • restart (int | None) – Optional positive number of iterations between restarts. Each restart recomputes b - A x and resets the search direction, limiting drift between the recursively updated residual and the true residual. Convergence checks and callbacks occur only at restart-cycle boundaries. The default None preserves standard recursive CG.

  • use_cuda_graph (bool | None) – Deprecated since Warp 1.20 and scheduled for removal in Warp 1.24. Pass the same value as use_graph instead.

Returns:

Tuple (final_iteration, residual_norm, absolute_tolerance)
  • final_iteration: The number of iterations performed before convergence or reaching maxiter

  • residual_norm: The recursively updated residual norm. When restart is enabled, this is the true residual norm ||b - Ax|| at the final restart-cycle boundary.

  • absolute_tolerance: The absolute tolerance used for convergence checking

If run is True and check_every is 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 recursively updated residual norm. When restart is enabled, this is the squared true residual norm ||b - Ax||² at the final restart-cycle boundary.

  • absolute_tolerance_squared_array: Device array containing the squared absolute tolerance

If run is False: a CG functor with all temporary buffers pre-allocated.

Return type:

If run is True and check_every > 0

Raises:
  • TypeError – If restart is not an integer or None, or if use_cuda_graph is passed with a use_graph other than None.

  • ValueError – If a specified restart is not positive.

  • RuntimeError – If run is True during graph capture with check_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)).