fix: add eig and eigvals to function lists

PR-URL: #996
Closes: #992

Author: kgryte

spec/2025.12/extensions/linear_algebra_functions.rst

@@ -95,7 +95,9 @@ A conforming implementation of this ``linalg`` extension must provide and suppor
    cross
    det
    diagonal
+   eig
    eigh
+   eigvals
    eigvalsh
    inv
    matmul

spec/draft/extensions/linear_algebra_functions.rst

@@ -95,7 +95,9 @@ A conforming implementation of this ``linalg`` extension must provide and suppor
    cross
    det
    diagonal
+   eig
    eigh
+   eigvals
    eigvalsh
    inv
    matmul

src/array_api_stubs/_2025_12/linalg.py

@@ -3,7 +3,9 @@
     "cross",
     "det",
     "diagonal",
+    "eig",
     "eigh",
+    "eigvals",
     "eigvalsh",
     "inv",
     "matmul",
@@ -163,29 +165,48 @@ def diagonal(x: array, /, *, offset: int = 0) -> array:
     """
 
 
-def eigh(x: array, /) -> Tuple[array, array]:
+def eig(x: array, /) -> Tuple[array, array]:
     r"""
-    Returns an eigenvalue decomposition of a complex Hermitian or real symmetric matrix (or a stack of matrices) ``x``.
+    Returns eigenvalues and eigenvectors of a real or complex matrix (or stack of matrices) ``x``.
 
-    If ``x`` is real-valued, let :math:`\mathbb{K}` be the set of real numbers :math:`\mathbb{R}`, and, if ``x`` is complex-valued, let :math:`\mathbb{K}` be the set of complex numbers :math:`\mathbb{C}`.
+    Let :math:`\mathbb{K}` be the union of the set of real numbers :math:`\mathbb{R}`
+    and the set of complex numbers, :math:`\mathbb{C}`.
 
-    The **eigenvalue decomposition** of a complex Hermitian or real symmetric matrix :math:`x \in\ \mathbb{K}^{n \times n}` is defined as
+    A real or complex value :math:`lambda \in \mathbb{K}` is an **eigenvalue** of a real
+    or complex matrix :math:`x \in \mathbb{K}^{n \times n}` if there exists a real or complex vector
+    :math:`v \in \mathbb{K}^{n}`, such that
 
     .. math::
-       x = Q \Lambda Q^H
 
-    with :math:`Q \in \mathbb{K}^{n \times n}` and :math:`\Lambda \in \mathbb{R}^n` and where :math:`Q^H` is the conjugate transpose when :math:`Q` is complex and the transpose when :math:`Q` is real-valued and :math:`\Lambda` is a diagonal matrix whose diagonal elements are the corresponding eigenvalues. When ``x`` is real-valued, :math:`Q` is orthogonal, and, when ``x`` is complex, :math:`Q` is unitary.
+            x v = \lambda v
+
+    Then, :math:`v` is referred to as an **eigenvector** of :math:`x`, corresponding to
+    the eigenvalue :math:`\lambda`.
+
+    A general matrix :math:`x \in \mathbb{K}^{n \times n}`
+
+    - has :math:`n` eigenvalues, which are defined as the roots (counted with multiplicity) of the
+      polynomial :math:`p` of degree :math:`n` given by
+
+       .. math::
+
+          p(\lambda) = \operatorname{det}(x - \lambda I_n)
+
+    - does not in general have :math:`n` linearly independent eigenvectors if it has
+      eigenvalues with multiplicity larger than one.
 
     .. note::
-       The eigenvalues of a complex Hermitian or real symmetric matrix are always real.
+       The eigenvalues of a non-symmetric real matrix are in general complex: for
+       :math:x \in \mathbb{R}^{n \times n}`, the eigenvalues, :math:`\lambda \in \mathbb{C}`,
+       may or may not reside on the real axis of the complex plane.
 
     .. 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.
+       The eigenvectors of a general 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 :math:`-1` when ``x`` is real-valued and by :math:`e^{\phi j}` (:math:`\phi \in \mathbb{R}`) when ``x`` is complex produces another set of valid eigenvectors.
+       For eigenvalues of multiplity :math:`s=1`, the non-uniqueness stems from the fact that multiplying an eigenvector by :math:`-1` when ``x`` is real-valued and by :math:`e^{\phi j}` (:math:`\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.
+       For eigenvalues of multiplity :math:`s > 1`, the :math:`s` computed eigenvectors may be repeated or
+       have entries differ by an order of machine epsilon for the data type of :math:`x`.
 
     Parameters
     ----------
