svd

svd(x: array, /, *, full_matrices: bool = True) → Tuple[array, array, array]

Returns a singular value decomposition (SVD) of a matrix (or a stack of matrices) x.

If x is real-valued, let \(\mathbb{K}\) be the set of real numbers \(\mathbb{R}\), and, if x is complex-valued, let \(\mathbb{K}\) be the set of complex numbers \(\mathbb{C}\).

The full singular value decomposition of an \(m \times n\) matrix \(x \in\ \mathbb{K}^{m \times n}\) is a factorization of the form

\[x = U \Sigma V^H\]

where \(U \in\ \mathbb{K}^{m \times m}\), \(\Sigma \in\ \mathbb{K}^{m \times\ n}\), \(\operatorname{diag}(\Sigma) \in\ \mathbb{R}^{k}\) with \(k = \operatorname{min}(m, n)\), \(V^H \in\ \mathbb{K}^{n \times n}\), and where \(V^H\) is the conjugate transpose when \(V\) is complex and the transpose when \(V\) is real-valued. When x is real-valued, \(U\), \(V\) (and thus \(V^H\)) are orthogonal, and, when x is complex, \(U\), \(V\) (and thus \(V^H\)) are unitary.

When \(m \gt n\) (tall matrix), we can drop the last \(m - n\) columns of \(U\) to form the reduced SVD

\[x = U \Sigma V^H\]

where \(U \in\ \mathbb{K}^{m \times k}\), \(\Sigma \in\ \mathbb{K}^{k \times\ k}\), \(\operatorname{diag}(\Sigma) \in\ \mathbb{R}^{k}\), and \(V^H \in\ \mathbb{K}^{k \times n}\). In this case, \(U\) and \(V\) have orthonormal columns.

Similarly, when \(n \gt m\) (wide matrix), we can drop the last \(n - m\) columns of \(V\) to also form a reduced SVD.

This function returns the decomposition \(U\), \(S\), and \(V^H\), where \(S = \operatorname{diag}(\Sigma)\).

When x is a stack of matrices, the function must compute the singular value decomposition for each matrix in the stack.

Warning

The returned arrays \(U\) and \(V\) are neither unique nor continuous with respect to x. Because \(U\) and \(V\) are not unique, different hardware and software may compute different singular vectors.

Non-uniqueness stems from the fact that multiplying any pair of singular vectors \(u_k\), \(v_k\) by \(-1\) when x is real-valued and by \(e^{\phi j}\) (\(\phi \in \mathbb{R}\)) when x is complex produces another two valid singular vectors of the matrix.

Parameters:

  • x (array) – input array having shape (..., M, N) and whose innermost two dimensions form matrices on which to perform singular value decomposition. Should have a floating-point data type.

  • full_matrices (bool) – If True, compute full-sized U and Vh, such that U has shape (..., M, M) and Vh has shape (..., N, N). If False, compute on the leading K singular vectors, such that U has shape (..., M, K) and Vh has shape (..., K, N) and where K = min(M, N). Default: True.

Returns:

out (Tuple[array, array, array]) – a namedtuple (U, S, Vh) whose

  • first element must have the field name U and must be an array whose shape depends on the value of full_matrices and contain matrices with orthonormal columns (i.e., the columns are left singular vectors). If full_matrices is True, the array must have shape (..., M, M). If full_matrices is False, the array must have shape (..., M, K), where K = min(M, N). The first x.ndim-2 dimensions must have the same shape as those of the input x. Must have the same data type as x.

  • second element must have the field name S and must be an array with shape (..., K) that contains the vector(s) of singular values of length K, where K = min(M, N). For each vector, the singular values must be sorted in descending order by magnitude, such that s[..., 0] is the largest value, s[..., 1] is the second largest value, et cetera. The first x.ndim-2 dimensions must have the same shape as those of the input x. Must have a real-valued floating-point data type having the same precision as x (e.g., if x is complex64, S must have a float32 data type).

  • third element must have the field name Vh and must be an array whose shape depends on the value of full_matrices and contain orthonormal rows (i.e., the rows are the right singular vectors and the array is the adjoint). If full_matrices is True, the array must have shape (..., N, N). If full_matrices is False, the array must have shape (..., K, N) where K = min(M, N). The first x.ndim-2 dimensions must have the same shape as those of the input x. Must have the same data type as x.

Notes

Changed in version 2022.12: Added complex data type support.