The perf ladder: seven changes, 2.75x, bit-identical throughout

[asinghvi17]

Stack position: 4 of 4 — main ← #62 claude/dgg-source-subtree ← #63 claude/subzone-store ← #64 claude/copdem-production ← #65 claude/perf-ladder (draft)

This is a stacked PR chain. Each PR's base is the previous branch, so each diff shows only its own commits. Do not squash-merge out of order; merge bottom-up and retarget children after each merge.

⚠️ DRAFT — carries temporary [sources] pins

This branch pins two dependencies to unmerged branches and must be repinned to released/main versions before merge:

• ConservativeRegridding → branch claude/budget-frontier @ 6a4b997 (upstream CR PR #137, not yet merged) — inherited from PR 1 in this stack.
• GeometryOps → branch claude/perf-ladder-predicates @ 36c853e0 — not yet even a GO PR. The N2+N4 predicate work below lives there; it has to be opened, reviewed and merged upstream first.

That GO pin is worth 15 % of the 2.75×, so unpinning is not a no-op — it is a blocking upstream dependency, and the reason this is a draft.

---

Headline

Over eight reference columns of the production run, single-threaded, bit-identical at every step:

184.60 → 67.0 core-seconds, 2.75× (three independent final runs: 66.66, 67.13, 67.35). Allocation 3.30 → 1.87 GiB per column, −43 %. Full suite 987,584 pass / 0 fail / 17 broken.

Projected production ETA at a 24-core budget, against the profile's 5.086e10 cells remaining:

configuration	cells / core-second	ETA
as running, 22.24 cores	28,614	22.2 h
24 cores, unchanged code	28,614	20.6 h
24 cores, this branch	~78,700	~7.5 h

Column 728 alone: 29.11 → 10.41 core-seconds, 2.80×; 28.2k → 79.1k cells per core-second.

Record: regrid-notes/2026-08-20-perf-ladder.md (+ .ndjson, 202 measurements). Spec: 2026-08-20-perf-ladder-spec.md. Profile it was built from: 2026-08-20-production-profile.md. Mid-campaign findings: 2026-08-20-more-improvements.md.

The ladder, in commit order

Every row at -t 1 on the eight reference columns (three mid-latitude fed, one single-source 100 %-NaN, four polar), against frozen bit-exact fingerprints — NaN count plus a hash of every value's bits.

#	commit	change	core-s	Δ	alloc/col
0	47961ea	base	184.60	—	3.30 GiB
1	9e9e2c6	N1 destination bucket size	84.13	−54.4 %	2.34 GiB
2	c337155	c1 source node-extent memo	80.47	−4.3 %	2.34 GiB
3	72391eb	c2 inline leaf cells	~80.5	null	2.12 GiB
4	ef43b0b	c3 wave scheduling	no-op at -t 1	—	—
5	224903b	b2 worker sizing	script only	—	—
6	f868d7b	N3 inline cell boundary	null	null	1.87 GiB
7	7627ee3	N2+N4 GeometryOps repin	66.9	−15 %	1.87 GiB

9e9e2c6 — N1: the destination tree descended one layer too far

STI.isleaf for HierarchicalGridCursor stops early only when bucket_size > 0, and the default is 0 — so a level-12 column rooted at level 5 ended in 823,543 single-cell leaves, and that bottom layer alone is 6/7 of the tree's nodes. Stopping at 49 stored cells (7², two refinement levels early) deletes it. Swept, every point bit-identical:

column	leaf 1	leaf 8	leaf 49	leaf 343
728	20.39	13.16	12.69	18.67
98241 (all NaN)	18.27	11.66	10.97	16.60
115426 (polar)	20.36	13.30	12.34	18.89

Design call worth reading. 2026-08-20-more-improvements.md proposes the principled home as a non-zero bucket_size default on PartialGrid. That is unsafe, and its own data says so: against a bare HierarchicalGridCursor, which re-derives a leaf's cell caps on every visit, the same sweep costs +25 % at leaf 50 and +441 % at leaf 350. The sign of the change depends on whether the caps are cached, and three uncached paths exist today (GR.celltree, _cachedchunktree above _CHUNK_CAP_CACHE_MAX, _cachedcelltree's fallback). So the leaf size is attached to the cap-cached seam, not to the grid: _CACHED_BUCKET_SIZE is applied by _bucketed at exactly the two sites returning a CapCachedTree, and only when the cursor's own bucket_size is 0 — an explicit caller choice still wins and no bare cursor is affected.

