eigh — Python array API standard 2024.12 documentation (original) (raw)

eigh(x: array, /) → Tuple[array, array]¶

Returns an eigenvalue decomposition of a complex Hermitian or real symmetric 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 eigenvalue decomposition of a complex Hermitian or real symmetric matrix \(x \in\ \mathbb{K}^{n \times n}\) is defined as

\[x = Q \Lambda Q^H\]

with \(Q \in \mathbb{K}^{n \times n}\) and \(\Lambda \in \mathbb{R}^n\) and where \(Q^H\) is the conjugate transpose when \(Q\) is complex and the transpose when \(Q\) is real-valued and \(\Lambda\) is a diagonal matrix whose diagonal elements are the corresponding eigenvalues. When x is real-valued, \(Q\) is orthogonal, and, when x is complex, \(Q\) is unitary.

Note

The eigenvalues of a complex Hermitian or real symmetric matrix are always real.

Warning

The eigenvectors of a symmetric matrix are not unique and are not continuous with respect to x. Because eigenvectors are not unique, different hardware and software may compute different eigenvectors.

Non-uniqueness stems from the fact that multiplying an eigenvector by \(-1\) when x is real-valued and by \(e^{\phi j}\) (\(\phi \in \mathbb{R}\)) when x is complex produces another set of valid eigenvectors.

Note

Whether an array library explicitly checks whether an input array is Hermitian or a symmetric matrix (or a stack of matrices) is implementation-defined.

Note

The function eig will be added in a future version of the specification.

Parameters:

x (array) – input array having shape (..., M, M) and whose innermost two dimensions form square matrices. Should have a floating-point data type.

Returns:

out (Tuple[array, array]) – a namedtuple (eigenvalues, eigenvectors) whose

• first element must have the field name eigenvalues (corresponding to \(\operatorname{diag}\Lambda\) above) and must be an array consisting of computed eigenvalues. The array containing the eigenvalues must have shape (..., M) and must have a real-valued floating-point data type whose precision matches the precision of x (e.g., if x is complex128, then eigenvalues must be float64).
• second element have have the field name eigenvectors (corresponding to \(Q\) above) and must be an array where the columns of the inner most matrices contain the computed eigenvectors. These matrices must be orthogonal. The array containing the eigenvectors must have shape (..., M, M) and must have the same data type as x.

Notes

Note

Eigenvalue sort order is left unspecified and is thus implementation-dependent.

Changed in version 2022.12: Added complex data type support.