solve

xitorch.linalg.solve(A: xitorch._core.linop.LinearOperator, B: torch.Tensor, E: Optional[torch.Tensor] = None, M: Optional[xitorch._core.linop.LinearOperator] = None, bck_options: Mapping[str, Any] = {}, method: Optional[Union[str, Callable]] = None, **fwd_options) → torch.Tensor[source]

Performing iterative method to solve the equation

\[\mathbf{AX=B}\]

or

\[\mathbf{AX-MXE=B}\]

where \(\mathbf{E}\) is a diagonal matrix. This function can also solve batched multiple inverse equation at the same time by applying \(\mathbf{A}\) to a tensor \(\mathbf{X}\) with shape (...,na,ncols). The applied \(\mathbf{E}\) are not necessarily identical for each column.

Parameters

  • A (xitorch.LinearOperator) – A linear operator that takes an input X and produce the vectors in the same space as B. It should have the shape of (*BA, na, na)

  • B (torch.Tensor) – The tensor on the right hand side with shape (*BB, na, ncols)

  • E (torch.Tensor or None) – If a tensor, it will solve \(\mathbf{AX-MXE = B}\). It will be regarded as the diagonal of the matrix. Otherwise, it just solves \(\mathbf{AX = B}\) and M is ignored. If it is a tensor, it should have shape of (*BE, ncols).

  • M (xitorch.LinearOperator or None) – The transformation on the E side. If E is None, then this argument is ignored. If E is not None and M is None, then M=I. If LinearOperator, it must be Hermitian with shape (*BM, na, na).

  • bck_options (dict) – Options of the iterative solver in the backward calculation.

  • method (str or callable or None) – The method of linear equation solver. If None, it will choose "cg" or "bicgstab" based on the matrices symmetry. Note: default method will be changed quite frequently, so if you want future compatibility, please specify a method.

  • **fwd_options – Method-specific options (see method below)

Returns

The tensor \(\mathbf{X}\) that satisfies \(\mathbf{AX-MXE=B}\).

Return type

torch.Tensor

method="cg"
solve(..., method="cg", *, posdef=None, precond=None, max_niter=None, rtol=1e-06, atol=1e-08, eps=1e-12, resid_calc_every=10, verbose=False)

Solve the linear equations using Conjugate-Gradient (CG) method.

Keyword Arguments

  • posdef (bool or None) – Indicating if the operation \(\mathbf{AX-MXE}\) a positive definite for all columns and batches. If None, it will be determined by power iterations.

  • precond (LinearOperator or None) – LinearOperator for the preconditioning. If None, no preconditioner is applied.

  • max_niter (int or None) – Maximum number of iteration. If None, it is set to int(1.5 * A.shape[-1])

  • rtol (float) – Relative tolerance for stopping condition w.r.t. norm of B

  • atol (float) – Absolute tolerance for stopping condition w.r.t. norm of B

  • eps (float) – Substitute the absolute zero in the algorithm’s denominator with this value to avoid nan.

  • resid_calc_every (int) – Calculate the residual in its actual form instead of substitution form with this frequency, to avoid rounding error accummulation. If your linear operator has bad numerical precision, set this to be low. If 0, then never calculate the residual in its actual form.

  • verbose (bool) – Verbosity of the algorithm.

method="bicgstab"
solve(..., method="bicgstab", *, posdef=None, precond_l=None, precond_r=None, max_niter=None, rtol=1e-06, atol=1e-08, eps=1e-12, verbose=False, resid_calc_every=10)

Solve the linear equations using stabilized Biconjugate-Gradient method.

Keyword Arguments

  • posdef (bool or None) – Indicating if the operation \(\mathbf{AX-MXE}\) a positive definite for all columns and batches. If None, it will be determined by power iterations.

  • precond_l (LinearOperator or None) – LinearOperator for the left preconditioning. If None, no preconditioner is applied.

  • precond_r (LinearOperator or None) – LinearOperator for the right preconditioning. If None, no preconditioner is applied.

  • max_niter (int or None) – Maximum number of iteration. If None, it is set to int(1.5 * A.shape[-1])

  • rtol (float) – Relative tolerance for stopping condition w.r.t. norm of B

  • atol (float) – Absolute tolerance for stopping condition w.r.t. norm of B

  • eps (float) – Substitute the absolute zero in the algorithm’s denominator with this value to avoid nan.

  • resid_calc_every (int) – Calculate the residual in its actual form instead of substitution form with this frequency, to avoid rounding error accummulation. If your linear operator has bad numerical precision, set this to be low. If 0, then never calculate the residual in its actual form.

  • verbose (bool) – Verbosity of the algorithm.

method="exactsolve"
solve(..., method="exactsolve")

Solve the linear equation by contructing the full matrix of LinearOperators.

Warning

  • As this method construct the linear operators explicitly, it might requires a large memory.

method="broyden1"
solve(..., method="broyden1", *, alpha=None, uv0=None, max_rank=None, maxiter=None, f_tol=None, f_rtol=None, x_tol=None, x_rtol=None, line_search=True, verbose=False, custom_terminator=None)

Solve the root finder or linear equation using the first Broyden method 1. It can be used to solve minimization by finding the root of the function’s gradient.

References

1

B.A. van der Rotten, PhD thesis, “A limited memory Broyden method to solve high-dimensional systems of nonlinear equations”. Mathematisch Instituut, Universiteit Leiden, The Netherlands (2003). https://web.archive.org/web/20161022015821/http://www.math.leidenuniv.nl/scripties/Rotten.pdf

Keyword Arguments

  • alpha (float or None) – The initial guess of inverse Jacobian is - alpha * I + u v^T.

  • uv0 (tuple of tensors or str or None) – The initial guess of inverse Jacobian is - alpha * I + u v^T. If "svd", then it uses 1-rank svd to obtain u and v. If None, then u and v are zeros.

  • max_rank (int or None) – The maximum rank of inverse Jacobian approximation. If None, it is inf.

  • maxiter (int or None) – Maximum number of iterations, or inf if it is set to None.

  • f_tol (float or None) – The absolute tolerance of the norm of the output f.

  • f_rtol (float or None) – The relative tolerance of the norm of the output f.

  • x_tol (float or None) – The absolute tolerance of the norm of the input x.

  • x_rtol (float or None) – The relative tolerance of the norm of the input x.

  • line_search (bool or str) – Options to perform line search. If True, it is set to "armijo".

  • verbose (bool) – Options for verbosity

method="scipy_gmres"
solve(..., method="scipy_gmres", *, min_eps=1e-09, max_niter=None)

Using SciPy’s gmres method to solve the linear equation.

Keyword Arguments

  • min_eps (float) – Relative tolerance for stopping conditions

  • max_niter (int or None) – Maximum number of iterations. If None, default to twice of the number of columns of A.

method="gmres"
solve(..., method="gmres", *, posdef=None, max_niter=None, rtol=1e-06, atol=1e-08, eps=1e-12)

Solve the linear equations using Generalised minial residual method.

Keyword Arguments

  • posdef (bool or None) – Indicating if the operation \(\mathbf{AX-MXE}\) a positive definite for all columns and batches. If None, it will be determined by power iterations.

  • max_niter (int or None) – Maximum number of iteration. If None, it is set to int(1.5 * A.shape[-1])

  • rtol (float) – Relative tolerance for stopping condition w.r.t. norm of B

  • atol (float) – Absolute tolerance for stopping condition w.r.t. norm of B

  • eps (float) – Substitute the absolute zero in the algorithm’s denominator with this value to avoid nan.