warp.optim.linear.bicgstab#

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

Compute an approximate solution to a linear system using the Biconjugate Gradient Stabilized method (BiCGSTAB).

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.

  • M (array | BsrMatrix | LinearOperator | None) – optional left- or right-preconditioner, ideally chosen such that M A (resp A 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_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.

  • 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. If False, return a pre-allocated BiCGSTAB 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. Whether M was provided at construction must match subsequent calls.

  • 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 final residual norm ||b - Ax||

  • 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 residual norm ||b - Ax||²

  • absolute_tolerance_squared_array: Device array containing the squared absolute tolerance

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

Return type:

If run is True and check_every > 0

Raises:
  • TypeError – If use_cuda_graph is passed with a use_graph other than None.

  • 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)).