@@ -197,36 +218,43 @@ def eigh(x: array, /) -> Tuple[array, array]:
     out: Tuple[array, array]
         a namedtuple (``eigenvalues``, ``eigenvectors``) whose
 
-        -   first element must have the field name ``eigenvalues`` (corresponding to :math:`\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 must have the field name ``eigenvectors`` (corresponding to :math:`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``.
+        -   first element must have the field name ``eigenvalues`` (corresponding to :math:`\lambda` above) and must be an array consisting of computed eigenvalues. The array containing the eigenvalues must have shape ``(..., M)`` and must have a complex floating-point array data type having the same precision as that of ``x`` (e.g., if ``x`` has a ``float32`` data type, ``eigenvalues`` must have the ``complex64`` data type; if ``x`` has a ``float64`` data type, ``eigenvalues`` have the ``complex128`` data type).
+
+        -   second element must have the field name ``eigenvectors`` (corresponding to :math:`v` 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 ``eigenvalues``.
 
     Notes
     -----
 
+    -   Eigenvalue sort order is left unspecified and is thus implementation-dependent.
+
     .. note::
-       Eigenvalue sort order is left unspecified and is thus implementation-dependent.
+        For real symmetric or complex Hermitian matrices, prefer using the ``eigh`` routine.
 
-    .. versionchanged:: 2022.12
-       Added complex data type support.
+    .. versionadded:: 2025.12
     """
 
 
-def eigvalsh(x: array, /) -> array:
+def eigh(x: array, /) -> Tuple[array, array]:
     r"""
-    Returns the eigenvalues of a complex Hermitian or real symmetric matrix (or a stack of matrices) ``x``.
+    Returns an eigenvalue decomposition of a complex Hermitian or real symmetric matrix (or a stack of matrices) ``x``.
 
     If ``x`` is real-valued, let :math:`\mathbb{K}` be the set of real numbers :math:`\mathbb{R}`, and, if ``x`` is complex-valued, let :math:`\mathbb{K}` be the set of complex numbers :math:`\mathbb{C}`.
 
-    The **eigenvalues** of a complex Hermitian or real symmetric matrix :math:`x \in\ \mathbb{K}^{n \times n}` are defined as the roots (counted with multiplicity) of the polynomial :math:`p` of degree :math:`n` given by
+    The **eigenvalue decomposition** of a complex Hermitian or real symmetric matrix :math:`x \in\ \mathbb{K}^{n \times n}` is defined as
 
     .. math::
-       p(\lambda) = \operatorname{det}(x - \lambda I_n)
+       x = Q \Lambda Q^H
 
-    where :math:`\lambda \in \mathbb{R}` and where :math:`I_n` is the *n*-dimensional identity matrix.
+    with :math:`Q \in \mathbb{K}^{n \times n}` and :math:`\Lambda \in \mathbb{R}^n` and where :math:`Q^H` is the conjugate transpose when :math:`Q` is complex and the transpose when :math:`Q` is real-valued and :math:`\Lambda` is a diagonal matrix whose diagonal elements are the corresponding eigenvalues. When ``x`` is real-valued, :math:`Q` is orthogonal, and, when ``x`` is complex, :math:`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 :math:`-1` when ``x`` is real-valued and by :math:`e^{\phi j}` (:math:`\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.
 
@@ -237,8 +265,11 @@ def eigvalsh(x: array, /) -> array:
 
     Returns
     -------
-    out: array
-        an array containing the computed eigenvalues. The returned array must have shape ``(..., M)`` and have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then must have a ``float64`` data type).
+    out: Tuple[array, array]
+        a namedtuple (``eigenvalues``, ``eigenvectors``) whose
+
+        -   first element must have the field name ``eigenvalues`` (corresponding to :math:`\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 must have the field name ``eigenvectors`` (corresponding to :math:`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
     -----
@@ -251,48 +282,24 @@ def eigvalsh(x: array, /) -> array:
     """
 
 
-def eig(x: array, /) -> Tuple[array, array]:
+def eigvalsh(x: array, /) -> array:
     r"""
-    Returns eigenvalues and eigenvectors of a real or complex matrix (or stack of matrices) ``x``.
+    Returns the eigenvalues of a complex Hermitian or real symmetric matrix (or a stack of matrices) ``x``.
 
-    Let :math:`\mathbb{K}` be the union of the set of real numbers :math:`\mathbb{R}`
-    and the set of complex numbers, :math:`\mathbb{C}`.
+    If ``x`` is real-valued, let :math:`\mathbb{K}` be the set of real numbers :math:`\mathbb{R}`, and, if ``x`` is complex-valued, let :math:`\mathbb{K}` be the set of complex numbers :math:`\mathbb{C}`.
 
-    A real or complex value :math:`lambda \in \mathbb{K}` is an **eigenvalue** of a real
-    or complex matrix :math:`x \in \mathbb{K}^{n \times n}` if there exists a real or complex vector
-    :math:`v \in \mathbb{K}^{n}`, such that
+    The **eigenvalues** of a complex Hermitian or real symmetric matrix :math:`x \in\ \mathbb{K}^{n \times n}` are defined as the roots (counted with multiplicity) of the polynomial :math:`p` of degree :math:`n` given by
 
     .. math::
+       p(\lambda) = \operatorname{det}(x - \lambda I_n)
 
-            x v = \lambda v
-
-    Then, :math:`v` is referred to as an **eigenvector** of :math:`x`, corresponding to
-    the eigenvalue :math:`\lambda`.
-
-    A general matrix :math:`x \in \mathbb{K}^{n \times n}`
-
-    - has :math:`n` eigenvalues, which are defined as the roots (counted with multiplicity) of the
-      polynomial :math:`p` of degree :math:`n` given by
-
-       .. math::
-
-          p(\lambda) = \operatorname{det}(x - \lambda I_n)
-
-    - does not in general have :math:`n` linearly independent eigenvectors if it has
-      eigenvalues with multiplicity larger than one.
+    where :math:`\lambda \in \mathbb{R}` and where :math:`I_n` is the *n*-dimensional identity matrix.
 
     .. note::
-       The eigenvalues of a non-symmetric real matrix are in general complex: for
-       :math:x \in \mathbb{R}^{n \times n}`, the eigenvalues, :math:`\lambda \in \mathbb{C}`,
-       may or may not reside on the real axis of the complex plane.
-
-    .. warning::
-       The eigenvectors of a general 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.
-
-       For eigenvalues of multiplity :math:`s=1`, the non-uniqueness stems from the fact that multiplying an eigenvector by :math:`-1` when ``x`` is real-valued and by :math:`e^{\phi j}` (:math:`\phi \in \mathbb{R}`) when ``x`` is complex produces another set of valid eigenvectors.
+       The eigenvalues of a complex Hermitian or real symmetric matrix are always real.
 
-       For eigenvalues of multiplity :math:`s > 1`, the :math:`s` computed eigenvectors may be repeated or
-       have entries differ by an order of machine epsilon for the data type of :math:`x`.
+    .. 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.
 
     Parameters
     ----------
@@ -301,22 +308,17 @@ def eig(x: array, /) -> Tuple[array, array]:
 
     Returns
     -------
-    out: Tuple[array, array]
-        a namedtuple (``eigenvalues``, ``eigenvectors``) whose
-
-        -   first element must have the field name ``eigenvalues`` (corresponding to :math:`\lambda` above) and must be an array consisting of computed eigenvalues. The array containing the eigenvalues must have shape ``(..., M)`` and must have a complex floating-point array data type having the same precision as that of ``x`` (e.g., if ``x`` has a ``float32`` data type, ``eigenvalues`` must have the ``complex64`` data type; if ``x`` has a ``float64`` data type, ``eigenvalues`` have the ``complex128`` data type).
-
-        -   second element must have the field name ``eigenvectors`` (corresponding to :math:`v` 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 ``eigenvalues``.
+    out: array
+        an array containing the computed eigenvalues. The returned array must have shape ``(..., M)`` and have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then must have a ``float64`` data type).
 
     Notes
     -----
 
-    -   Eigenvalue sort order is left unspecified and is thus implementation-dependent.
-
     .. note::
-        For real symmetric or complex Hermitian matrices, prefer using the ``eigh`` routine.
+       Eigenvalue sort order is left unspecified and is thus implementation-dependent.
 
-    .. versionadded:: 2025.12
+    .. versionchanged:: 2022.12
+       Added complex data type support.
     """