docs(showpieces): Monodromy Loom + Flight Recorder gallery - #341
Merged
ofloveandhate merged 6 commits intoJul 13, 2026
Merged
Conversation
A new "Showpieces" docs gallery (python/docs/source/showpieces/) — beautiful
renders generated from real tracked data that put the tracking machinery on
stage. First piece: the Monodromy Loom.
Walk a polynomial family's parameter around a closed loop; the roots come back
permuted -- the family's monodromy (its Galois action) as a literal braid of
tracked solution paths. The whole loop is baked into ONE homotopy by making the
coefficient a function of the path variable, c(t)=center+radius*e^{i(theta+phi)},
theta=2pi(1-t), so a single continuous track per strand traces the loop. Each
strand's brightness/width is the adaptive tracker's own step-size diagnostics
(via PathDataCollector): it flares where the loop grazes a branch point and the
tracker sweats through the near-collision.
Two frames from the same engine:
* teaching: x^3-3x-c, loop one branch point -> one transposition (two swap).
* showpiece: x^5-5x-c, loop four branch points -> a full 5-cycle, four pinches.
Raster (PNG-only) showpiece, wired into the main toctree; not doctested (the
page embeds the pre-rendered image + literalincludes the generator).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…seed Fold the Monodromy Loom into tools/refresh_doc_artifacts.py's plot manifest (--plots --only monodromy_loom) so the showpiece stays current with the library like every other doc figure. Pin a random seed in the generator so the render is byte-reproducible run-to-run (verified: identical sha256 across two refreshes). Raster PNG only -- noted in the manifest entry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Second showpiece: film one brutally hard homotopy path to a highly singular
solution and read out the adaptive-precision tracker's full telemetry.
Subject: the origin (0,0) where two rotated rose curves meet -- multiplicity 35
for (7,5), and crankable. Ask for tight accuracy (final_tolerance=1e-24) and
capture one path via a SolutionPathCollector (PathDataCollector per path):
* cockpit (flight_recorder.png, per-path): the Cauchy endgame spiral (cycle 7),
precision staircasing 16->20->30->40 digits as AMP escalates into mpfr,
condition number blowing up ~10^14, step size sawtoothing with rejected-step
markers. Notes the cycle-vs-multiplicity distinction (35 = 5 cyclic groups
of 7) since it's a natural point of confusion.
* setup (flight_recorder_setup.png, system-level): the two rose curves meeting
at (0,0), and all 35 homotopy paths wandering in to converge on it. The
convergence view is the paths' real-time continuation -- the Cauchy endgame's
circular sampling is filtered out by keeping only steps where |t| reaches a
new minimum (reuses the one solve; no second solve).
Serial solve (num_threads=1) + fixed seed -> byte-reproducible. Wired into the
showpieces gallery + tools/refresh_doc_artifacts.py; docs build clean under -W.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…e (no zig-zags) The convergence panel's "loop-free" paths were reconstructed by filtering the Cauchy solve (keep steps where |t| hits a new minimum). That was a heuristic, and it showed: the Cauchy endgame crosses the real axis c times per radius (one per cycle sheet), so any filter picks points off different sheets at different arg(t) -> visible zig-zags, |t| non-monotone. You cannot carve a single-valued radial path out of the endgame's (deliberately multi-sheeted) data. Fix: give the convergence figure its own POWER-SERIES solve. That endgame tracks radially toward t=0 with no circular sampling, so every path is an honest single-valued descent (|t| monotone, smooth) onto the singular point. The cockpit stays Cauchy (its spiral IS the point). Two solves now; still serial + seeded -> reproducible. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…string coeffs The engine hand-rolled pi, i, x**d and float/complex coefficient wrappers (_cnode/_rnode/_xpow/_I/_TWO_PI). All but one were reinventing tools the library already has: x**degree (IntegerPower), 2*bertini.Pi (the EXACT pi node, not a truncated math.pi), bertini.I, and int auto-promotion. Collapse the five helpers to a single _const that turns a Python float/complex into an exact constant node via coefficient's string path (the library deliberately refuses raw float/complex to protect the tree's precision). Same braid; exact pi now. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Following up the de-smell: _const still modelled "how to sneak a float past coefficient's refusal" and built a complex constant wastefully as re + im*I. Remove it entirely by never having a float: the loop parameters are exact rationals (fractions.Fraction) and the phase is a rational multiple of pi (phi_over_pi -> phi_over_pi * bertini.Pi). A single _c_of_theta builds c = center + radius*(cos theta + i sin theta) for both the homotopy and the start configuration (DRY). branch_values is gone too -- the branch modulus is exactly degree-1. The only remaining float/complex is value transport for numpy plotting (extracting roots, axis ticks), which is correct. Same braid, exact. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ofloveandhate
added a commit
that referenced
this pull request
Jul 13, 2026
Flip VERSION 3.3.2.dev1 -> 3.3.2 and add a Documentation section to the [3.3.2] entry (Showpieces gallery #341 + site-root redirect #340) so the GitHub Release notes cover them. After merge, tag v3.3.2 -> PyPI + Release + docs deploy. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ofloveandhate
added a commit
that referenced
this pull request
Jul 13, 2026
Final release prep for **3.3.2**: flips `VERSION 3.3.2.dev1 → 3.3.2` and adds a **Documentation** section to the `[3.3.2]` CHANGELOG entry — the Showpieces gallery (#341) and the site-root redirect (#340) — so they appear in the GitHub Release notes. 3.3.2 bundles: the `metadata_for` representatives fix (#338), the Monodromy Loom + Flight Recorder showpieces (#341), and the docs-site landing redirect (#340). VERSION + CHANGELOG only (both in `paths-ignore`) → **no CI**, merges immediately. After merge, tagging `v3.3.2` triggers publish → **PyPI + GitHub Release + docs deploy** (the deploy builds the 3.3.2 docs *including the showpieces* and re-assembles the site so `bertini2.org` redirects to `/v3.3.2/`). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A new Showpieces docs gallery — beautiful renders generated entirely from real tracked data that
put the tracking machinery on stage. Two pieces:
🧬 The Monodromy Loom
Walk a polynomial family's parameter around a closed loop; the roots come back permuted — the
family's monodromy (its Galois action) as a literal 3-D braid of tracked solution paths. The whole
loop is baked into one homotopy (
c(t) = center + radius·e^{i·2π(1−t)}); each strand's brightness/widthis the adaptive tracker's step-size stress, flaring where the loop grazes a branch point. Two frames:
a teaching cubic (one transposition) and a showpiece quintic (a full 5-cycle, four pinches).
The engine is fully exact — no floats:
bertini.Pi,bertini.I,x**d,fractions.Fraction.Film one brutally hard path to a multiplicity-35 singular point (two rose curves meeting at the
origin) and read out the adaptive-precision tracker's full telemetry. A cockpit (per path): the
Cauchy endgame spiral (cycle 7), precision staircasing 16→20→30→40 as AMP escalates into mpfr,
condition number blowing up ~10¹⁴, step size sawtoothing with rejected-step markers — and the
cycle-vs-multiplicity distinction spelled out (35 = 5 groups of 7). Plus a system-level Singular
Rendezvous: the two roses, and all 35 homotopy paths converging on the point, computed loop-free
with the power-series endgame.
Notes
python/docs/source/showpieces/gallery, wired into the main toctree. Not doctested; each pageembeds a pre-rendered PNG and
literalincludes its generator. Raster (PNG-only) — a 3-D render hasno meaningful SVG.
tools/refresh_doc_artifacts.py(seed-pinned, serial → byte-reproducible), sothey stay current with the library.
sphinx -b html -W.Docs-only; no library code changes.
🤖 Generated with Claude Code