Batch 7 of expansion-v2. Extends the product across surfaces and adds an
analysis primitive. Deterministic/offline/std-only (Rust) or graceful-absence
(Python).
python/lawsynth analysis.py (new): Python client for the engine's stability,
control, and domains analyses — shells out to the lawsynth CLI (--json) and
parses to typed dataclasses. No numerics re-implemented in Python; the Rust
engine is the single source of truth. Locates the binary like the benchmarks,
raises MissingBinaryError/CliError honestly, and is fully parse-testable
offline. 20 tests; full SDK suite 114 passed.
crates/lawsynth-features: opt-in std::thread-parallel feature-library
evaluation, bit-identical to serial for ALL thread counts (row-chunked via
thread::scope, ordered assembly, no parallel float reduction). Verified via
f64::to_bits across {1,2,3,4,7,8} threads x 10 library variants x uneven row
counts. Measured 3.6x at 8 threads; honestly sublinear (allocation-bound,
~few-thousand-row crossover). 28 tests + benchmark.
crates/lawsynth-sensitivity (new): forward sensitivity analysis. Integrates the
variational equations Ṡ_j = J_x·S_j + f_θj (J_x from the analytic Jacobian, f_θ
by symbolic differentiation) on the augmented system with fixed-step RK4.
Analytic check to <1e-6; finite-difference cross-check at 1e-6 for every
parameter on logistic + Lotka-Volterra. 22 tests.
docs/guide (new): verified end-to-end guide — getting-started, workflow
(discover→simplify→stability→control→export→validate→uncertainty), and a
determinism demo. All 17 documented commands run exit-0 via run_all.sh; honest
about real behaviors (already-minimal law simplifies to 0 nodes saved, CLI
bootstrap doesn't surface per-coef intervals, center points are inconclusive).
README links the guide.
specs/{parallel-evaluation,sensitivity-analysis}: boundary specs.
LawSynth guide
A cohesive, end-to-end walkthrough of LawSynth: build the CLI, discover a governing-equation world from a CSV, then simplify, analyze, control, export, and quantify uncertainty — every command verified against the current build.
LawSynth is a deterministic, offline, Rust-first toolkit that discovers governing
equations from time-series data and packages them as executable .lsworld
worlds. Nothing in this guide touches the network, and every run is reproducible.
Pages
| Page | What it covers |
|---|---|
| getting-started.md | Build lawsynth-cli, the core concept, and a first discover → explain → simulate run on a shipped dataset. |
| workflow.md | The full pipeline: discover → simplify → stability → control → export → validate → uncertainty, each a real command with real output. |
| determinism.md | Why re-running discovery yields a byte-identical world, shown with shasum/cmp, plus what is and isn't guaranteed. |
Runnable examples
Everything shown in these pages is executable and CI-checkable:
| File | Purpose |
|---|---|
examples/run_all.sh |
Runs every documented command against the built binary and asserts each exits 0. Locates the binary via $LAWSYNTH_BIN → target/debug → target/release → cargo run. |
examples/lotka-volterra.csv |
Deterministic 200-sample predator–prey dataset (regenerate with lawsynth new lotka-volterra ... --samples 200). |
examples/forced-oscillator.csv |
Deterministic forced (controlled) dataset for lawsynth control. |
examples/gen_forced_oscillator.py |
Pure-math, RNG-free generator for the forced dataset (byte-reproducible). |
Run the whole guide as a test:
bash docs/guide/examples/run_all.sh
Boundary specifications
This guide links each feature to its specs/ contract for the honest limits and
semantics of that feature (it does not restate the math). Key contracts:
discovery-run,template-priors— discovery and candidate-library contracts.simulation-contract— solver, time-grid, and trajectory semantics.egraph-simplification,structural-reductions— simplification.stability-analysis,analytic-jacobian— fixed points and classification.controlled-discovery,control-design— forced-system (SINDYc) discovery.uncertainty-contract,coefficient-uncertainty— confidence bands and coefficient uncertainty.reproducibility— determinism, hashing, and versioning.domain-packs— curated, self-validating domain presets.
See specs/README.md for the full contract index.
Authoritative command list
lawsynth help prints the subcommands your build actually ships. If a capability
appears in specs/ but not in lawsynth help (e.g. bifurcation analysis,
implicit/DAE dynamics), it is a library crate rather than a CLI command — this
guide documents only what the CLI exposes today.