Wave 10 — rigor & sharing: CLI — lawsynth backtest (rolling-origin/walk-forward: N origins x horizon, per-state RMSE/MAE/R2 + skill-vs-horizon decay + verdict, --html report); lawsynth workspace export/import (portable .lsworkspace archive: world bytes + provenance + runs, per-entry SHA-256 integrity, non-destructive import). SDK — Study.backtest -> Backtest (skill-vs-horizon decay, deterministic); lawsynth.Project workspace persisting in the CLI library.tsv format (verified bidirectional CLI<->SDK interop) with export/import archives. Docs — a real cookbook (10 task recipes, CLI + SDK each) + 3 end-to-end tutorials, verified against the shipped source (two-intervention-semantics and preset-vs-recipe differences called out). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cookbook
Task-oriented recipes for LawSynth. Each page is short and copy-pasteable, and gives you both a CLI recipe and its Python-SDK equivalent, with the expected shape of the output.
Everything LawSynth does is deterministic and offline: the same inputs reproduce the same worlds, reports, forecasts, and IDs, with no network access and no wall clock. Where output is shown, it is a representative shape — exact numbers depend on your data and your build of the native engine.
Before you start
-
Build the CLI (
cargo install --path crates/lawsynth-cliinstalls thelawsynthbinary; or runcargo run -p lawsynth-cli -- <args>). -
Build the SDK's native extension (
python/lawsynth/scripts/build-native.sh), thenimport lawsynth. -
Check your install with
lawsynth doctor. -
Need sample data? Every recipe below can run on a synthetic system generated by
lawsynth new— no external files required. For example:lawsynth new lotka-volterra --data prey.csv --samples 400writes a real
.lsworldtemplate and a deterministictime,x,yCSV you can immediatelydiscover.
Recipes
- Discover a model from a CSV — the core loop:
discover → explain → report. - Clean noisy data before discovery —
profile → prep → discover, and how cleaning improves the fit. - Pick the right settings per domain — presets and recipes for physics / ecology / epidemiology / finance.
- Forecast and run what-ifs —
forecast,scenarios, and--confidencebands. (Read the intervention-semantics box.) - How much can I trust it? — holdout
validate, rolling-originbacktest, anddiscover_ensembleterm stability. - Watch a live system for drift —
monitor/ anomaly detection. - Take your model elsewhere — export to Python / C / ONNX-style graph / LaTeX / MATLAB / JSON.
- Organize & share your work — the
libraryregistry,runsexperiment tracking, and provenance. - Automate a reproducible pipeline —
one
pipeline.tomlfrom CSV to validated, exported model. - Use LawSynth as a service, and explore in Jupyter
— the
Client+/v1run workflow, theStudydashboard, andexplore().
Longer walkthroughs
For narratives that chain many of these steps into one story, see the tutorials.
A note on two intervention semantics
LawSynth has two distinct ways to ask "what if?", and they are not the same:
- CLI
forecast --intervene NAME=VALUE@TIMEandscenarios --scenario NAME:k=v@tschedule a change to a parameter or a non-state input at a given time. These target named parameters — which template worlds (fromlawsynth new) carry, but discovered worlds do not (discovery inlines coefficients as constants). On a discovered world, use--initialto change starting conditions instead. - SDK
Study.forecast(...),add_scenario(...)andcompare_scenarios()override initial conditions on state variables — every scenario starts the same dynamics from a different starting point.
Each recipe uses the correct one for its surface; the forecast recipe explains the difference in detail.