caelum0x 728f42b82c
Some checks failed
Pull request checks / rust (push) Failing after 35s
Pull request checks / python (push) Failing after 40s
Pull request checks / typescript (push) Failing after 37s
Nightly scientific checks / scientific-fixtures (push) Failing after 40s
docs: cross-link Scribase/Toolgate ecosystem (Rithub discoverability pass, 2026-11-16)
2026-11-16 14:35:26 +00:00
2026-08-17 13:40:09 +03:00
2026-08-16 20:29:23 +03:00
2026-08-17 13:40:09 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-17 13:40:09 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-17 13:40:09 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-17 13:40:09 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 20:29:23 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00
2026-08-16 22:04:11 +03:00

LawSynth — turn observations into executable mathematical worlds

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.

License: Apache 2.0 Rust Python · TypeScript SDKs

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

LawSynth recovering the Lorenz system and simulating its trajectory

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 bare cargo fetch inherits 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._native extension with a plain cargo build: python/lawsynth/scripts/build-native.sh. Both paths produce an import-compatible module; import lawsynth then exposes the Study API.


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

LawSynth discovery pipeline

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:


License

Licensed under Apache-2.0. Third-party notices, when required, are recorded in NOTICE.

More from this account

Description
Open-source, deterministic tool that discovers interpretable governing equations (ODEs) from time-series CSV data — a local-first alternative to symbolic regression and SINDy
Readme Apache-2.0 Cite this repository 25 MiB
Languages
Rust 53.8%
Python 27.4%
TypeScript 16%
JavaScript 0.9%
HCL 0.6%
Other 1.3%