Routers
Lightcycle, soldermask's own router, lays the copper, and KiCad's DRC judges it. This page covers which router runs, what each is told, and the settings that change it.
The router is the only judge of a placement: a placement is good if a router closes it. So part of every verdict is the tool, and every board records which router laid its copper.
At a glance
| Lightcycle | The A* router | |
|---|---|---|
| What it is | Soldermask's own router: soldermask/router.py, with its search in the lightcycle wheel. The wheel is built from soldermask-org/lightcycle, a private repository. | KiCadRoutingTools (drandyhaas, MIT): a grid A* search with a Rust core |
| Role | The router, by default. It also ranks the placements by routing them. | By name, or when Lightcycle is not installed |
| Reads | The netlist and placement, in memory | The .kicad_pcb |
| Track and clearance | 0.127 / 0.127 mm | 0.127 / 0.127 mm |
| Pinned by | Its wheel's version, 0.1.5 (router.LIGHTCYCLE) | Commit (KRT_SHA) and core version (KRT_CORE_VERSION) |
| Needs | The lightcycle wheel at the pinned version. soldermask setup downloads it with your GitHub login (gh, or GH_TOKEN), which needs access to the private repository. With no wheel for your machine, it builds one with cargo. router.ready() says what is missing. | Git, and a C and a Rust toolchain. soldermask setup --astar builds it; astar.ready() says what is missing. |
| Corpus label | lightcycle-0.1.5 | krt-02e4b52 |
Each router is pinned, so the corpus always records which program labelled each example. An unpinned checkout would relabel the corpus with a program nobody recorded.
Freerouting is not in the build. A design that names it is routed by Lightcycle, and the gaps say so. Only the corpus labeller still runs it.
Choosing which goes first
Lightcycle goes first unless the board names the A* router. The choice is a constraint, saved with the project, so every rebuild honours it.
| Where | How |
|---|---|
| Command line | --router lightcycle or --router krt |
| Constraints | constraints.rules.router: lightcycle (the default) or krt |
| Prompt | Name it: use the A* router, use Lightcycle |
| Workbench | The Router knob in the rack |
| Environment | SOLDERMASK_ROUTER, for a board whose constraints name no router |
When the chosen router cannot run, the other one routes the board. The gaps say so once:
| Case | What happens |
|---|---|
| Lightcycle is not built | The A* router routes the board. The gap gives the reason. |
The A* router is not installed, or the board carries copper somebody drew or inner planes (astar.refuses) | Lightcycle routes the board. The gap gives the reason. |
| Neither router is installed | The board is placed and not routed. The gap reads no router is installed: the board is placed and not routed (soldermask setup). |
The design names freerouting | Lightcycle routes the board, and the gap says freerouting is retired. |
A net wider than the track does not change the router. Both routers lay each net at its own width.
A person's floor (constraints.rules.min_track_mm) and a net's declared current widen the track for every router. A part whose pads sit closer than the clearance pulls the clearance down, never below the fab's 0.127 mm.
In the build
- The chosen router routes the placement.
- The pipeline walks the copper itself and names every pin a net misses.
- If a net is short of a pin, the build tries the next placement, up to three. It keeps the best board it saw.
On a machine of 32 cores or more, under the command line and the app, the three are routed at once. Each runs in a process of its own, and the rest are stopped once one comes back clean in rank order.
No second router is asked. This runs inside workspace.realise(), so the command line and the app both get it. On a poured board, the pour is laid over the kept copper.
With Lightcycle, the placements are routed and ranked before step 1. See Placing and routing in one loop.
No router installed
With neither router installed, the board is placed and not routed. The gaps say so and name soldermask setup, which builds Lightcycle.
Lightcycle
The A* router routes one net at a time and repairs afterwards. A net routed early can take the place a later one needed. Lightcycle routes every net together instead.
How it routes
Lightcycle is PathFinder (McMurchie and Ebeling, 1995), the negotiated-congestion scheme chip routers use.
- Every net is routed, with the other nets' copper priced rather than forbidden.
- Where two nets want one place, its price rises. It rises every round and never falls.
- Only the nets still in conflict are routed again.
No net is refused for being routed late. The search is compiled Rust (lightcycle.route_board) and has no numpy twin.
The rule on a grid
- The search steps on a 0.05 mm grid. A cell is legal for a net when all other nets are further than the clearance, both half-widths and g/√2 (the grid step's margin).
- Distances are measured to the exact pad shape (rectangle, circle or stadium, turned) and to the centre line of other nets' copper. So a path through legal cells is legal copper at every point.
router.violations()measures the copper independently of the search. It finds none on any board intests/test_router.py, including a 0.5 mm-pitch chip with a resistor on every pin.SOLDERMASK_LC_EXACT=1asks for exact margins instead: the clearance plus a few microns, not plus g/√2. It is off by default.- Each track width gets its own picture of the board, and vias one more. The search lands no via in a pad.
- An exposed pad, such as a QFN's thermal pad, can seal its net in. Where the first route leaves that net short, the board is routed again with one via at the pad's centre. The answer that reaches more pins is kept.
- A pad the grid cannot end on gets an escape stub before the attempt loop routes it. See Escape stubs.
- A plated hole of the net's own is a free layer change. Overlapping pad pieces of one net, such as a TO-252's tab or a QFN's exposed pad, are one terminal.
- A board left short is routed once more on a 0.035 mm grid, and the better answer is kept.
- A board still short by one or two pins is routed again under three other settings in turn, until one reaches every pin. The board's notes name the setting kept.
- A board further short keeps its first answer. The other settings have never closed one, so its notes say they were not tried.
| Setting | What it changes |
|---|---|
sharp | Nets that share a place pay more for it, sooner, and remember it longer. |
vias | A via costs 0.4 mm of track, and a layer's direction matters less. |
h1 | The search estimates the distance left exactly, so it explores more. |
Set SOLDERMASK_ROUTER_RETRY=0 to stop after the grid retry. Set SOLDERMASK_ROUTER_RETRY_SHORT to retry boards further short than 2 pins. A board the first route leaves more than 6 pins short skips the grid retry too, since it has never closed one. Set SOLDERMASK_ROUTER_RETRY_GRID_SHORT to move that line, or to 0 to retry every short board. Only a board still short pays for these tries; the changelog has the measurement.
Hand copper and wide nets
- Copper somebody drew (
Netlist.laid) and copper a caller keeps come back as they were. They act as pads of their net, and their net may start from them. The A* router refuses such a board (astar.refuses), so Lightcycle routes it even when the A* router was named. - A pad too narrow for its net's track, like a TSSOP's 0.3 mm pin on a 1.4 mm motor rail, is reached through a neck. Within 1 mm of that pad the net may narrow to the widest width the pad takes. Everywhere else it keeps its full width.
- Each neck is a note. It names the net, both widths, the pads and the net's current. A pad that no neck reaches keeps its gap.
| Setting | What it does | Default |
|---|---|---|
router.NECK_MM | How far from a pad a net may run narrower | 1.0 mm |
SOLDERMASK_ROUTER_NECK_MM | Overrides it; 0 turns necking off | unset |
Wide nets that will not fit
Wide nets can wall each other in at a fine-pitch driver. When that leaves a board short, the router tries once more, thin first:
- It routes the board again with every net at most 0.5 mm wide, then at the board's track width if still short.
- It measures how hot each net's copper would run (see below). Each net that runs warm is taken up and routed again alone at its own width. If that does not fit, it tries 0.6, 0.4 and then 0.3 of that width. The other nets hold their places.
- It widens every track still narrower than its net asks for, as far as its neighbours allow. Neighbouring nets share the room between them a step at a time.
- A track held on one side gets a shoulder. That is a parallel track of its own net, laid on the free side and overlapping it.
The result is kept only if it reaches more pins than the board had. A note says how many tracks reached their width and which nets were routed again.
The thin route also runs while the six placements are ranked, so a placement it closes ranks as closed.
| Setting | What it does | Default |
|---|---|---|
SOLDERMASK_ROUTER_THIN | The width caps tried in turn, in mm; 0 is the board's track; empty turns this off | 0.5,0 |
SOLDERMASK_ROUTER_UPGRADE | How many warm nets are routed again alone; 0 only widens | 12 |
SOLDERMASK_WIDEN_SHOULDERS | 0 widens tracks about their centre only | on |
SOLDERMASK_ROUTER_THIN_RANK | 0 keeps the thin route out of the ranking pass | on |
Copper too narrow for its current
Every build judges the copper it routed against each net's declared current. This covers every board, not only thin routes.
- It measures width across the copper. At points along a narrow track, it takes the span of the net's own copper on that layer. A shoulder or an overlapping track counts.
- It skips necks. Copper within
NECK_MMof the net's own pads carries one pin's share and is not judged. - It judges each narrow run on its own. A run is an unbroken stretch narrower than the net asks for. Its rise is the lesser of two estimates.
- The long-track estimate is IPC-2221 at the run's narrowest width.
- The short-run estimate starts from the 10 °C the widths are drawn for. It adds the run's own heating as it conducts into the wider copper at its ends.
| Rise | What the build does |
|---|---|
| Under 20 °C | Nothing |
| 20 °C up to 100 °C | A gap naming the net, the run's length and width, and the rise |
| 100 °C or more | The verdict fails, and the copper station holds |
SOLDERMASK_WARM_C and SOLDERMASK_HOT_C move the two lines. At 100 °C over a 25 °C room, FR-4 reaches its glass transition and softens.
Differential pairs
The build lays a USB, CAN or other differential pair as a pair. Its two tracks run side by side at a fixed gap, on the copper the board ships with.
- It finds the pairs by name.
USB_DPandUSB_DN,D+andD-,CANHandCANLare pairs, asphysics.pairsreads them. - It finds each pair's ends. An end is a P pad and an N pad within 3 mm of each other, on one part or two. A pair through two series resistors placed apart gets a far end within 10 mm.
- It routes the pair's middle as one net. The net is as wide as both tracks and the gap. It runs between two free points just off each end's pads. Every other net's copper is held.
- It keeps to one layer where it can. Otherwise the middle may change layer, at a via cost of 8 mm against 1.2 mm for a net.
- It splits that middle into two tracks. Each side is offset from the centre line by half the pitch. Both stop 0.8 mm short of a layer change. A stretch within clearance of another net's pad is cut out.
- It joins the pads to the tracks. The two nets are routed again, alone, with everything else held. That route also lays each side's own via at a layer change.
- It picks a side for P. It tries P on one side of the middle, and on the other only if the sides' lengths differ by more than 1 mm. It keeps the closer match.
- It tidies the tracks. Each track is cut back to the outermost points its pads' copper meets it, so no stub hangs off the end.
- It matches the lengths. If the two sides still differ by more than 1 mm, the shorter gets square bumps on its longest straight laid segment. The bumps go away from its partner, at most 0.5 mm tall, only where they clear every other net.
A pair is kept only when all of these hold:
- Both nets reach every pin they reached before.
- At least 1 mm of each laid track is still in the copper.
- The two sides together run no more than 1.3 times their old length, plus 6 mm.
- The sides differ in length by no more than they did as routed plus 1 mm, or by 1.5 mm at most.
Otherwise the pair stays as routed. Length here is what the physics review measures: the longest run between two of a side's pads, a via's barrel included.
| Board | Track width | Gap |
|---|---|---|
| Two layers | The board's track | The board's clearance |
| Four layers | The width nearest 90 Ω for USB, 100 Ω for others, 120 Ω for CAN | The board's clearance |
On two layers the plane is 1.5 mm below, so no sensible width reaches 90 Ω. The note gives the impedance the pair has. The build's physics review measures each pair's coupled length, skew and impedance on the finished copper.
| Setting | What it does | Default |
|---|---|---|
SOLDERMASK_PAIRS | 0 routes a pair's two nets as two nets | on |
Boards read from a file
A board read from a KiCad file is routed as the file draws it. The reader hands the router:
- Every pad's true shape. Ovals are stadiums, and rounded rectangles keep their corners. A chamfered pad keeps its rectangle as the outline, and a track may end only inside its inscribed arc.
- Every pad where the file puts it. That includes a pad on the other side from its part, and a pad whose angle cancels its footprint's turn.
- The holes. Non-plated holes are obstacles of no net.
- Copper no pad owns. Text, lines and shapes in copper are obstacles. A shape drawn with a net is that net's copper, and the router reaches it.
- The solder mask. One net may cross a mask opening over no pad. An opening over pads of several nets lets those nets reach their own pads. An opening over a pad with no net, or over copper the file draws, keeps copper out. A pad's opening wider than the clearance keeps other nets off the pad.
- The outline. Copper stays inside a notched or rounded outline by the edge rule, not just inside its bounding box.
- The rule areas. A zone the file marks as no tracks or no vias keeps that copper out. A footprint's own area moves with its part.
The file draws all of this around the author's placement. When the placer moves the parts:
- A part's own holes and copper go with it. A connector's pegs and a footprint's copper text move and turn with the part.
- The rest holds where no pad sits on it. That is the outline, the board's own copper, a mounting hole of its own and any logo opened in its solder mask. The placer keeps parts off all of it, so on a placement it made, all of it holds.
- A part placed on it is a gap. A pad past the outline or on a mounting hole is named in the gaps, and that piece is left out. Past the outline, only the strips of edge the pad touches are let go. A note says what was left out.
The file's own rules are not read
The build reads the board file and not its project. Net classes and custom rules in the .kicad_pro or .kicad_dru do not reach the router. The board is routed at 0.127 / 0.127 mm, like any other.
kicadpcb.read(exact_rotation=True) also keeps parts turned off the quarter turns at their own angle. It is off by default, because the Gerbers assume quarter turns.
It stops on work, not time
Lightcycle stops negotiating after a fixed amount of search: 600 million grid cells expanded. So the same board gives the same copper on any machine, at any load.
A 300 s clock is only a backstop. If it fires, the board's notes say so.
Under the command line and the app, a whole-board route also runs in a process of its own. It is stopped after 600 s, and the gaps say so. SOLDERMASK_ROUTER_WALL_S moves that wall, and 0 turns it off.
How it measured
Lightcycle is measured on held-out benches: boards nobody looked at while it was tuned. Each task is an author's board with its copper stripped, routed at the author's placement and outline. A referee (bench/referee.py) judges every route with kicad-cli under one 600 s clock.
| Bench | Boards | Lightcycle clean | Next best |
|---|---|---|---|
| Held-out, two layers (3 Oct 2026) | 249 | 190 (76.3%) | 159, KiCadRoutingTools at its upstream head |
| Held-out, four layers (5 Oct 2026) | 141 | 92 (65.2%) | 51, KiCadRoutingTools with escalation |
- Up to 50 nets, Lightcycle and KiCadRoutingTools are not separated. Lightcycle's lead is on the large boards.
- Fixes to how Lightcycle reads a KiCad file, found on the two-layer tasks, took it to 209 of the 249. That figure is not held out.
- On the earlier 300-board bench, 138 of whose boards were used to tune it, Lightcycle passed 253 of 299 (4 Oct 2026).
- On that bench's 135 boards both routers closed (27 Sep 2026), Lightcycle laid 21% less track and 23% fewer vias than the A* router.
The changelog holds every run, every other router measured, and the protocols.
The judge
Clean means every connection made and no DRC error the bare board lacks. The referee counts open connections and errors apart. It forgives only errors the bare board already has.
In the product's own replays, the 60-design suite passes 60 of 60 and the 305 saved designs pass 277. Those count the whole build, not only the router.
Placing and routing in one loop
With Lightcycle, the default, soldermask/tandem.py joins placing and routing:
- All six candidate placements are routed at once, a thread each.
- They are ranked by what the router did, not by the model. Within one board, the model's ranking has measured at chance.
- If none reaches every pin, three more placements are annealed from fresh seeds, routed, and ranked with the six.
A pad no placement can fix, like the wide rail above, gets no extra placements. SOLDERMASK_TANDEM_MORE sets how many are added, and SOLDERMASK_TANDEM=0 turns the loop off.
A targeted repair was built and measured first. It grew the courtyards of the parts where the router struggled and re-annealed around them. On the 13 bench boards where none of the six routed, it closed none. Three fresh placements closed two. tandem.repair is kept as the instrument that measured this; the build does not call it.
Watching it route
python tools/lightcycle_view.py routes bench boards one after another in 3D, at http://127.0.0.1:8778:
- Each net is drawn as it is laid. A net that is ripped up fades out before it is laid again.
- The places two nets still fight over flash red as each round ends.
- The corner shows the round and the nets still in conflict.
It is fed from inside the search (router.solve(watch=...)), so it shows every step. --board NAME holds one board; --pcb FILE routes any .kicad_pcb at its own placement.
The measurements are in the changelog under 26 Sep 2026, with tools/route_bench.py and tools/tandem_bench.py.
The A* router
What it is told
| Flag | Why |
|---|---|
--escalation off | Track, clearance and via sizes are exact. Left to its defaults, it closes a fine-pitch net by shrinking a via to 0.28 mm with a 0.18 mm drill, under the fab's floor. |
--same-net-pad-clearance at the clearance | No via sits in a pad. On one ATmega board, vias in pads showed as 28 clearance violations the router's own check called clean. |
--board-edge-clearance, --hole-to-hole-clearance | The same edge and hole rules every other writer uses |
--power-nets, --power-nets-widths | Each net wider than the track is routed at its own width (astar.net_widths) |
--no-power-tap-neckdown | A tap of a wide net that will not fit is left open and reported, rather than laid at the thin track |
Round pads longer than they are wide are written as KiCad's oval. Written as circle, KiCad, the pour and the router all read them as small dots, and tracks were laid through them.
Fine-pitch fanout
SOLDERMASK_FANOUT runs the A* router's own fanout (astar.fanout_pass) before it routes. It applies to parts with 16 pads or more at a pitch of 0.5 mm or finer (astar.fanout_candidates). It is off by default.
| Value | What it draws |
|---|---|
stub | A short trace out of every pad, fanned at 45° so the ends sit a rule apart |
underpad | A via just past each pad, staggered so neighbours a pitch apart still clear |
The board's notes say which parts it ran on and how many pads each escape reached.
What its tests hold
tests/test_astar.py holds the seam between the A* router and the pipeline:
- Copper written to a
.kicad_pcband read back matches to KiCad's three decimals. - Copper read back without the y-flip is a mirror image, and the pin walk catches it.
- No board is refused for a wide net.
One rule, every writer
Each reader is told the rule in its own language:
| Reader | Where the rule is written |
|---|---|
| Lightcycle | Its problem, built in memory (router.problem) |
| The A* router | Its command line (astar.argv) |
| kicad-cli, the judge | The project file (kicad.project) |
| Any Specctra router | The DSN each version stores (dsn.write) |
tests/test_rules.py holds the DSN, the command line and the project file to the same numbers: track, clearance and via, and every floor the DRC checks. tests/test_router.py holds Lightcycle's problem to them. Nine of the sixty evaluation boards once routed every net and then failed DRC on a difference between the writers.
Settings
| Setting | What it does | Default |
|---|---|---|
--router, constraints.rules.router | Which router goes first: lightcycle or krt | lightcycle |
SOLDERMASK_ROUTER | The first router for a board whose constraints name none | unset, so Lightcycle |
constraints.rules.min_track_mm | A floor under every routed track, in mm | none |
SOLDERMASK_ROUTE_WORKERS | How many placements the attempt loop routes at once | 3 on a machine of 32 cores or more, else 1 |
SOLDERMASK_ROUTE_PROCESSES | 0 routes those placements in threads, not processes. In processes, the rest stop once one comes back clean | on |
SOLDERMASK_ROUTER_RETRY_WORKERS | How many of a short board's retries run at once, in worker processes. The copper is the same | One a core under the CLI and the app, 1 in the library |
SOLDERMASK_ROUTER_WALL_S | Seconds before a whole-board route is stopped, under the CLI and the app. 0 turns it off | 600 |
SOLDERMASK_ESCAPE | 0 lays no escape stubs | on |
SOLDERMASK_EP_VIAS | 0 never gives an exposed pad a via | on |
SOLDERMASK_MASK_SHARED | 0 makes a mask window over several nets' pads a wall for all of them | on |
SOLDERMASK_LC_EXACT | 1 asks Lightcycle for exact margins | off |
SOLDERMASK_FANOUT | stub or underpad fanout before the A* router | off |
SOLDERMASK_TANDEM | 0 turns off Lightcycle's place-and-route loop | on |
SOLDERMASK_TANDEM_MORE | Fresh placements annealed when none of the six reaches every pin | 3 |
soldermask setup | Installs the pinned Lightcycle wheel, or builds it with cargo | |
soldermask setup --astar | Builds the A* router |
The corpus labels
- Each router's labels stay apart. A label names the router that made it (
corpus.Outcome.router).learn generatewrites the A* router's labels into.cache/corpus-astarby default. Each is kicad-cli's verdict on A* copper at the A* rule, withbase_violationsbeside it. An example's id names the placement, not the judge, solearn train --routerfits on one set or the other. See Routability. - An A* label keeps no count of its own. Its
corpus.OutcomehasunroutedandviolationsasNoneand is nevercleanby the label's rule. In a build, the pipeline's walk and kicad-cli's DRC judge its copper instead (PourOutcome.router_ok). - How much of a label is the tool. The older corpus was labelled by the retired router. Routability measures how many of its failures another router closes, and the CHANGELOG holds the rest.
Placement and routing
This page explains how the placer arranges parts, how the router joins them with copper, and how ground is poured over both layers.
Fab files
Every build writes the files a fab needs to make and assemble the board. This page lists each file, what is drawn on it, and how the pipeline checks it.