c337155 — c1: memoize the source cursor's derived node extents

STI.node_extent(::BlockCursor) re-derived _node_box → _box_cap (five sincosd pairs, four spherical distances) for every interior node, every block build, every column, every worker, over a lattice that never changes. MemoBlockCursor wraps it with a per-task, direct-mapped 1024-slot table in task_local_storage, keyed on (r0,r1,q0,q1,j0,j1,i0,i1,inpixels) and cleared when the task turns to another grid, system or level.

Deviation from the spec (which asked for an LRU keyed by source chunk): task-local storage is lock-free for the 21 workers sharing one source DGGSpace, memory is O(slots) not O(tiles), and there is no eviction policy to get wrong. Key correctness verified: _node_box/_leaf_pad read only sys, level, inpixels and the eight rectangle fields, and the empty-slot sentinel cannot collide with a real key (its ninth field is −1 while inpixels is 0 or 1).

−27.2 % standalone, −4.3 % once N1 stands first.

72391eb — c2: hand a leaf's cells back inline

The leaf (position, cap) call allocated a fresh Vector{Tuple{Int,Cap}} per leaf: 71.6 % of the base's 3.22 GiB per column.

Latent-bug finding. The spec prescribed "a per-task reusable buffer". Reading the consumer showed that would be wrong: GeometryOps' dual_depth_first_search binds both leaves' entry lists and nests the loops, and raster_tree_memo.jl retains the returned vector in a memo slot. A single shared buffer would silently corrupt any self-join — a Copernicus grid regridded onto a Copernicus grid, which is supported API. A lazy view was implemented and measured at only −0.9 %, because the join reads the inner leaf's entries once per cell of the outer leaf, so a view re-derives each cap up to nine times.

What shipped is neither: LeafCells <: AbstractVector, an isbits struct holding NTuple{9,Tuple{Int,Cap}} plus a length. It lives in the caller's frame, never heap-allocates, is copied by value so aliasing is impossible, and derives each cap exactly once. −46 % allocation standalone; −9.4 % after N1, wall inside noise. Kept as an allocation change.

LEAF_CELLS = 9 was swept (4 / 9 / 16 / 25 / 49) with bracketing runs 0.9 % apart; wall rises monotonically to +14.9 % at 49 while allocation falls monotonically to −25 %. No change recommended — and the reason confirms N1's mechanism rather than contradicting it: the destination tree caches its leaf caps, the source BlockCursor derives them, so a fatter leaf is strictly more expensive per visit on the source side.

ef43b0b — c3: let a narrow wave stand aside

_fillwave! wrapped every spawned block build in @with OUTER_PARALLEL => true, suppressing CR's inner threading — measured at 8.7× on 12 threads, 92 % per-core efficiency — whenever a column had more than one source chunk, while the wave itself delivered only 1.05–2.26×. The fix is in the estimator, not the spawn: _fillwave! already has an i == j branch that does not set the scoped value, so _wavesize returning 1 reaches inner threading with no restructuring. _wavesize now estimates per-chunk cost as ncells × (cap-overlap(tile, chunk) / chunk cap area) and keeps the wave only when its ideal speedup beats 0.73 × nthreads.

The estimator was validated before being trusted: Spearman 0.70–1.00 against nnz, where the naive cell-count proxy scores −0.70, anti-correlated. A 4× error in the wide-cap overlap formula was found and fixed against a 4M-sample Monte Carlo. Hazard handled: when a caller has already set OUTER_PARALLEL (the production worker body does), inner threading is off and the wave is the only parallelism left, so _wavesize consults the scoped value and preserves today's behaviour.

At -t 12, OUTER_PARALLEL unset:

