vyges physical ppl — CLI reference

Generated from vyges physical ppl --help — this page is the tool’s own output, verbatim.

vyges physical ppl — IO pin placement: pins on the die boundary, where the wiring is cheapest

USAGE:
  vyges physical ppl slots      <design.odb> --hor-layers L[,L…] --ver-layers L[,L…] [options]
  vyges physical ppl place-pins <design.odb> --hor-layers L[,L…] --ver-layers L[,L…] [options]
  vyges physical ppl --describe
  vyges physical ppl --help

OPTIONS:
  --hor-layers L,…       layers carrying pins on the LEFT and RIGHT edges (required)
  --ver-layers L,…       layers carrying pins on the BOTTOM and TOP edges (required)
  --min-distance D       minimum spacing between pins, in MICRONS
                         (omitted: candidates every 2 tracks — not 'no spacing')
  --min-distance-in-tracks   read --min-distance as a count of candidate slots instead
  --corner-avoidance D   keep pins this far from each corner, in MICRONS
                         (omitted: 2 tracks, capped at 1um)
  --hor-multiplier M     widen pins on the left/right edges by this factor
  --ver-multiplier M     widen pins on the bottom/top edges by this factor
  --hor-length L         `set_pin_length -hor_length`, microns: the depth of pins on the
                         left/right edges, which also deepens what keeps them off nearby shapes
  --ver-length L         the same for pins on the bottom/top edges
  --hor-extension L      `set_pin_length_extension -hor_extension`, microns: how far pins on the
                         left/right edges reach OUT past the die (written pins only)
  --ver-extension L      the same for pins on the bottom/top edges
  --out-odb FILE         write the placed pins into a copy of the database: each port's pin
                         replaced by one rectangle on its layer, PLACED
  --slots-per-section N  slots per matching section (default 200)
  --annealing            place by simulated annealing instead of optimal matching
  --temperature T        annealing start temperature (default 1.0)
  --max-iterations N     annealing temperature steps (default 2000)
  --perturb-per-iter N   perturbations per step (default: scaled to the pin count)
  --alpha A              annealing cooling rate (default 0.985)
  --random-seed N        annealing seed (default 42)
  --evaluate FILE        also score a reference placement under the same cost model.
                         FILE is JSON mapping each pin name to an [x, y] pair in DBU.
                         Reports reference_hpwl, so a placement that merely DIFFERS
                         can be told from one that is WORSE.
  -o FILE                write the report to FILE instead of stdout
  --json                 emit JSON (the default)
  --describe             print a machine-readable JSON description of the command

EXIT STATUS:
  0  ok        slots were generated / every pin was placed
  1  refused   no legal pin position on the layers given, or not enough room for the pins
  2  error     usage error, unreadable database, or no DBU scale

Contract

Generated from vyges physical ppl --describe.

ppl

IO pin placement: pins on the die boundary, positioned to minimise the wire needed to reach them

Maturity: structured

place-pins {odb} --hor-layers {hor_layers} --ver-layers {ver_layers}

Consumes: odb

Artifacts: slot_report (report_path)

Assertion: pins-placed — passes when status equals ok

Provenance limitations

