Wave 5 — approachability & front door: CLI — discover --preset (physics/ecology/epidemiology/finance/general) + presets catalog; explicit flags override presets. library becomes a provenance-aware workspace: world/data content hashes, columns, config, tags captured on add; library search + compare over the workspace (backward-compatible index). SDK — lawsynth.recipes (parity with CLI presets) + Study.discover(recipe=..., **overrides); three runnable domain demos. Van der Pol shows the payoff: general recipe misses the cubic term, mechanics recipe recovers -x+v-x^2*v (R2 0.99995). Docs — a real product README (hero + Lorenz GIF, CLI+Python quickstart, feature matrix by product loop, surfaces + HTTP endpoints, honest tone); refreshed getting-started pages and a CHANGELOG Unreleased section. All flags verified against the shipped CLI usage. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
95 lines
3.1 KiB
Markdown
95 lines
3.1 KiB
Markdown
# Quickstart: the core loop end to end
|
|
|
|
This walks the full **discover → understand → use → share** loop on a two-state
|
|
system. Substitute your own columns for `x,y`.
|
|
|
|
## 1. Prepare observations
|
|
|
|
Create a numeric CSV with a header, a strictly increasing finite `time` column, and
|
|
one or more finite state columns. For example `observations.csv`:
|
|
|
|
```csv
|
|
time,x,y
|
|
0,1,0
|
|
0.05,0.998,0.099
|
|
0.10,0.990,0.197
|
|
```
|
|
|
|
CSV, TSV, and a numeric Parquet subset are accepted (`.csv`, `.tsv`, `.parquet`).
|
|
|
|
## 2. Discover the law system
|
|
|
|
```sh
|
|
lawsynth discover observations.csv \
|
|
--time time --state x,y --output world.lsworld
|
|
```
|
|
|
|
`discover` writes a portable `.lsworld` bundle and prints the fit (mean squared
|
|
error) and complexity. Useful options: `--degree N`, `--threshold VALUE`,
|
|
`--solver stlsq|sr3`, `--trigonometric`, `--rational`, one derivative estimator
|
|
(`--spline`, `--spectral`, `--savgol-window ODD_N`, or `--tvreg-lambda VALUE`),
|
|
`--smooth-radius N`, `--bootstrap REPLICATES`, `--symbolic-depth N`, and the
|
|
optional stages `--regimes`, `--pareto`, `--refine`, `--causal`.
|
|
|
|
## 3. Understand what it found
|
|
|
|
```sh
|
|
lawsynth explain world.lsworld
|
|
lawsynth inspect world.lsworld
|
|
```
|
|
|
|
`explain` prints the readable laws, their dominant terms, the dependency structure,
|
|
and the assumptions a result is contingent on. `inspect` reports state, variable,
|
|
and parameter counts and distinguishes continuous from discrete worlds.
|
|
|
|
## 4. Use it: simulate and forecast
|
|
|
|
```sh
|
|
# Simulate over a fixed window
|
|
lawsynth simulate world.lsworld --initial x=1 --initial y=0 \
|
|
--start 0 --end 10 --step 0.05
|
|
|
|
# Forecast beyond the observed window
|
|
lawsynth forecast world.lsworld --horizon 20 --step 0.05 --output forecast.csv
|
|
```
|
|
|
|
Interventions are first-class and *scheduled*: `--parameter-at TIME:NAME=VALUE` and
|
|
`--input-at TIME:NAME=VALUE` on `simulate`, and `--intervene NAME=VALUE@TIME` on
|
|
`forecast`. Each targets a **parameter or a non-state input** at a given time — for
|
|
example `--intervene beta=0.2@5` on an SIR world.
|
|
|
|
## 5. Compare
|
|
|
|
Diff two worlds directly:
|
|
|
|
```sh
|
|
lawsynth compare world.lsworld other.lsworld --html compare.html
|
|
```
|
|
|
|
Or overlay named what-if scenarios (each a set of scheduled interventions) against a
|
|
baseline over one horizon:
|
|
|
|
```sh
|
|
lawsynth scenarios world.lsworld --horizon 20 --step 0.05 \
|
|
--scenario mitigated:beta=0.2@5 --scenario surge:beta=0.6@5 --html scenarios.html
|
|
```
|
|
|
|
The Python `Study` API also offers scenario boards keyed by *initial-condition*
|
|
overrides (`study.add_scenario("hot", interventions={"x": 2.0})`) — see
|
|
[python.md](python.md).
|
|
|
|
## 6. Share
|
|
|
|
```sh
|
|
lawsynth report world.lsworld --output report.html
|
|
lawsynth export world.lsworld --format python --output world_model.py
|
|
```
|
|
|
|
`report` is a single self-contained HTML file — rendered equations, fit, regime
|
|
timeline, uncertainty bands, and inline SVG charts, with no server or external
|
|
assets. `export` emits a dependency-free Python module, a LaTeX `align*` block, or a
|
|
documented JSON description.
|
|
|
|
Discovery is deterministic for identical input and options: rerun any step and you
|
|
get exactly the same world, report, and forecast.
|