LawSynth
Discover interpretable governing equations from time-series data. Point LawSynth at a CSV and it recovers the law system behind the numbers — a world you can read, simulate, stress-test, and share.
Read the equations, not a black box. Every result is explicit differential equations, not opaque weights — computed deterministically and offline, so the same inputs reproduce the same world, every time. A local-first, open-source alternative to black-box ML and to symbolic-regression / SINDy pipelines.
lawsynth.dev · Documentation · Getting started · GitHub · Contributing · Apache-2.0
What is this? (30 seconds)
You have measurements. LawSynth discovers the equations behind them — a sparse
system of state laws (dx/dt = …) recovered directly from a CSV — and hands you a
portable .lsworld bundle you can understand, run forward, intervene on, compare,
and share as a single self-contained HTML report.
It is a mechanistic model, not a black box: every result is a set of equations you can read. Discovery is deterministic (identical inputs and options reproduce the same world) and offline (no data leaves your machine).
The whole product is one loop:
observe (CSV) → discover (laws) → understand (explain) → use (simulate / forecast /
intervene) → compare → share (report / .lsworld bundle) → organize (library)
Install
LawSynth is a Rust workspace with a Python SDK. The core CLI builds from source:
# Build and install the `lawsynth` binary
cargo install --path crates/lawsynth-cli
# ...or run it in place during development
cargo run -p lawsynth-cli -- --help
Cargo is configured offline by default (
[net] offline = true) for reproducible local builds. A barecargo fetchinherits that setting and still fails with "attempting to make an HTTP request, but --offline was specified". On a fresh machine, first populate the registry cache with offline mode disabled —CARGO_NET_OFFLINE=false cargo fetch— then build normally. See docs/getting-started/installation.md.
Python SDK (builds the native extension with maturin):
cd python/lawsynth
python -m pip install maturin
maturin develop
Offline or maturin-free machines can build the same
lawsynth._nativeextension with a plaincargo build:python/lawsynth/scripts/build-native.sh. Both paths produce an import-compatible module;import lawsynththen exposes theStudyAPI.
Quickstart — the core loop end to end
Start with a numeric CSV: a header, a strictly increasing finite time column, and
one or more finite state columns (here x,y).
CLI
# 1. Discover the law system and write a portable .lsworld bundle
lawsynth discover observations.csv --time time --state x,y --output world.lsworld
# 2. Understand what it found (readable laws, dependencies, assumptions)
lawsynth explain world.lsworld
# 3. Use it: forecast beyond the observed window, with an optional what-if
lawsynth forecast world.lsworld --horizon 20 --step 0.05 --output forecast.csv
# 4. Share it: a single self-contained HTML report, no server, no external assets
lawsynth report world.lsworld --output report.html
Python (Study — the same loop, fluently)
import lawsynth
study = lawsynth.Study.from_csv("observations.csv", time="time", state=["x", "y"])
result = study.discover() # discover the executable world
print(result.explain()) # readable laws, fit quality, dependencies, assumptions
study.forecast({"x": 1.5}) # what-if: override an initial condition vs. baseline
study.add_scenario("hot", interventions={"x": 2.0})
study.add_scenario("cold", interventions={"x": 0.5})
study.compare_scenarios() # overlay scenarios against the baseline
study.report("report.html") # self-contained HTML report
study.save("world.lsworld") # portable bundle the CLI/Studio also read
Every object (Study, DiscoveryResult, Explanation, Forecast,
ScenarioComparison, trajectories, and the native World) renders richly in a
Jupyter notebook.
Feature matrix (by the product loop)
Every capability below is shipped and works against the same validated World IR and
.lsworld bundles.
Discover
| CLI | lawsynth discover OBS.{csv,tsv,parquet} --time COL --state x,y --output world.lsworld — polynomial --degree, --threshold, --solver stlsq|sr3, --trigonometric, --rational, derivative estimators (--spline, --spectral, --savgol-window, --tvreg-lambda), --smooth-radius, --bootstrap, --symbolic-depth, --regimes, --pareto, --refine, --causal |
| SDK | Study.from_csv(...).discover(), lawsynth.discover(time, columns, state=...), DiscoveryConfig |
| Studio | Data Lens (profile the dataset), Discovery Canvas (configure a run, inspect candidate laws) |
Understand
| CLI | lawsynth explain world.lsworld, lawsynth inspect world.lsworld |
| SDK | study.explain() / result.explain() → Explanation (readable laws, fit R²/RMSE, dependency graph, assumptions) |
| Studio | Equation Explorer, Structure Map (variable coupling), Regime Timeline, Uncertainty Lens |
Use
| CLI | lawsynth simulate / lawsynth simulate-discrete (RK4 + discrete stepping, scheduled --parameter-at TIME:NAME=VALUE / --input-at interventions), lawsynth forecast --horizon T --intervene NAME=VALUE@TIME |
| SDK | study.simulate(...), study.forecast({state: value}, horizon=..., step=...) → Forecast (baseline vs. counterfactual + divergence) |
| Studio | World Lab (simulate, forecast, intervene) |
Compare
| CLI | lawsynth compare A.lsworld B.lsworld [--json] [--html FILE], lawsynth scenarios world.lsworld --scenario NAME[:k=v@t,...] [--html FILE] |
| SDK | study.add_scenario(label, interventions=...), study.compare_scenarios() → ScenarioComparison |
| Studio | Scenario Board (overlay what-ifs against a baseline) |
Share
| CLI | lawsynth report world.lsworld --output report.html, lawsynth export world.lsworld --format python|latex|json |
| SDK | study.report("report.html"), study.save("world.lsworld"), notebook StudyDashboard |
| Studio | Export (equations, LaTeX, Python, raw World IR) |
Organize
| CLI | lawsynth library <add|list|show|remove> [--dir DIR] — tag, describe, and search a local world library (index defaults to ~/.lawsynth/library.tsv) |
| SDK | Study.save(...) / Study.load(...) for .lsworld round-trips |
Explore & scaffold
| CLI | lawsynth templates, lawsynth new TEMPLATE [--output world.lsworld] [--data obs.csv] [--samples N] (built-in worlds: lorenz, lotka-volterra, pendulum, van-der-pol, sir), lawsynth validate world.lsworld --data obs.csv [--holdout FRACTION], lawsynth pipeline PIPELINE.toml | lawsynth pipeline --example, lawsynth doctor |
| SDK | Study.from_source(kind, resource, ...) / lawsynth.load_source(...) — import from filesystem, http, s3, postgres, sqlite connectors |
| Studio | 9 navigable screens driven by shared TypeScript packages |
Surfaces
| Surface | For | Entry point |
|---|---|---|
| CLI | power users, automation, CI | lawsynth <command> (crates/lawsynth-cli) |
| Python SDK | notebooks, pipelines | import lawsynth → Study (python/lawsynth) |
| Studio | interactive exploration | 9 screens (apps/studio) |
| Services | teams, self-hosting | /v1 HTTP API (services/api) |
| Applied labs | measured grid and cascade workflows | GridSynth (apps/gridsynth), information diffusion (apps/information-diffusion) |
All four operate on the same validated World IR and .lsworld bundles. A
discovery made in the CLI opens in the SDK, renders in Studio, and serves from the API.
HTTP product endpoints
The API mirrors the product loop over its stored worlds, backed by the same native engine as the CLI/SDK:
| Method | Path | Action |
|---|---|---|
GET |
/v1/worlds/{id}/explain |
structured explanation (laws, dependencies, complexity, assumptions) |
POST |
/v1/worlds/{id}/forecast |
simulate-backed forecast honouring scheduled interventions |
GET |
/v1/worlds/{id}/report |
self-contained HTML report |
POST |
/v1/worlds/compare |
structured diff of two worlds |
POST |
/v1/worlds/{id}/simulate |
RK4 simulation |
explain / report / compare read declarative structure and work offline;
forecast / simulate require the compiled native engine (and return a clear
503 native_unavailable otherwise). See services/api/docs/api.md.
How it works
Multivariate observations flow through derivative reconstruction (finite
differences, Savitzky–Golay, natural cubic spline, spectral, or total-variation
regularization), a feature library (polynomial, optional trigonometric and
bounded rational terms), and sparse regression (STLSQ or SR3) into a validated
World IR. That IR compiles to a portable .lsworld bundle and to a deterministic
simulation. Optional stages add a Pareto complexity/accuracy frontier, regime
segmentation, parameter refinement, bootstrap uncertainty, and causal hypotheses.
Principles
- Interpretable first. If you can't read and reason about the result, it isn't a LawSynth result.
- Local-first & reproducible. Same inputs → same world, offline, forever.
- Honest about uncertainty. Fit quality, assumptions, and the fact that extrapolation beyond the observed window is not validated are surfaced, never hidden. Discovery finds a sparse fit — it is not proof that a relation is causal.
- Composable. CLI, SDK, Studio, and services share one World IR and bundle format.
Documentation
The full documentation is published at lawsynth.dev/docs — a
deterministic, offline-built static site (the same values LawSynth stands on). It renders
the entire docs/ tree below, plus a hand-written getting-started
walkthrough, a complete CLI reference for every
subcommand, a capabilities tour of the discover →
analyze → control → share pillars, and the core concepts
vocabulary. Everything is cross-linked and searchable; the site itself is generated from a
tested TypeScript SSG in apps/docs-site.
Browse it on the site, or read the source Markdown here on GitHub:
- Getting started — installation · quickstart · your first world · CLI · Python · Studio
- Guide — verified end-to-end CLI walkthrough (discover → simplify → stability → control → export) with a determinism demo
- Product overview — what a user actually does with LawSynth
- Reference — CLI, Python, and Rust API references
- Methods — differentiation, simulation, and causal method notes
- Self-hosting — running the services surface
- Architecture · Contributing · Changelog
License
Licensed under Apache-2.0. Third-party notices, when required, are recorded in NOTICE.
More from this account
- Scribase — hosted Postgres, one backend instead of stitching together Supabase + Neon + Clerk + Resend
- Toolgate — one key for agent tools, pay only for what you call
- All repos: git.ereboslab.com/caelum0x
