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.
4.2 KiB
Determinism
Determinism is LawSynth's core differentiator. Discovery is a fixed, seeded computation: the same observations and the same configuration produce a byte-identical world bundle, every time, on any machine — no wall-clock reads, no unseeded randomness, no network. This is what makes a discovered world citable and auditable rather than a one-off result you can never reproduce.
The claim below is exactly what the tool guarantees and nothing more; the formal
contract is the reproducibility spec (data hash,
plan hash, algorithm version, seed plan, environment).
Demonstrate it: two runs, one file
Run discovery twice into different output paths, then compare the bytes:
lawsynth discover lotka-volterra.csv --time time --state x,y --preset ecology --output a.lsworld
lawsynth discover lotka-volterra.csv --time time --state x,y --preset ecology --output b.lsworld
shasum -a 256 a.lsworld b.lsworld
cmp a.lsworld b.lsworld && echo "BYTE-IDENTICAL"
7fdde728d3ecd68a6f6f0687e2a393e1006894c022740314f48c2d0fc081a18c a.lsworld
7fdde728d3ecd68a6f6f0687e2a393e1006894c022740314f48c2d0fc081a18c b.lsworld
BYTE-IDENTICAL
The two bundles hash to the same digest and cmp reports no differences. The
run_all.sh verification script performs exactly this cmp check and fails if
the two runs ever diverge.
The digest above is for this exact input (the shipped 200-sample
lotka-volterra.csv) and configuration (--preset ecology) built from the current workspace. Change the data, any flag, or the algorithm version and the digest changes — deliberately, because the world changed.
Simulation is deterministic too
simulate and forecast print trajectories at full 17-digit precision so
downstream tooling can diff them exactly:
lawsynth simulate a.lsworld --initial x=10 --initial y=5 --start 0 --end 2 --step 0.5
time,x,y
0.00000000000000000e0,1.00000000000000000e1,5.00000000000000000e0
5.00000000000000000e-1,5.65127591640327775e0,6.03519841161347159e0
1.00000000000000000e0,2.88374771443967415e0,6.06930302659370557e0
1.50000000000000000e0,1.56084342004881460e0,5.52822818892534595e0
2.00000000000000000e0,9.61564303591452840e-1,4.81134687372857694e0
Re-running the same command yields identical text. forecast --confidence takes
an explicit --seed, so even its bootstrap band is reproducible.
What is (and isn't) guaranteed
- Guaranteed: identical inputs + identical config + identical algorithm
version + identical binary → byte-identical
.lsworldand identical printed trajectories. Verified here byshasum/cmpand byrun_all.sh. - Not claimed: cross-version stability. A different LawSynth version may
change the algorithm and therefore the bytes; the
reproducibilityspec versions the algorithm so a digest is always interpreted against a known version. Floating-point results can also differ across fundamentally different hardware/math libraries; the spec documents a hardware class for this reason.
Self-validating domain presets
The curated domain presets are a built-in, deterministic round-trip: synthesize a textbook law's clean trajectory, discover from it, and report per-state RHS RMSE against the reference.
lawsynth domains run damped-oscillator
Round-trip recovery for preset 'damped-oscillator'
Damped linear harmonic oscillator: dx/dt = v, dv/dt = -x - 0.5 v.
Discovered law(s):
dv/dt = -0.999987 * x + -0.499985 * v
dx/dt = 0.999983 * v
Recovery vs. reference (clean trajectory):
x RHS RMSE=3.7257e-6 terms 1/1 (discovered/reference) -> recovered
v RHS RMSE=3.3642e-6 terms 2/2 (discovered/reference) -> recovered
Recovery: OK (every state within RMSE tolerance 1e-3 on clean data).
Note: round-trip is on clean synthetic data; it validates the search space, not noise robustness.
This is deterministic (no RNG, no clock) and doubles as a self-test: the preset
recovers its own reference law on clean data. The closing note is the honest
caveat — a good round-trip validates that the preset's search space contains the
reference law, not that discovery is robust to real measurement noise. See
domain-packs.