perf(accumulate): parallel cell grouping

[Borda]

Description

accumulate() sorts each (category, area range) work item once instead of once per maxDets entry. Every precision, recall, and scores value is bit-identical to before.

Motivation

Profiling hotcoco inside RF-DETR's validation loop (OnePassCocoMeanAveragePrecision(backend="hotcoco"), 5,000 images × 300 detections = 1.5M detections, maxDets=[1, 10, 300]) showed that accumulate() is the single largest phase: 40–58% of CPU time, more than IoU computation and matching combined. Inside it, for every (category, area range) cell the code gathered all detection scores and 20 match/ignore flag rows, sorted them by score, and did that three times — once per maxDets entry — on what is essentially the same sequence.

pycocotools does the same three sorts (np.argsort(-dtScores, kind='mergesort') per maxDet), which is why the port inherited them. They are redundant: a stable sort of the concatenation truncated at the largest cap, filtered to detections whose rank inside their image is below the smaller cap, equals the stable sort of the smaller-cap concatenation. Filtering preserves relative order, and ties break on concatenation position, which the filter also preserves. So one gather and one sort per cell suffice, and each maxDets slot is a stable filter of that order.

Change

• crates/hotcoco/src/detection/accumulate.rs: gather once at Params::max_det(), record each detection's rank inside its cell, sort once, derive each maxDets slot by rank_in_cell < max_det. Cells are truncated to the current cap, so lowering maxDets between evaluate() and accumulate() (pycocotools' accumulate(p) idiom) keeps working. The metric kernel in metrics::counts is untouched.
• crates/hotcoco/tests/integration_test.rs: test_accumulate_shared_order_equals_per_cap_runs — 12 images × 3 categories, scores quantized to two decimals plus a hand-built cross-image TP/FP tie at the same score, asserts to_bits() equality of all four arrays for the [1, 10, 100] slices against fresh single-cap runs (which never take the filter branch), the [100, 1, 10] permutation, caps lowered after evaluate(), and slice_by halves against from-scratch subset evaluations. The test was checked to fail on two injected violations (<= in the filter, sort_unstable_by).
• CHANGELOG.md: entry under Unreleased → Changed.

Measured impact

RF-DETR-shaped synthetic workload: 5,000 images, 80 categories, 300 detections per image (1.5M total), iouThrs 0.50:0.95, 101 recall thresholds, maxDets=[1, 10, 300]. Apple M4 Max, release build, 3 repeats (last two shown). total = evaluate() + accumulate() + summarize().

RAYON_NUM_THREADS	accumulate() before	after	Δ	total before	after	Δ
1	1.459 / 1.467 s	1.120 / 1.105 s	−24%	2.483 / 2.516 s	2.151 / 2.174 s	−14%
2	0.798 / 0.781 s	0.602 / 0.605 s	−24%	1.553 / 1.534 s	1.385 / 1.361 s	−11%
16	0.209 / 0.223 s	0.168 / 0.163 s	−22%	0.743 / 0.786 s	0.686 / 0.688 s	−10%

Against RF-DETR's full compute() on the same workload (2.00 s at 2 threads, replayed in the RF-DETR venv): about −0.19 s, −10%. Peak RSS is unchanged; the per-cell rank vector is a transient of about 50 MB at 1.5M detections.

What the change removed per (category, area range): two of three gathers (scores plus 20 flag rows per cell) and two of three sorts. What remains, per profile: the precision/recall kernel (~0.56 s CPU) and cumulative TP/FP (~0.17 s), one gather (~0.15 s), one sort (~0.05 s), grouping (~0.07 s) — the kernel is the next target.

Correctness evidence

Bit-for-bit comparison of precision, recall, scores, and stats (as u64 views) plus a SHA-256 digest of evalImgs against the pre-change build, identical on all 10 configurations:

• 1.5M-detection workload, maxDets=[1, 10, 300]
• 100K-detection workload: [1, 10, 300], [100, 1, 10] (unsorted), [7], evaluate([1, 10, 100]) → accumulate([10]), → accumulate([50, 5])
• 100K-detection workload with scores rounded to two decimals so 99.7% of detections share a score with a detection in another image (cross-image ties are the only place a wrong tie-break would show): [1, 10, 300], [100, 1, 10], evaluate([1, 10, 100]) → accumulate([10]), → accumulate([50, 5])

compare(n_bootstrap=20) output is byte-identical; slice_by is exercised by the new test. cargo test -p hotcoco (151 integration tests), cargo clippy --all-targets -D warnings, and pytest scripts/test_parity.py crates/hotcoco-pyo3/tests (107 passed) are green.

Not run: just parity on COCO val2017 (data/ absent on this machine). The change does not alter the numbers the metric kernel receives — only how the sorted order is produced — so parity is expected to hold as before; please run it before release.

Not in this PR

• Fusing the precision/recall kernel into a single pass (metrics::counts), the next largest item in accumulate().
• Aligning the per-cell None gate with pycocotools' len(gt)==0 and len(dt)==0 — affects only eval["scores"] at recall threshold 0 for non-"all" area ranges, unrelated to this change.
• Hoisting the sort into EvalGrouping::build (one sort per evaluator across bootstrap resamples) was prototyped and measured at ≈0% on compare(n_bootstrap=20); reverted.

[Borda]

@derekallman ^^ if you could have look 🦝