# Performance
This document describes how `ries-rs` handles benchmark claims and where the
artifact-backed performance data lives.
## Source of Truth
For any published performance claim, prefer these sources in order:
1. `docs/benchmarks/`
2. raw files under `docs/benchmarks/artifacts/`
3. reproducible local commands recorded alongside the report
Avoid citing hand-written numbers without a matching benchmark report or raw
artifact in the repository.
## Current Benchmark Reports
- `docs/benchmarks/2026-02-25-level3-baseline.md`
End-to-end CLI baseline for a non-exact level-3 workload.
- `docs/benchmarks/2026-02-25-generation-parallel-scaling.md`
Criterion-based generation scaling report.
- `docs/benchmarks/README.md`
Index of the current benchmark set and raw artifact layout.
## Reporting Rules
When publishing numbers in the README, release notes, issues, or papers, record:
- the `ries-rs` git commit or tag
- `rustc --version --verbose` and `cargo --version`
- enabled features (`parallel`, `highprec`, `wasm`, etc.)
- exact command lines
- target triple and build profile
- CPU, core/thread count, RAM, and OS details
- whether the result is a single run, median, or another aggregation
If different machines are involved, say so explicitly in the report.
## Recommended CLI Benchmark Commands
Use explicit flags so the configuration is unambiguous:
```bash
# Sequential deterministic baseline
cargo run --release --no-default-features -- \
3.141592653589793 -l3 --classic --deterministic --report false -n 16 --json
# Parallel baseline
cargo run --release -- \
3.141592653589793 -l3 --classic --report false -n 16 --json
```
Why `--json`:
- includes structured timing and search stats
- preserves the exact run configuration more clearly than formatted text output
- is easy to archive under `docs/benchmarks/artifacts/`
## Criterion Benchmarks
Repository microbenchmarks live under `benches/` and use Criterion.
```bash
# Run all Criterion benches
cargo bench
# Or run one suite
cargo bench --bench evaluation
cargo bench --bench generation
cargo bench --bench search
```
The GitHub benchmark workflow uploads Criterion reports as artifacts; treat those
reports as exploratory data unless a matching repository benchmark note has been
written under `docs/benchmarks/`.
## Local Profiling
Build with release settings before profiling:
```bash
cargo build --release --locked
```
Linux CPU profiling:
```bash
perf record -g ./target/release/ries-rs 2.5 -l3
perf report
```
macOS CPU profiling:
```bash
instruments -t "Time Profiler" ./target/release/ries-rs 2.5 -l3
```
The repository also includes `scripts/profile_comparison.sh` for side-by-side
local comparison against a historical C RIES build when that binary is
available.
## Memory Notes
`--json` output and `--stats` include peak RSS when the platform runtime can
report it:
- Unix/macOS: populated via `getrusage(RUSAGE_SELF)`
- other platforms: may be unavailable and appear as `null`
For architectural context on batch vs streaming generation and why memory usage
varies strongly with search mode, see `docs/ARCHITECTURE.md`.
## Tuning for Your Use Case
### For Accuracy (High Precision)
```bash
# Use higher complexity levels
./target/release/ries-rs 2.5 -l4
# Future: use high-precision feature
cargo run --release --features highprec -- 2.5 --precision 256
```
### For Speed
```bash
# Use lower complexity levels
./target/release/ries-rs 2.5 -l1
# Stop at first exact match
./target/release/ries-rs 2.5 -l2 --stop-at-exact
```
### For Memory Efficiency
```bash
# Reduce max matches
./target/release/ries-rs 2.5 -l2 --max-matches 10
```