QuatIca: Quaternion Linear Algebra Library

Numerical linear algebra for quaternions — fast, practical, and well‑tested.

📚 Documentation

📖 Complete Documentation - Comprehensive guides, API reference, and examples

Quick Links:

• Getting Started - Setup and installation guide
• Examples - Copy-paste commands and code snippets
• API Reference - Complete function documentation
• Troubleshooting - Common issues and solutions

🚀 Try it Online - Colab Demos

No installation required! Try QuatIca directly in your browser:

🎯 Getting Started

🖼️ Image Processing Applications

📊 Algorithm Benchmarks

🔬 Research Applications

⚡ Quick Start (2 minutes)

Installation

pip install quatica

Basic Usage

import numpy as np
import quaternion
from quatica.data_gen import create_test_matrix
from quatica.utils import quat_matmat, quat_frobenius_norm
from quatica.decomp.qsvd import qr_qua, classical_qsvd
from quatica.solver import NewtonSchulzPseudoinverse, QGMRESSolver

# Create quaternion matrices
A = create_test_matrix(4, 3)
B = create_test_matrix(3, 2)

# Basic operations
C = quat_matmat(A, B)  # Matrix multiplication
norm_A = quat_frobenius_norm(A)  # Frobenius norm

# Advanced: Pseudoinverse computation
ns_solver = NewtonSchulzPseudoinverse(gamma=0.5)
A_pinv, residuals, metrics = ns_solver.compute(A)

# Decompositions
Q, R = qr_qua(A)  # QR decomposition
U, s, V = classical_qsvd(A, R=2)  # SVD decomposition

# Linear system solving
A = create_test_matrix(3, 3)
x_true = create_test_matrix(3, 1)
b = quat_matmat(A, x_true)
qgmres_solver = QGMRESSolver(tol=1e-6, max_iter=100)
x, info = qgmres_solver.solve(A, b)
print("Solution x shape:", x.shape)
print("Convergence info:", info)

print("✅ QuatIca is working!")

🎓 Getting Started

After installing QuatIca, you can start coding immediately. For more comprehensive examples and tutorials, clone the GitHub repository and run one of the interactive demos:

# Comprehensive tutorial with visualizations (recommended for beginners)
python run_analysis.py tutorial

# Core functionality demo (comprehensive overview)
python run_analysis.py demo

# Q-GMRES solver introduction
python run_analysis.py qgmres

🤔 What is QuatIca?

QuatIca brings modern numerical linear algebra and optimization tools to quaternion matrices, with growing support for quaternion tensor workflows.

• Matrix Operations: Multiplication, norms, and core operations adapted to quaternion-valued data
• Factorizations: QR, LU, SVD, eigendecomposition, Hessenberg, tridiagonal, Cholesky, and Schur
• Pseudoinverse Methods: Newton–Schulz iterations with higher-order variants
• Linear Solvers: Q-GMRES with LU preconditioning
• Optimization: Quaternion Hermitian SDP tools through the OptiQ module
• Applications: Image processing, signal processing, and related scientific computing tasks

Key Features

• 🚀 Performance: Efficient quaternion operations built on top of the NumPy ecosystem
• 🧪 Well-tested: Comprehensive test suite covering the main algorithms and utilities
• 📚 Documented: Complete API documentation with examples and tutorials
• 🔬 Research-ready: Implements recent algorithms from the quaternion numerical linear algebra literature
• 🎯 Practical: Includes real-world applications in image processing and signal analysis

📖 Core Functionality

Matrix Operations

from quatica.data_gen import create_test_matrix
from quatica.utils import quat_matmat, quat_frobenius_norm

# Basic operations
A = create_test_matrix(5, 4)
B = create_test_matrix(4, 3)
C = quat_matmat(A, B)
norm = quat_frobenius_norm(A)

Matrix Decompositions

from quatica.decomp.qsvd import qr_qua, classical_qsvd_full
from quatica.decomp.eigen import quaternion_eigendecomposition
from quatica.decomp import quaternion_lu
from quatica.utils import quat_hermitian

# QR decomposition
Q, R = qr_qua(A)

# SVD decomposition
U, s, V = classical_qsvd_full(A)

# Eigendecomposition (Hermitian matrices)
# Create a Hermitian matrix A = B^H @ B
A = create_test_matrix(4, 3)
A_H = quat_hermitian(A)
A_herm = quat_matmat(A_H, A)
eigenvals, eigenvecs = quaternion_eigendecomposition(A_herm)

# LU decomposition
L, U, P = quaternion_lu(A)

Pseudoinverse and Linear Systems

from quatica.solver import NewtonSchulzPseudoinverse, QGMRESSolver

# Newton-Schulz pseudoinverse
ns_solver = NewtonSchulzPseudoinverse(gamma=0.5)
A_pinv, residuals, metrics = ns_solver.compute(A)

