Getting started

This walkthrough takes you through the whole loop — install, discover, understand, use, share — with the real CLI commands and the equivalent Python SDK. Everything runs locally; no data leaves your machine.

1. Install

Install the CLI with Cargo, or the Python SDK with pip:

$ cargo install lawsynth-cli
$ pip install lawsynth

2. Discover

Point discover at a CSV, name the time column and the state variables whose dynamics you want to model, and write a .lsworld bundle:

$ lawsynth discover obs.csv --time t --state x,y --output world.lsworld

The same run from the Python SDK, using the fluent Study façade:

import lawsynth

study = lawsynth.Study.from_csv("obs.csv", time="t", state=["x", "y"])
result = study.discover()

for target, equation in result.equations.items():
    print(f"d{target}/dt = {equation}")

Discovery is tunable: add --regimes to detect regime switches, --pareto to report the accuracy/complexity frontier, --refine to jointly fit parameters, and --causal for dependency hypotheses.

3. Understand

explain turns a world into meaning: a plain-language description of each law, the dominant terms, discovered regimes, fit quality, and the assumptions a result is contingent on.

$ lawsynth explain world.lsworld

explanation = result.explain()
print(explanation.to_text())

4. Use

forecast runs the world forward beyond the observed window. Override parameters, set initial values, and schedule interventions to ask what-if:

$ lawsynth forecast world.lsworld --horizon 40 --step 0.05 \
    --initial x=1.0 --intervene y=0.5@20 --output forecast.csv

forecast = result.forecast({}, horizon=40, step=0.05)

5. Share

report renders a self-contained HTML report — rendered equations, fit and Pareto candidates, regime timeline, uncertainty bands, and inline SVG trajectory charts. No server, no external assets: one file a colleague can open.

$ lawsynth report world.lsworld --output report.html

result.report("report.html")
result.save("world.lsworld")  # the portable bundle everything else operates on

Next steps

• Reproduce a canonical system from the Examples gallery.

• Learn the vocabulary in Core concepts.

• Go beyond the loop: the Capabilities page covers analysis (stability, lyapunov, basins, invariants, bifurcation, sensitivity) and control (estimate, reduce, mpc).

• Diff two worlds or two scenarios with lawsynth compare, and keep a workspace navigable with lawsynth library.