LawSynthGitHub

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-cli installs the

lawsynth binary; or run cargo run -p lawsynth-cli -- <args>).

  • Build the SDK's native extension (python/lawsynth/scripts/build-native.sh),

then import 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:

``bash lawsynth new lotka-volterra --data prey.csv --samples 400 ``

writes a real .lsworld template and a deterministic time,x,y CSV you can immediately discover.

Recipes

  1. Discover a model from a CSV — the core loop:

discover → explain → report.

  1. Clean noisy data before discovery —

profile → prep → discover, and how cleaning improves the fit.

  1. Pick the right settings per domain — presets and

recipes for physics / ecology / epidemiology / finance.

  1. Forecast and run what-ifs — forecast,

scenarios, and --confidence bands. (Read the intervention-semantics box.)

  1. How much can I trust it? — holdout validate,

rolling-origin backtest, and discover_ensemble term stability.

  1. Watch a live system for drift — monitor /

anomaly detection.

  1. Take your model elsewhere — export to

Python / C / ONNX-style graph / LaTeX / MATLAB / JSON.

  1. Organize & share your work — the library

registry, runs experiment tracking, and provenance.

  1. Automate a reproducible pipeline —

one pipeline.toml from CSV to validated, exported model.

  1. Use LawSynth as a service, and explore in Jupyter

— the Client + /v1 run workflow, the Study dashboard, and explore().

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@TIME and **`scenarios --scenario

NAME:k=v@t schedule a change to a parameter or a non-state input** at a given time. These target *named parameters* — which template worlds (from lawsynth new) carry, but discovered worlds do not (discovery inlines coefficients as constants). On a discovered world, use --initial` to change starting conditions instead.

  • SDK Study.forecast(...), add_scenario(...) and

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