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, ifx
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, whenx
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}\)) whenx
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-sizedU
andVh
, such thatU
has shape(..., M, M)
andVh
has shape(..., N, N)
. IfFalse
, compute on the leadingK
singular vectors, such thatU
has shape(..., M, K)
andVh
has shape(..., K, N)
and whereK = min(M, N)
. Default:True
.
- Returns:
out (Tuple[array, array, array]) – a namedtuple
(U, S, Vh)
whosefirst element must have the field name
U
and must be an array whose shape depends on the value offull_matrices
and contain matrices with orthonormal columns (i.e., the columns are left singular vectors). Iffull_matrices
isTrue
, the array must have shape(..., M, M)
. Iffull_matrices
isFalse
, the array must have shape(..., M, K)
, whereK = min(M, N)
. The firstx.ndim-2
dimensions must have the same shape as those of the inputx
. Must have the same data type asx
.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 lengthK
, whereK = min(M, N)
. For each vector, the singular values must be sorted in descending order by magnitude, such thats[..., 0]
is the largest value,s[..., 1]
is the second largest value, et cetera. The firstx.ndim-2
dimensions must have the same shape as those of the inputx
. Must have a real-valued floating-point data type having the same precision asx
(e.g., ifx
iscomplex64
,S
must have afloat32
data type).third element must have the field name
Vh
and must be an array whose shape depends on the value offull_matrices
and contain orthonormal rows (i.e., the rows are the right singular vectors and the array is the adjoint). Iffull_matrices
isTrue
, the array must have shape(..., N, N)
. Iffull_matrices
isFalse
, the array must have shape(..., K, N)
whereK = min(M, N)
. The firstx.ndim-2
dimensions must have the same shape as those of the inputx
. Must have the same data type asx
.
Notes
Changed in version 2022.12: Added complex data type support.