Skip to content

ADR-0006 — HLLC-core allocation micro-opt rejected; the dev box is not a benchmark host

Status: Accepted

Context

The HLLC flux core (src/aeolus1d/solver/hllc.py) allocates small temporary arrays per face. A natural perf idea is to strip those allocations (scratch buffers / in-place writes) to cut per-face cost. This was attempted and benchmarked.

Two things made the attempt a net loss:

  1. It was slower, not faster, on the cases measured — and it broke bit-identity of the output under fastmath (the rearranged arithmetic reorders floating-point ops, which the regression net detects at the ~1e-14 level).
  2. The development machine cannot benchmark kernel micro-optimisations reliably. It is a WSL2 box with ~2.3× run-to-run wall-clock noise on the hot kernels — larger than the effect being measured — and Numba's fastmath codegen is cache-sensitive at the 1e-14 level, so "improvements" are indistinguishable from noise and can silently change results.

Decision

The HLLC-core allocation strip is rejected ("closed-negative") — do not re-attempt it on the current evidence. More broadly: kernel-level micro-optimisations are not to be accepted on the strength of dev-box timings alone. A perf change to a hot kernel must (a) preserve bit-identity (or be explicitly gated behind a numerics-changing flag with re-baselined snapshots), and (b) show its gain on a quiescent benchmark host, not the WSL2 dev box.

Consequences

  • Time isn't spent re-deriving this rejected micro-opt; the rationale is now in-repo, not in working memory.
  • Hot-kernel perf work is blocked on a real benchmark host (a quiescent, pinned-arch machine) — tracked as a conditional infrastructure item. Until it exists, perf claims lean on cProfile self-time and machine-tolerant bands rather than raw wall-clock.
  • The golden-snapshot regression net (measured-tolerance tier) is the guard that catches a "faster but different" kernel change.

References

  • src/aeolus1d/solver/hllc.py — the core whose allocations were the target.
  • tests/regression/ — the bit-identity / measured-tolerance guard.
  • Related: ADR-0002 (the other "we benchmarked the tempting alternative and it lost" decision).