matrealm 0.1.1

矩阵域计算工具 - Domain-Aware Matrix Computation

Matrealm — Matrix Realm

Domain-Aware Matrix Computation for Python

---

Matrealm is a domain-aware matrix computation library that brings algebraic field information directly into matrix operations. Every matrix is bound to its algebraic domain — ℝ (real), ℂ (complex), GF(p) (finite field), or ℍ (quaternion) — and all operations respect the rules of that domain.

Why domains matter: 1 + 1 = 2 in ℝ, but 1 + 1 = 0 in GF(2). Matrealm keeps you mathematically honest.

---

Features

Feature	Description
🧠 Domain-Aware Matrices	Every matrix tracks its algebraic domain automatically
🔢 Multi-Domain Support	ℝ · ℂ · GF(p) · ℍ — all first-class citizens
🔄 Domain Transforms	Seamlessly convert between domains (ℝ→ℂ, ℝ→GF(p), etc.)
🛡️ Domain Safety	Prevents cross-domain operations at runtime
⚡ NumPy Backend	Performance of NumPy, semantics of abstract algebra
🖥️ Built-in CLI	Full command-line interface, no code required

---

Installation

pip install matrealm

Or from source:

git clone https://github.com/matrealm/matrealm.git
cd matrealm
pip install -e .

---

Quick Start

Python API

from matrealm import Matrix, Domain, MatrixOperations, DomainTransform

# Create 3×3 matrices over ℝ
A = Matrix.random(3, 3, domain=Domain.real())
B = Matrix.random(3, 3, domain=Domain.real())

# Matrix multiplication (domain-safe)
C = MatrixOperations.multiply(A, B)

# Domain transform: ℝ → GF(7)
A_finite = DomainTransform.to_finite(A, p=7)
print(A_finite)

# Determinant
det = MatrixOperations.determinant(A)
print(f"det(A) = {det:.4f}")

# Eigenvalues
eigs = MatrixOperations.eigenvalues(A)
print(f"λ(A) = {eigs}")

Finite Field Example

from matrealm import Matrix, Domain, MatrixOperations

# GF(2) — the simplest finite field
A = Matrix([[1, 0], [1, 1]], domain=Domain.finite(2))
B = Matrix([[0, 1], [1, 0]], domain=Domain.finite(2))

# In GF(2): 1 + 1 = 0
C = MatrixOperations.add(A, B)
print(C)
# [[1, 1],
#  [0, 1]]    ← note: 1+1 became 0

---

CLI

# Create a 3×3 random matrix over ℝ
matrealm create 3 3 --type random

# Create a 4×4 identity matrix over GF(11)
matrealm create 4 4 --type identity --domain finite --mod 11

# Transform a matrix from ℝ to GF(7)
matrealm transform --from-domain real --to-domain finite --mod 7

# Compute determinant of a 4×4 random matrix
matrealm op det --size 4

# Multiply two 3×3 random matrices
matrealm op mul --size 3

# Show matrix info
matrealm info --rows 5 --cols 5

---

API Overview

Domains

Domain.real()              # ℝ
Domain.complex()           # ℂ
Domain.finite(p=7)         # GF(7)
Domain.quaternion()        # ℍ

Matrix Factory Methods

Method	Description
Matrix.zeros(m, n)	Zero matrix
Matrix.ones(m, n)	All-ones matrix
Matrix.identity(n)	Identity matrix
Matrix.random(m, n)	Random entries ~ N(0,1)

Operations

Function	Symbol	Description
MatrixOperations.add(A, B)	A + B	Addition
MatrixOperations.subtract(A, B)	A − B	Subtraction
MatrixOperations.multiply(A, B)	A · B	Matrix product
MatrixOperations.transpose(A)	Aᵀ	Transpose
MatrixOperations.trace(A)	tr(A)	Trace
MatrixOperations.determinant(A)	det(A)	Determinant
MatrixOperations.inverse(A)	A⁻¹	Inverse
MatrixOperations.eigenvalues(A)	λ(A)	Eigenvalues

Domain Transforms

Transform	Description
DomainTransform.to_complex(M)	ℝ → ℂ
DomainTransform.to_real(M)	ℂ → ℝ (drops imaginary part)
DomainTransform.to_finite(M, p)	Any → GF(p) (mod p)
DomainTransform.to_quaternion(M)	ℝ → ℍ

---

Project Structure

matrealm/
├── matrealm/              # Library source
│   ├── __init__.py        # Public API exports
│   ├── cli/
│   │   └── main.py        # CLI entry point
│   └── core/
│       ├── domain.py      # Domain types & definitions
│       ├── matrix.py      # Matrix data structure
│       ├── operations.py  # Domain-safe arithmetic
│       └── transform.py   # Inter-domain conversion
├── tests/
│   └── test_core.py       # Unit tests
├── examples/
│   └── demo.py            # Usage examples
├── docs/
│   └── guide.md           # User guide
├── README.md
├── CONTRIBUTING.md
└── pyproject.toml

---

Documentation

Full documentation: https://matrealm.readthedocs.io

• User Guide
• API Reference
• Contributing Guide

---

Development

git clone https://github.com/matrealm/matrealm.git
cd matrealm
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e ".[dev]"
pytest tests/ -v

---

Roadmap

• Core matrix structure with domain binding
• ℝ, ℂ, GF(p) domain support
• Domain-safe arithmetic operations
• CLI interface
• GF(p) determinant & inverse
• Eigenvalue decomposition
• SVD & QR factorization
• GPU backend (CUDA)
• Custom user-defined domains

---

License

MIT License — see LICENSE for details.

---

_{Built with numpy, powered by abstract algebra.}