matrealm 0.1.0__tar.gz

matrealm-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+global-exclude matrealm/item/encryption.py
+global-exclude matrealm/item/eachmouth.md

matrealm-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.1
+Name: matrealm
+Version: 0.1.0
+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>

matrealm-0.1.0/README.md

@@ -0,0 +1,231 @@
+# 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>

matrealm-0.1.0/matrealm/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to Matrealm
+
+Thank you for your interest in Matrealm!
+
+## Development Setup
+
+```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]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Code Style
+
+- PEP 8 compliant
+- Full type annotations
+- Google-style docstrings
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/your-feature`
+3. Commit your changes: `git commit -m "feat: add ..."`
+4. Push: `git push origin feat/your-feature`
+5. Open a Pull Request
+
+## Versioning
+
+This project follows [SemVer](https://semver.org/):
+
+- MAJOR: incompatible API changes
+- MINOR: backward-compatible feature additions
+- PATCH: backward-compatible bug fixes