118 lines
6.5 KiB
Markdown
118 lines
6.5 KiB
Markdown
# SymClaw Architecture
|
||
|
||
## Overview
|
||
|
||
SymClaw is an 8-crate Rust workspace with 48 modules and 9 GPU compute kernels.
|
||
|
||
## Crate Dependency Graph
|
||
|
||
```
|
||
symclaw-core (0 internal deps — the foundation)
|
||
├── symclaw-gpu (core)
|
||
├── symclaw-skill (core)
|
||
├── symclaw-wasm (core)
|
||
├── symclaw-python (core)
|
||
├── symclaw-cli (core, gpu, skill)
|
||
└── symclaw-collab (core, skill)
|
||
```
|
||
|
||
## Data Flow
|
||
|
||
```
|
||
Input text
|
||
→ parser::parse() — nom combinators → Arc<Expr> AST
|
||
→ simplify::simplify() — multi-pass: constant fold → identity → like-terms → e-graph
|
||
→ [operation] — differentiate / integrate / solve / series / limits / transforms
|
||
→ codegen / latex / eval — output rendering
|
||
```
|
||
|
||
All operations consume and produce `Arc<Expr>`, enabling zero-copy sharing and structural deduplication.
|
||
|
||
## Core Modules (32)
|
||
|
||
### Symbolic Engine
|
||
- **ast** — `Arc<Expr>` expression tree. Variants: `Num`, `Var`, `BinaryOp`, `UnaryOp`, `Func`, `Matrix`, `Tensor`. Canonical ordering for deterministic simplification.
|
||
- **parser** — nom-based parser. Infix operators, implicit multiplication, function calls, matrix literals.
|
||
- **simplify** — Pipeline: constant folding → identity elimination → like-term collection → e-graph saturation (optional).
|
||
- **egraph** — egg-based equality saturation with 30+ rewrite rules. Explanation mode for proof generation.
|
||
- **differentiate** — All elementary functions, chain rule, higher-order, partial derivatives.
|
||
- **integrate** — Power rule, trig, exponential, u-substitution, integration by parts, linearity.
|
||
- **solve** — Linear, quadratic, polynomial (rational root theorem), trig, exponential, 2×2 systems.
|
||
- **series** — Taylor/Maclaurin expansion. Fast-path for sin, cos, exp, ln; general differentiation fallback.
|
||
- **limits** — 7 strategies: direct substitution, factoring, L'Hôpital, Taylor, conjugate, growth rate, squeeze.
|
||
- **transforms** — Laplace and Fourier transforms with pattern-based lookup tables.
|
||
- **pattern** — Multi-wildcard pattern matching with conditions, type filters, and commutative awareness.
|
||
- **ode** — First-order ODE solver (separable, linear, exact, Bernoulli).
|
||
|
||
### Algebra
|
||
- **poly** — Sparse multivariate polynomials. Lex, DegLex, DegRevLex orderings. Arithmetic, division, GCD.
|
||
- **modular_gcd** — Zippel's sparse modular GCD. Modular homomorphism, CRT reconstruction, leading coefficient correction.
|
||
- **packed_poly** — FORM-inspired flat byte-buffer polynomial representation. 4-8× less memory than tree form.
|
||
- **linalg** — Matrix type with determinant, inverse, LU decomposition, eigenvalues (QR iteration).
|
||
- **tensor** — Symbolic tensors with Einstein summation convention, index contraction, Minkowski metric.
|
||
- **number_theory** — 30+ functions: primality, factorization, totient, Möbius, CRT, Fibonacci, Bernoulli numbers.
|
||
- **precision** — BigFloat arbitrary precision, error propagation, finite fields GF(p).
|
||
|
||
### Novel Features
|
||
- **discover** — Symbolic regression via genetic programming. Fitness = accuracy + parsimony. GPU-accelerable.
|
||
- **units** — Dimensional analysis with SI 7-vector (m, kg, s, A, K, mol, cd). Type-checked arithmetic.
|
||
- **proof** — Step-by-step proof traces. Each simplification step recorded with rule name. LaTeX/Markdown export.
|
||
- **symbols** — Symbol attributes: real, positive, integer, symmetric, antisymmetric, linear. Tag system.
|
||
- **confidence** — Heuristic confidence scoring for expression correctness.
|
||
|
||
### Infrastructure
|
||
- **codegen** — Code generation for 7 targets: Python, C, Rust, Julia, JavaScript, GLSL, WGSL.
|
||
- **streaming** — Compact binary encoding (variable-length integers), file I/O, streaming expression iterators.
|
||
- **simd_arith** — Montgomery multiplication, batch modular addition/multiplication. AVX2 when available.
|
||
- **eval** — IEEE 754 numeric evaluation with variable substitution maps.
|
||
- **latex** — Publication-quality LaTeX rendering (fractions, roots, Greek letters, matrices).
|
||
- **cache** — LRU expression cache keyed by structural hash.
|
||
- **metrics** — Prometheus-compatible counters/histograms for operation timing.
|
||
- **interner** — String interning for efficient variable name comparison.
|
||
|
||
## GPU Architecture (9 Modules)
|
||
|
||
All GPU modules use [CubeCL](https://github.com/tracel-ai/cubecl) for cross-platform compute:
|
||
|
||
```
|
||
Feature flag Backend
|
||
───────────── ──────────────────
|
||
cuda NVIDIA CUDA
|
||
rocm AMD ROCm
|
||
wgpu (default) WebGPU/Vulkan/Metal
|
||
cpu CubeCL software runtime
|
||
```
|
||
|
||
### Module Details
|
||
- **device** — Runtime detection, backend selection, device handle caching.
|
||
- **eval** — Compile AST → bytecode → GPU kernel. Batch evaluate expressions over parameter grids.
|
||
- **linalg** — GPU matrix multiply, used by other modules internally.
|
||
- **ode** — Parallel RK4 parameter sweeps. Each GPU thread integrates one parameter set.
|
||
- **monte_carlo** — GPU-parallel Monte Carlo integration with Philox PRNG.
|
||
- **ntt** — Number Theoretic Transform for polynomial multiplication. O(n log n) on GPU.
|
||
- **poly_gcd** — Batch multi-point polynomial evaluation for Zippel GCD reconstruction.
|
||
- **groebner** — F4 algorithm with GPU-accelerated row reduction of Macaulay matrices.
|
||
- **discover** — GPU fitness evaluation for symbolic regression populations.
|
||
|
||
## Key Design Decisions
|
||
|
||
| Decision | Rationale |
|
||
|----------|-----------|
|
||
| `Arc<Expr>` everywhere | Zero-copy sharing, structural dedup, safe concurrency |
|
||
| egg for e-graphs | Mature Rust library, explanation mode enables proof traces |
|
||
| CubeCL for GPU | Single codebase for CUDA/ROCm/WebGPU/Metal/CPU |
|
||
| nom for parsing | Zero-allocation, composable, excellent error messages |
|
||
| Sparse polynomial repr | Symbolic math polynomials are typically sparse |
|
||
| Montgomery multiplication | Fastest modular arithmetic for repeated operations |
|
||
| PyO3 for Python | Direct Rust↔Python with operator overloading |
|
||
| Workspace of small crates | Compile only what you need; WASM doesn't pull GPU code |
|
||
|
||
## Testing Strategy
|
||
|
||
- **Unit tests** — per-module, testing individual functions
|
||
- **Property tests** — proptest for algebraic identities (d/dx of integral = original, etc.)
|
||
- **Integration tests** — cross-module workflows (parse → simplify → differentiate → LaTeX)
|
||
- **E2E tests** — CLI, WASM, and skill action round-trips
|
||
- **GPU tests** — correctness validation against CPU reference implementations
|
||
- **1,170+ tests total**, 0 failures
|