symclaw/README.md

<p align="center">
  <img src="docs/assets/symclaw-logo.svg" alt="SymClaw" width="200" />
</p>

<h1 align="center">🔮 SymClaw — Symbolic Computing for the Agentic Age</h1>

<p align="center">
  <strong>A GPU-accelerated, AI-integrated computer algebra system built in Rust.</strong>
</p>

<p align="center">
  <a href="https://github.com/osobh/symclaw/actions"><img src="https://github.com/osobh/symclaw/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://crates.io/crates/symclaw-core"><img src="https://img.shields.io/crates/v/symclaw-core.svg" alt="crates.io"></a>
  <a href="https://docs.rs/symclaw-core"><img src="https://docs.rs/symclaw-core/badge.svg" alt="docs.rs"></a>
  <a href="https://github.com/osobh/symclaw/blob/master/LICENSE-MIT"><img src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue" alt="License"></a>
</p>

<p align="center">
  <b>65,000+ lines of Rust &nbsp;·&nbsp; 1,808 tests (0 failures) &nbsp;·&nbsp; 12 crates &nbsp;·&nbsp; 11 GPU modules</b>
</p>

---

## ✨ Why SymClaw?

- 🚀 **GPU-Accelerated** — GPU polynomial GCD (Zippel), NTT polynomial multiply, Gröbner basis row reduction, Monte Carlo integration, ODE parameter sweeps — all via [CubeCL](https://github.com/tracel-ai/cubecl)
- 🤖 **AI-Native** — OpenClaw skill bridge (22 JSON-RPC actions); every result includes LaTeX and confidence scores
- 🌐 **Everywhere** — Rust library, Python (PyO3), WASM/browser (wasm-bindgen), C FFI, CLI REPL, WebSocket collab
- 🔬 **Research-Grade** — Quantum computing (Pauli/ZX-calculus/UCCSD), systems biology (SIAN identifiability), quantum chemistry (Wick's theorem, Gaussian integrals), crystallography (space groups, structure factors)
- ⚡ **Blazing Fast** — Packed polynomial representation (FORM-inspired), AVX2 Montgomery multiplication, E-graph equality saturation

---

## 🏗️ Architecture

```
symclaw-core      — 32 modules: the complete symbolic math engine
├── Symbolic:       parser · simplify · egraph · differentiate · integrate
│                   solve · series · limits · transforms · pattern · ode
├── Algebra:        poly · modular_gcd · packed_poly · linalg · tensor
│                   number_theory · precision (BigFloat, GF(p))
├── Novel:          discover (symbolic regression) · units · proof · symbols
└── Infra:          codegen · streaming · simd_arith · eval · latex · cache

symclaw-quantum    — Pauli group · stabilizer tableau · circuits (30 gates)
                     ZX-calculus (11 rewrite rules) · OpenQASM3/Qiskit/PennyLane/Cirq

symclaw-bio        — ODE models · SIAN structural identifiability
                     reaction networks · Hardy-Weinberg · JC69/K80 · genome reversals

symclaw-qchem      — Wick's theorem (bitmask) · McMurchie-Davidson integrals
                     Boys function · Clebsch-Gordan (Racah) · VQE/UCCSD

symclaw-materials  — 14 Bravais lattices · 32 point groups · 230 space groups
                     structure factors · Cromer-Mann · BVS · Madelung/Born-Landé

symclaw-gpu        — NTT · FFT (Cooley-Tukey) · Gröbner (F4) · poly_gcd (Zippel)
                     Monte Carlo · ODE sweeps · linalg · eval · SIMD batch ops

symclaw-cli        — Interactive REPL, 30+ commands (:diff, :integrate, :plot, :codegen, …)
symclaw-python     — PyO3 bindings with operator overloading
symclaw-wasm       — 24+ browser-ready exports via wasm-bindgen
symclaw-ffi        — C FFI for embedding in any language
symclaw-skill      — OpenClaw AI agent bridge (22 JSON-RPC actions)
symclaw-collab     — Multi-user WebSocket real-time collaboration
```

---

## 🚀 Quick Start

### Python

```python
# pip install symclaw  (via maturin)
from symclaw import Expression as E, S

x = S("x")
expr = (x + 1)**2
print(expr.simplify())        # x^2 + 2*x + 1
print(expr.diff("x"))         # 2*x + 2
print(expr.integrate("x"))    # x^3/3 + x^2 + x
print(expr.to_latex())        # x^{2} + 2 x + 1
print(expr.to_code("python")) # x**2 + 2*x + 1
```

### CLI REPL

```
$ cargo run -p symclaw-cli

symclaw> (x + 1)^2
  x^2 + 2·x + 1

symclaw> :derive sin(x^2) x
  2·x·cos(x²)

symclaw> :integrate x^3 x
  x⁴/4

symclaw> :limit sin(x)/x x 0
  1

symclaw> :taylor exp(x) x 4 0
  1 + x + x²/2 + x³/6 + x⁴/24

symclaw> :codegen x^2 + 2*x + 1 rust
  x.powi(2) + 2.0 * x + 1.0

symclaw> :plot sin(x) x -6.28 6.28 60
  [ASCII chart]
```

### Rust

```rust
use symclaw_core::{parser, simplify, differentiate, integrate, latex};

let expr = parser::parse("sin(x)^2 + cos(x)^2").unwrap();
let simplified = simplify::simplify(&expr);
println!("{}", simplified);                      // 1
println!("{}", latex::to_latex(&simplified));    // 1
```

### WASM / JavaScript

```javascript
import init, { simplify, differentiate, to_latex, eval_range } from 'symclaw-wasm';
await init();

console.log(simplify("sin(x)^2 + cos(x)^2"));    // "1"
console.log(differentiate("x^3 + 2*x", "x"));    // "3·x² + 2"
console.log(to_latex("1/2 + 1/3"));              // "\\frac{5}{6}"

// Evaluate over a range for plotting
const pts = JSON.parse(eval_range("sin(x)", "x", 0, 6.28, 100));
```

### OpenClaw Skill (AI Agent)

```json
// Request
{"action": "differentiate", "expr": "x^3 + sin(x)", "var": "x"}

// Response
{"success": true, "result": "3·x² + cos(x)", "latex": "3 x^{2} + \\cos(x)", "confidence": 1.0}
```

---

## 📦 What's Inside

### symclaw-core (32 modules, 1,279 unit tests)

| Area | Modules |
|------|---------|
| **Parser & AST** | `parser`, `ast`, `interner` |
| **Simplification** | `simplify`, `egraph` (equality saturation via egg) |
| **Calculus** | `differentiate`, `integrate`, `series`, `limits`, `ode`, `transforms` |
| **Algebra** | `solve`, `poly`, `modular_gcd`, `packed_poly`, `linalg`, `tensor` |
| **Number theory** | `number_theory` (30+ functions), `precision` (BigFloat, GF(p)) |
| **Advanced** | `pattern`, `discover` (symbolic regression), `units`, `proof`, `symbols` |
| **Output** | `codegen` (7 languages), `latex`, `streaming`, `eval` |
| **Infrastructure** | `cache`, `metrics`, `simd_arith`, `confidence` |

### symclaw-quantum (85 tests)

- **Pauli group**: n-qubit operators, phase, commutators, weight, dagger
- **Stabilizer tableau**: SympRow binary symplectic representation, H/CNOT/S gates
- **Quantum circuits**: 30 gate types, depth, T-count, gate cancellation, state-vector simulator
- **ZX-calculus**: diagram builder, 11 rewrite rules (spider fusion, π-copy, bialgebra, …), simplifier
- **Codegen**: OpenQASM 3, Qiskit, PennyLane, Cirq
- **Clifford gates**: CliffordGate1Q as Cl(3,0) algebra elements

### symclaw-bio (55 tests)

- **ODE models**: state/parameter/output builder, Lie derivatives, input-output equations
- **Identifiability**: SIAN structural identifiability via numerical Jacobian rank
- **Reaction networks**: stoichiometry matrix, deficiency theorem, mass-action kinetics → ODEs
- **Population genetics**: Hardy-Weinberg equilibrium, JC69 and K80 substitution models
- **Genome algebra**: signed permutation reversals, breakpoints, greedy sorting; genetic code (64 codons)

### symclaw-qchem (53 tests)

- **Second quantization**: FermionTerm/FermionOp, number-conserving operators
- **Wick's theorem**: bitmask enumeration (iterative, no stack overflow), vacuum expectation values
- **Molecular integrals**: GaussianBasis, normalization, Boys function F_m(x), McMurchie-Davidson E coefficients, overlap and kinetic energy integrals
- **Angular momentum**: Pauli matrices, Clebsch-Gordan coefficients via Racah formula
- **VQE**: parameter-shift gradient rule, HF reference state, UCCSD single/double excitations, Ansatz builder

### symclaw-materials (63 tests)

- **Lattice**: all 14 Bravais lattice types, 7 crystal systems, lattice parameter constructors, unit cell volumes, primitive and reciprocal lattice vectors
- **Groups**: all 32 crystallographic point groups (centrosymmetric=11, polar=10, chiral=11), SymOp (rotation matrix + fractional translation, compose, determinant), 230 space groups descriptor
- **Structure**: CrystalStructure with built-in NaCl/Si/α-Fe, Cromer-Mann scattering factors, structure factors F(hkl), Debye-Waller factors, systematic absence detection
- **Bonding**: Lennard-Jones 12-6 (Ar parameters), coordination environments, Bond Valence Sum (BVS) with R₀ table, Pauling electronegativity (30 elements) + ionicity, Madelung constants + Born-Landé lattice energy

### symclaw-gpu (101 tests)

| Module | Algorithm | Backend |
|--------|-----------|---------|
| `ntt` | Number Theoretic Transform (NTT-friendly primes) | GPU/CPU |
| `fft` | Cooley-Tukey radix-2 FFT; poly multiply via convolution | CPU |
| `groebner` | Faugère F4 with sparse GF(p) matrix reduction | GPU/CPU |
| `poly_gcd` | Zippel modular GCD batch evaluation | GPU/CPU |
| `linalg` | Matrix multiply (f32 GPU), batch determinants, LU | GPU/CPU |
| `monte_carlo` | LCG Monte Carlo integration, n-dimensional | CPU |
| `ode` | RK4 parameter sweep (parallel runs) | CPU |
| `eval` | Bytecode expression evaluator | CPU |
| `simd` | Batch Horner eval, dot, norms, mat-vec, Lagrange, Welford stats | CPU |
| `discover` | GPU symbolic regression | GPU/CPU |
| `device` | Auto-detect: CUDA/ROCm/Metal/WebGPU/CPU | — |

---

## 📊 Test Coverage

| Crate | Unit | Integration | Total |
|-------|------|-------------|-------|
| symclaw-core | 1,279 | 54 | **1,333** |
| symclaw-quantum | 70 | 15 | **85** |
| symclaw-bio | 40 | 15 | **55** |
| symclaw-qchem | 38 | 15 | **53** |
| symclaw-materials | 47 | 16 | **63** |
| symclaw-gpu | 101 | — | **101** |
| symclaw-cli | 36 | — | **36** |
| symclaw-wasm | 11 | — | **11** |
| symclaw-ffi | 8 | — | **8** |
| symclaw-skill | 21 | — | **21** |
| symclaw-collab | 42 | — | **42** |
| **Total** | **1,693** | **115** | **1,808** |

All 1,808 tests pass. 0 failures. No files exceed 1,250 lines.

---

## 🆚 vs Competition

| Feature | SymClaw | Symbolica | Mathematica | SymPy |
|---------|---------|-----------|-------------|-------|
| GPU acceleration | ✅ 11 modules | ❌ | ❌ | ❌ |
| E-graph simplification | ✅ | ❌ | ❌ | ❌ |
| Symbolic regression (GPU) | ✅ | ❌ | ❌ | ❌ |
| Quantum computing module | ✅ | ❌ | partial | partial |
| Systems biology module | ✅ | ❌ | ❌ | ❌ |
| Quantum chemistry module | ✅ | ❌ | partial | partial |
| Crystallography module | ✅ | ❌ | partial | ❌ |
| Dimensional type system | ✅ | ❌ | ✅ | ✅ |
| Step-by-step proof traces | ✅ | ❌ | ❌ | ❌ |
| AI agent integration | ✅ | ❌ | ❌ | ❌ |
| Multi-user collab | ✅ | ❌ | ❌ | ❌ |
| Browser / WASM | ✅ | ❌ | ❌ | ❌ |
| C FFI | ✅ | ✅ | N/A | ❌ |
| Python bindings | ✅ | ✅ | N/A | N/A |
| Open source | ✅ MIT/Apache-2 | ❌ source-avail | ❌ commercial | ✅ BSD |

---

## 🛠️ Building

```bash
git clone https://github.com/osobh/symclaw && cd symclaw

# Build & test
cargo build --release
cargo test                    # runs all 1,808 tests

# CLI
cargo run -p symclaw-cli

# Python wheel (requires maturin)
cd crates/symclaw-python
maturin develop

# GPU backends (choose one at build time)
cargo build -p symclaw-gpu --features cuda    # NVIDIA
cargo build -p symclaw-gpu --features wgpu    # WebGPU / cross-platform (default)
cargo build -p symclaw-gpu --features cpu     # Software fallback (always available)
```

### Requirements

- **Rust** 1.75+ (MSRV)
- **Python** 3.8+ (for symclaw-python)
- **CUDA 12+** or **WebGPU-capable GPU** (optional, for GPU acceleration)

---

## 📄 License

Dual-licensed under [MIT](LICENSE-MIT) and [Apache 2.0](LICENSE-APACHE). Choose whichever suits you.

## Acknowledgements

- [**egg**](https://egraphs-good.github.io/) — E-graph equality saturation
- [**CubeCL**](https://github.com/tracel-ai/cubecl) — Cross-platform GPU compute kernels
- [**OpenClaw**](https://openclaw.com/) — Agentic AI platform and skill bridge
- [**nom**](https://crates.io/crates/nom) — Parser combinator framework
- [**PyO3**](https://pyo3.rs/) — Rust ↔ Python bindings

---

<p align="center">Built with 🦀 in Rust &nbsp;·&nbsp; 1,808 tests &nbsp;·&nbsp; 0 failures</p>