Skip to content

Candles: light the lights near a flame, not all of them - #43

Merged
rossry merged 1 commit into
mainfrom
perf/candles-neighbour-gather
Aug 28, 2026
Merged

rossry merged 1 commit into
mainfrom
perf/candles-neighbour-gather

Conversation

@rossry

@rossry rossry commented Aug 28, 2026

Copy link
Copy Markdown
Owner

Option 3 from the frame-cost todo. Candles was the most expensive thing in the repertoire — a default render cost 38 ms on the 6,660-light star, more than a whole 30 fps frame, and it is the primitive two shows lean on hardest.

The work was almost entirely wasted. Pools are gaussians in the angle between a light and a flame, so at the tunings in use 85–93% of the (n_lights × count) matrix was computing that a candle on the far side of the sphere contributes nothing. Profiling the dense path, the single worst line wasn't even the exponential:

nl @ fl.T           3.9 ms
(d - 1) / sigma^2  13.9 ms   <-- two full (n, k) float64 temporaries
np.exp on (n, k)    6.9 ms
spot @ strength     3.2 ms

The change

Which pairs actually carry light is fixed by the geometry and the seat parameters, so they're found once and cached — keyed on a content fingerprint of the lights plus every parameter that shapes seats or pool sizes, the way SmallPlanet caches its statics (a pure function of its key, so call order can't matter). The render walks a flat pair list, takes one exponential over it, and accumulates back to lights with bincount. cos(angle) − 1 is precomputed per pair, so the matmul goes too.

The cutoff covers the widest each pool ever gets, not its width right now — a pool growing on spot_to would otherwise outgrow its own cached neighbours halfway through a movement.

before after
Candles() default 38.0 ms 3.7 ms (10×)
nocturne's candles act 24.3 ms 6.5 ms
a 52-candle ballad 18.3 ms 4.7 ms

Nocturne is where it lands at show level: its two Candles crossfades — the seams where a conductor renders two scenes on one frame — were 33–46 ms and are now under 23. Nocturne's worst seam is now 41 ms and no longer involves candles at all.

Correctness

Dropping the tails is an approximation, so it gets a bound tied to something real rather than a tolerance picked to make the test pass. Measured against the dense path: at most 2×10⁻⁵ in L — about a seven-hundredth of one wire quantization step (1/63, spec §11.4.1) — and fewer than 1 in 5,000 lights land on a different wire byte.

Four tunings are held to that: plain, per-candle vary, pools growing on spot_to, and the anchored seats with a snuff. The test fails as it should when the cutoff is coarsened (checked, not assumed). Two more tests pin the parts that would fail silently: that wide pools take the dense fallback (past 40% of pairs surviving, the gather is all overhead), and that two tunings differing only in pool size don't share a pair list.

444 passed; black --check and mypy clean (the two mapping/tui.py errors are pre-existing and fixed in #41).

What this does not do

It does not get any show under a 33 ms frame. promises contains no candles at all and still peaks near 54 ms at its AuroraVeils → AuroraVeils seams; apollo is unchanged at ~33 ms. This removes Candles as a cause, and nothing more — options 1, 2 and 4 in the todo are still on the table for the rest.

Also still true: this is measured on the pattern render in isolation, with no codec, serial, or viewers attached, and never on the deployment box under load.

plan/todo/conducted-show-frame-cost.md arrives with #42 — I'll update its option 3 section to match once the merge order is settled.

Candles was the most expensive thing in the repertoire — a full
Candles() render cost 38 ms on the 6,660-light star, more than a whole
30 fps frame, and it is the primitive two shows lean on hardest. The
work was almost entirely wasted: pools are gaussians in the angle
between a light and a flame, so at the tunings in use 85-93% of the
(n_lights x count) matrix was computing that a candle on the far side
of the sphere contributes nothing.

Which pairs actually carry light is fixed by the geometry and the seat
parameters, so they are found once and cached — keyed on a content
fingerprint of the lights plus every parameter that shapes seats or
pool sizes, the way SmallPlanet caches its statics. The render walks a
flat pair list, takes one exponential over it, and accumulates back to
lights with bincount. The cutoff has to cover the widest each pool ever
gets rather than its width right now, or a pool growing on spot_to
would outgrow its own neighbours halfway through a movement.

    Candles() default        38.0 -> 3.7 ms   (10x)
    nocturne's candles act   24.3 -> 6.5 ms
    a 52-candle ballad       18.3 -> 4.7 ms

Nocturne is where it lands: its two Candles crossfades — the seams
where a conductor renders two scenes on one frame — were 33-46 ms and
are now under 23. The show's worst seam is 41 ms and no longer involves
candles at all.

Wide pools fall back to the dense path: past 40% of pairs surviving the
cutoff the gather is all overhead, and the matrix is the better shape.
A test pins that fallback, because silently building a pair list larger
than the matrix it replaces is the way this optimization goes wrong.

Dropping the tails is an approximation, so it gets a bound tied to
something real rather than a tolerance picked to pass: measured against
the dense path it costs at most 2e-5 in L, about a seven-hundredth of
one wire quantization step, and moves fewer than 1 in 5,000 lights onto
a different wire byte. Four tunings are held to that — plain, per-candle
vary, pools growing on spot_to, and the anchored seats with a snuff —
and the test fails as it should when the cutoff is coarsened.

This is option 3 of plan/todo/conducted-show-frame-cost.md (which
arrives with the arcs branch). It does NOT get any show under a 33 ms
frame: promises has no candles in it and still peaks near 54 ms at its
AuroraVeils seams. It removes Candles as a cause, and nothing more.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FbzmvdzTNSUxDUjVraRZMx
@rossry
rossry merged commit 304b3f4 into main Aug 28, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant