Metadata-Version: 2.1
Name: matrealm
Version: 0.1.1
Summary: 矩阵域计算工具 - Domain-Aware Matrix Computation
Author-email: Matrealm Project <dev@matrealm.io>
License: MIT
Project-URL: Homepage, https://github.com/matrealm/matrealm
Project-URL: Documentation, https://matrealm.readthedocs.io
Project-URL: Repository, https://github.com/matrealm/matrealm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24.0

# Matrealm — Matrix Realm

**Domain-Aware Matrix Computation for Python**

[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/matrealm/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Status](https://img.shields.io/badge/status-alpha-orange)]()

---

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

```bash
pip install matrealm
```

Or from source:

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

---

## Quick Start

### Python API

```python
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

```python
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

```bash
# 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

```python
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](https://matrealm.readthedocs.io)

- [User Guide](docs/guide.md)
- [API Reference](https://matrealm.readthedocs.io/en/latest/api/)
- [Contributing Guide](CONTRIBUTING.md)

---

## Development

```bash
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

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

---

## License

MIT License — see [LICENSE](LICENSE) for details.

---

<p align="center">
  <sub>Built with numpy, powered by abstract algebra.</sub>
</p>
