107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
# 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.
|