scipy.sparse.linalg.svds

scipy.sparse.linalg.svds(A, k=6, ncv=None, tol=0, which='LM', v0=None, maxiter=None, return_singular_vectors=True, solver='arpack', options=None)[source]

Partial singular value decomposition of a sparse matrix.

Compute the largest or smallest k singular values and corresponding singular vectors of a sparse matrix A. The order in which the singular values are returned is not guaranteed.

In the descriptions below, let M, N = A.shape.

Parameters
Asparse matrix or LinearOperator

Matrix to decompose.

kint, default: 6

Number of singular values and singular vectors to compute. Must satisfy 1 <= k < min(M, N).

ncvint, optional

When solver='arpack', this is the number of Lanczos vectors generated. See ‘arpack’ for details. When solver='lobpcg', this parameter is ignored.

tolfloat, optional

Tolerance for singular values. Zero (default) means machine precision.

which{‘LM’, ‘SM’}

Which k singular values to find: either the largest magnitude (‘LM’) or smallest magnitude (‘SM’) singular values.

v0ndarray, optional

The starting vector for iteration; see method-specific documentation (‘arpack’ or ‘lobpcg’) for details.

maxiterint, optional

Maximum number of iterations; see method-specific documentation (‘arpack’ or ‘lobpcg’) for details.

return_singular_vectorsbool or str, optional

Singular values are always computed and returned; this parameter controls the computation and return of singular vectors.

  • True: return singular vectors.

  • False: do not return singular vectors.

  • "u": only return the left singular values, without computing the right singular vectors (if N > M).

  • "vh": only return the right singular values, without computing the left singular vectors (if N <= M).

solverstr, optional

The solver used. ‘arpack’ and ‘lobpcg’ are supported. Default: ‘arpack’.

optionsdict, optional

A dictionary of solver-specific options. No solver-specific options are currently supported; this parameter is reserved for future use.

Returns
undarray, shape=(M, k)

Unitary matrix having left singular vectors as columns. If return_singular_vectors is "vh", this variable is not computed, and None is returned instead.

sndarray, shape=(k,)

The singular values.

vhndarray, shape=(k, N)

Unitary matrix having right singular vectors as rows. If return_singular_vectors is "u", this variable is not computed, and None is returned instead.

Notes

This is a naive implementation using ARPACK or LOBPCG as an eigensolver on A.conj().T @ A or A @ A.conj().T, depending on which one is more efficient.

Examples

Construct a matrix A from singular values and vectors.

>>> from scipy.stats import ortho_group
>>> from scipy.sparse import csc_matrix, diags
>>> from scipy.sparse.linalg import svds
>>> rng = np.random.default_rng()
>>> orthogonal = csc_matrix(ortho_group.rvs(10, random_state=rng))
>>> s = [0.0001, 0.001, 3, 4, 5]  # singular values
>>> u = orthogonal[:, :5]         # left singular vectors
>>> vT = orthogonal[:, 5:].T      # right singular vectors
>>> A = u @ diags(s) @ vT

With only three singular values/vectors, the SVD approximates the original matrix.

>>> u2, s2, vT2 = svds(A, k=3)
>>> A2 = u2 @ np.diag(s2) @ vT2
>>> np.allclose(A2, A.todense(), atol=1e-3)
True

With all five singular values/vectors, we can reproduce the original matrix.

>>> u3, s3, vT3 = svds(A, k=5)
>>> A3 = u3 @ np.diag(s3) @ vT3
>>> np.allclose(A3, A.todense())
True

The singular values match the expected singular values, and the singular values are as expected up to a difference in sign. Consequently, the returned arrays of singular vectors must also be orthogonal.

>>> (np.allclose(s3, s) and
...  np.allclose(np.abs(u3), np.abs(u.todense())) and
...  np.allclose(np.abs(vT3), np.abs(vT.todense())))
True