Regression ladder¶

The cases¶

Seed 0, with the initial placement pool (8 starts, 3 routed finalists), the legacy fabrication profile; KiCad 10.0.6. “Opens” and “findings” are KiCad’s DRC counts on the saved board; the time is the case’s wall time on the development Mac (darwin-arm64), niced, next to other work.

The baseline configuration (no pool), seeds 0 and 1, as the nightly CI lane runs it, passes all sixteen runs as well. The machine-readable results are in animations/ladder-results.json, and the provenance of the animations (the ladder run’s engine commit, sources_sha256 over its frozen sources, fabrication profile, platform and KiCad; the render’s Pillow version; each file’s trace and content hash) is in animations/manifest.json.

The gate (see the ladder README) requires a legal placement, complete routing with no deferred nets, the original pin and net assignments, tracks at their source widths, qualified SMD pad entries, and zero KiCad unconnected items and findings, warnings included. Signal tracks are 0.25 mm, supply and return at least 0.4 mm, clearance 0.2 mm, vias 0.6/0.3 mm: the fixtures’ own fabrication block, which the runner routes and judges under (PNR_FAB_PROFILE=legacy for every stage). --fab-profile jlc-pofv routes and judges under the engine’s default JLCPCB profile instead (0.127 mm clearance, 0.45/0.30 mm vias, vias 0.127 mm off SMD pads).

Reading an animation¶

• Header: the case, and its parts, connected nets and copper layers.

• Footer: the phase and the experiment it belongs to (start-05 is the sixth start of the initial placement pool), the share of connections routed, and the step within the phase. The number and the mint bar count committed copper (or, after writeback, KiCad’s own count); while the router still negotiates (provisional routes, overlaps allowed), a lighter violet bar fills behind it.

• Board: front copper orange, back copper blue, inner layers violet and yellow (planes as a light fill), vias as rings, unrouted connections as thin grey ratsnest lines. New copper flashes green; ripped-up copper flashes red. A red ring marks each KiCad DRC finding, if any.

• Montages: where the engine chose between experiments, the candidates appear side by side with their score; the chosen one is framed, and the view zooms back into it. A montage comes right after the winner’s own replay has reached the state its tiles show, so the timeline never runs ahead of itself: the pool’s shortlist (legal starts ranked by a capacity proxy) follows the chosen start’s legalization, and the routed finalists follow its route.

• The straight line: title card, the unplaced board (footprints in the generator’s row), the chosen start’s global placement and legalization, the shortlist, detailed routing (negotiation, then commits), the finalists, KiCad’s writeback, planes and zone refill, then the verdict. With feedback rounds, each round on the path follows with its congestion map.

• End card: KiCad’s DRC on the saved board (mint when the gate passes, red with the rules it breaks when it fails), vias, copper length, seed and the number of rivals set aside.

Animations¶

Regenerating¶

The ladder needs a numerical Python (torch, NumPy, PyYAML) and KiCad 10 with its Python module and footprint library. On macOS, use the headless KiCad copy (see DEVELOPERS.md), never the application bundle; run niced on a shared machine. The committed animations were made in two steps, a traced ladder run and a render:

# 1. The traced ladder (about 8 minutes on the development Mac); the output must not exist.
#    The fabrication profile defaults to legacy (--fab-profile).
"$NUMERIC_PYTHON" hardware/pnr/regression/run.py --repo . --out .yapnr/ladder/RUN --seed 0 \
  --trace --initial-pool --initial-starts 8 --initial-finalists 3 \
  --python "$NUMERIC_PYTHON" --kicad-python "$PNR_KICAD_PYTHON" \
  --kicad-cli "$PNR_KICAD_CLI" --library "$PNR_KICAD_FOOTPRINTS"

# 2. Render every case into docs/animations/ (WebP, the README GIF, manifest.json and
#    ladder-results.json); no KiCad needed. --allow-failed also renders failed cases (their end
#    card names the broken rules in red).
bazel run //hardware/pnr:ladder_animations -- --render-only "$PWD/.yapnr/ladder/RUN"

bazel run //hardware/pnr:ladder_animations without --render-only does both (pass --python, --kicad-python, --kicad-cli and --library); it reruns a case that fails in pool mode in the baseline configuration. One case, or another trace, renders with bazel run //hardware/pnr:animate -- SOURCE --out FILE.webp (python -m pnr.animate; .gif and, with ffmpeg, .mp4 work too). .yapnr/ is git-ignored: only the rendered animations and the two JSON files are committed.

pnr.animate also takes the output directory of a successive-halving search (pnr.mc.halving). Such a run records no trace, so its animation is reconstructed from what it saved (the overlay does not claim more): the winner’s placement moving in from the source board, a montage per promotion (the candidates’ placements with their rung objective), the winning rung’s native phases (phases/NN-name/diagnostic.kicad_pcb with each phase’s KiCad DRC) and a montage of that rung’s final boards, then the verdict. Blocks assembled from a synthesis library appear in place; a library itself has no board to draw, and --storyboard FILE writes its critical path (the chosen layout per template and its rivals) instead. The animator only reads its sources.

Rendering is deterministic: the same trace gives the same bytes. Budgets: the ladder’s WebPs at most 2.5 MB (800 px), its README GIF at most 5 MB (640 px), the folder at most 30 MB with the showcases, whose own widths and budgets are on Constraints and hierarchy (tests/unit/repo/test_animations.py checks them all). Refresh the committed animations deliberately, after a notable engine change, not on every pull request: each refresh adds about 12 MB to the history.

In CI¶

.github/workflows/ladder.yaml runs the ladder inside the published arm64 image: cases 01 to 06 with seed 0 on pull requests that change engine inputs, and nightly all eight cases with seeds 0 and 1, plus a traced pool run whose animations are uploaded as an artifact and whose trace hashes are compared with animations/manifest.json (a drift is a notice). The lane is informational, not a required check yet; its aggregate check is named ladder.