placement-study
Skill4 starsChanged 28 days agoMITView on GitHub
Compare and search component placements by their ratsnest before routing: score crossings, length, via-field zones and free pin or gate choices in milliseconds per candidate, draw the ratsnest for review, and route only the winner. Use when a full route is slow (minutes to an hour), when deciding where a block of parts should sit, which side or angle a connector takes, or which register output or GPIO drives which net, and when reviewing a placement before routing.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- bom-costSkill
- enclosure-fitSkill
- fab-orderSkill
- failure-reviewSkill
- pcb-kitSkill
- power-simSkill
- routingSkill
- visual-reviewSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Look at it: pcbkit place-score BOARD --planes GND,VLED --svg out.svg --png out.png, then read the PNG.
- Very specific: line 18
Write the study in the project, e.g.
- Very specific: line 22
Look at the best one's picture (--svg), and at the runners-up: a near tie is a judgement call (heat, assembly, the enclosure) the score …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Placement study
Routing to find out whether a placement works is slow: a full A* route of a dense board can take most of an hour, and a small change moves which net fails. A ratsnest score takes milliseconds, so compare placements by it and route only the winner. On Orbitchron's driver board the first scored placement cut the unconnected items of the full route from 7 to 3 (2026-10-14).
Steps
- Generate a placed, unrouted board with the project's own generator (routed boards work too: tracks are ignored).
- Look at it:
pcbkit place-score BOARD --planes GND,VLED --svg out.svg --png out.png, then read the PNG. Edges are coloured by side (front red, back blue, both purple), crossings are circled, courtyards of back parts dashed. - Write the study in the project, e.g.
scripts/place_study.py(below): which footprints move together, where they may go, the zones to keep clear, the free choices. pcbkit place-score BOARD --study scripts/place_study.pyscores the current placement;--searchruns coordinate descent over the groups and prints the best and the next few.- Look at the best one's picture (
--svg), and at the runners-up: a near tie is a judgement call (heat, assembly, the enclosure) the score cannot make. --write design/placement.json; the project's generator reads it, so the schematic (for pin and gate choices) and the board follow. Regenerate both from the project's scripts; the kit never writes the board.- Route the winner. Record the score, the route result (unconnected items, DRC) and the date in LAYOUT.md.
The study file
from pcbkit.placement import Study, Group, Zone, Perm, grid, assign
import layout # the project's own placement code, if it has one
STUDY = Study(
planes={"GND", "VLED"}, # plane nets: their pads only need a via
groups=[
# rigid: (dx, dy, rot) from where the board has it, rotating about the first footprint
Group("buck", ["U4", "L2", "C25"], grid(dx=(-6, 6, 1), dy=(-6, 6, 1), rot=(0, 90, 180, 270), r=8)),
# the project's code places it: place(parameter) -> {ref: (x, y, orientation)}; home = current parameter
Group("qwiic", ["J2", "R12", "R13"], range(40, 145, 5), place=layout.qwiic, home=90),
],
zones=[Zone(via_field_polygon, weight=2.0, side="B", name="via field"), # mm^2 x weight
Zone(keep_clear_polygon, forbid=True)], # any overlap is invalid
perms=[Perm("gates", gates, nets=["ROW0_G", "ROW1_G"])], # free choices, solved per candidate
weights=dict(cross=10.0, length=0.2))
def gates(ctx):
"""Which register output drives which FET gate: assign() finds the best one-to-one choice."""
fet = {r: next(p for p in ctx.pads[f"ROW{r}_G"] if p[3].startswith("Q")) for r in range(2)}
outs = {q: ctx.pad("U5", pin) for q, pin in (("QA", "15"), ("QB", "1"))}
return assign(range(2), outs, lambda r, q: [ctx.edge(f"ROW{r}_G", outs[q], fet[r])], ctx)- Pads are
(x, y, side, ref, number); nets can be named in full (/Rows/ROW2_G) or by their last part. assign()is exact (branch and bound) up to 9 slots and greedy with swaps above that.- Several perms are solved in the study's order, each seeing the edges the ones before it chose (a crossing between two choices is priced once, in the later one): put the choice with the fewest options first.
- Rule areas on the board that keep footprints out are forbidden zones automatically, and the board outline is the
copper limit (
edge_clr, 0.3 mm; a connector body may overhang, its pads may not).
Reading the score
- Crossings count only where two nets' ratsnest edges could meet on one layer: front-only against back-only
never does; through-hole pads and side-changing edges meet everything.
--any-sidecounts them all (a 2-layer board routed mostly on one side). - The total is relative: compare candidates of one study, not boards. Crossings dominate at the default weights (one crossing = 50 mm of ratsnest).
- A fan-out from a chip to a header crosses itself in the ratsnest however it is placed; that cost is constant and does not steer the search. Judge it in the picture, not by the number.
Gotchas
- Plane nets left in swamp the score with long edges that the plane makes free.
- Courtyard lines touching is fine; overlapping area is not. Through-hole pads block both sides.
- The rules are only as good as the courtyards. Run
pcbkit courtyards BOARDfirst on a board with imported or project-library footprints: an EasyEDA import's connector courtyard sat 1 mm inside its body, and the first layout put a FET, a capacitor and the buck IC under it (ESP Candle base, 2026-11). - An invalid start (the board or
--start) is repaired before the descent: each group that breaks a rule takes its best valid candidate. If one has none, the search stops and says which rule. - The search is coordinate descent: it can stop in a local minimum. Start it from a few hand-made placements
(
--start other.json) when groups interact strongly. - A free choice changes the netlist: regenerate the schematic from the written JSON before routing, then run the project's netlist assertions.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

