caelum0x 8bae186f19 feat(product): rolling-origin backtest, portable workspaces, cookbook
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>
2026-08-17 23:46:25 +03:00
..

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:

    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.
  2. Clean noisy data before discovery — profile → prep → discover, and how cleaning improves the fit.
  3. Pick the right settings per domain — presets and recipes for physics / ecology / epidemiology / finance.
  4. Forecast and run what-ifs — forecast, scenarios, and --confidence bands. (Read the intervention-semantics box.)
  5. How much can I trust it? — holdout validate, rolling-origin backtest, and discover_ensemble term stability.
  6. Watch a live system for drift — monitor / anomaly detection.
  7. Take your model elsewhere — export to Python / C / ONNX-style graph / LaTeX / MATLAB / JSON.
  8. Organize & share your work — the library registry, runs experiment tracking, and provenance.
  9. Automate a reproducible pipeline — one pipeline.toml from CSV to validated, exported model.
  10. 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.