col	wall	cores held	cells/core-s	peak RSS
728	9.56 → 2.01 s	1.48 → 7.01	58.2k → 58.3k	2.82 → 2.21 GiB
729	12.23 → 2.03 s	1.33 → 7.16	50.5k → 56.6k	3.09 → 2.46 GiB
730	10.87 → 1.88 s	1.20 → 7.16	63.1k → 61.2k	3.92 → 2.54 GiB
115426	7.21 → 1.81 s	1.83 → 7.26	62.3k → 62.7k	3.71 → 2.50 GiB

Bit-identical at -t 1 and -t 12. The honest cost: in the multi-worker regime the new shape spends ~8 % more CPU per unit of work (60k vs 65k cells/core-s), so at a fixed 24-core budget the old shape converts cores into cells slightly faster. c3's value is reaching the same cores with a third of the workers and two thirds of the memory, and being the only path past 24 cores. It is not counted in the ETA above.

224903b — b2: workers from a core budget

workers=21/threadsper=3 described thread arithmetic the run never had. workercount() now derives W from a cores budget, and the parallel shape is selectable: outer (1.06 cores/worker, 65k cells/core-s, needs W ≈ cores) or inner (saturates at W ≈ nthreads/4 holding ~78 % of the pool, 60k cells/core-s). outer is the default because the standing budget is 24 cores; cores=24 shape=outer gives W=23, independently reproducing the profile's own recommendation.

f868d7b — N3: inline the Copernicus cell boundary

