Logo
ScienceStack
Table of Contents
Fetching ...
Sign In

QuatIca: Advanced Numerical Linear Algebra and Optimization for Quaternionic Matrices in Python

Valentin Leplat, Salman Ahmadi-Asl, Junjun Pan, Henni Ouerdane, Michael Ng

Abstract

Quaternion-valued representations provide a convenient way to model coupled multi-channel signals (e.g., RGB imagery, polarization data, vector fields, and multi-detector time series). Yet practical and numerically reliable software support remains far less mature than those based on the real/complex setting. Here, we present QuatIca, an open-source Python library for quaternion numerical linear algebra and optimization, designed for both research prototyping and reproducible experimentation. QuatIca provides core quaternion matrix operations and norms; dense decompositions and reductions (QR, LU, Q-SVD, eigendecomposition, Hessenberg/tridiagonal reduction, Cholesky decomposition, and Schur helpers); iterative solvers including quaternion GMRES (with preconditioning) and Newton-Schulz pseudoinverse schemes; and domain-focused routines for signal and image processing such as quaternion Tikhonov restoration. The library also includes OptiQ, which solves quaternion Hermitian semidefinite programs using log-det barrier Newton methods with $μ$-continuation. We highlight design choices that preserve quaternion structure, and we provide end-to-end demonstrations including quaternion image deblurring, Lorenz-attractor filtering, and quaternion image completion. QuatIca is distributed via PyPI and accompanied by open-source development on GitHub and continuously deployed documentation with runnable tutorials.

QuatIca: Advanced Numerical Linear Algebra and Optimization for Quaternionic Matrices in Python

Abstract

Quaternion-valued representations provide a convenient way to model coupled multi-channel signals (e.g., RGB imagery, polarization data, vector fields, and multi-detector time series). Yet practical and numerically reliable software support remains far less mature than those based on the real/complex setting. Here, we present QuatIca, an open-source Python library for quaternion numerical linear algebra and optimization, designed for both research prototyping and reproducible experimentation. QuatIca provides core quaternion matrix operations and norms; dense decompositions and reductions (QR, LU, Q-SVD, eigendecomposition, Hessenberg/tridiagonal reduction, Cholesky decomposition, and Schur helpers); iterative solvers including quaternion GMRES (with preconditioning) and Newton-Schulz pseudoinverse schemes; and domain-focused routines for signal and image processing such as quaternion Tikhonov restoration. The library also includes OptiQ, which solves quaternion Hermitian semidefinite programs using log-det barrier Newton methods with -continuation. We highlight design choices that preserve quaternion structure, and we provide end-to-end demonstrations including quaternion image deblurring, Lorenz-attractor filtering, and quaternion image completion. QuatIca is distributed via PyPI and accompanied by open-source development on GitHub and continuously deployed documentation with runnable tutorials.
Paper Structure (91 sections, 95 equations, 9 figures, 1 table, 1 algorithm)

This paper contains 91 sections, 95 equations, 9 figures, 1 table, 1 algorithm.

Table of Contents

  1. Introduction
  2. Contributions.
  3. Availability, dependencies, and reproducibility.
  4. Positioning with respect to existing software.
  5. Article outline.
  6. Quaternion preliminaries
  7. Real inner product on $\mathrm{Herm}_n(\mathbb{H})$.
  8. Adjoint vs Hermitian projection (implementation-critical).
  9. Unit quaternions and 3D rotations (qtraj).
  10. Rotation matrices and the map $S^3\to SO(3)$.
  11. Sign consistency (unwrapping) and the dot product in $\mathbb{R}^4$.
  12. Axis--angle representation and quaternion exponential/logarithm.
  13. Software architecture and design goals
  14. Design principles
  15. Module overview
  16. ...and 76 more sections

Figures (9)

  • Figure 1: High-level architecture of QuatIca: the core quaternion matrix layer (utils) supports decompositions and spectral reductions, iterative solvers and restoration modules, conic optimization (OptiQ), and rotation trajectories (qtraj), together with standardized diagnostics and plotting.
  • Figure 2: Quaternion image completion demo with $70\%$ missing pixels. The output summarizes the original image, the masked observation, the final reconstruction, and the evolution of the PSNR across iterations, together with key summary information such as the rank parameters, the pseudoinverse iteration budget, and the total runtime.
  • Figure 3: Example of quaternion image deblurring with QuatIca on kodim16 at resolution $64\times 64$. The grid shows the clean image, the degraded observation, and the restorations obtained with QSLST and the FFT-based Newton--Schulz method. The corresponding PSNR and SSIM values are reported in the figure title.
  • Figure 4: Lorenz attractor filtering example generated with python run_analysis.py lorenz_signal --num_points 500. Top: noisy observed trajectory (left) and reconstructed trajectory (right) in three-dimensional phase space. Bottom: observed component signals (left) and reconstructed component signals (right). The reconstruction is obtained with the built-in Q-GMRES solver with automatic left LU preconditioning; see Section \ref{['subsec:QGMRES']}. A complementary Newton--Schulz-based experiment can be generated with python run_analysis.py lorenz_benchmark --methods newton --points 500; see Section \ref{['subsec:NS_solver']}.
  • Figure 5: Trajectory on $S^2$ obtained by rotating a fixed unit vector with the interpolated quaternion orientations. Using the same randomly generated keyframes, piecewise SLERP, SQUAD, and log--exp spline interpolation all produce valid rotation trajectories passing through the prescribed keyframes, while following different between-keyframe paths on the sphere.
  • ...and 4 more figures