perf(seed): batched prefetching MMP search — measured at 0.5%, not recommended

[BenjaminDEMAILLE]

Stacked on #185 → #184 → #182 → #179 → #178 → #176 → #175 → #174 → #173.

I measured this at 0.5% and I do not recommend merging it as it stands. That is the headline, not the footnote, and the rest of this explains how I got there so you can disagree with the reasoning rather than the conclusion.

This is roadmap P3's lead item: the donor's batched prefetching MMP search, which its own benchmarks put at 2.09× on the search engine.

What it does

max_mappable_length becomes a state machine (Phase, MmpState, mmp_advance, mmp_step_loop, mmp_finish) so a search can be suspended at each probe, and max_mappable_length_batch drives SEED_BATCH_WIDTH of them together. Three passes per round, and the split is the point: issue every live search's suffix-array prefetch, then read those entries and prefetch each search's dependent genome byte, then compare. One search serialises those two DRAM misses; N overlap them.

A single read has only 2–4 independent chains, well under the width where interleaving pays (the donor measures a regression at 8), so find_seeds_batch takes a slice of reads and drives their chains in lockstep.

The measurement

Profiling first put the seed search at 16.4% of on-CPU time on a human 10x run. A 2.09× on that would be worth ~8.6% of wall clock. So I built it, then measured it in isolation — this branch against #185's tip, which carries the cluster_seeds work but not this:

block	#185 tip	+ batched search
1	90.0 s	89.6 s	−0.5%
2	90.7 s	90.4 s	−0.3%
3	91.3 s	90.8 s	−0.6%
4	91.7 s	91.2 s	−0.5%

Faster in 4 of 4, median −0.5%. ABBA ordering, drift across the run only 2%, so for once the effect is well clear of the noise — it is just a small effect.

0.5%, not 8.6%. I would rather report the factor-of-seventeen miss than the direction.

I also measured the whole branch against the pre-P3 baseline at −4.6% (4/4 blocks), which looks better but is almost entirely #185's two cluster_seeds changes. Attributing that to this PR would be exactly the error I made earlier in this stack when I quoted a figure measured without #165.

Why the donor's 2.09× does not transfer

One concrete reason, verifiable in the diff: rustar already prefetches inside a single search. max_mappable_length issues prefetches for both possible next midpoints before comparing the current probe, with a comment saying so. The donor's sequential baseline had no such thing, so its batch was recovering memory-level parallelism that here was already partly recovered.

Two more I can offer only as hypotheses, since I did not instrument them: the genome is byte-per-base with a SIMD scan, so compare_seq_to_genome may be more compute than stall; and the SAindex hierarchical lookup resolves many positions outright, so fewer positions reach the batched search than the 16.4% figure suggests.

It is correct, at least

Whatever you decide about the trade, the equivalence is not in doubt:

• batched_mmp_search_matches_the_sequential_one_at_every_width — widths 1/2/8/32/128, every start position of seven reads
• batched_mmp_handles_single_element_ranges_and_empty_batches
• batched_seed_finding_matches_per_read_sequential_calls — same seeds and same order; order matters because cluster_seeds builds windows in seed order and the earliest window wins the primary tie-break, so a reordering would change which alignment is primary without changing any seed
• empty diff on 20 M read pairs of 10x pbmc_1k_v3 against GRCh38: matrix.mtx, barcodes.tsv, features.tsv, SJ.out.tab, and Log.final.out identical apart from its timestamp

find_seed_at_position is split into prepare_seed_at_position and finish_seed, shared by both paths, so the sequential and batched searches cannot drift by transcription. chain_starts, push_seed and finalize_seed_order are shared for the same reason.

Gate: 584 lib + 27 integration tests, cargo clippy --all-targets -- -D warnings, cargo fmt --check, all green.

My recommendation

Close it, or park it. 892 lines and a restructured hot path, on the file #146 is also rewriting, for 0.5% on the one workload I can measure. The state machine and its equivalence tests are the durable part; if the seed search ever becomes a larger share — a much faster stitcher would do it — this is ready and proven equivalent.

If you would rather keep only the cheap part, #185 stands alone and carries most of the measured gain.