Added: Add benchmark comparison tool and performance documentation

Introduce a Python script to compare Criterion results across baselines
and generate markdown reports. Integrate performance snapshots into the
release workflow and add justfile recipes for baseline management to
track exact arithmetic performance.

Refs: #63

Author: acgetchell

docs/PERFORMANCE.md

@@ -0,0 +1,56 @@
+# Exact Arithmetic Performance
+
+**la-stack** v0.3.0 · `0a8ce5b` (perf/63-custom-f64-to-bigrational) · 2026-04-10 23:57:42 UTC
+**Statistic**: median
+
+## Benchmark Results
+
+Current performance snapshot (no baseline comparison).
+
+| Group | Benchmark | Median | 95% CI |
+|-------|-----------|-------:|-------:|
+| exact_d2 | det | 0.6 ns | [0.6 ns, 0.6 ns] |
+| exact_d2 | det_direct | 0.7 ns | [0.7 ns, 0.7 ns] |
+| exact_d2 | det_exact | 3.93 µs | [3.89 µs, 3.97 µs] |
+| exact_d2 | det_exact_f64 | 4.19 µs | [4.17 µs, 4.21 µs] |
+| exact_d2 | det_sign_exact | 1.1 ns | [1.1 ns, 1.1 ns] |
+| exact_d2 | solve_exact | 10.72 µs | [10.72 µs, 10.72 µs] |
+| exact_d2 | solve_exact_f64 | 11.22 µs | [11.19 µs, 11.25 µs] |
+| exact_d3 | det | 1.4 ns | [1.4 ns, 1.4 ns] |
+| exact_d3 | det_direct | 5.1 ns | [5.1 ns, 5.1 ns] |
+| exact_d3 | det_exact | 21.32 µs | [21.20 µs, 21.45 µs] |
+| exact_d3 | det_exact_f64 | 20.90 µs | [20.78 µs, 21.01 µs] |
+| exact_d3 | det_sign_exact | 3.3 ns | [3.2 ns, 3.3 ns] |
+| exact_d3 | solve_exact | 46.73 µs | [46.53 µs, 46.92 µs] |
+| exact_d3 | solve_exact_f64 | 51.25 µs | [50.61 µs, 51.90 µs] |
+| exact_d4 | det | 2.3 ns | [2.3 ns, 2.3 ns] |
+| exact_d4 | det_direct | 2.4 ns | [2.4 ns, 2.4 ns] |
+| exact_d4 | det_exact | 71.86 µs | [71.40 µs, 72.33 µs] |
+| exact_d4 | det_exact_f64 | 72.30 µs | [72.20 µs, 72.40 µs] |
+| exact_d4 | det_sign_exact | 6.3 ns | [6.3 ns, 6.3 ns] |
+| exact_d4 | solve_exact | 140.23 µs | [137.78 µs, 142.68 µs] |
+| exact_d4 | solve_exact_f64 | 144.25 µs | [142.93 µs, 145.58 µs] |
+| exact_d5 | det | 26.6 ns | [26.1 ns, 27.2 ns] |
+| exact_d5 | det_direct | 2.2 ns | [2.2 ns, 2.2 ns] |
+| exact_d5 | det_exact | 163.15 µs | [162.53 µs, 163.77 µs] |
+| exact_d5 | det_exact_f64 | 176.47 µs | [176.10 µs, 176.84 µs] |
+| exact_d5 | det_sign_exact | 176.38 µs | [173.58 µs, 179.18 µs] |
+| exact_d5 | solve_exact | 328.97 µs | [325.89 µs, 332.05 µs] |
+| exact_d5 | solve_exact_f64 | 333.97 µs | [333.03 µs, 334.91 µs] |
+| exact_near_singular_3x3 | det_sign_exact | 12.71 µs | [12.63 µs, 12.78 µs] |
+| exact_near_singular_3x3 | det_exact | 12.83 µs | [12.75 µs, 12.91 µs] |
+
+## How to Update
+
+```bash
+# Save a baseline at the current release
+just bench-save-baseline v0.3.0
+
+# Compare current code against a saved baseline
+just bench-compare v0.3.0
+
+# Generate a snapshot without comparison
+just bench-compare
+```
+
+See `docs/RELEASING.md` for the full release workflow.

docs/RELEASING.md

@@ -91,7 +91,20 @@ just plot-vs-linalg-readme
 Review the updated table in `README.md` and the plot in `docs/assets/` for
 accuracy.
 
-5. Stage and commit release artifacts
+5. Save an exact-arithmetic benchmark baseline for this release
+
+```bash
+# Run exact benchmarks and save a named Criterion baseline
+just bench-save-baseline $TAG
+
+# Generate a performance snapshot in docs/PERFORMANCE.md
+just bench-compare
+```
+
+This baseline can be compared against in future optimization work using
+`just bench-compare $TAG`. See `docs/PERFORMANCE.md` after generation.
+
+6. Stage and commit release artifacts
 
 ```bash
 git add Cargo.toml Cargo.lock CHANGELOG.md README.md docs/
@@ -104,7 +117,7 @@ git commit -m "chore(release): release $TAG
 - Update documentation for release"
 ```
 
-6. Push the branch and open a PR
+7. Push the branch and open a PR
 
 ```bash
 git push -u origin "release/$TAG"

justfile

@@ -93,6 +93,26 @@ bench:
 bench-compile:
     RUSTFLAGS='-D warnings' cargo bench --no-run --features bench
 
+# Compare exact-arithmetic benchmarks against a saved baseline.
+# Omit the baseline arg to generate a snapshot without comparison.
+bench-compare baseline="": python-sync
+    #!/usr/bin/env bash
+    set -euo pipefail
+    baseline="{{baseline}}"
+    if [ -n "$baseline" ]; then
+        uv run bench-compare "$baseline"
+    else
+        uv run bench-compare
+    fi
+
+# Run the exact-arithmetic benchmark suite.
+bench-exact:
+    cargo bench --features bench,exact --bench exact
+
+# Save a Criterion baseline for the exact-arithmetic benchmarks.
+bench-save-baseline tag:
+    cargo bench --features bench,exact --bench exact -- --save-baseline {{tag}}
+
 # Bench the la-stack vs nalgebra/faer comparison suite.
 bench-vs-linalg filter="":
     #!/usr/bin/env bash
@@ -342,7 +362,7 @@ python-sync: _ensure-uv
 
 python-typecheck: python-sync
     uv run ty check scripts/
-    uv run mypy scripts/criterion_dim_plot.py scripts/tag_release.py scripts/postprocess_changelog.py scripts/subprocess_utils.py
+    uv run mypy scripts/bench_compare.py scripts/criterion_dim_plot.py scripts/tag_release.py scripts/postprocess_changelog.py scripts/subprocess_utils.py
 
 # Setup
 setup: setup-tools

pyproject.toml

@@ -37,14 +37,15 @@ dependencies = [  ]
 "Bug Tracker" = "https://github.com/acgetchell/la-stack/issues"
 
 [project.scripts]
+bench-compare = "bench_compare:main"
 criterion-dim-plot = "criterion_dim_plot:main"
 postprocess-changelog = "postprocess_changelog:main"
 tag-release = "tag_release:main"
 
 # Configure setuptools to find modules in scripts/ directory.
 [tool.setuptools]
 package-dir = { "" = "scripts" }
-py-modules = [ "criterion_dim_plot", "postprocess_changelog", "subprocess_utils", "tag_release" ]
+py-modules = [ "bench_compare", "criterion_dim_plot", "postprocess_changelog", "subprocess_utils", "tag_release" ]
 
 [tool.ruff]
 line-length = 150