Metadata-Version: 2.4
Name: srbf
Version: 0.15.0
Summary: srbf: Symbolic Regression Benchmark Framework (Benchmark driver, model adapters, metrics) over symbolic-data catalogs and flash-ansr.
Author: Paul Saegert
License-Expression: MIT
Project-URL: Repository, https://github.com/psaegert/srbf
Project-URL: Issues, https://github.com/psaegert/srbf/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES
Requires-Dist: scipy>=1.9
Requires-Dist: flash-ansr<0.16,>=0.15
Requires-Dist: simplipy<0.15,>=0.14.6
Requires-Dist: symbolic-data<0.19,>=0.18
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.3
Requires-Dist: scikit-learn>=1.0
Requires-Dist: torch>=2.0
Requires-Dist: tqdm
Requires-Dist: pyyaml
Requires-Dist: zss
Requires-Dist: editdistance
Provides-Extra: baselines
Requires-Dist: sympy>=1.10; extra == "baselines"
Requires-Dist: pysr; extra == "baselines"
Requires-Dist: omegaconf; extra == "baselines"
Provides-Extra: analysis
Requires-Dist: matplotlib>=3.5; extra == "analysis"
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: srbf[baselines]; extra == "dev"
Requires-Dist: srbf[analysis]; extra == "dev"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/psaegert/srbf/main/assets/brand/srbf-wordmark-dark.svg">
    <img alt="srbf" src="https://raw.githubusercontent.com/psaegert/srbf/main/assets/brand/srbf-wordmark.svg" width="200">
  </picture>
</p>
<h3 align="center">Symbolic Regression Benchmark Framework</h3>
<p align="center">
  <a href="https://pypi.org/project/srbf/">PyPI</a> ·
  <a href="https://srbf.readthedocs.io/">Docs</a> ·
  <a href="https://psaegert.github.io/srbf/">Interactive results</a>
</p>

# srbf: Symbolic Regression Benchmark Framework

## Publications

- Saegert & Köthe 2026, _Breaking the Simplification Bottleneck in Amortized Neural Symbolic Regression_ (ICML 2026) [https://arxiv.org/abs/2602.08885](https://arxiv.org/abs/2602.08885)

<p align="center">
  <a href="https://psaegert.github.io/srbf/">
    <img alt="srbf visual abstract: benchmarks and methods go through one fair protocol (same expressions, wall-clock budgets, paired statistics, pre-declared corrected comparisons) into the interactive explorer with four-state verdicts."
         src="https://raw.githubusercontent.com/psaegert/srbf/main/assets/brand/visual-abstract.svg" width="100%">
  </a>
</p>

`srbf` evaluates symbolic-regression models on shared benchmarks with shared metrics. It is the
Symbolic Regression Benchmark Framework carved out of
[flash-ansr](https://github.com/psaegert/flash-ansr): the `Benchmark` driver, model adapters, and
metrics, over `symbolic-data` catalogs. It depends one-way on `flash-ansr` (`srbf` imports
`flash-ansr`; `flash-ansr` never imports `srbf`).

**Built for contributions.** Developers of SR methods add their model with an **adapter** that runs
in the method's own environment (any torch, simplipy or Julia version): `srbf new mymethod` writes the
worker, its suite config, an environment recipe and a test; `srbf check` runs it on real problems;
`srbf run` and `srbf analyze` give the numbers. The pull request carries those files. Methods
compatible with srbf's pins can instead register an in-process adapter class. The built-in adapters
(`flash_ansr`, `pysr`, `nesymres`, `e2e`, `lample_charton`, `brute_force`) are reference examples, not
a closed set. See the [adapter contribution guide](docs/adapters.md) and [CONTRIBUTING.md](CONTRIBUTING.md).

The benchmark seam (`srbf.core` Protocols + the `Benchmark` driver) is model-agnostic, the data
source is always a `symbolic-data` catalog, and adapters are a thin mapper over each model
(flash-ansr via `FlashANSR.infer()`). Inline `!sweep` config cross-products and multi-draw
bootstrap reporting (`bootstrap_report` / `draw_distribution`) are built in.

## Install

```bash
pip install srbf                 # benchmark driver + metrics + the flash-ansr adapter (usable out of the box)
pip install "srbf[baselines]"    # + PySR and other pip baseline deps (sympy, pysr, omegaconf)
```

`srbf` pulls in `flash-ansr`, `symbolic-data`, and `simplipy` automatically, and requires
**Python >= 3.12**. The PySR adapter ships in the base wheel but the `pysr` package (plus a
Julia precompile) comes with the `[baselines]` extra, so a bare install does not include a
runnable PySR baseline. The unpackaged research baselines (NeSymReS, E2E) are provisioned
out-of-band; see [docs/models.md](docs/models.md).

## Quickstart

```bash
# 1. point srbf at a tree holding configs/, data/, and models/ (your srbf checkout works)
export FLASH_ANSR_ROOT=$(pwd)

# 2. get a model to evaluate (flash-ansr's CLI ships with srbf)
flash_ansr install psaegert/flash-ansr-v25.0-T7-3M

# 3. run an evaluation. The config names a symbolic-data catalog (`fastsrb`); it is fetched from
#    Hugging Face on first use and cached, so there is no local data-build step. The config is a
#    sweep over candidate counts; --sweep-filter picks one rung for a smoke test.
srbf run -c configs/evaluation/scaling/flash-ansr-v25.0-T7-3M_fastsrb.yaml --sweep-filter ladder=32 --limit 50 -v
```

Outputs land under `results/evaluation/.../*.pkl`, one row per evaluated problem with the raw
prediction columns (derive FVU / recovery / F1 in a separate step; see
[docs/running.md](docs/running.md#deriving-metrics)). Run programmatically instead:

```python
from srbf import Benchmark

# A config with inline !sweep / experiments expands to several runs; expand and run each one.
for benchmark in Benchmark.runs_from_config("configs/evaluation/scaling/flash-ansr-v25.0-T7-3M_fastsrb.yaml"):
    benchmark.run()  # resume-aware; a no-op if that run's configured target is already reached

# For a single, fully-resolved run (no !sweep / experiments), use from_config directly:
# Benchmark.from_config(config_dict).run()
```

## Documentation

| Guide | What it covers |
|---|---|
| [Running evaluations](docs/running.md) | the `srbf run` CLI, config anatomy (data_source / model_adapter / runner / experiments / `!sweep`), outputs, resume, reporting |
| [Benchmarks & datasets](docs/benchmarks.md) | the `data_source` catalog block, the shipped catalog (`fastsrb`), custom catalogs |
| [Models & provisioning](docs/models.md) | installing/patching the built-in models; the `model_adapter` block per type |
| [Fairness & provenance](docs/fairness.md) | one protocol for every method, the upstream-defaults policy, config-provenance labels, blessed configs |
| [**Adding your model**](docs/adapters.md) | the adapter protocol + registry, and the PR flow to contribute a new SR method |

## Development

```bash
pip install -e ".[dev]"
pre-commit run --all-files
pytest tests
```

## License

MIT (see [LICENSE](LICENSE)). Third-party attributions in [THIRD_PARTY_LICENSES](THIRD_PARTY_LICENSES).
