# Benchmark Baseline Workflow (rc.2 → stable → 2.0.x)

`cargo bench` uses the [criterion](https://github.com/bheisler/criterion.rs)
harness, which natively supports named baselines for regression tracking.
This document codifies the baseline-management workflow that the
`§1.6 cargo bench baseline` line item from `docs/V2_RC2_TODO.md` requires.

## Establishing the rc.2 baseline

Run from the workspace root with the relevant features:

```bash
# Full umbrella crate baseline (default features)
cargo bench --bench distributions     -- --save-baseline rc2
cargo bench --bench fgn_fbm           -- --save-baseline rc2
cargo bench --bench process_generation -- --save-baseline rc2
cargo bench --bench gn_batching       -- --save-baseline rc2
cargo bench --bench dist_multicore    -- --save-baseline rc2
cargo bench --bench distributions     -- --save-baseline rc2
cargo bench --bench option            -- --save-baseline rc2
cargo bench --bench risk              -- --save-baseline rc2
cargo bench --bench instruments       -- --save-baseline rc2
cargo bench --bench microstructure    -- --save-baseline rc2
cargo bench --bench factors           -- --save-baseline rc2
cargo bench --bench credit            -- --save-baseline rc2
cargo bench --bench cashflows         -- --save-baseline rc2
cargo bench --bench calendar          -- --save-baseline rc2
cargo bench --bench lattice           -- --save-baseline rc2
cargo bench --bench market            -- --save-baseline rc2
cargo bench --bench filtering         -- --save-baseline rc2
cargo bench --bench realized          -- --save-baseline rc2
cargo bench --bench poisson_process   -- --save-baseline rc2
cargo bench --bench fgn_accelerate    -- --save-baseline rc2
cargo bench --bench slv               -- --save-baseline rc2
```

GPU/Metal benches are platform-conditional and excluded from the standard
baseline:

- `fgn_gpu`, `fgn_metal`, `fgn_cuda_native` — run only when the relevant
  feature flag is enabled.

Hot-path-only benches (`hotpath_profile`) require the `hotpath` feature
and are tracked separately.

OpenBLAS benches (`econometrics`, `mle`) require `--features openblas` and
are baselined under a separate name to keep the linear-algebra-heavy
suite out of the default comparison:

```bash
cargo bench --bench econometrics --features openblas -- --save-baseline rc2-openblas
cargo bench --bench mle          --features openblas -- --save-baseline rc2-openblas
```

## Comparing against the baseline

Before merging any post-rc.2 PR with non-trivial perf impact:

```bash
cargo bench --bench <bench> -- --baseline rc2
```

criterion prints a `change: [-X%, +Y%, +Z%]` line per benchmark with a
significance test. The §1.6 cut criteria is **no regression > 5%** on
the load-bearing benches:

- Hot path: `fgn_fbm`, `process_generation`, `dist_multicore`,
  `gn_batching` (FGN sampling is the inner loop of every rough-vol
  calibration).
- User-facing: `option`, `risk`, `factors` (called per pricer / per
  Greeks evaluation).

A regression > 5% on these requires either a documented perf trade-off
(linked in the PR description) or an investigation before merging.

## When the baseline rolls forward

- **rc.2 → stable**: keep the `rc2` baseline; add `stable` baseline at
  v2.0.0 tag.
- **stable → 2.0.x patch**: each patch tag may add its own baseline
  (`v2.0.1`, `v2.0.2`, etc.) so multi-version regression bisection has
  reference points.
- **2.0.x → 2.1.x**: roll a fresh `2.1.0` baseline; retire `rc2` /
  pre-stable baselines.

criterion stores baselines under `target/criterion/<bench>/<id>/` and
they are NOT checked into git. Each developer / CI runner re-establishes
the baseline locally on first use.

## Adding a new bench

When adding a `[[bench]]` to `Cargo.toml`, also save its rc.2 baseline so
future PRs have a comparison point:

```bash
cargo bench --bench <new_bench> -- --save-baseline rc2
```

If the bench is feature-gated, add `[[bench]] required-features = [...]`
in `Cargo.toml` and document the gating in the file's module-level doc.