cell_boundary was the only heap polygon left on the hot path (IGeo7's equivalent already returned an inline SmallList); now isbits end to end. Allocation −11.6 / −12.0 / −13.0 % on columns 728 / 98241 / 115426, beating the −9 % estimate. Wall: null — an A/B/A bracket (heap 78.44, 78.17; inline 79.80, 78.72) puts the claimed −2.57 % inside the noise. Kept on allocation alone.

7627ee3 — N2+N4: the GeometryOps repin

Two predicates paid for work they discarded. spherical_orient normalized a cross product and asserted unit-length inputs only to take the sign of a dot product: 36.5 → 4.5 ns (8.1×) once the degeneracy band is tested as (n·c)² < tol²‖n‖². The SphericalCap intersection test called spherical_distance — an atan2 — where a squared chord answers: 16.5 → 3.4–7.4 ns. −15 % end-to-end, bit-identical, twice, allocation unchanged.

Both were checked well past "the tests pass":

• spherical_orient keeps the exact-arithmetic and symbolic-perturbation fallback (the source report's patch deleted it), now guarded by exactly the criterion robust_cross_product applies internally. Over 22.2 M triples, zero sign flips. The 839,708 disagreements are all in deliberately constructed boundary suites and all within ±5 % of the tolerance, which is inherent (tol = 16 eps ≈ 3.55e-15 against a three-term dot product's ~2e-16 rounding noise).
• The new cap test is more accurate than the old one. spherical_distance's cross(p,q) cancels catastrophically for nearly-equal centers. Adjudicated in 256-bit arithmetic over the 111,514 knife-edge pairs where the two differ: the old test is wrong on all of them and the new one on none.
• The sketched N4 patch benchmarked at 0.71× — slower — because random cap centers sit ~π/2 apart so its c ≤ 1 gate always missed; it was restructured to be entirely sqrt-free.

GeometryOps' own suite is unchanged: 231,527 pass / 0 fail, per-testset identical on both sides. N6 was declined with cause (find_orthogonal does not normalize, so the divisions in _sh_spherical_intersection are load-bearing for a == b).

What this campaign teaches, beyond the number

1. The spec's ranking was wrong, and measurement is the only reason we know. The two changes the spec led with were sized against a profile in which node_extent was 47.7 % of CPU — a profile taken with the destination tree descending to 823,543 single-cell leaves. Once N1 stops that descent, most of the calls c1 memoizes never happen: c1 fell from −27.2 % to −4.3 %, and c2 fell to zero. Run in the specced order and stopped there, this campaign would have reported ~35 % and left a 2.19× sitting underneath it.
2. Wall-clock predictions from isolated microbenchmarks mostly did not survive; allocation predictions did. c2 (−9 % predicted, null), N3 (−2.57 % predicted, null), c1 (−26 % predicted, −4.3 %) all shrank or vanished; every allocation claim held or beat its estimate.
3. Two of the seven changes are correctness improvements, not just speed (§2.3, §2.7 above).

Where the time goes now

Re-profiled (2 ms sampling, 21,896 samples, four mid-latitude column builds): pair-finding fell from 67.8 % → 29.0 % of CPU (−16.5 s of 19.7 s, −84 % absolute), and the source tree's interior-node geometry — formerly the single largest cost in the program at 47.7 % — is now 1.7 %. Sparse assembly / BlockAreaOperator is now 50.3 %, of which 32.2 % is the Sutherland–Hodgman spherical clipper (the useful work). Runtime dispatch stays at 0.0137 % self.

The two clearest remaining levers, both measured and both out of scope here:

• snyder_inv_xyz — 21.7 % of all CPU, the largest single item, reached from the destination-polygon memo (10.8 %) and cell_cap under _leafcaps (10.5 %). Not in either phase this campaign optimized.
• The destination half of child_indices_extents (src/cap_cached_tree.jl:52): 5.63 % of CPU and ~0.75 GiB/column — ~40 % of all remaining allocation, ~675,000 allocations — from a heap Vector per leaf visit. Its caps already sit in a flat vector, so c2's treatment applies with no derivation at all.

c4 was dropped as a measured null: the spec's own condition ("only if the re-profile still shows child_indices_extents as the next sink") is not met — it fell 21.3 % → 11.8 %, and a perfectly-free 100 %-hit-rate memo could not exceed −6.2 % against an original target of −10 to −15 %.

Tests

Full suite 987,584 pass / 0 fail / 17 broken. Bit-exact fingerprints (NaN count + hash of every value's bits) held at every rung, and at -t 12 as well as -t 1. Reproduction harness and the fingerprint oracle are described in regrid-notes/2026-08-20-perf-ladder.md §6.

The live production run and its store, log, done log and column cache were not touched at any point during the campaign.

Before merge

1. Repin ConservativeRegridding off claude/budget-frontier (needs CR PR #137 merged and released).
2. Open, review and merge the GeometryOps claude/perf-ladder-predicates work upstream, then repin GO to a released version. Without this the −15 % from N2+N4 is not available.
3. Fix the heartbeat-ETA-after-resume double-count in scripts/copdem_production.jl (carried from PR 3 in this stack).

🤖 Generated with Claude Code

https://claude.ai/code/session_01AC7rbi9eqZypWseMjBGSJ2

[asinghvi17]

Don't know why this has to be a constant

[asinghvi17]

It didn't — one call site, no type-stability or isbits reason. It's now an innerspeedup::Float64 = 0.73 keyword on _wavesize (the only reader), and the const is gone from shared.jl; same default, so no behaviour change. 1633933 on claude/perf-ladder-review, merging into this branch once the live production run exits.

[asinghvi17]

storytelling and generally too deep in context

[asinghvi17]

Dropped the allocation-share figure and the rejected-designs section; kept the two invariants a caller can trip over (bounded by LEAF_CELLS, and each call must return its own value). 1b0923b on claude/perf-ladder-review, merging into this branch once the live production run exits.

[asinghvi17]

Pushed e2f90d1..25e6e7b — two plain merges, no rebase or force-push.

• 2e7ffc8 merges claude/perf-ladder-review (e5e078d): the PR DGGSpace as a regridding source descends its own subtree (42x) #62–The perf ladder: seven changes, 2.75x, bit-identical throughout #65 review responses — _wavesize's threshold becomes a keyword, and the LeafCells / MemoBlockCursor docstrings drop their provenance narrative for a statement of mechanism. Clean merge.
• 25e6e7b merges claude/mem-attribution (10b3d0d): rssgib() now reports the current resident set from /proc/self/statm with peakrssgib() labelled separately (the old Sys.maxrss() high-water reading is what produced the false 83.7 GiB alarm), plus a malloctrim knob that freezes glibc's M_TRIM_THRESHOLD so it stops retaining ~3× the live heap.

One conflict, in scripts/copdem_production.jl: both sides appended a knob to DEFAULTS — this branch's allowsweeper (from e2f90d1's gcguard) against malloctrim. The knobs are independent, so both lines are kept; the rest of the file auto-merged, with gcguard() and the malloc report both running in main(), gcguard first.

Verification: the driver loads and builds its synthetic config without starting a run (both knobs present, tunemalloc(32 MiB) succeeds, gcguard() accepts --gcthreads=4), and rssgib()/peakrssgib() were shown to diverge by 6.0 GiB across a transient allocation — the exact false-alarm shape being fixed. lib/GlobalRegridding: 2220 pass, 1 broken, 0 fail.

Note for whoever merges this: the split of scripts/copdem_production.jl into production/synthetic/store files lives on the base branch (claude/copdem-production, 27452bd), not on claude/perf-ladder-review, so this head still edits the monolith. Head-into-base therefore conflicts in three files — scripts/copdem_production.jl (monolith vs. split), src/cap_cached_tree.jl (_ShiftedCaps) and src/systems/CopernicusDEM/cursor.jl. Staying draft.

[asinghvi17]

Follow-up: pushed 25e6e7b..0d0f069, two more plain merges. PR now shows MERGEABLE — the three-file conflict against the base that I flagged in the previous comment is resolved.

• 828d37a merges the base, claude/copdem-production, down into this branch (standard stack maintenance: merge parent into child, never rebase). Three conflicts, and in each the base's structure won while this branch's semantics were carried into it:
  • scripts/copdem_production.jl — the base split the monolith into an editable CONFIG NamedTuple threaded through main(config) plus copdem_store.jl / copdem_synthetic.jl, and renamed the destination unit "column" → "chunk". This branch's four additions were re-expressed against that: gcguard/allowsweeper (now gcguard(config), called first in main), true-RSS rssgib() with a labelled peakrssgib(), tunemalloc/malloctrim, and workercount sizing the pool from a cores budget with an :outer/:inner shape wired into the renamed runchunks. Also carried: FAILURES as a Threads.Atomic{Int} and the GDALLOCK around readtile. Knob names follow the base's NamedTuple idiom, so the shape is the symbol :outer, not the string "outer".
  • src/cap_cached_tree.jl — the base moved the offset field into a _ShiftedCaps wrapper; this branch passed it as a third constructor argument and applied _bucketed. Composed to CapCachedTree(_bucketed(cursor), _ShiftedCaps(...)), which is exactly the shape the sibling _cachedcelltree auto-merged into one function above.
  • src/systems/CopernicusDEM/cursor.jl — both sides trimmed the same subcursor docstring; kept the base's terser run-test phrasing plus this branch's MemoBlockCursor paragraph, which the base had dropped even though the signature and the _memoized body depend on it. Documentation only.
• 0d0f069 merges claude/snyder-closed-form: Snyder's inverse azimuth solved in closed form instead of by up to ten Newton steps. Writing the equal-area condition as H = K − Az and taking cosines eliminates the acos and leaves something linear in (sin Az, cos Az), so there is no quadrant logic and no atan. Merged clean — it touches only src/systems/ISEA/snyder.jl and the ISEA4R tests, which the base sync never went near.

Verified after the base sync: driver dry check re-run against the split entry points — 26/26, including workercount(CONFIG) == (23, :outer) and (8, :inner) at a 24-core budget, tunemalloc(32 MiB) succeeding, and gcguard(config) accepting --gcthreads=4. Full root suite 987595 pass / 17 broken / 0 fail (13m59s; the 17 broken match the standing baseline), GlobalRegridding 2220 / 1 broken / 0 fail. After the snyder merge: ISEA4R subset 276826 pass / 0 fail, with pinned-sample deviation 0.000e+00 — the closed form reproduces the pinned oracle exactly — and GlobalRegridding unchanged at 2220/1/0.

Staying draft until the pin blockers clear.