• input_hash covers the argument vector, not the content of the .odb it names.
• SCOPE: this build implements slot generation, EXCLUDED REGIONS (exclude_io_pin_region), REGION CONSTRAINTS (set_io_pin_constraint -region edge:lo-hi, by pin name or by direction), PIN GROUPS (-group/-order, including fallback placement for groups too large for a section), MIRRORED PIN PAIRS (-mirrored_pins), ports already fixed by place_pin, and the deterministic assignment of the remaining pins – sections plus optimal (Hungarian) matching within each section. TOP-LAYER placement (define_pin_shape_pattern + -region up:), and the deterministic assignment of the rest. POLYGON (rectilinear) dies, SIMULATED ANNEALING for plain pins, and the deterministic assignment of the rest.
• ANNEALING (--annealing) reproduces the reference EXACTLY, including its random stream: the reference draws from Boost, whose algorithms are specified and portable, so the engine, both distributions and the shuffle are reimplemented bit-for-bit. Verified by comparing all 86000 perturbations of a run against the reference own debug trace – every cost and delta identical. Scope: plain pins only. A design with groups, constraints or mirrored pairs is REFUSED rather than annealed, because those add move types whose draws would desynchronise the stream and yield a plausible wrong answer.
• ⚠️ The committed annealing goldens in the reference test suite are STALE: a live run of the pinned build disagrees with annealing1.defok on 49 of 54 pins. Compare annealing against a live run, never against those files.
• A POLYGON die has no named edges, so its boundary is handled as a list of segments: an edge is a segment, its direction comes from the order of its endpoints, and sections are cut per segment. Five points is a RECTANGLE (the ring repeats its first point); more than five takes the polygon path. LIMITATION: edge-named region constraints (-region bottom:...) are REPORTED AND IGNORED on a polygon die rather than reinterpreted against the bounding box, which would satisfy a constraint the design did not ask for.
• TOP-LAYER pins are placed on a 2-D lattice INSIDE the die rather than on its boundary, so almost none of the edge rules apply to them: there is no direction to order a group along and no opposite side to mirror to. A lattice position is legal only if a pin of the declared size FITS there – inside the die, and clear of routing blockages, the power grid and fixed ports on that layer by at least the keepout. Non-rectangular grid regions are not handled.
• A MIRRORED pair is one decision, not two: only one half competes for a position and it is costed for both, its partner taking the reflection of whatever it gets. Mirrored pins are placed before free ones – they need two positions open at once, so they have the least room to manoeuvre. If a reflection is unavailable, BOTH halves are reported unplaced; half a pair is a broken symmetry, not a partial success.
• MEASURED: all 62 comparable reference cases match the reference total wirelength or beat it – 25 of them position-for-position, the rest by a cost-equal tie. No case is worse, none violates a constraint, and none leaves a pin unplaced.
• A slot is unusable for two independent reasons, both read from the block: it falls inside an EXCLUDED region, or it is covered by the metal of a port already placed FIXED. An excluded region is strict at both ends – a slot exactly on the boundary is still usable, which is the reference’s own convention.
• A pin GROUP occupies a contiguous run of slots and is placed before any individual pin, because a single pin dropped into the only long enough run destroys it irrecoverably. -order fixes the sequence, and only changes the result on the top and left edges, whose slot lists run in the opposite direction.
• A group larger than one section takes a FALLBACK path: the first contiguous run long enough, searched over slot indices rather than sections, so the run may cross an edge. On the top and left edges that path reverses the group unconditionally, where the matched path reverses only when -order is given – a difference inherited from the reference, not a rule with a stated reason.
• Constraints are read back from the DATABASE, where set_io_pin_constraint stores them on the ports – they are not command-line arguments here. A constrained pin is placed BEFORE any free pin, into sections cut from its own region, and the slots it takes are withdrawn; the reverse order would let a free pin occupy a region a constrained pin has no alternative to.
• Where two constraint regions OVERLAP, the one with more room per pin is served first, since whoever is served first takes the shared slots. Non-overlapping constraints keep the design’s own order.
• A constrained pin that does not fit its region is reported UNPLACED, not relocated: the design asked for a region, and somewhere else is not a smaller version of that answer.
• It reports the chosen pin positions, and with --out-odb WRITES them: each placed port’s pins replaced by one rectangle on its layer, PLACED – the depth from the layer’s minimum width and area (or --hor-length/--ver-length), widened by the thickness multiplier, extended out of the die by --hor-extension/--ver-extension, oriented from the position (from probes either side of the segment on a polygon die). Measured 2026-10-14: every pin both this and the reference place at the same point carries an identical DEF record, 4853 of 4853, rectangle and polygon dies alike. A placement that leaves a pin unplaced writes nothing.
• Assignment is optimal WITHIN a section and greedy BETWEEN sections: pins are routed to the cheapest section with room, and only then matched optimally inside it. This is the reference decomposition, not an approximation introduced here.
• Cost is half-perimeter wirelength over the net bounding box. A net whose driver or loads are unplaced uses the die centre for them, as the reference does.
• The optimal assignment COST is unique but the optimal PAIRING is not: where two pairings cost the same, this and the reference may place two pins in swapped slots and both be correct. Compare total cost before treating a difference as a defect – --evaluate scores a reference placement under the same cost model for exactly this.
• Slots are generated on the DIE boundary from each layer’s routing track patterns, minus corner avoidance, minus half the pin width at each end, minus the requested minimum distance.
• PARTIAL: slot availability accounts for excluded regions and for fixed ports’ metal, but NOT yet for macros or routing obstructions. Where a macro abuts the boundary, availability remains optimistic.
• The default corner avoidance is resolved once from a layer’s FIRST track pattern and reused for the rest, which is the reference’s behavior and is observable on layers carrying mixed-pitch patterns. Reproduced deliberately.
• -min_distance_in_tracks with a distance of 0 is a division by zero in the reference; here it keeps every candidate. A deliberate divergence, on an input that has no defined meaning.
• Written against the reference ppl sources at pin 4155ac31014923e0fa721b691d222511adc7d8c3. The algorithm is reimplemented from the published behavior, not transliterated.