# 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