svds(A, k=6, ncv=None, tol=0, which='LM', v0=None, maxiter=None, return_singular_vectors=True, solver='arpack', random_state=None, options=None)

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 .

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.

Parameters

A : sparse matrix or LinearOperator

Matrix to decompose.

k : int, default: 6

Number of singular values and singular vectors to compute. Must satisfy 1 <= k <= kmax , where kmax=min(M, N) for solver='propack' and kmax=min(M, N) - 1 otherwise.

ncv : int, optional

When solver='arpack' , this is the number of Lanczos vectors generated. See 'arpack' <sparse.linalg.svds-arpack> for details. When solver='lobpcg' or solver='propack' , this parameter is ignored.

tol : float, 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.

v0 : ndarray, optional

The starting vector for iteration; see method-specific documentation ( 'arpack' <sparse.linalg.svds-arpack> , 'lobpcg' <sparse.linalg.svds-lobpcg> ), or 'propack' <sparse.linalg.svds-propack> for details.

maxiter : int, optional

Maximum number of iterations; see method-specific documentation ( 'arpack' <sparse.linalg.svds-arpack> , 'lobpcg' <sparse.linalg.svds-lobpcg> ), or 'propack' <sparse.linalg.svds-propack> for details.

return_singular_vectors : {True, False, "u", "vh"}

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" : if M <= N , compute only the left singular vectors and return None for the right singular vectors. Otherwise, compute all singular vectors.

• "vh" : if M > N , compute only the right singular vectors and return None for the left singular vectors. Otherwise, compute all singular vectors.

If solver='propack' , the option is respected regardless of the matrix shape.

solver : {'arpack', 'propack', 'lobpcg'}, optional

The solver used. 'arpack' <sparse.linalg.svds-arpack> , 'lobpcg' <sparse.linalg.svds-lobpcg> , and 'propack' <sparse.linalg.svds-propack> are supported. Default: :None:None:`'arpack'`.

random_state : {None, int, `numpy.random.Generator`,

numpy.random.RandomState }, optional

Pseudorandom number generator state used to generate resamples.

If random_state is None (or :None:None:`np.random`), the numpy.random.RandomState singleton is used. If random_state is an int, a new RandomState instance is used, seeded with random_state . If random_state is already a Generator or RandomState instance then that instance is used.

options : dict, optional

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

Returns

u : ndarray, shape=(M, k)

Unitary matrix having left singular vectors as columns.

s : ndarray, shape=(k,)

The singular values.

vh : ndarray, shape=(k, N)

Unitary matrix having right singular vectors as rows.

Partial singular value decomposition of a sparse matrix.

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.toarray(), 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.toarray())
True

The singular values match the expected singular values, and the singular vectors are as expected up to a difference in sign.

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

The singular vectors are also orthogonal. >>> (np.allclose(u3.T @ u3, np.eye(5)) and ... np.allclose(vT3 @ vT3.T, np.eye(5))) True

See :

Back References

The following pages refer to to this document either explicitly or contain code examples using this.

scipy.sparse.linalg._eigen.arpack.arpack.eigs scipy.sparse.linalg._eigen.arpack.arpack.eigsh scipy.sparse.linalg scipy.sparse.linalg._eigen._svds.svds

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

GitHub : /scipy/sparse/linalg/_eigen/_svds.py#131
type: <class 'function'>
Commit: