symclaw/ARCHITECTURE.md

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