Skip to content

quatica.decomp.eigen

quatica.decomp.eigen

Quaternion Hermitian eigendecomposition utilities.

This module provides eigenvalue decomposition algorithms for Hermitian quaternion matrices.

Key functions

  • quaternion_eigendecomposition(A): returns (eigenvalues, eigenvectors) for Hermitian quaternion A
  • quaternion_eigenvalues(A): returns eigenvalues only (fast path; no eigenvectors)
  • quaternion_eigenvectors(A): returns eigenvectors only

Implementation notes

We follow the QTFM-style approach:

1) Tridiagonalize Hermitian quaternion matrix A: P * A * P^H = B where B is quaternion tridiagonal (and, in the Hermitian case, can be represented in a complex subalgebra spanned by {1, i}).

2) Convert B to a complex Hermitian matrix Bc using the (w + i*x) components.

3) Use LAPACK-backed numpy routines: - np.linalg.eigvalsh(Bc) for eigenvalues only (fast, stable) - np.linalg.eigh(Bc) for eigenpairs (fast, stable)

4) Map eigenvectors back: V = P^H * V_B (in quaternion arithmetic).

This module is primarily imported as part of the QuatIca package

from quatica.decomp.eigen import quaternion_eigendecomposition

but it also supports legacy flat-import contexts used by some tests.

References

  • QTFM (Quaternion Toolbox for MATLAB): http://qtfm.sourceforge.net/ Stephen J. Sangwine & Nicolas Le Bihan

quaternion_eigendecomposition(A_quat, *, check_hermitian=True, atol_herm=1e-10, tol_jk=1e-10, verbose=False)

Compute eigendecomposition of a Hermitian quaternion matrix.

Parameters

A_quat : np.ndarray (dtype=quaternion) Square Hermitian quaternion matrix. check_hermitian : bool If True, validates A is Hermitian (within atol_herm). atol_herm : float Tolerance for Hermitian check. tol_jk : float Tolerance for j/k parts in the tridiagonal matrix reduction. verbose : bool Print diagnostic info.

Returns

w : np.ndarray (float), shape (n,) Real eigenvalues (Hermitian quaternion eigenvalues are real). V : np.ndarray (dtype=quaternion), shape (n,n) Quaternion eigenvectors (columns), unitary up to numerical error.

quaternion_eigenvalues(A_quat, *, check_hermitian=True, atol_herm=1e-10, tol_jk=1e-10)

Compute eigenvalues only (fast path) for a Hermitian quaternion matrix.

This function avoids computing quaternion eigenvectors altogether.

quaternion_eigenvectors(A_quat, *, check_hermitian=True, atol_herm=1e-10, tol_jk=1e-10, verbose=False)

Compute eigenvectors only for a Hermitian quaternion matrix.

verify_eigendecomposition(A_quat, eigenvalues, eigenvectors, *, tol=1e-06)

Verify A v ≈ v λ for each eigenpair (Hermitian quaternion).

Returns a dict with max/mean errors and a boolean success flag.