keplearn

keplearn [--target NAME] [--top-k N] [--sample N] [--quick-n N] [--timeout MS] [-o FILE] [--pretty] [--max-depth D] [--trace FILE] [--dump-candidates FILE] < table

keplearn is a single-binary symbolic regression engine. It reads a TSV or CSV table with a header row on stdin, treats one named column as the quantity to explain, and searches for a compact closed-form expression of that column in terms of the others. The delimiter is taken from the header: tab if a tab is present, otherwise comma.The search is deterministic best-first recursive reduction: the same input produces the same output. Exact laws often finish in milliseconds. Fitted constants snap to nearby rationals and to multiples of pi, e, and sqrt(2), and a snap is kept only when a verification pass still scores as well. The reported r2 comes from evaluating the printed model string on the supplied data, not from an internal fitting stage.Stdout is always one JSON object (parse from the first `{`). Diagnostics go to stderr. Feature columns are named x1..xN in file order with the target excluded. Candidates arrive best-first: the first result's model field is the answer. The stopped-by field is one of exact-exit, frontier-exhausted, or timeout.The engine targets analytic laws (ratios, powers, trig, exp/log). On noisy black-box tables the best model may still carry a low r2; that is the intended trade-off, not a crash. Input larger than 1 GiB is rejected. If stdin is a terminal, keplearn prints a usage hint and exits 2.

--target NAME

Target column to predict. Default: `target`. Every other column is a feature.

Number of candidate models to emit, best-first (default: 10, minimum: 1).

Maximum training rows used by the search (default: 500, minimum: 1).

Rows for the quick pre-probe (default: 50, minimum: 1).

Wall-clock budget in milliseconds. On expiry the best-so-far result is emitted. Default: 0 (unbounded).

Write the result JSON to FILE instead of stdout.

Indent the result JSON for reading.

Clamp search depth downward. Default is the compiled maximum.

Append a JSONL event trace to FILE.

Write the full scored candidate list to FILE.

Accepted for compatibility. Unused. Output is deterministic; `--seed` has no effect.

Print help, including the output schema, and exit.

Print `keplearn` and the package version, then exit.

keplearn expects a headered table on stdin. Piping is required; running it with no redirect on a terminal exits 2.Base any downstream decision on r2 or holdout r2 rather than the internal search r2. On noisy data the search score can sit far above the score of the printed string.With many columns, run subsets of 2-5 at a time. Irrelevant columns often fit to exponent 0 and drop out, but conditioning worsens as they accumulate. Column order has no effect.`--timeout 0` is unbounded. For batch runs the help text recommends `--timeout 60000`.`--seed` and `--max-evals` are parsed and ignored. Several other legacy flags (`--pool`, `--reject`, `--prune-cols`, `--reeval-cap`, `--max-arity`, `--compose`) are also accepted and discarded.

Keplearn is a MIT-licensed Rust program by Chandler Freeman (owls-on-wires). The name refers to Johannes Kepler recovering planetary laws from Tycho Brahe's tables. Version 0.1.2 is the crate version at the time of this page. The method is included in SRBench, the standard symbolic regression benchmark.

mlr(1), jq(1), csvstat(1), datamash(1)

Source code