docs(showpieces): The Nebula — one solve, every path, every step

[ofloveandhate]

A fourth showpiece: one solve, every path, every step, exposed onto a single additive buffer
like a long exposure. Where the Loom draws a few strands and Basins (#352) photographs parameter
space, the Nebula photographs solution space in transit.

Draft: the frames and the prose are settled, but see Open questions below.

The idea

The exposure is meant literally: brightness = time spent. Between each pair of tracked samples
the tracker spent some path time |Δt|; that much light is deposited along the segment joining
them, spread evenly over its length. A path that crawls burns bright; a path racing to infinity
leaves a faint comet streak — the same light, smeared further.

The part that makes it honest: a segment's light does not depend on how many samples the tracker
chose to leave on it. Weighting by step count draws a picture of the stepper; weighting by path
time draws the path. Refine the tolerances until the step count doubles and the image is
unchanged.

Colour runs with log|t| — cool at the start system, white-hot into the endgame — so the frame
reads as a flow without arrows. (Colouring by arg ℓ(x) is a trap worth naming: position already
is (Re ℓ, Im ℓ), so arg ℓ is just the screen's polar angle, a pinwheel carrying nothing.)

The frames

	system	paths	solutions	time
hero	Kuramoto, 7 oscillators	4096	124 equilibria	28s
teaching	Noonburg-style, 6 neurons	729	717	2.4s

Kuramoto is the model of synchronisation — fireflies flashing together, a grid locking to one
frequency — algebraized the way its equilibria are actually counted by continuation. Two
constraints there are load-bearing, not decoration: the phase-rotation symmetry makes the solution
set positive-dimensional, so the last oscillator is gauge-fixed at θ=0; and the frequencies
must sum to zero or no equilibrium exists (summing the equations annihilates the antisymmetric
coupling term), so the last frequency is derived, never drawn.

The whole piece is ~31s of tracking. The subject search was the expensive part, not the render.

Measured, not assumed

Everything load-bearing here was measured, and three assumptions died:

• Power-series endgame, not Cauchy. Cauchy samples in circles around t=0, so |t| is
  multi-sheeted and a path can teleport back to the endgame boundary — which the dwell weighting
  would draw as the brightest artifact in the frame. Measured over 5880 cyclic-5/6/7 paths,
  power-series gives |t| monotone on every path, zero teleports. It is also ~1500× cheaper
  here: under Cauchy, samples/path explode superlinearly (259 → 970 → 11861 for n=5,6,7) and
  cyclic-7 becomes a ~29-hour render; under power-series they stay flat (202 → 462 → 335) and
  cyclic-7 is 68 seconds. Same wall the Flight Recorder hit in 0cbc756.
• Serial, not threaded. A Python observer re-acquires the GIL every step, so 12 threads convoy:
  cyclic-6 measured 8.95s serial vs 66.21s threaded (7.4× slower). Threading only wins with no
  observer attached (6.79s → 2.43s). threaded_solve_test.py guarantees observers fire safely
  under threads — not that they are fast.
• cyclic-n is the wrong subject — and not for the reason the design note feared. It is not too
  symmetric, it is a fuzzy ball: every path starts near |x|=1 and ends near |x|=1, so the
  whole solve lives in one small disc. Not a tone-map failure — the buffer's peak is only 5× its
  99.5th percentile, so the core is a genuinely broad dense region.

The criterion that emerged: what makes a nebula is flow structure plus a workable
solution-to-path ratio. cyclic-7 (921/5040) is a blob because nothing travels; 4-site
phosphorylation (9/4096) is a starburst because everything diverges.

Verification

• python nebula.py --selftest asserts the exposure conserves energy exactly (rel err 0.00e+00) on synthetic segments including sub-pixel ones, and reports the real-data border loss
  (0.001%).
• refresh_doc_artifacts.py --plots --only nebula regenerates both frames byte-identically to
  the committed PNGs — the real check that seed + num_threads=1 is deterministic.
• tools/py_doclint.py passes both gates (correctness; undocumented ratchet at baseline 14).
• Sphinx builds clean, no warnings, both images resolve.
• Renderer A/B: the same cached track rendered through my numpy bincount splat and through
  datashader's numba AA lines gives visually identical images — an independent cross-validation of
  the splat. numpy ships: same picture, 2× faster (0.79s vs 1.71s), no dependency.

Notable implementation details

• Streaming meta-observer subclasses SolutionPathCollector and drains .series as it fills, so
  memory is O(one path) rather than O(solve).
• Energy is spread as E/m over m = max(1, ceil(L/step)) subsamples, not as E/L: identical
  for long segments, but no 1/L → ∞ singularity when a segment lands inside one pixel. The pixel
  is the sensor; motion below it is not resolvable.
• Segments are clipped to the frame before subdividing, or one diverger allocates millions of
  subsamples.
• Windows are literal constants (Basins' convention): suggest_window() proposes them from the
  data and prints them; they get pasted in. Auto-windowing would make a committed PNG depend on
  run-to-run data.
• The generator carries a system registry (cyclic-n, Noonburg, Katsura, Kuramoto, multisite
  phosphorylation, Stewart-Gough, dense random), a --scout contact sheet that renders every
  candidate projection from a single solve, and the --selftest.

Open questions for review

• The docs page names Homotopy Basins in plain text, not a :doc: link, because docs(showpieces): Homotopy Basins #352 is
  unmerged and a cross-reference would break this build. It wants to become a link when docs(showpieces): Homotopy Basins #352 lands
  — the Loom/Nebula/Basins triangle is the page's closing move.
• Precision. Both frames are double. Double is lossy on some systems (cyclic-7 finds 921 of
  the known 924 cyclic 7-roots), though neither shipped frame depends on that. Worth deciding
  whether the hero should be AMP.
• The teaching frame is deliberately not the noon-n benchmark. It is a sibling:
  x_i(1 + Σ_{j≠i} x_j²) - 1, whereas noon-n is x_i Σ_{j≠i} x_j² - c x_i + 1 with c = 11/10.
  x → -x carries it onto noon at c = -1, so their solution sets are mirror images — but their
  paths differ regardless, since a total-degree homotopy runs from a fixed start system and
  reflecting the target does not reflect the journey. Both real noon variants render worse
  (lopsided, clipped). Both are in the registry, each named for what it is. Flagging in case the
  sibling should be swapped for the benchmark on principle.
• No ADR. This is a doc artifact, not a library decision. Happy to add one if the
  track-once/render-many split or the power-series choice reads as arbitrary.

Not in this PR

Alt-Burmester 9-0 was explored as a subject and is not feasible with a Bézout-style start
system: it is the (1,8) case, a 24×24 system with 8652 solutions, but the total-degree start is
1,099,511,627,776 paths (b2's own num_start_points(); 453 years at the measured 0.013 s/path) and
the best mhom grouping found is still ~1.2e9. That gap is exactly what regeneration exists for.
A showpiece for when the regeneration cascade lands.

🤖 Generated with Claude Code

[ofloveandhate]

This is, obviously, Claude-written, with me steering. I won't accept this til I rewrite it in my own style. It was fun to brainstorm with the AI, to find good systems to visualize in this way.

[ofloveandhate]

See #360