Design: compact placement (PNR_COMPACT) and shrink-to-fit (PNR_SHRINK)¶
Status: PNR_COMPACT is the runner’s own default since ladder-v2 (2026-10-06,
docs/decisions.md; --no-compact restores the pre-ladder-v2 path). Implemented on branch
claude/compact; section 11 (legalizer spacing and turns) on branch claude/legalize; section 12
(the 09-mcu-usb-31 lane: PAIRS, RELAX, power-first placement, the router key) on branch
claude/lv2-compact, which is what let the default flip; section 13 (displacement-minimizing
legalization) on branch claude/lv2-legal, on by default with or without compact; appendix F
(block-level motion, GP reserves escape-channel room) also on claude/lv2-legal. Code:
hardware/pnr/pnr/compact_flags.py
(the switches, stdlib only) and hardware/pnr/pnr/place/compact.py (metrics, cluster box,
legalizer settings, shrink search); the call sites guard on the switches. Tests:
hardware/pnr/tests/test_compact.py.
Owner request (2026-10-03): the PnR can achieve a much more compact result for the demoed blocks, since they are two layers and simple slow digital routing. The minimum distance between parts looks too conservative during global placement and legalization.
Measured before the change (seed 0): the ladder’s courtyards cover only 11 to 22 % of their
outlines. Four causes, one switch part each, and a fifth part (DROPS) for a defect the denser
placement exposed:
Part |
Cause |
Change |
|---|---|---|
|
The ladder places at |
Spread 1.0; the starts are drawn in a cluster box around the fixed parts. Space grows only where the router measured congestion. |
|
Slots are |
The courtyard gap (0.01 mm, or |
|
Courtyards are modelled symmetric about the footprint origin: a 1x8 pin header whose origin is pin 1 reserves twice its length, and |
Each part occupies its ingested body box ( |
|
Selections among equally complete candidates ignore compactness. |
A compactness tie-break after every completion key and the vias. |
|
A |
The router plans those drops with the signal escapes before routing, as it does for a declared stack. |
1. Switches¶
PNR_COMPACT=1turns onGP,RANK,LEGALIZE,COURTYARDandDROPS, the three legalizer parts of section 11 (WIRE,TURN,SATELLITES) and the two parts of section 12 (PAIRS,RELAX);PNR_COMPACT_<PART>=0drops one part (ablations).The router key (
pnr.feedback.signals.current_key) carries acompactfield, a digest of the active parts,PNR_SHRINKand the legalizer switches’ effective values (section 12), so evaluations and block libraries of two placement configurations never mix.run.py’s--compact-offchoices and theladder-cellkind’scompact_offlist the same parts aspnr/compact_flags.py(tests keep them equal).PNR_SHRINK=1is separate and never on by default: it changes the board outline.Unset, every caller takes its unchanged path and the engine’s JSON gains no key. The flag-off identity is tested on 04-inverter-leds-8 and 07-chaser-20 against the parent commit (the legalizer, the initial pool’s starts and fixed poses on every platform; the whole placer on the platform the golden was recorded on). On every platform a guard test runs the placer, the legalizer and the initial pool with the compact-only functions patched to fail and checks that no part has an offset body.
The ladder:
run.py --compact [--compact-off PART ...] [--shrink]sets the variables after the runner strips the ambientPNR_*ones, soprovenance.jsonrecords them. Theladder-cellexperiment kind takescompact,compact_off,shrink,gloss,gloss_measureandhard.
2. Offset courtyards (COURTYARD)¶
Data: the ingest already records
Component.body, the box the symmetriccourtyardis built from (courtyard, or body, united with the pads and silk), as it lies about the origin in the unrotated frame of the current side, mirrored with the pads. No ingest or schema change.Rectangle:
geometry.courtyard_rectreturnspos + regions.rotate_box(body, rot)andgeometry.body_shift(comp, rot)its centre’s offset frompos(exact at quarter turns). Block and line macros keep their centred courtyard.Correct through the rectangle: hard violations,
pose_checker, the capacity proxy, relocation, feedback moves and the hierarchical extent; regions and aligns already measuredbody.Converted between pose and slot centre:
legalize._place_part(..., shift)compares the candidate slot centres less the shift with the target, the hard group discs, the edge box and the candidate cost, so all of them stay in pose space; callers setpos = slot centre - shift(the main loop,available_pose, the power-first look-ahead,centre_limits,refine_channels,matched.refine_matched). Landing reserves and region masks take the shift; a side retry recomputes it.Global placement:
model.global_placeandcost_inspect.Objectiveuse the body half sizes and the body offset expected under the rotation probabilities, mixed over both sides for a side-free part like the pin offsets; the overlap, outline, edge and keep-out terms usepos + offset. The cost capture replays the same offsets (effective_shift).Also: edge-resolved fixed poses (the body flush with the edge, at the held rotation), ref-relative keep-outs (against the body’s edge), the elastic mesh and its projection, hull macro boards (
hull.gp_bodies),regions.check_feasible, andplane_intent, which widens the body to its symmetric via-array reservation.Unchanged (the symmetric box contains the body):
_fit_outline, rows, line-group spacing,_opposite_body_basins, hierarchical block areas.Power-first placement (
PNR_POWER_FIRST=1,power_first.staged_place):GP(spread and the cluster box of the staged placer’s random starts),LEGALIZE(the courtyard gap in the staged overlap term and the legalizer, the slot grid, the copper margins),COURTYARD,DROPSandRANKapply;WIREandTURNdo not (the power-first legalizer and its retry judge every slot by the hot loops; section 11). Line groups (SATELLITES) are refused there with or without compact.
3. Global placement (GP)¶
compact.spread()returns 1.0 at the top ofplacer.place,initial_pool.select_initial_placementandfeedback.route_and_place, overriding the ladder’sspread=1.3; the feedback loop’s per-part inflation (RePlAce, from routed congestion) is unchanged.compact.cluster_box: a rectangle of twice the summed body area with the board’s aspect, centred on the fixed parts (else the board) and clamped inside it.global_place(start_box=)and the initial pool’s stratified and Latin starts map their existing random draws into it (no new draws).The hierarchical regression driver’s block trials also try the utilisations 0.5 and 0.6 (its own budget,
hier_case.budget_of; a caller ofpnr.hiersets its own).
4. Legalizer (LEGALIZE)¶
compact.legalize_settings(graph, constraints, rules) returns (gap, grid_mm, margins), and
compact.placement_clearance(constraints) replaces board.default_clearance_mm wherever
placement reads it as a courtyard clearance: the placer (legalize, snap_aligns,
refine_matched, the side moves), the global objective and its inspector, the initial pool’s
basin fallback and the hierarchical feedback boards. The copper margins go wherever that
clearance is checked after legalization: snap_aligns, the side moves (pose_checker) and
the feedback MoveBoard (both parts’ margins added to the gap). Rows and line groups keep the
board’s default_clearance_mm, not the gap, so they need none.
Gap:
board.courtyard_clearance_mmwhen authored, else 0.01 mm (KiCad courtyards carry about 0.25 mm around the pads; touching courtyards are legal; 10 µm guards nanometre rounding).Copper margin:
m = max(0, c / 2 - pad inset), withcthe routing copper clearance and the inset the smallest distance from a pad to the part’s box: zero for library courtyards, up toc / 2for a box that hugs its pads (a part without a courtyard layer). Two neighbours’ pads keep at leastc.Slot:
ceil((w · inflation + gap + 2m) / g)cells withg = 0.125 mm; edge-band and align caps subtract the margin too.Edges: the pad and drill edge rule (
PNR_PAD_EDGE_CLEARANCE) is on.Copper clearance stays with the router and native DRC;
channels.py(escape demand) is unchanged.
5. Compactness metric and selection (RANK)¶
compact.metrics(graph, W, H) is measured on the body boxes of every part, fixed ones included,
whatever the switches (so every arm is measured alike): bbox_mm2, utilization = ΣA / bbox,
occupancy = ΣA / WH and bucket = floor(20 · bbox / WH), rounded to 1e-3. The ladder records
the same measure in each case’s result.json (compactness, every arm).
initial_pool.route_rank(the pool’s routed finalists, the halving screen,mc_case, the hierarchical top seed):missing, unresolved, length_unmatched, vias, bucket, length, then the id: on a fixed outline a smaller bounding box is free but a via is not. UnderPNR_SHRINK(the outline follows the bounding box) the bucket ranks before the vias. A record without a bucket (the switch off) keeps the previous key.Halving native and deep stages:
bbox_mm2after every completion key, before the id.The place-route loop’s best round:
(overflow, unfinished, bbox_mm2).
6. Plane drops before routing (DROPS)¶
A net class with a plane_layer and no declared stack (the legacy plane path, e.g.
08-chaser-20-plane) routed its signals first and left every surface pad’s via to the plane to
writeback’s dog-bone search (writeback.apply_planes, eight directions and five distances). Where
routed copper enclosed a pad, the search failed (planes: no clear fanout for ...) and the pad
stayed off the plane: 1 seed in 6 with the switch off, 3 in 6 under compact. A placement-level
count (a dog-bone site clear of every other net’s pad and of the edge, writeback’s search
without the routed copper) found a free site for every plane pad in all 52 runs, so a placement
margin would not have helped; the routed copper closed them.
With DROPS, route_board treats those nets as a declared stack’s plane nets are treated: each
surface pad gets a drop (stub plus through via, the pad’s required width) planned jointly with the
signal exits and reserved before the maze runs. The via may cross its own net’s plane region on
the plane layer (RouteGrid.own_plane_cells; blocked for tracks there, not for vias), which is
cleared after the planning so the maze kernels see the grid they model. The planes stage then
dog-bones only the pads still without a through contact (skip_connected).
7. Shrink-to-fit (PNR_SHRINK, flat driver)¶
route_and_place treats the outline as an envelope:
The loop runs on the envelope (the fallback); the search stops unless it converges legally.
The first probe is the envelope run’s body bounding box plus
2 · (edge clearance + 0.5 mm)per axis, as a scale of the outline.Then bisection between the largest failed scale (at first the lower bound
max(√(ΣA / 0.7 WH), the part and fixed-part bounds)) and the smallest converged one: at most four probes, sizes rounded to 0.5 mm.Each probe is a same-seed
_place_route_looponcompact.scaled_constraints. The outline keeps its origin and gives up its north and east: a fixedatkeeps its absolute position, except one within 25 % of the north or east edge, which keeps its distance to that edge (moved_fixedin the record lists those). The lower bound keeps every fixed part’s box inside the scaled outline.The smallest probe that converges legally sets the constraints’ outline and fixed poses and
placed.outline, which write-back stamps;pnr-report.jsonrecords the search (shrink).
Skipped, and recorded so, with auto_outline, keep-outs or regions; the hierarchical and Monte
Carlo drivers never call it and record shrink: {"skipped": "hier driver"} (or "mc driver"),
and run.py exempts the hard rungs (their outline is part of the rung). Under --shrink the
runner’s constraint audit judges hard edges against placed.json’s outline, otherwise against
the design’s.
8. Trace and animation¶
The trace header carries each part’s
body(µm) underCOURTYARD; the renderer draws and measures it (courtyards, edge tethers, rigid line boxes).Shrink runs are trace scopes
shrink-NN, the choice the selectionshrink; the provenance model then follows only the chosen run and the header outline becomes its outline.animate_ladder.pyandanimate_showcases.pytake--runner-arg ARG(repeatable); the options that changed a run’s boards (--compact,--compact-off,--shrink,--gloss,--gloss-flag, read back from its provenance) are part of each animation’sconfigin the manifest.animate_ladder.py’s baseline fallback reruns a failed case with the same arguments unless--fallback-runner-arg ARGnames its own (--fallback-runner-arg=--gloss: a compact ladder’s failed case falls back to the default mode).The committed animations (
docs/animations/, 2026-10-03) are rendered from traced runs with--compact --gloss(ladder: 8 of 8 pass; showcases: 5 of 5), with the gloss stage as a before/after (renderer 3, Regression ladder); CI’s traced runs take the same options.
9. Determinism¶
No new random streams (the cluster box maps the existing draws), integer buckets, rounded floats, a fixed probe order and exact quarter-turn offsets: runs stay bitwise reproducible per platform, as before.
10. Measurements and the default-on rule¶
Default-on (with PNR_COMPACT=0 restoring the previous behaviour) only if, for each gloss
setting, every case that passes with the switch off also passes with it on, opens and DRC
findings are no worse, and 09-mcu-usb-31-header passes. Shrink stays opt-in.
Outcome (2026-10-03): both stay off by default. Measured on GCP C4D (x86-64), every arm on one image, seeds 0 and 1 unless noted:
Cells |
off |
compact |
|
|---|---|---|---|
8 ladder cases + 4 showcases (24) |
24 pass |
24 pass (also with gloss) |
24 pass |
|
0 (pool fails) |
2 pass |
2 pass |
|
7 pass |
10 pass (7 without |
7 pass |
nightly hard rungs, seed 0 (14) |
14 pass |
14 pass |
14 pass |
manual |
16 pass |
11 pass |
13 pass |
|
1 pass |
2 pass |
2 pass |
On the 24 cells compact cuts the summed placed bounding box from 13068 to 8122 mm² (median
utilisation 0.36 to 0.55) and copper from 4777 to 4022 mm, for 28 more vias (282 to 310) and
21 % more CPU; with RANK after the vias, dropping RANK changes nothing there. The manual
09-mcu-usb-31 rungs fail the rule: their USB pairs end out of skew (skew_out_of_range) or
with one leg or VBUS unrouted on 5 cells under compact and 3 under COURTYARD alone, all of
which pass with the switch off. Dense placement leaves no room for the pair tuning; reserving
it (inflating the parts on declared pairs and length groups) is the next step before another
A/B. Shrink passes 23 of 24: on line-chaser-20 seed 1 a 0.4 mm GND track runs 0.175 mm from
the shrunk edge, through pad cells the router’s edge inset leaves open.
The full tables are in the workflow’s A/B notes; the ladder documentation (compact placement) summarises them.
Still open: the 0.01 mm courtyard gap (no DRC finding in any arm). The manual 09-mcu-usb-31
lane is resolved in section 12.
11. Spacing and turns at legalization (PNR_GP_POLISH, PNR_LEGALIZE_HPWL, …)¶
Owner (2026-10-04): the legalizer moves a lot of components. How were the global placement distances tuned? Are there slight overlaps with the packed placement? Does legalization have the resolution not to treat the closer packing as overlaps? A component the legalizer moves should have its rotation re-evaluated to minimise wirelength: the line-constrained LED chaser in the README ends with extra track because its series resistors are not turned to lie flush with the row after legalization.
Findings (a GCP probe of 81 legalize calls per arm and paired Mac prototypes on 64 recorded pool starts; the workflow’s notes keep the data):
Nothing was tuned. The global weights are the first placer’s, unchanged; compact chose the 0.01 mm gap, the 0.125 mm grid, the cluster box and spread 1.0 in its design and measured them only as a bundle.
Global placement does leave slight overlaps under compact (6.8 true courtyard overlaps per result, median depth 0.07 mm), but removing them alone changes nothing measurable after routing.
Resolution is not why parts move. Re-legalizing the same result on a 0.01 mm grid removes 2.6 % of the displacement for 375 times the CPU; snapping is 4 % of the moved parts.
The legalizer moves parts mainly for its routing-channel cost (
channels.py, 70 % of the moves over 0.1 mm), which global placement never sees, then for the overlaps.The legalizer never turned a part on these boards: it tries
rot + 90only when the global turn has no free slot at all, and its slot cost has no wirelength. The README resistors are not a turn-in-place case: the legalizer put them on the far side of the LED row (the nearest free slot), where every correctly polarised turn has the same wirelength. Choosing the slot and the turn together, with wirelength in the cost, puts them upright beside their LEDs.
Seven switches, each off by default and usable with or without PNR_COMPACT
(pnr/legalize_flags.py, stdlib only):
Switch |
Part |
What it does |
|---|---|---|
|
A |
200 more iterations of |
|
A |
The polish (implied) also carries the legalizer’s channel cost, smooth: |
|
A4 |
The initial pool’s source start begins with every movable part clamped into the outline (the cluster box under |
|
C1 |
The legalizer’s slot cost gains |
|
C2 |
After legalization, greedy in-place turns that shorten a part’s wirelength, stay legal and do not raise its channel shortage; |
|
D |
The legalizer’s channel model spaces unclassed nets at the fab clearance (the router’s) instead of the board’s |
|
E |
A line group carries each member’s satellite (a free two-pad part on a two-pin net to one member pad) flush beside the member, in line with it. |
|
14 |
The channel model (global placement, the legalizer and its push alike) credits the board’s other signal layers: a net that can drop off the surface asks its share of the channel (section 14). |
run.py takes --gp-polish, --gp-channels L, --pool-source-clamp, --legalize-hpwl W,
--legalize-reorient [wire], --legalize-channel-clearance fab and --line-satellites (after
it strips the ambient PNR_* variables, so provenance.json records them); the ladder-cell
kind takes gp_polish, gp_channels, pool_source_clamp, legalize_hpwl,
legalize_reorient, legalize_reorient_wire, legalize_channel_clearance_fab and
line_satellites. A trace’s header lists the active switches (placement_switches).
Three of them are PNR_COMPACT parts since the review-fix A/B below: WIRE (PNR_LEGALIZE_HPWL
at weight 4), TURN (PNR_LEGALIZE_REORIENT=wire) and SATELLITES (PNR_LINE_SATELLITES).
Under PNR_COMPACT=1 each is on unless its variable is set (0 included) or
PNR_COMPACT_<PART>=0 drops it. The polish (A) and the fab channel clearance (D) stay opt-in.
A. Global placement and the legalizer agree on spacing¶
pnr/place/gp_polish.py, run by model.global_place(polish=...) from the placer:
The legalizer’s slot. Per frozen turn and side,
ceil((w · s + clearance + 2m) / g) · gper axis, centred where the legalizer centres it (the occupied box centre, offset courtyards included), withs,clearance,mandgexactly aslegalize()gets them (compact: 1 or the feedback inflation, the gap, the margins, 0.125 mm; off: 1.3 or the inflation, the board clearance, none, 0.25 mm). Slots of whole cells that do not overlap stay disjoint after the nearest-cell snap, so a polished result legalizes by snapping alone unless the channel cost moves a part. With the pad-edge rule the slot centre is also held insidepad_edge_box.The channel cost, soft. The required gap of each ordered pair and facing direction is
ChannelModel.active_demandover the facing rows’ nets that reach a third part (pair-local nets reserve nothing), precomputed once for the frozen turns; the term is counted on facing envelopes only (gap at least 0, projections overlapping),ChannelModel.penalty’s definition. Enforcing the full demand as a hard spacing over-spaces (+5 to +11 % wirelength, +11 to +32 % bounding box in the prototype); the legalizer itself tolerates some shortage.Everything else stays on (wirelength, regions, aligns, groups, keep-outs, edge aligns, planes, matched lengths, side terms); a fresh positions-only Adam runs the fixed 200 steps. The trace shows them as more global-placement snapshots, so parts glide apart before legalization instead of jumping at it.
Not with hull macros (ignored) or power-first placement (never asked).
B. Resolution: no change¶
The 0.125 mm grid stays: a finer grid or an Abacus-style pass would buy 2.6 % of the displacement at 375 times the CPU, and Abacus assumes equal-height rows and a separable cost that the channel cost is not. Part A removes the grid’s share instead.
C. Turns¶
C1, the slot and the turn together (
legalize.py:wire_cost,wire_turns, the nestedsearch_scored). The candidate cost (displacement², channel demand, soft rules) gainsw · wire_cost: the half-perimeter wirelength of the part’s nets with placed parts at their legal pins, unplaced parts at their global targets and plane nets left out.search_scoredruns the existingsearch()once per turn of[rot, rot + 90, rot + 180, rot + 270]and keeps the cheapest outcome byslot_cost(which gains the same term); a tie keeps the earlier turn, hard rotations andallow_rotation=Falsekeep the global turn, line and block macros turn as one body, the side retry compares both sides’ best turns, and underlookahead: regionsa turn whose every slot strands a part counts only when every turn does. The region and align reach then also covers the four turns.The placer passes the weight to
legalize()(wire_weight), which never reads the environment: power-first placement and the initial pool’s basin fallback keep the plain legalizer, as they keep it without C2.Parts on a
diff_pairorlength_matchnet keep the plain search (wire_exempt,reorient.matched_refs): no wirelength term and no four-turn choice, so the two legs of a pair are not turned apart; the matched-length pass evens them afterwards, as without C1.A backtracking ban on a slot also bans the slot at the half turn, which covers the same cells (hull macros aside).
Cost: the channel cost dominates the search (85 % of the legalizer’s time in a profile of
09-mcu-usb-31; the wirelength term 2 %), and four turns score it four times. The search therefore ranks every free cell bydisplacement² + w · wirelength, a lower bound of its full cost (the channel and soft terms are never negative), scores the 64 lowest in full, and then only the cells whose bound does not exceed the best full cost (_cheapest). The sums are taken in the same order as the full scoring, so the chosen slot, ties included, is the same: 96 of 96 recorded pool starts on 12 boards give byte-identical placements, and the legalizer’s CPU under C1 falls from 3.7 times compact’s to 1.0 times. Not used with cost capture (it records every candidate) or for a part with soft rules.Cost capture records the wirelength term with the others, and the candidate fields gain a
wire_rawcolumn.
C2, in-place turns (
pnr/place/reorient.py), run inplacer.placeafterlegalize,snap_alignsandrefine_matchedand beforedetail_moves, so inside every pool start, line group macro graph and hierarchical block, and only where the placer may turn parts (orient). Greedy, best wirelength gain first (then the reference, then the turn), to a fixed point with at most four times as many turns in all as candidates (every accepted turn shortens the total, so the cap only bounds the work), each about the slot centre and checked bymetrics.pose_checkerwith the legalizer’s clearance, spreading factor, margins and pad-edge rule. Never turned: fixed, locked and hard-rotated parts, row and line-group members, macros, and parts on a diff-pair or length-match net. Ties keep the turn. With=1a turn must not raise the part’sChannelModel.penaltyagainst the others.
D. The channel model at the fab clearance (PNR_LEGALIZE_CHANNEL_CLEARANCE=fab)¶
The legalizer’s channel model gives a net without a class the board’s default_clearance_mm
(0.4 mm on the ladder) between tracks and pads, where the router and KiCad hold the fab clearance
(fab.clearance_mm, 0.2 mm): one escaping 0.25 mm track then asks 1.05 mm between facing pad
rows where 0.65 mm routes. Under compact placement that cost causes 70 % of the legalizer’s moves
over 0.1 mm. With the switch the placer builds the legalizer’s model (and C2’s guard) at the fab
clearance; net classes and pairs with their own clearance keep it. Reports and every other model
are unchanged.
E. Line satellites (PNR_LINE_SATELLITES=1)¶
The README’s line-constrained chaser holds the LEDs in a rigid line, but their series resistors
are free parts: global placement leaves them anywhere along their nets, and wirelength alone
cannot prefer the pose beside the LED (a resistor anywhere on the straight path from its driver
pin to its LED has the same wirelength). With the switch a line group carries its members’
satellites (line_group.satellites): a free two-pad part (no constraint names it, not locked, on
the top side, on no diff-pair or length-match net) one of whose pads shares a two-pin net with one
member pad. Each sits flush beside its member, across the line on the side of that pad, turned so
its pads lie across the line with the shared pad facing the member’s, the two shared pads in line
and the courtyards the line’s clearance apart (satellite_layout); a member pad that lies along
the line takes none, nor does a satellite that would come too close to another. The satellites
are members of the line’s rigid macro, so global placement turns the line knowing where the
resistors’ other nets go, and the legalizer packs the row as one body. Not on a double-sided board
(a satellite there may want the other side).
Determinism and tests¶
Fixed step counts, no new random draws, float64 in the legalizer, first-index ties, a fixed
turn order and (gain, ref, turn) order in C2: a seed reproduces its board on one platform.
Tests: test_legalize_flags.py (parsing, the runner’s options, the trace header, and the flag-off
identity on 04-inverter-leds-8 and 07-chaser-20 against the compact goldens with every new
function patched to fail), test_legalize_wire.py (the README case: the near-side slot with the
term and the far one without; a reversed part half-turned; ties; hard rotations; offset courtyards
at the chosen turn; and a line-group chaser whose series resistors end upright beside their LEDs
only with the term), test_reorient.py (the best legal turn; neighbours, keep-outs and the spread
factor rule turns out; the channel guard; exclusions; idempotence; the placer only gets shorter)
and test_gp_polish.py (a tight toy packing legalizes by snapping alone after the polish, at most
half a cell diagonal per part, against 2.9 mm without; the channel term opens an escaping pair and
ignores a pair-local net; zero steps change nothing; the source clamp).
Measurements¶
Wave 0 (2026-10-04, darwin-arm64, compact): the design’s 64 recorded pool starts (8 ladder cases
and showcases, seed 0) replayed through the unchanged placer with each switch set, every
placement legal and routed once at the pool’s finalist budget, paired against compact as on
main on the same global result. 56 starts without the source start (which begins up to 233 mm
off the board); base copper 191 mm per board:
Switches |
Legalizer move |
Moved > 0.5 mm |
HPWL |
Bounding box |
Copper per board [95 % CI] |
Vias |
|---|---|---|---|---|---|---|
none (compact as on |
2.31 mm |
76 % |
||||
|
1.92 mm |
70 % |
−1.8 % |
+1.4 % |
+0.1 [−4.1, +4.4] |
+0.36 |
|
0.53 mm |
30 % |
−3.1 % |
+6.7 % |
−1.8 [−6.8, +3.2] |
−1.88 |
|
1.06 mm |
50 % |
−4.5 % |
+1.9 % |
||
|
2.31 mm |
76 % |
−2.3 % |
−0.9 % |
−3.5 [−7.9, +0.9] |
−0.14 |
|
3.28 mm |
95 % |
−13.4 % |
−5.4 % |
−22.0 [−28.7, −15.3] |
−1.25 |
|
3.28 mm |
95 % |
−13.6 % |
−5.4 % |
−23.3 [−29.5, −17.2] |
−1.20 |
|
3.28 mm |
95 % |
−14.6 % |
−6.0 % |
−26.6 [−32.5, −20.8] |
−1.50 |
|
4.20 mm |
95 % |
−25.6 % |
−11.1 % |
−46.5 [−54.9, −38.0] |
−2.29 |
|
2.42 mm |
89 % |
−13.4 % |
−0.2 % |
−20.8 [−26.5, −15.1] |
−1.38 |
|
2.42 mm |
89 % |
−14.1 % |
−0.5 % |
−21.2 [−27.9, −14.4] |
−1.52 |
Every figure lies inside the prototype’s confidence interval; the wirelength term reproduces the prototype’s placements start by start, and the engine without switches its copper on 60 of 64 starts (the replay rounds the recorded targets to float32).
REORIENT=1(the channel guard) turns little: −0.5 % HPWL alone and −1.3 mm afterLEGALIZE_HPWL=4, against −2.3 % and −4.6 mm without the guard, whose turns raise the channel model’s shortage score from 1.2 to 2.8 mm² per board. The A/B measures both.Legalization CPU per start rises from 0.21 s to 0.77 s with
LEGALIZE_HPWL(four searches and the term) and the polish adds about 0.2 s; global placement is not counted here.README board (
line-chaser-20, seed 0, start 00): 272.0 mm as onmain; 295.7 mm withLEGALIZE_HPWL=4alone; 257.9 mm (21 vias) withREORIENT=wiretoo, the series resistors R4, R6 and R7 upright beside their LEDs; 277.2 mm (18 vias) withGP_CHANNELS=1as well.Switches off: the unit suites, and
run.py --compacton 04-inverter-leds-8 and 05-timer-led-10, give the same placements and routes asmain.
These are one platform, seed 0, one route per placement, without the pool’s ranking, feedback
rounds or gloss. Adoption waits for the ladder A/B (8 cases and 4 showcases on two seeds, the
header rung, then 08-chaser-20-plane on ten seeds, the hard rungs, the manual 09-mcu-usb-31
lane and 10-quad-bank-56): a switch becomes a PNR_COMPACT part only if no cell loses
completion or gains DRC or skew findings, copper improves with its 95 % interval below zero on
the core cells and no hard family is more than 2 % worse, vias rise by at most 0.5 per board,
placement CPU by at most 30 % and the bounding box by at most 5 % (GP_CHANNELS=1 is at +6.7 %
here, 0.5 the fallback). None of them targets the manual lane’s failure (no room to tune the USB
pairs), so compact placement itself is expected to stay opt-in.
Review-fix A/B (2026-10-04)¶
The switches after the review fixes above (the exact prune, matched parts exempt, half-turn bans),
paired against compact placement as on main. Core: the 8 ladder cases and 4 showcases at seeds
0 and 1 on darwin-arm64 (24 cells); hard cells on GCP x86. Copper is paired over cells both arms
pass, with a 95 % interval clustered by case.
Arm (with |
Core copper per board |
Vias |
Bbox |
Placement CPU |
USB-pair lanes pass |
Nightly 14 + 07-rel, 08 x 8, quad x 2 |
|---|---|---|---|---|---|---|
none (compact as on |
22 / 36 |
all pass |
||||
|
−27.4 [−47.4, −7.5] |
−1.75 |
−6.4 % |
×1.10 |
23 / 36 |
all pass; −52.0, −37.7, −184 mm |
|
−12.1 [−35.3, +11.2] |
+0.50 |
−8.2 % |
×1.01 |
23 / 36 (+4.3 vias) |
all pass; −7.2, −19.2, −86.8 mm |
|
−30.2 [−49.7, −10.7] |
−0.54 |
−9.7 % |
×1.03 |
16 / 36 |
1 fail |
Cost. The prune leaves every placement as it was (96 of 96 recorded pool starts, and the routed copper of all 33 re-run core cells is byte-identical) and brings placement CPU from 1.92 times compact’s to 1.10 on the core cells and 0.89 on the nightly rungs.
The USB-pair lanes (
09-mcu-usb-31x 7 at seeds 0 to 3, the header rung at 0 to 5 and the Monte Carlo driver at 0 and 1): with the matched parts exempt,WIRE+TURNpasses 23 of 36 against compact’s 22 (9 cells pass only with it, 8 only without), where the version before the fixes passed only 18 of them. Boards without a matched net place exactly as before.The fab clearance shortens the legalizer’s moves on the core (2.00 to 1.46 mm on average, parts moved over 0.5 mm 66 to 52 %) but adds vias on the hard cells and, with
WIRE, packs the USB pairs too tightly to tune; it stays opt-in.Line satellites, on
line-chaser-20at seeds 0 to 9: −82.6 [−117.0, −48.2] mm of copper and −11.5 vias per board against compact, 10 of 10 pass, the legalizer’s mean move 2.28 to 1.15 mm; on07-chaser-20-rel(seeds 0 to 4) −67.6 mm and −8 vias, 5 of 5 pass; on09-mcu-usb-31-rel2 of 4 pass against compact’s 1. The README board (seed 0): 205.5 mm and 8 vias against 268.7 mm and 20, every series resistor in line with its LED (none withWIRE+TURNalone).
The ladder’s default stays as it was: compact placement, now with these parts, still fails the
manual 09-mcu-usb-31 lane more often than the default mode (which passes it on every seed), so
it stays opt-in.
Conflicts and open points¶
The legalizer options of
claude/s3a-legal(scarcity order, region look-ahead, exact outline) are onmain(#44); C1 adds oneonly=argument tosearch()and a flag where its stranded fallback is taken, so the look-ahead runs per turn. Their interaction is not measured.The channel model reads
default_clearance_mm(0.4 on the ladder) where the router and KiCad use the fab clearance (0.2) for unclassed nets: one escaping track asks 1.05 mm between pads where 0.65 to 0.90 mm routes.PNR_LEGALIZE_CHANNEL_CLEARANCE=fabmeasures the change (above).Global placement’s own weights were never tuned; with
WIREthe legalizer re-places parts for wirelength (a mean move of 4.15 mm on the core), which a better global placement would leave less to do. The polish (A) brought the two closer by lengthening global placement’s wirelength (+16 %) and is not adopted.
12. The 09-mcu-usb-31 lane: PAIRS and RELAX (2026-10-06)¶
Ladder v2 makes compact placement the default, which needs the manual 09-mcu-usb-31 lane (the
seven layout and constraint variants, -header and -mc) to pass with it wherever it passes
without. At origin/main (82ec1a5, GCP C4D x86-64, the lane’s options: pool 8/1, 2 rounds,
packed maze; seeds 0 and 1) it passed 16 of 16 off and 11 of 16 compact (-header 0 of 2 off, 1
of 2 compact).
Root cause. All five failing cells (and every failure on seeds 2 and 3) are one of two kinds:
A pair out of skew (
length_unmatched, 1.5 to 12.6 mm). In every one, one leg of a USB pair carries a via pair and a detour that its partner does not: the two series resistors sit staggered, stacked across the legs or on either side of the connector, so one leg crosses the other or squeezes past a resistor through the bottom layer (a via pair alone is 2 x 1.51 mm on the 1.6 mm board). Without compact the same crossings happen, and the length tuner meanders the short leg back into the 1 mm budget (16 to 20 mm of meanders on some cells); with the courtyards packed at 0.01 mm there is no free cell beside the short leg for a bump, so the tuner adds nothing and the set is reverted. The place-route loop then stops anyway: it counted only unrouted nets, so a round with an unmatched pair was “converged”.A net unrouted on the plane variants (
4L-SGPS,4L-SSGS,6L-SGSGPS): every ground and supply pad drops a via to its plane, and the packed layout leaves the signal escapes no room.
PAIRS. The matched-length pass after legalization (pnr.place.matched.refine_matched) may
also turn a part on a pair or length group, or a line group’s rigid macro (the -rel variant’s
authored usb-series line), a quarter turn, so that the pads its legs leave from face where the
legs go. It never turns a part a hard rotation holds, nor without orient.
RELAX: compact as far as the board routes. In the place-route loop
(pnr.route.feedback) a round that leaves a signal net unrouted, or a declared pair or group
outside its budget, is not converged. Every later round runs with compact placement switched off
(pnr.compact_flags.relaxed, read by every part’s call site) at the board’s own spread, and the
first of them takes the initial pool again at the run’s seed. Recovery retains enabled
COURTYARD geometry: relaxing the packing policy must not replace a pin-1-origin header’s
actual footprint with its larger origin-symmetric envelope. Explicit COURTYARD ablations
still apply. Earlier recovery switched every compact part off; its byte-for-byte comparison
to the noncompact run predates this correction. If the recovery pool genuinely has no legal
placement, the best compact round remains (termination: relaxed_placement_failed).
pnr-report.json records the switch (relaxed: the round, the spread, why).
Rejected on the way (A/B on GCP, the 8 rungs with the lane’s options, seeds 0 to 3):
the two series resistors placed as a rigid mirrored twin (an engine line group): 15 of 32 against 21 of 32 without it, since a twin of 0805s puts its legs 2 mm apart and a twin turned across the legs mismatches them by that pitch;
the declared pairs routed coupled (
board.route_pairs: coupled): the staggered resistors give the coupled solver no channel (no_coupled_channel), both pairs fall back to legs;the short leg routed again, longer, through a waypoint or a via hop where meanders find no room: unit-tested, but on the lane’s boards no such route cleared the other nets, so it never fired and was removed.
Measured (GCP C4D, x86-64; the 8 rungs of the lane run with the initial pool, seeds 0 to 3,
32 cells; -mc passes in every arm):
Arm |
Pass |
Rounds run without compact |
|---|---|---|
off ( |
26/32 |
- |
compact ( |
21/32 |
- |
compact, |
28/32 |
17 |
compact, |
31/32 |
16 |
compact, |
32/32 |
14 |
Off fails -header on every seed (its envelope cannot be placed) and -abs, -sidelock on seed 3
(pairs out of skew). The one failure with PAIRS off is -header seed 0, whose round without
compact cannot place the header: the run stopped there, before the fallback kept its compact
round (fixed since).
The plane variants fall back on most seeds (their compact rounds leave a net unrouted); the two-layer variants keep their compact layout on most.
Validation (c5c1f5c against main 586857d, GCP C4D x86-64, seeds 0 and 1; the lane with
its options, the ladder and showcases with the pool 8/3, the 15 nightly hard rungs as the nightly
lane runs them):
Cells |
compact |
off |
|
Placed bbox, compact vs off |
Copper |
Vias |
|---|---|---|---|---|---|---|
8 ladder cases (16) |
16/16 |
16/16 |
0 |
6427 to 3795 mm² (-41 %) |
2317 → 1633 |
134 → 128 |
4 showcases (8) |
8/8 |
8/8 |
0 |
6641 to 3899 mm² (-41 %) |
2460 → 1660 |
148 → 132 |
15 nightly hard rungs (30) |
30/30 |
30/30 |
0 |
26629 to 16935 mm² (-36 %) |
8514 → 5787 |
821 → 775 |
|
18/18 |
16/18 |
7 |
22412 to 19833 mm² (-12 %) |
12012 → 10244 |
983 → 964 |
The bbox, copper (mm) and vias are summed over the cells that place in both arms (the lane
without -header, which off cannot place). Off on the branch is byte-identical to main on 70
of 72 cells (placed.json, routes.json, the routed board modulo UUIDs); the other two are
-header, which neither places (the same pool exhaustion). Compact costs 2 to 18 % more CPU
(the lane’s fallback rounds).
Power-first placement (PNR_POWER_FIRST=1) no longer refuses compact (section 2).
13. Displacement-minimizing legalization (PNR_LEGALIZE_KEEP, on by default)¶
Owner report (2026-10-05): the hierarchical demo animation “shows a lot of component movement at the legalization phase, both at the block level and at the top level … even though all three blocks find positions with plenty of room around them, all three of them get relocated.” And: a part that is fully occluded is a candidate for relocation, but a slight overlap should push the parts around it outwards rather than upset the order global placement found.
Measured cause (seed 0, ladder, showcases and 10-quad-bank-56, every legalize() call
recorded from its global poses; pnr.place.motion): before #41 and on main without compact, the
parts that were legal where global placement left them (no overlap, inside the outline, clearance
met) mostly stayed (0 to 50 % of them moved; 0 % at the hier top level). Under --compact every
one of them moved and about half turned (100 % on 13 of 15 stages; topology kept 0.76 to 0.90),
at the top level of hier-twin-bank-32 all four bodies (19.1 mm in all, 56 % turned). Without
WIRE (--compact-off WIRE) the top level moves 2.2 mm in all. The causes, in order of weight:
WIRE(PNR_LEGALIZE_HPWL4 under compact) prices each part’s slot by its wirelength there and searches all four turns, so every part, legal or not, is re-sited and re-turned toward a wirelength optimum (the top level’s three blocks among them);TURNthen turns any part.The routing-channel term of the slot cost moves legal parts whose pads face a neighbour’s.
The packer places biggest first into the nearest free slot, so a part that conflicts can take the place of one that did not.
There was no frame or origin mismatch between block and top level, no courtyard inflation and no snap offset beyond half a grid cell.
Change (pnr.place.keep, pnr.place.legalize; PNR_LEGALIZE_KEEP=0 restores the packer):
Triage. Each movable part’s slot (as the packer sizes it) is tested at its global pose. A part half or more occluded (by other slots, fixed parts, keep-outs, the outside of the outline) is severe (the worst first, re-measured without it); the rest are clean or mild.
Push. Mild overlaps are resolved by an order-preserving push: horizontal and vertical constraint graphs from the global poses (an overlapping pair separates along its smaller penetration, a side-by-side pair keeps its order), solved as the weighted least-squares projection of the global centres (Dykstra, per axis), with the outline, fixed parts and the parts the push may not move (regions, aligns, edge bands, hard discs, hull macros) as bounds. The physical overlap is cleared first: a cluster whose push goes beyond a part’s reach (1.5 mm or half its smaller side) gives up its most occluded mild part (
push_infeasible) and is pushed again. Then the escape channel the packer’s channel model asks between facing pad rows is a soft goal: the cluster is pushed again with each pair’s distance including its channel, and that push is kept when it fits within every part’s reach; otherwise the overlap-only push stands. A channel never makes the push give up a part; a cluster with no overlap but a part short of a channel is pushed only when the whole channel fits.Anchors. Held parts (hard groups, aligns, regions, edge bands, hard discs) are placed first as before; then every part that is not severe takes the free slot nearest its (pushed) pose within 1.5 grid cells, at its global turn, without the channel or wirelength terms. A part whose slot is taken (
slot_taken) or that the push gave up (push_infeasible) then takes the nearest free slot in rings expanding from its global pose (radius 3, 6, 12, … grid cells; its global turn first at each ring, then its other turns), never the full search; a held part whose slot is taken keeps the packer’s own search, which carries its constraint’s costs (an exact align needs them). Only the severe parts go through the packer’s full search (its cost,WIREand turns).TURNturns only the parts the legalizer moved. If the result leaves a part without a slot, the board is legalized again with the plain packer (keep_fallback).Metric. Every legalization records its motion: parts moved (beyond 0.4 mm or turned), displacement sum and maximum, turns, topology kept (the fraction of pairwise left/right and above/below relations of the global poses that the legal poses keep), the neighbour order kept (
neighbour_order: the same over each part’s four nearest parts only, counting an axis when it carries at least a quarter of the pair’s distance;neighbour_relationsis its count), the triage counts and, per part that left its pose, the reason (relocations;relocated_severe,relocated_push_infeasible,relocated_slot_taken,nudged,channel_unopened). It is in the placement report,pnr-report.json(legal_motion;blockandtopfor the hierarchical driver),ladder-results.json, the trace’slegalevents and the animation’s end card (“legalization moved …”).
Measured after (the same runs, Mac, seed 0; legalize-motion notes): under --compact the
hier top level moves 0 of 4 bodies (0.3 mm) in the docs run, 1.2 mm per top-level seed on average
(topology 1.00), against 19.1 mm; 10-quad-bank-56 top 7.7 mm against 34.4 mm. On the larger
flat cases (06 to 08, the edge-io pair, the line chaser) 40 to 74 % of the parts move against 90
to 100 %, with 40 to 64 % less displacement, and topology kept is 0.80 to 1.00 against 0.76 to
1.00. Most of what still moves is the push opening routing channels the compact global placement
left out, and the parts relocated where a push could not open them.
Regression (GCP, c4d, seeds 0 and 1, every cell of the ladder, the showcases, the quad bank, the
MCU lane, the six UFBGA-201 rungs, the 15 nightly hard rungs and the buck rungs under --compact,
and the ladder, showcases, quad bank and nightly rungs without it; control main 82ec1a5, the MCU
lane’s from campaign 20261005-mceval-f97cc0; plus seeds 2 to 9 of 08-chaser-20-plane and 2 to
5 of the quad bank): 84 of 92 compact cells pass against 86, and 61 of 64 default-mode cells
against 62; every flip has a counterpart (the MCU lane 11 of 18 against 12, gaining three cells
and losing four; 08-chaser-20-plane 7 of 10 against 8 of 10; the quad bank 5 of 6 against 6
of 6). Copper is 597 mm shorter over the default-mode cells and 416 mm longer over the compact
ones; vias −29 and +42 (seeds 0 and 1). The control’s seeds 0 and 1 of the core and hard rungs
ran on c4 (another region’s Spot quota), the branch’s on c4d; the extra seeds ran both on
c4d. A first version without the channels in the push moved fewer parts still (the core flat
cases 0 to 43 %) but passed only 40 of 50 compact cells against 44 (the MCU lane 8 of 18), so the
channels stay.
F. Block-level motion: reserving channel room in GP, not only in the push¶
The above still left the block level moving almost as much as before the push’s channel term
(10-quad-bank-56 block: 70 % of parts, 16.3 mm; hier-twin-bank-32 block: 65 %, 16.3 mm — both
close to, not below, main’s non-compact 65–67 % / 15.0 mm). Mechanically this is because GP’s
density term (w_spread * overlap, §4) only ever reserves each part’s own courtyard at the global
spread floor; it has no notion of the escape-channel room classified nets will need between facing
pads, so the legalizer’s push still has to open that room itself, at legalization time, moving
parts that were already legal by the courtyard-only measure.
Fix (pnr.place.compact.channel_margin, gp_channel_inflation; GP only, additive): before
global_place runs, a pnr.place.channels.ChannelModel is built on the incoming (pre-placement)
graph — a rough proxy, since GP may still turn a part, but good enough for a density floor. For
each part, channel_margin takes the largest single-face demand (mm) its own externally-connected
pads ask for (half of it: the facing neighbour owes the other half), and gp_channel_inflation
turns that into a multiplier on the part’s own smaller courtyard half-extent, capped at 1.3 (the
legalizer’s own spread cap). The result merges (max) into the existing inflation floor
global_place already took from the place-route loop’s congestion feedback (§6) — the same
mechanism, a different reason to ask for room, so GP’s density term now reserves (part of) the
channel room up front instead of leaving it entirely to the legalizer’s push.
Measured (Mac, seed 0, --compact, pnr.place.motion, legalize-motion/table-final.md):
Stage |
|
§13 push alone |
+ this fix |
|---|---|---|---|
|
65 % moved, 15.0 mm |
70 %, 16.3 mm |
14 %, 3.2 mm |
|
33 %, 30.0 mm |
17 %, 7.7 mm |
0 %, 0.3 mm |
|
67 %, 14.9 mm |
65 %, 16.3 mm |
18 %, 3.4 mm |
|
19 %, 13.0 mm |
19 %, 1.2 mm |
0 %, 0.2 mm |
Block-level motion now sits well below the non-compact baseline instead of at parity with it, and
top-level motion is essentially zero. The same improvement holds across every ladder and showcase
case (01–08, the edge-io pair, the line chaser): every one moves less, and by a wider margin, than
main without compact (legalize-motion/gp3-on.out, summary-main-off-main-on-v2-on-gp3-on.json).
All 13 cases still pass. The trade-off is a smaller compaction win on 11 of the 13 — copper is
still below main’s non-compact figure by 2–27 % on 11 cases (06–08, the line chaser, both edge-io
cases, both hierarchical cases), but 2 trivial cases (01, 02: two and three parts) end up a few mm
longer than uncompacted, since reserving channel room up front leaves GP less free to shrink an
already-tiny board. Frame strips: legalize-motion/strips/after-gp-*.png.
Not done: the early ChannelModel ignores the rotation GP may still pick (the final legalizer’s
own channel push, §13, still uses the correct post-placement one); _place_line_groups and
power-first staged placement do not call this path (compact does not support power-first, and no
rung currently needs the channel-aware GP floor inside a line group).
G. A slight overlap is nudged, never re-placed (2026-10-06)¶
Owner report (2026-10-05): “In the block step, the global placement puts R6 overlapping with D4, and instead of nudging R6 a bit to the right, it re-places it north of the SOIC.” And: “if it’s only a very small overlap that caused the placement to be illegal, then it would be much smarter to push all of the other parts around it outwards to make room slightly rather than completely replacing it.”
Cause (hier-twin-bank-32 seed 0, block top.bank_a trial start-13, 19.75 x 13.25 mm,
reproduced from the legalizer’s input alone: hardware/pnr/testdata/legalize_keep). Four parts
overlap slightly (R6 over D4 among them), none severe, and all 12 are short of an escape channel.
The push asked for the overlap and the full channels at once; with every part channel-short that
exceeded the 1.5 mm cascade bound, so the cluster gave up its most occluded part (R6), the push
failed again and the cluster was left as it was (pushed 0). R6, its slot taken by D4, went to
the packer’s full search with WIRE and landed 10.7 mm away, north of the SOIC, with a quarter
turn; R7 also left its slot with a half turn.
Fix (pnr.place.keep.resolve, pnr.place.legalize): the courtyard overlap is cleared first
and the channels are a soft goal (kept only where they fit; never a reason to give a part up); a
part the push cannot clear (push_infeasible) or whose slot is taken (slot_taken) takes the
nearest free slot in rings around its global pose, its global turn first, never the full search;
only severe parts are relocated wholesale. The motion record names each relocated part’s reason.
On start-13 R6 now stays put (under 0.4 mm, same turn): D4 moves 0.47 mm, nothing else moves
more than a snap, and nothing is relocated (was: max 10.7 mm, 2 relocated).
Measured (Mac, seed 0, --compact, every legalize() call; ladder, showcases and both
hierarchical cases, 1448 part placements; r6-fix notes):
Legalizer |
Parts moved |
Sum (mm) |
Max (mm) |
Relocated (severe / push / slot) |
Moved > 3 mm |
|---|---|---|---|---|---|
before ( |
218 |
463.1 |
14.1 |
86 (by the full search) |
24 |
this fix |
132 |
216.5 |
10.1 |
4 (0 / 4 / 0) |
2 |
channels opened as far as reach |
518 |
580.0 |
8.5 |
4 (0 / 4 / 0) |
0 |
Block level: hier-twin-bank-32 106 parts moved and 220 mm before, 58 and 103 mm after (40
relocated before, 2 after); 10-quad-bank-56 82 and 202 mm before, 50 and 73 mm after (34 and
2). The two parts still moved far are the same D4 in the start-14 block trial of
hier-twin-bank-32 and of 10-quad-bank-56 (13.25 x 19.75 mm, a mild part, 22 % occluded),
whose column above the SOIC is full: no push within reach clears it, so it takes the nearest free
slot (10.1 mm, a quarter turn). Neither trial is the chosen block. All 13 cases pass in every
arm. The third row opens each cluster’s channels by the largest fraction the reach allows: it
moves 2.4 times as many parts, mostly legal ones, for no routing gain on these cases, so channels
are all or nothing.
A/B (GCP c4d us-west4 for both arms, the runner’s ladder-v2 defaults, --legalize-keep
against --no-legalize-keep; ladder, showcases and all 33 hard rungs, seeds 0 and 1; campaigns
20261006-ladder-091262 and, after the fixes below, 20261006-ladder-8a0b4d):
Arm |
Pass |
Parts moved by legalization |
Copper (both pass) |
Vias (both pass) |
|---|---|---|---|---|
KEEP on |
88/90 |
148 of 1496 (285 mm) |
33455 mm |
3828 |
KEEP off |
90/90 |
1361 of 1496 (4677 mm) |
31131 mm |
3772 |
The first run found three cells that failed only with KEEP on. Seeds 2 to 7 of those rungs
decided which were real. 11-ufbga201-fanout-6L-SGSGPS-pairs (5 of 8 seeds against 7 of 8): the
initial pool took the finalist with the fewest vias although its LVDS pair had fallen back to
two legs, which KiCad’s gap rule fails; the pool now ranks a pair left as legs with the length
budgets, before the vias, and the rung passes 8 of 8 in both arms. -rails fails 3 of 8 seeds
in both arms (different seeds): no change. 11-buck-vqfnhr-4L-SGPS-pour stays at 5 of 8 against
7 of 8: global placement leaves the feedback resistor on the far side of the 2 x 2 mm regulator
from its pin, KEEP keeps it there, the feedback net crosses under the part and the ground pin
next to it loses its pad entry (unqualified_pad_entry); the wirelength packer moves the
resistor beside the pin. Moving such wrong-side parts back is open (a rescue tried here moved
them but the board then failed on a router short). Copper is 7.5 % longer with KEEP on (13 to
18 % on the ladder, showcases and 07-chaser-20 variants, 6 % on the MCU lane, none on the BGA
rungs): the wirelength packer improves every legal pose, KEEP keeps them.
H. Detailed placement after legalization (PNR_DETAIL_PLACE, on with KEEP; 2026-10-06)¶
Owner decision (2026-10-06): the displacement-minimizing legalizer ends wholesale relocations but costs copper; add an order-preserving detailed-placement pass after legalization, then turn KEEP and it on by default once the A/B shows no rung worse and copper restored.
Why KEEP costs copper. With KEEP off, WIRE re-sites every part by displacement, channels and
four times its wirelength, over all four turns: 1361 of 1496 parts moved, 4677 mm (3.4 mm each),
and that is the 7.5 % less copper. With KEEP on every legal part keeps its global pose and turn,
and TURN only turns the parts the legalizer moved.
Change (pnr.place.detail, its own stage after legalization, the align snap and the
matched-length pass, before the side moves and routing; PNR_DETAIL_PLACE=0 turns it off,
unset it follows PNR_LEGALIZE_KEEP):
Compaction. Every movable part is drawn half way toward the point that minimizes its wirelength (per axis the median of its nets’ spans), and the layout is projected, weighted least squares (the KEEP push’s solver), onto its present order: two parts side by side keep their order, their slots apart and as much of the routing channel between them as they have; every part stays in the outline and within 3 mm of its legal pose; four rounds, and a pair that comes to overlap keeps the order it had. It is kept only when the legalizer’s checker accepts every shifted part (a part it refuses is held where it was and the compaction solved again) and the wiring shortens.
Greedy moves, best gain first, each legal by the legalizer’s checker (its clearance, spreading, margins, pad-edge rule, regions, aligns, bands, group radii): a turn about the slot centre (every movable part, in place of
TURN), a slide along x or y within a budget of max(1.5 mm, the larger courtyard side) from where compaction left it (blocked, it shifts up to two parts in front along, in order), a swap of two adjacent parts of one size class with nothing between them (each re-picks its turn), and a wrong-side move: a part whose connection crosses the body of the part it connects to goes beside the edge that pin faces, within that part’s extent plus its own plus two cells, only where the other part’s channel penalty does not rise. Ball arrays route through their vias and have no far side.Cost. Half-perimeter wirelength (plane nets out) plus the crossing detour (a Manhattan spanning tree per net; a segment a same-side courtyard cuts across, the endpoint’s own body behind its pin included, costs the shorter way round) plus the channel penalty at the packer’s ratio (25 / 4) and the soft terms. A move must shorten the wiring by more than 0.05 mm.
Never moved: fixed, locked and hard-rotated parts, macros, row and line-group members, parts with landing reserves, parts on a pair or length-match net, and parts within 3 mm of a ball array (its escape and fanout are the board’s tightest routing). Held parts only turn and slide. A part also keeps out of a ball array’s 1.5 mm escape field and stays 1 mm clear of the line between consecutive pins of a matched net, moving no deeper into the box between them (or keeps what it has, if less). Deterministic (fixed orders, float64, exact quarter turns, no random draws; a golden hash).
Its moves are a trace event (detail, phase detailed-placement), their own animation segment
and an end-card line, and the record detail_motion (moves by kind, parts moved, sum, maximum
and median distance, wirelength and crossing before and after, channel delta, topology, time) in
the placement report, pnr-report.json, the hierarchical report and ladder-results.json.
legal_motion stays the legalizer’s own. The record carries the neighbour order kept from the
legal poses (neighbour_order) and from the global poses (neighbour_order_global), and
ladder-results.json gives each case order (gp_legal, legal_dp, gp_dp; end to end is
the legal poses’ when the pass did not run) and the document order (showcases_order for the
showcases): each stage’s order kept over every case, weighted by relation count.
KEEP push. A cluster whose push is infeasible now moves the conflicting pair needing the
least shift to its other axis and solves again (up to four times; channel pushes keep their
axis), and a failing push is retried with a size-scaled reach (0.75, then 1.0 of the larger side,
at most 4 mm), kept only when it displaces less (area-weighted) than relocating the part it would
give up. start-14 of the hierarchical block (testdata/legalize_keep): the column under D4 was
0.12 mm too tall for the outline in y, so D4 went 10.1 mm east; D4 is now pushed 0.76 mm and
nothing is relocated. 04-inverter-leds-8 seed 1’s U1 stays relocated: the outline corner and
the fixed connector box it in, and no push in its global order exists.
A/B (GCP c4d us-west4 for both arms, the runner’s ladder-v2 defaults, --legalize-keep --detail-place against --no-legalize-keep --no-detail-place; ladder, showcases and all 33 hard
rungs, seeds 0 and 1, then seeds 2 to 7 of the BGA rungs and buck-pour and 2 to 15 of the BGA
-pairs rung; KEEP alone from the R6 A/B above; campaigns 20261006-ladder-e132b3 (both arms),
-9c8a75, -931103, -56306d, -6f8fb4 (detailed placement at the final code) and -67bfc3,
-6f7476, -c18ee3 (KEEP off at the extra seeds)):
Rungs (seeds 0 and 1) |
Cells |
Pass: KEEP+DP / KEEP / off |
Copper: KEEP+DP vs off |
KEEP alone vs off |
|---|---|---|---|---|
ladder 01-08 |
16 |
16 / 16 / 16 |
-0.8 % |
+15.7 % |
showcases |
8 |
8 / 8 / 8 |
+5.8 % |
+13.7 % |
|
28 |
28 / 28 / 28 |
+3.3 % |
+17.5 % |
MCU lane |
18 |
18 / 18 / 18 |
-1.3 % |
+5.8 % |
BGA |
12 |
11 / 11 / 12 |
-0.2 % |
+0.0 % |
quad-bank, power-switch, buck |
8 |
8 / 7 / 8 |
-2.2 % |
+11.4 % |
all |
90 |
89 / 88 / 90 |
+0.12 % |
+7.84 % |
Copper on the 87 cells all three arms pass; over the 140 cells with the extra seeds KEEP+DP is
0.9 % shorter than KEEP off. Extra seeds: buck-pour 7 of 8 in both arms (seed 5 fails with
detailed placement on a pad entry, seed 3 without; on the KEEP-only placement of seed 5,
testdata/detail_place, detailed placement takes R1 off U1’s far side); BGA base,
-block, -classes and -partial 8 of 8 in both arms; -rails 7 of 8 against 5 of 8; -pairs
13 of 16 against 15 of 16 with KEEP off and 14 of 16 with KEEP alone (-4cf25e): seeds 9 and 12
fail the LVDS pair’s gap rule by one or two findings with KEEP alone too (detailed placement moved
nothing in their chosen placements), and on seed 1 every finalist the initial pool routed had the
pair uncoupled or a connection missing, so it took one with the pair as legs. Parts within 3 mm
of the ball array no longer move, so the BGA rungs gain little copper.
The confirming round fixed both causes, which are the pool’s and the pair router’s, not the
placement’s. The router now prefers pad fanouts without a stretch parallel to the other leg off
the gap for a pair whose coupling the design judges (max_uncoupled_mm; coupled.gap_breaks,
KiCad’s nearest-parallel model). The pool counts such a pair off its gap or as legs against a
finalist (pairs_gap, judged_pair_flaws) and routes up to two more candidates by the proxy
screen when every finalist leaves a connection open or such a pair flawed (EXTRA_FINALISTS).
On the Mac, seeds 1, 9 and 12 pass.
Detailed placement moved 1174 parts by 2243 mm in the final placements (the median of the cells’
medians 1.2 mm, mostly compaction; the largest 14 mm), 79 s in all. The
legalization motion (the legalizer’s own, legal_motion) is 179 of 1496 parts and 999 mm with 43
relocated, against 148, 285 mm and 29 with KEEP alone: on four cells the pool now picks the
source start, whose global placement leaves 4 to 12 parts mostly occluded; without those 155 of
1455 parts and 283 mm (KEEP alone on the same cells: 131 and 237 mm).
I. The pool’s own screen penalizes wholesale relocation (PNR_POOL_MOTION_PENALTY, 2026-10-06)¶
Superseded by section J: the penalty had no effect on the selection.
Review of the A/B above (section H): “legalization motion stays at the KEEP level” missed its own
pass mark (999 mm / 43 relocated against 285 mm / 29 with KEEP alone), driven by cells where the
initial pool picked a start whose global placement left 4 to 12 parts mostly occluded, so
PNR_LEGALIZE_KEEP correctly relocated them (the packer’s cost and turn search, per its own
triage) but the pool had a legal, lower-relocation alternative on the shortlist and never
screened for that. 11-ufbga201-fanout-6L-SGSGPS-rails seeds 3, 4, 6 and 7 (11 of 11 parts, 356 mm
each) and the 07-chaser-20-4L-SGPS family seed 0 (12 parts, 617 mm) carried most of the overshoot.
Change (pnr.place.initial_pool.pool_motion_penalty_factor, legalize_flags.pool_motion_penalty,
PNR_POOL_MOTION_PENALTY; unset follows PNR_LEGALIZE_KEEP, 0 off for an A/B): each start’s
cheap_score (the pool’s own screen, before the capacity proxy and the routed comparison) is
multiplied by 1 + 4 * max(0, relocated_fraction - 0.2), where relocated_fraction is that
start’s legal_motion.relocated (parts PNR_LEGALIZE_KEEP actually relocated, not pushed) over
the movable part count. A start under the fifth of the board the owner’s principle treats as
normal (only a mostly occluded part relocates) screens exactly as before; a start that forces
relocation of most or all of the board, as -rails/07-SGPS did, loses its shortlist slot to any
legal alternative at a comparable raw screen, before proxy scoring or routing ever sees it. The
penalty is diagnostic-visible (pool_motion_penalty, raw_cheap_score on the candidate record)
and never improves a start’s score, so a design with no low-relocation alternative is unaffected.
Status. Unit-level (initial_pool_test: PoolMotionPenaltyTest) and the full legalizer/pool
suites (legalize_flags_test, legalize_keep_test, legalize_wire_test, detail_place_test)
pass; CI’s ladder is green on both #64 and #70. This has not yet been re-measured on
-rails/07-SGPS themselves on GCP (the A/B in section H predates this change) — that re-run,
plus whether it also narrows the -pairs seed-1 gap (a pool-selection problem, not relocation:
every routed finalist had the LVDS pair uncoupled or a connection missing), is the next step before
reconsidering the section H merge decision.
J. A start that relocates much of the board enters no shortlist (PNR_POOL_RELOCATION_SCREEN, 2026-10-07)¶
The confirming A/B of section I (KEEP + detailed placement against KEEP off, every rung at seeds
0-1) still measured 255 parts, 1522 mm and 73 relocated by legalization against 148, 285 mm and 29
with KEEP alone. On five cells the pool picked the source start (start-01): its global placement
leaves most parts occluded, so PNR_LEGALIZE_KEEP relocated 11 of 11 parts on -rails s0 (356 mm)
and 12 of 19 on 07-chaser-20-4L-SGPS s0 (617 mm). The cheap_score penalty never acted: the pool’s
proxy budget equals its start count (8), so every legal start reached the capacity proxy whatever
its cheap score, and the finalists’ RMS pose-diversity fill then took the source start because it
lay far from every other start; the routed comparison picked it for two fewer vias (-rails s0: 134
against 136).
Change (pnr.place.initial_pool.wholesale_relocation, legalize_flags.pool_relocation_screen,
PNR_POOL_RELOCATION_SCREEN; unset follows PNR_LEGALIZE_KEEP, 0 off for an A/B). A start whose
own legalization relocated more than one part and more than 20 % of the movable parts is flagged
(wholesale_relocation and relocated on its candidate record) and kept out of the proxy
shortlist, its diversity fill and the routed finalists while another legal start exists (the report
lists it under relocation_screened); when every legal start is flagged the pool selects among them
as before. The cheap_score penalty is removed.
The threshold. The 20 % is the upper edge of KEEP’s own relocation mode. Over the 42 KEEP pools
logged by the Mac detailed-placement measurement runs (the eight ladder rungs, three flat showcases,
09-mcu-usb-31 and buck-pour, mostly seed 0; 373 distinct legalized starts), 321 starts relocate
nothing, 14 relocate at most 20 % (one or two occluded parts, the case the owner’s principle names)
and 38 relocate 28 % to 100 %, one or two per pool in 33 pools, the source start among them. No
start lies between 20 % and 28 %, and no pool had every start above 20 %. The one-part floor keeps a
single fully occluded part legal on a small board (one of five parts is 20 %, one of two is 50 %).
14. Layer-aware channel model (PNR_CHANNEL_LAYERS, 2026-10-06)¶
The routing-channel model (pnr.place.channels.ChannelModel) prices the gap between two facing
pad rows as if every externally connected net on both rows ran along it on the surface. Global
placement (the compact GP inflation floor), the legalizer’s slot cost and the
PNR_LEGALIZE_KEEP push all read it, so an overestimate spreads parts that the router never
needed apart, or makes the push give up on channels it cannot open.
Measurement (regression/channel_audit.py, pnr.place.channel_audit). For each channel the
model prices on a routed board, the audit takes the busiest cut across the gap and counts the
surface tracks that run along the channel there (tracks crossing straight from row to row do not
count) and the vias in it, priced the way the model prices its own demand. Each predicted net is
classed as surface (it ran along the channel), dropped (a via within 1 mm of its pad) or
elsewhere. On the 88 passing cells of the default configuration (ladder, showcases and the 33
hard rungs, seeds 0 and 1), in the channels the model calls short:
Copper layers |
Short channels |
Width used / predicted |
Predicted nets on surface / dropped / elsewhere |
|---|---|---|---|
2 |
752 |
36 % |
23 / 32 / 45 % |
4 |
208 |
38 % |
13 / 54 / 33 % |
6 |
87 |
45 % |
13 / 56 / 31 % |
8 |
22 |
35 % |
11 / 57 / 31 % |
The model is about 2.5 times too conservative at every layer count. Two things account for it: nets leave by another face (a two-pad part’s pad lies on three faces of its part), and nets drop to another layer next to their pad. Dropping grows from a third of the nets on two layers to over half on four or more.
Model. With PNR_CHANNEL_LAYERS=1 the model credits the board’s other signal layers (copper
layers less plane layers, channels.signal_layers). A net with a drop site off the channel asks
only its surface share, one over the signal-layer count. A drop site is a through-hole pad, a pad
that holds a via in pad under the fab’s in-pad class, or a pad that also lies on another face of
its part, whose via can go out that way. A mid-row net may also drop at that share, but then the
channel pays one shared via row (the via diameter and a clearance). The demand is the cheaper of
the two options, never more than the surface-only one. It is unchanged on a single signal layer
and for plane nets. A block’s port nets (block_ports) keep the surface price, because they must
reach the block edge where the parent board routes them. Without this rule both seeds of
hier-twin-bank-32 lost CLOCK at the top level. The change lives in the model itself, so
global placement, the legalizer and its push price every channel the same way. Repriced on the
same boards, the short channels fall to 258 / 111 / 49 / 11, and the router still used about half
of the new predicted width there.
A/B (GCP C4D, claude/lv2-defaults plus this change, every ladder-v2 default on, the same
90 cells per arm; hierarchical cells from the rerun with the block-port rule, seeds 0 to 5):
Arm |
Pass |
Copper (86 both-pass cells) |
Vias |
|
Legalization motion, cells with the same pool start (47) |
|---|---|---|---|---|---|
on |
89/90 |
31826 mm (-1.8 %) |
3696 |
582 |
56 parts moved, 141 mm, 22 relocated |
off |
88/90 |
32405 mm |
3740 |
1033 |
71 parts moved, 157 mm, 21 relocated |
Both arms fail 11-buck-vqfnhr-4L-SGPS-pour seed 0 (the open issue in section 11). Off also
fails 11-ufbga201-...-rails seed 1. 10-quad-bank-56 loses CLOCK on seeds 2 and 3 in both
arms (a top-level knit issue, independent of the switch). Copper by family: 07 variants -3.9 %,
MCU lane -1.2 %, BGA -0.1 %, showcases -3.0 %, power -20 %, ladder +3.0 %. The two BGA cells with
large relocations in the on arm picked the initial pool’s source start, whose global placement
stacks the decoupling capacitors (severe, relocated 74 mm). The off arm picked another start, so
the full-table motion total (976 against 285 mm) compares different starts. On cells where both
arms chose the same start, on moves less.
The switch stays off by default here. Turning it on with the other ladder-v2 defaults changes the
flag-off identity goldens (compact_test) and the shortage-driven fixtures (elastic_test,
region_align_test), which then need regenerating.