symclaw/README.md

🔮 SymClaw — Symbolic Computing for the Agentic Age

A GPU-accelerated, AI-integrated computer algebra system built in Rust.

65,000+ lines of Rust  ·  1,808 tests (0 failures)  ·  12 crates  ·  11 GPU modules

---

✨ 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
• 🤖 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

# 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

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

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)

// 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

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 and Apache 2.0. Choose whichever suits you.

Acknowledgements

• egg — E-graph equality saturation
• CubeCL — Cross-platform GPU compute kernels
• OpenClaw — Agentic AI platform and skill bridge
• nom — Parser combinator framework
• PyO3 — Rust ↔ Python bindings

---

Built with 🦀 in Rust  ·  1,808 tests  ·  0 failures