mindspore.scipy.sparse.linalg.cg

mindspore.scipy.sparse.linalg.cg(A, b, x0=None, *, tol=1e-05, atol=0.0, maxiter=None, M=None, callback=None)[source]

Use Conjugate Gradient iteration to solve the linear system:

\[A x = b\]

The numerics of MindSpore’s cg should exact match SciPy’s cg (up to numerical precision).

Derivatives of cg are implemented via implicit differentiation with another cg solve, rather than by differentiating through the solver. They will be accurate only if both solves converge.

Note

  • Input A must represent a hermitian, positive definite matrix. If not, the output is wrong and inconsistent with scipy.

  • cg is not supported on Windows platform yet.

  • Currently, when A is a CSRTensor, the derivatives of cg is not supported on PyNative mode.

Parameters

  • A (Union[Tensor, CSRTensor, function]) – 2D Tensor, CSRTensor or function that calculates the linear map (matrix-vector product) \(Ax\) when called like \(A(x)\). As function, A must return Tensor with the same structure and shape as its input matrix.

  • b (Tensor) – Right hand side of the linear system representing a single vector. Can be stored as a Tensor.

  • x0 (Tensor) – Starting guess for the solution. Must have the same structure as b. Default: None.

  • tol (float, optional) – Tolerances for convergence, \(norm(residual) <= max(tol*norm(b), atol)\). We do not implement SciPy’s “legacy” behavior, so MindSpore’s tolerance will differ from SciPy unless you explicitly pass atol to SciPy’s cg. Default: 1e-5.

  • atol (float, optional) – The same as tol. Default: 0.0.

  • maxiter (int) – Maximum number of iterations. Iteration will stop after maxiter steps even if the specified tolerance has not been achieved. Default: None.

  • M (Union[Tensor, CSRTensor, function]) – Preconditioner for A. The preconditioner should approximate the inverse of A. Effective preconditioning dramatically improves the rate of convergence, which implies that fewer iterations are needed to reach a given error tolerance. Default: None.

  • callback (function, optional) – User-supplied function to call after each iteration. It is called as callback(xk), where xk is the current solution vector. Default: None.

Returns

  • Tensor, the converged solution. Has the same structure as b.

  • Tensor, placeholder for convergence information: 0 : successful exit. >0 : convergence to tolerance not achieved, number of iterations. <0 : illegal input or breakdown.

Raises

  • TypeError – If tol is not float.

  • TypeError – If atol is not float.

  • TypeError – If maxiter is not int.

  • ValueError – If callback is not None.

  • TypeError – If A is not Tensor, CSRTensor, or Function.

  • TypeError – If M is not None, Tensor, CSRTensor, or Function.

  • TypeError – If b is not Tensor.

  • TypeError – If x0 is not None or Tensor.

  • ValueError – If b is not 1 or 2 dimension.

  • ValueError – If x0 and b don’t have the same structure and type.

  • ValueError – If A is a square matrix.

  • ValueError – If M is a square matrix when M is not a function.

  • TypeError – If A and b don’t have the same data types.

Supported Platforms:

CPU GPU

Examples

>>> import numpy as onp
>>> from mindspore.common import Tensor
>>> from mindspore.scipy.sparse.linalg import cg
>>> A = Tensor(onp.array([[1, 2], [2, 1]], dtype='float32'))
>>> b = Tensor(onp.array([1, -1], dtype='float32'))
>>> result, info = cg(A, b)
>>> print(result)
[-1.  1.]
>>> print(info)
0