lawsynth/docs/guide/README.md
caelum0x fab9a4a45a feat: reach + performance + docs — Python analysis client, parallel eval, sensitivity, guide
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.
2026-08-18 16:14:46 +03:00

3.5 KiB
Raw Permalink Blame History

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:

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.