perf: evaluate native search acceleration

This commit is contained in:
Dandaedre 2026-10-06 19:54:53 +02:00
parent bdc3f3161e
commit ba2083af34
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 76 additions and 8 deletions

65
PERFORMANCE.md Normal file
View File

@ -0,0 +1,65 @@
# Search performance
Native searches use Rayon when `--threads` is greater than one. Results are
collected in ordered chunks, so changing the worker count changes throughput
but not the seeds, ranks, scores, or output order. `--threads 0` selects the
machine's available parallelism; `--threads 1` remains the deterministic serial
baseline.
## Multithreading benchmark
Release-mode measurements from the development machine are shown below. They
are comparative measurements rather than promises for other hardware.
| Search | Seeds | 1 thread | 2 threads | 4 threads | 4-thread speedup |
| --- | ---: | ---: | ---: | ---: | ---: |
| Blueprint, ante 1, exact slot | 1,000,000 | 548k/s | — | 2.11M/s | 3.86x |
| Blueprint AND Brainstorm through ante 4 | 250,000 | 39.5k/s | 77.8k/s | 154k/s | 3.90x |
| Ante-1 boss filter | 1,000,000 | 573k/s | — | 2.10M/s | 3.66x |
Before the partitioning fix, the one-million-seed Blueprint benchmark achieved
559k/s with one thread and 552k/s with four threads. The outer cancellation
runner and inner Rayon scanner both used 4,096-seed chunks, leaving only one
Rayon job per runner iteration. The inner jobs are now 256 seeds, providing 16
ordered jobs per cancellation slab while keeping scheduling overhead small.
## SIMD decision
Explicit SIMD is intentionally not implemented at this stage. Benchmarking and
hot-path inspection identified parallel work partitioning as the useful
bottleneck, and fixing it yielded 3.7-3.9x scaling on four workers.
The remaining hot path is poorly suited to a narrow SIMD patch:
- Balatro's `pseudohash` processes each character sequentially because the next
floating-point step depends on the previous step's result.
- Filter evaluation has data-dependent early exits, resampling, variable shop
and pack traversal, and per-seed caches.
- SIMD across independent seeds would require a second batched engine with lane
masking, rather than accelerating one isolated arithmetic loop.
- Bit-for-bit floating-point behavior must remain identical across the x86-64
and ARM64 release targets.
That complexity is not justified by measured evidence after multithreading was
fixed. A future SIMD implementation should begin with a representative profiler
trace and must demonstrate a release-mode gain while passing the existing
serial/parallel parity suite on every supported architecture.
## Reproducing the checks
```bash
cargo build --release --locked --bin balatro-seed-search
target/release/balatro-seed-search find-jokers \
--joker Blueprint --before-ante 1 --slot 0 \
--max-seeds 1000000 --max-matches 0 --threads 1 --progress 0 \
--output seeds > /dev/null
target/release/balatro-seed-search find-jokers \
--joker Blueprint --before-ante 1 --slot 0 \
--max-seeds 1000000 --max-matches 0 --threads 4 --progress 0 \
--output seeds > /dev/null
```
Each command prints its scanned count, matches, rate, and elapsed time to
stderr.

View File

@ -79,7 +79,8 @@ Useful search controls:
- `--max-matches 0` scans the whole range; any other value stops after that many
results.
- `--threads 0` uses available CPU parallelism; `--threads 1` is deterministic
serial mode.
serial mode. Searches are split into small ordered Rayon jobs, so multi-core
execution preserves exactly the same result order as serial execution.
- `--progress 1s` reports rate on stderr. Use `--progress 0` to disable it.
- `--output human|jsonl|seeds` keeps stdout suitable for people, parsers, or
shell pipelines.
@ -198,7 +199,8 @@ cargo run --release --example bench_throughput
The benchmark binary covers joker, boss, voucher, tag, pack, and mixed filters.
`AGENT.md` and `TASK.md` record the native migration contract and acceptance
work. See `LICENSE` for licensing.
work. See `PERFORMANCE.md` for measured thread scaling and the SIMD decision,
and `LICENSE` for licensing.
## Releasing

View File

@ -188,7 +188,7 @@ Known gaps to address:
CLI smoke search; `cargo test --all-targets --locked`; strict Clippy.
- Commit: `feat: add named seed searches`.
- [ ] **15. Evaluate search acceleration.**
- [x] **15. Evaluate search acceleration.**
- Benchmark existing single-thread and Rayon search throughput across
representative filters and available worker counts.
- Profile the hot path and evaluate portable or runtime-dispatched SIMD only

View File

@ -54,11 +54,12 @@ impl<'a> Searcher<'a> {
Self: Sync,
{
use rayon::prelude::*;
// We chunk by 4096-seed slabs so each rayon job is big enough to
// amortise dispatch overhead but small enough to load-balance
// across cores. Chunks come back in order; per-chunk matches are
// emitted in rank order, so concatenating preserves global order.
const CHUNK: u64 = 4096;
// The CLI feeds this method 4096-seed cancellation slabs. Split each
// slab further so it actually fans out across the Rayon pool while
// retaining enough work per job to amortise scheduling. Chunks come
// back in order; per-chunk matches are emitted in rank order, so
// concatenating preserves global order.
const CHUNK: u64 = 256;
let num_chunks = count.div_ceil(CHUNK);
let chunk_results: Vec<Vec<Match>> = (0..num_chunks)
.into_par_iter()