# Q-GMRES solver
qgmres_solver = QGMRESSolver(tol=1e-6, max_iter=100, restart=20)
x, info = qgmres_solver.solve(A, b)

Advanced Algorithms

from quatica.decomp.qsvd import rand_qsvd
from quatica.utils import power_iteration_nonhermitian
from quatica.decomp.schur import quaternion_schur_unified

# Build a square test matrix for the advanced routines
from quatica.data_gen import create_test_matrix

A = create_test_matrix(12, 12)

# Randomized SVD (rank-R approximation)
U_rand, s_rand, V_rand = rand_qsvd(A, R=10, oversample=10, n_iter=2)

# Power iteration for a dominant eigenpair (non-Hermitian, experimental)
q_vec, lambda_complex, residuals = power_iteration_nonhermitian(
    A,
    max_iterations=100,
    eig_tol=1e-12,
    res_tol=1e-10,
    seed=0,
    return_vector=True,
)

# Schur decomposition (stable variants: 'rayleigh' or 'implicit')
Q, T = quaternion_schur_unified(A, variant="rayleigh")

🏗️ Applications

QuatIca excels in various real-world applications. Explore comprehensive examples and demos:

🚀 Interactive Demos

See the Colab demo links at the top of this page to run QuatIca directly in your browser.

📂 GitHub Repository Examples

Clone the QuatIca repository for complete application examples:

Image Processing Applications:

• Quaternion Image Deblurring - Compare QSLST vs Newton-Schulz methods
• Image Completion - Matrix completion techniques for missing pixels
• Deblurring Benchmarks - Comprehensive performance analysis

Signal Processing Applications:

• Lorenz Attractor Analysis - Q-GMRES solver for dynamical systems
• Quaternion Signal Processing - Multi-channel signal analysis
• Method Comparisons - Performance benchmarks across algorithms

Research & Analysis Tools:

• Pseudoinverse Analysis - Single and multi-image studies
• CIFAR-10 Analysis - Large-scale image dataset processing
• Synthetic Matrix Validation - Controlled experiments and verification

📋 Quick Access

# Clone the repository
git clone https://github.com/vleplat/QuatIca.git
cd QuatIca

# See all available applications
python run_analysis.py

# Run specific examples
python run_analysis.py image_deblurring --size 64
python run_analysis.py lorenz_signal --num_points 500

🔬 Research Applications

QuatIca is designed for researchers working with:

• Computer Vision: Color image processing, stereo vision, 3D rotations
• Signal Processing: Quaternion-valued signals, spatial-temporal analysis
• Robotics: Orientation estimation, SLAM, sensor fusion
• Graphics: 3D rotations, animations, geometric transformations
• Machine Learning: Quaternion neural networks, geometric deep learning

🏆 Performance

QuatIca is optimized for performance:

• Efficient quaternion operations using numpy-quaternion backend
• Randomized algorithms for large-scale problems (rand_qsvd, power iteration)
• Optimized solvers with preconditioning (Q-GMRES with LU)
• Memory-efficient implementations for large matrices

Benchmarks

• Q-SVD: Up to 6x faster than full decomposition for low-rank matrices
• Newton-Schulz: Quadratic convergence for pseudoinverse computation
• Q-GMRES: Competitive with specialized quaternion solvers

📦 Installation Requirements

• Python: ≥3.11
• NumPy: ≥2.3.2
• numpy-quaternion: ≥2024.0.10
• SciPy: ≥1.16.1
• matplotlib: ≥3.10.3
• scikit-learn: ≥1.5.0
• seaborn: ≥0.13.0

🧪 Validation

QuatIca is thoroughly validated:

• 200+ unit tests covering all major functions
• Numerical accuracy verified against theoretical results
• Performance benchmarks comparing different algorithms
• Literature validation against published research results

📖 How to Cite

If you use QuatIca in your research, please cite the following paper:

@misc{leplat2026quaticaadvancednumericallinear,
  title         = {QuatIca: Advanced Numerical Linear Algebra and Optimization for Quaternionic Matrices in Python},
  author        = {Valentin Leplat and Salman Ahmadi-Asl and Junjun Pan and Henni Ouerdane and Michael Ng},
  year          = {2026},
  eprint        = {2603.24074},
  archivePrefix = {arXiv},
  primaryClass  = {math.NA},
  url           = {https://arxiv.org/abs/2603.24074}
}

🤝 Contributing

Contributions are welcome! Please see our GitHub repository for:

• Issues: Bug reports and feature requests
• Pull Requests: Code contributions and improvements
• Documentation: Help improve docs and examples
• Testing: Add test cases and benchmarks

📜 License

QuatIca is licensed under the MIT License (as of v1.0.0).

Earlier versions were released under CC0 1.0 Universal and remain available under those terms.

See LICENSE for details.

🔗 Links

• 📖 Documentation
• 🐙 GitHub Repository
• 📄 arXiv Paper
• 🔬 Colab Demo
• 📊 PyPI Package

Made with ❤️ for the quaternion computing community