# symclaw

> GPU-accelerated symbolic computing engine (CAS) with e-graph equality saturation — used throughout the platform for Hamiltonian algebra, constraint simplification, and symbolic regression.

## Problems It Solves

- Hamiltonian expressions for superconducting qubits are complex symbolic objects — simplification, differentiation, and constraint checking require a real CAS, not string manipulation
- GPU-accelerated polynomial GCD (Zippel/NTT) and Gröbner basis computation are unique capabilities not available in any other Rust CAS
- Provides multi-platform access (CLI, Python, WASM, REST, OpenClaw skill) so AI agents and web tools can do real math
- Dimensional analysis catches physics unit errors at compile/runtime

## What It's Comprised Of

| Crate | Role |
|-------|------|
| `symclaw-core` | 32 modules — complete symbolic engine: AST, parser, simplify, e-graph, diff, integrate, solve, series, limits, ODE, linalg, poly, GCD, tensor, discover, units, proof, codegen, eval, LaTeX, precision, transforms, pattern, streaming, SIMD |
| `symclaw-gpu` | 9 GPU modules via CubeCL (CUDA/ROCm/Metal/WebGPU/CPU fallback): poly_gcd, NTT, Gröbner, discover, eval, linalg, ODE, Monte Carlo |
| `symclaw-cli` | Interactive REPL with 20+ commands |
| `symclaw-python` | PyO3 bindings with full operator overloading |
| `symclaw-wasm` | 24 browser-ready exports via wasm-bindgen |
| `symclaw-skill` | OpenClaw AI agent bridge — 22 JSON-RPC actions |
| `symclaw-collab` | Multi-user WebSocket collaboration sessions |
| `benchmarks` | Criterion benchmarks |

**Total: 39K+ LOC, 1,170+ tests, 0 failures**

## Key APIs

**Rust library:**
```rust
parse("x^2 + 2*x + 1") -> Result<Expr>
simplify(&expr) -> Arc<Expr>           // e-graph equality saturation
differentiate(&expr, "x") -> Arc<Expr>
integrate(&expr, "x") -> Result<Arc<Expr>>
solve(&eq, "x") -> Result<Vec<Arc<Expr>>>
evaluate(&expr, &HashMap<String,f64>) -> f64
to_latex(&expr) -> String
to_code(&expr, "python") -> String    // python, c, rust, julia, js, glsl, wgsl
```

**CLI REPL:**
```
>> (x+1)^2           →  x^2 + 2*x + 1
>> :diff x^3 x       →  3*x^2
>> :limit sin(x)/x x 0  →  1
>> :codegen x^2 python  →  x**2
```

**Python (PyO3/maturin):**
```python
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
```

**OpenClaw skill (JSON-RPC stdin/stdout):**
```json
{"action": "simplify", "expr": "x^2 + 2*x + 1"}
→ {"success": true, "result": "(x + 1)^2", "latex": "(x + 1)^{2}"}
```

## Key Algorithms

1. **E-Graph Equality Saturation** (`egg` crate) — builds equivalence classes, applies 100+ rewrite rules, minimizes expression complexity
2. **Zippel Modular GCD** — sparse polynomial GCD without dense intermediates; evaluate modulo small primes → CRT reconstruction; 10–1000× faster than dense methods
3. **Number Theoretic Transform (NTT)** — GPU polynomial multiplication; 100–1000× speedup
4. **GPU F4 Gröbner Basis** — GPU row reduction; 10–100× speedup
5. **GPU Symbolic Regression** — genetic programming fitness evaluation on GPU; 50–100× speedup
6. **Dimensional Type System** — 7-vector SI base units; type-checks all operations

## GPU Performance Gains

| Module | Speedup |
|--------|---------|
| NTT polynomial multiply | 100–1000× |
| Zippel GCD evaluation | 10–100× |
| Gröbner basis (F4) | 10–100× |
| Symbolic regression | 50–100× |
| Monte Carlo integration | 50–500× |
| ODE parameter sweep | 10–100× |

## Platform Dependencies

- `egg` — e-graph
- `nom` — parser combinators
- `num`, `num-rational` — exact arithmetic
- `pyo3` — Python bindings
- `wasm-bindgen` — WASM exports
- CubeCL — GPU backend (CUDA/ROCm/Metal/WebGPU)

## Feeds Into

- **QPUDIDP** (`qpu-didp-physics`) — Hamiltonian constraint simplification, symbolic noise model regression, dimensional analysis
- **AI agents** — via `symclaw-skill` OpenClaw bridge (22 JSON-RPC actions)
- **Browser tools** — via WASM exports
- **Python workflows** — via PyO3 bindings

## Platform Role

**Layer 1 — Symbolic Mathematics Foundation.** symclaw is the math engine of the platform. Anywhere Hamiltonian expressions need to be manipulated symbolically — constraint checking in QPUDIDP, code generation for simulation scripts, dimensional analysis — symclaw provides it. The GPU acceleration makes it viable for production workloads, not just interactive use. It is also the AI agent math bridge via the OpenClaw skill.

## Current State

Production-ready, open source (MIT/Apache-2.0 dual license). 8 crates, 48 modules, 1,170+ tests. GPU modules validated on CUDA/ROCm/Metal/WebGPU.