symclaw/CLAUDE.md

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:

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):

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):

{"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.