traceforge-pcb 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. traceforge/__init__.py +3 -0
  2. traceforge/__main__.py +3 -0
  3. traceforge/acp_server.py +570 -0
  4. traceforge/agent.py +680 -0
  5. traceforge/altium/__init__.py +6 -0
  6. traceforge/altium/cfb.py +70 -0
  7. traceforge/altium/cli.py +60 -0
  8. traceforge/altium/model.py +163 -0
  9. traceforge/altium/outputs.py +24 -0
  10. traceforge/altium/pcb.py +301 -0
  11. traceforge/altium/project.py +328 -0
  12. traceforge/altium/schematic.py +400 -0
  13. traceforge/altium/tools.py +166 -0
  14. traceforge/approval.py +219 -0
  15. traceforge/attachments.py +346 -0
  16. traceforge/background.py +253 -0
  17. traceforge/bench/__init__.py +5 -0
  18. traceforge/bench/adapters.py +337 -0
  19. traceforge/bench/checks.py +410 -0
  20. traceforge/bench/cli.py +121 -0
  21. traceforge/bench/design.py +439 -0
  22. traceforge/bench/kicad.py +99 -0
  23. traceforge/bench/partscheck.py +159 -0
  24. traceforge/bench/review.py +100 -0
  25. traceforge/bench/runner.py +226 -0
  26. traceforge/bench/score.py +204 -0
  27. traceforge/bench/tasks.py +102 -0
  28. traceforge/chat.py +1185 -0
  29. traceforge/checks.py +328 -0
  30. traceforge/checks_sides.py +118 -0
  31. traceforge/cli.py +2224 -0
  32. traceforge/clipboard.py +107 -0
  33. traceforge/config.py +299 -0
  34. traceforge/context.py +276 -0
  35. traceforge/design/__init__.py +1 -0
  36. traceforge/design/constraints.py +397 -0
  37. traceforge/design/generate.py +1789 -0
  38. traceforge/design/outline.py +905 -0
  39. traceforge/design/schematic_layout.py +932 -0
  40. traceforge/design/schematic_lint.py +329 -0
  41. traceforge/design/schematic_route.py +207 -0
  42. traceforge/design/sheets.py +854 -0
  43. traceforge/design/sides.py +328 -0
  44. traceforge/design/spec.py +462 -0
  45. traceforge/design/specsheet.py +2351 -0
  46. traceforge/design/specsheet_render.py +183 -0
  47. traceforge/desktop/__init__.py +109 -0
  48. traceforge/desktop/keys.py +90 -0
  49. traceforge/desktop/project.py +443 -0
  50. traceforge/desktop/review.py +20 -0
  51. traceforge/desktop/server.py +1277 -0
  52. traceforge/desktop/static/app.css +223 -0
  53. traceforge/desktop/static/app.js +683 -0
  54. traceforge/desktop/static/highlight.js +77 -0
  55. traceforge/desktop/static/index.html +89 -0
  56. traceforge/desktop/static/md.js +90 -0
  57. traceforge/desktop/static/viewer.js +213 -0
  58. traceforge/desktop/symbols.py +212 -0
  59. traceforge/desktop/update.py +65 -0
  60. traceforge/diagnostics.py +67 -0
  61. traceforge/errata.py +219 -0
  62. traceforge/fab.py +108 -0
  63. traceforge/fab_layers.py +44 -0
  64. traceforge/features/__init__.py +6 -0
  65. traceforge/features/candidates.py +117 -0
  66. traceforge/features/cli.py +200 -0
  67. traceforge/features/package.py +433 -0
  68. traceforge/features/revdiff.py +224 -0
  69. traceforge/features/sarif.py +145 -0
  70. traceforge/features/viewer.py +265 -0
  71. traceforge/firmware/__init__.py +3 -0
  72. traceforge/firmware/cli.py +174 -0
  73. traceforge/firmware/drivers.py +372 -0
  74. traceforge/firmware/drivers_data.py +256 -0
  75. traceforge/firmware/mcus.py +177 -0
  76. traceforge/firmware/netlist.py +55 -0
  77. traceforge/firmware/pinmap.py +296 -0
  78. traceforge/firmware/scaffold.py +466 -0
  79. traceforge/firmware/toolchain.py +262 -0
  80. traceforge/hooks.py +237 -0
  81. traceforge/kicad/__init__.py +0 -0
  82. traceforge/kicad/cli.py +519 -0
  83. traceforge/kicad/diffpair.py +174 -0
  84. traceforge/kicad/edgegeom.py +191 -0
  85. traceforge/kicad/edit.py +405 -0
  86. traceforge/kicad/escape.py +1410 -0
  87. traceforge/kicad/formats.py +1073 -0
  88. traceforge/kicad/impedance.py +320 -0
  89. traceforge/kicad/install.py +75 -0
  90. traceforge/kicad/libraries.py +490 -0
  91. traceforge/kicad/models3d.py +942 -0
  92. traceforge/kicad/outputs.py +81 -0
  93. traceforge/kicad/pcb.py +787 -0
  94. traceforge/kicad/planes.py +1242 -0
  95. traceforge/kicad/project.py +136 -0
  96. traceforge/kicad/route.py +2698 -0
  97. traceforge/kicad/routegeom.py +164 -0
  98. traceforge/kicad/schematic.py +268 -0
  99. traceforge/kicad/sides.py +34 -0
  100. traceforge/kicad/stackup.py +424 -0
  101. traceforge/kicad_plugin/__init__.py +12 -0
  102. traceforge/kicad_plugin/actions.py +92 -0
  103. traceforge/kicad_plugin/cli.py +66 -0
  104. traceforge/kicad_plugin/client.py +86 -0
  105. traceforge/kicad_plugin/context.py +257 -0
  106. traceforge/kicad_plugin/discovery.py +81 -0
  107. traceforge/kicad_plugin/install.py +203 -0
  108. traceforge/kicad_plugin/overlay.py +60 -0
  109. traceforge/kicad_plugin/payload/action_plugin.py +65 -0
  110. traceforge/kicad_plugin/payload/ipc_main.py +42 -0
  111. traceforge/kicad_plugin/payload/plugin.json +90 -0
  112. traceforge/kicad_plugin/payload/requirements.txt +1 -0
  113. traceforge/kicad_plugin/views.py +202 -0
  114. traceforge/langchain.py +57 -0
  115. traceforge/local.py +580 -0
  116. traceforge/mcp_server.py +304 -0
  117. traceforge/models.py +310 -0
  118. traceforge/next_steps.py +110 -0
  119. traceforge/parts/__init__.py +52 -0
  120. traceforge/parts/alternates.py +488 -0
  121. traceforge/parts/bom.py +423 -0
  122. traceforge/parts/brief.py +705 -0
  123. traceforge/parts/catalog.py +297 -0
  124. traceforge/parts/cli_sourcing.py +156 -0
  125. traceforge/parts/data/duty_rates.yaml +37 -0
  126. traceforge/parts/data/hs_codes.yaml +103 -0
  127. traceforge/parts/datasheet.py +278 -0
  128. traceforge/parts/fx.py +100 -0
  129. traceforge/parts/model.py +185 -0
  130. traceforge/parts/net.py +187 -0
  131. traceforge/parts/offers.py +46 -0
  132. traceforge/parts/packages.py +397 -0
  133. traceforge/parts/pinout.py +714 -0
  134. traceforge/parts/providers/__init__.py +17 -0
  135. traceforge/parts/providers/base.py +100 -0
  136. traceforge/parts/providers/jlc.py +364 -0
  137. traceforge/parts/providers/keyed.py +661 -0
  138. traceforge/parts/report.py +508 -0
  139. traceforge/parts/supply.py +330 -0
  140. traceforge/parts/verify.py +455 -0
  141. traceforge/parts/web.py +575 -0
  142. traceforge/plans.py +70 -0
  143. traceforge/preferences.py +127 -0
  144. traceforge/prices.py +130 -0
  145. traceforge/prices.yaml +28 -0
  146. traceforge/prompts/__init__.py +54 -0
  147. traceforge/prompts/system.md +103 -0
  148. traceforge/providers.py +764 -0
  149. traceforge/remote/__init__.py +33 -0
  150. traceforge/remote/client.py +422 -0
  151. traceforge/remote/oidc.py +240 -0
  152. traceforge/remote/orgs.py +510 -0
  153. traceforge/remote/server.py +690 -0
  154. traceforge/remote/store.py +100 -0
  155. traceforge/review_changes.py +187 -0
  156. traceforge/routing.py +99 -0
  157. traceforge/runtime.py +435 -0
  158. traceforge/sessions.py +324 -0
  159. traceforge/sexpr.py +279 -0
  160. traceforge/sim/__init__.py +17 -0
  161. traceforge/sim/acmath.py +234 -0
  162. traceforge/sim/circuit.py +499 -0
  163. traceforge/sim/cli.py +162 -0
  164. traceforge/sim/engine.py +172 -0
  165. traceforge/sim/ltspice.py +175 -0
  166. traceforge/sim/measure.py +123 -0
  167. traceforge/sim/models.py +76 -0
  168. traceforge/sim/project.py +218 -0
  169. traceforge/sim/rawfile.py +123 -0
  170. traceforge/sim/results.py +298 -0
  171. traceforge/sim/tune.py +172 -0
  172. traceforge/skill_commands.py +165 -0
  173. traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
  174. traceforge/skill_library/compliance-review/SKILL.md +51 -0
  175. traceforge/skill_library/design-review/SKILL.md +47 -0
  176. traceforge/skill_library/errata-hunt/SKILL.md +30 -0
  177. traceforge/skill_library/firmware/SKILL.md +26 -0
  178. traceforge/skill_library/power-budget/SKILL.md +27 -0
  179. traceforge/skill_library/release-package/SKILL.md +29 -0
  180. traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
  181. traceforge/skill_library/thermal-review/SKILL.md +15 -0
  182. traceforge/skills.py +131 -0
  183. traceforge/thermal.py +557 -0
  184. traceforge/tools/__init__.py +48 -0
  185. traceforge/tools/agent_tools.py +213 -0
  186. traceforge/tools/base.py +303 -0
  187. traceforge/tools/batch.py +155 -0
  188. traceforge/tools/connections.py +245 -0
  189. traceforge/tools/files.py +777 -0
  190. traceforge/tools/firmware_tools.py +218 -0
  191. traceforge/tools/kicad_tools.py +1072 -0
  192. traceforge/tools/models3d_tools.py +141 -0
  193. traceforge/tools/parts_tools.py +473 -0
  194. traceforge/tools/processes.py +246 -0
  195. traceforge/tools/review_tools.py +178 -0
  196. traceforge/tools/sim_tools.py +230 -0
  197. traceforge/tui.py +620 -0
  198. traceforge/updates.py +124 -0
  199. traceforge/validate/__init__.py +77 -0
  200. traceforge/validate/builtins.py +1091 -0
  201. traceforge/validate/circuits.py +1240 -0
  202. traceforge/validate/config.py +410 -0
  203. traceforge/validate/default.yaml +113 -0
  204. traceforge/validate/design.py +191 -0
  205. traceforge/validate/explain.py +112 -0
  206. traceforge/validate/grounding.py +169 -0
  207. traceforge/validate/ipc2221.py +350 -0
  208. traceforge/validate/multilayer.py +805 -0
  209. traceforge/validate/netmodel.py +261 -0
  210. traceforge/validate/partcheck.py +472 -0
  211. traceforge/validate/report.py +280 -0
  212. traceforge/validate/review.py +322 -0
  213. traceforge/validate/runner.py +662 -0
  214. traceforge/workspace.py +171 -0
  215. traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
  216. traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
  217. traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
  218. traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
  219. traceforge_pcb-1.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,805 @@
1
+ """Checks for boards with inner layers: planes, return paths, via stubs, balance and fab stackups.
2
+
3
+ Everything here reads the written ``.kicad_pcb`` (and its ``.kicad_pro`` for layer roles and
4
+ differential pairs) without KiCad. It complements KiCad's DRC, which knows nothing about reference
5
+ planes. Two-layer boards are skipped.
6
+
7
+ Rules, with the ids their findings carry:
8
+
9
+ ``ml.layer_usage`` unused signal layers, tracks on plane layers, planes without a pour
10
+ ``ml.plane_gap`` a fast net runs where its reference plane has no copper
11
+ ``ml.plane_split`` a fast net crosses from one plane net to another on its reference layer
12
+ ``ml.return_via`` a fast net changes layers without a ground via nearby
13
+ ``ml.via_stub`` unused barrel left by a through via on a fast net
14
+ ``ml.copper_balance`` copper area very different on layers placed symmetrically about the core
15
+ ``ml.stackup_balance`` dielectrics or copper weights not mirrored about the core
16
+ ``ml.annular_ring`` ring around vias and holes by layer pair (inner layers need more)
17
+ ``ml.fab_stackup`` thickness, copper weight, drill depth and layer service against the fab
18
+
19
+ "Fast" nets are the differential pairs (from the project file and from net names) plus any nets
20
+ passed in. Thresholds are module constants; the geometry is sampled, not field-solved.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import json
26
+ import math
27
+ from dataclasses import dataclass, field
28
+
29
+ from traceforge import sexpr
30
+ from traceforge.checks import Finding
31
+ from traceforge.fab import FabProfile
32
+ from traceforge.fab_layers import capability
33
+ from traceforge.kicad import diffpair, stackup
34
+ from traceforge.kicad.pcb import Board, Track, Via
35
+ from traceforge.sexpr import Node, find, find_all, num, value
36
+
37
+ SAMPLE_MM = 0.25 # spacing of reference-plane samples along a track
38
+ GAP_MIN_MM = 1.0 # shorter uncovered runs are via / pad voids, not plane gaps
39
+ RETURN_VIA_MM = 3.0 # a ground via this close to a layer-changing via carries the return current
40
+ STUB_WARN_MM = 0.8
41
+ STUB_ERROR_MM = 1.5
42
+ BALANCE_WARN = 0.30 # difference in copper fraction between mirrored layers
43
+ BALANCE_ERROR = 0.50
44
+ MIRROR_TOLERANCE = 0.15 # relative difference between mirrored dielectrics
45
+ PLANE_TRACKS_MM = 15.0 # signal length on a plane layer that counts as a real split
46
+ LOPSIDED = 0.9 # share of track length on one signal layer, with other signal layers unused
47
+ C_MM_PER_NS = 299.79
48
+
49
+
50
+ Point = tuple[float, float]
51
+
52
+
53
+ # ------------------------------------------------------------------------ geometry
54
+ @dataclass
55
+ class Zone:
56
+ net: str
57
+ layers: list[str]
58
+ outline: list[Point]
59
+ filled: dict[str, list[list[Point]]] = field(default_factory=dict)
60
+ keepout: dict[str, str] = field(default_factory=dict)
61
+ name: str = ""
62
+
63
+ @property
64
+ def is_area(self) -> bool:
65
+ return bool(self.keepout)
66
+
67
+
68
+ @dataclass
69
+ class Geometry:
70
+ board: Board
71
+ names: list[str] # copper layers, top to bottom
72
+ stack: stackup.Stackup | None
73
+ zones: list[Zone]
74
+ roles: dict[str, str] # layer -> signal | plane
75
+ pairs: list[tuple[str, str]]
76
+ area: float # board outline area, mm2
77
+
78
+ def plane_layers(self) -> list[str]:
79
+ return [n for n in self.names if self.roles.get(n) == "plane"]
80
+
81
+ def copper_zones(self, layer: str) -> list[Zone]:
82
+ return [z for z in self.zones if not z.is_area and layer in z.layers]
83
+
84
+ def z_positions(self) -> dict[str, tuple[float, float]]:
85
+ """Layer -> (top, bottom) height in mm from the top face of the top copper."""
86
+ stack = self.stack
87
+ if stack is None or stack.count != len(self.names):
88
+ try:
89
+ stack = stackup.default_for(len(self.names))
90
+ except stackup.StackupError:
91
+ return {}
92
+ z = 0.0
93
+ out: dict[str, tuple[float, float]] = {}
94
+ for i, layer in enumerate(stack.copper):
95
+ out[self.names[i]] = (z, z + layer.thickness)
96
+ z += layer.thickness
97
+ if i < len(stack.dielectrics):
98
+ z += stack.dielectrics[i].thickness
99
+ return out
100
+
101
+
102
+ def _points(node: Node | None) -> list[Point]:
103
+ pts = find(node, "pts") if node is not None else None
104
+ if pts is None:
105
+ return []
106
+ return [(num(c[1]), num(c[2])) for c in find_all(pts, "xy")]
107
+
108
+
109
+ def _read_zones(root: Node) -> list[Zone]:
110
+ zones: list[Zone] = []
111
+ for z in find_all(root, "zone"):
112
+ layers = [str(value(z, "layer"))] if find(z, "layer") else []
113
+ multi = find(z, "layers")
114
+ if multi is not None:
115
+ layers = [str(a) for a in multi[1:]]
116
+ keepout = find(z, "keepout")
117
+ zone = Zone(
118
+ net=str(value(z, "net_name", "") or ""),
119
+ layers=layers,
120
+ outline=_points(find(z, "polygon")),
121
+ keepout={
122
+ str(c[0]): str(c[1])
123
+ for c in (keepout[1:] if keepout is not None else [])
124
+ if isinstance(c, list) and len(c) > 1
125
+ },
126
+ name=str(value(z, "name", "") or ""),
127
+ )
128
+ if not zone.net and keepout is None: # KiCad 10 names the net directly
129
+ net = find(z, "net")
130
+ if net is not None and len(net) > 1 and isinstance(net[1], str):
131
+ zone.net = str(net[1])
132
+ for filled in find_all(z, "filled_polygon"):
133
+ layer = str(value(filled, "layer", layers[0] if layers else ""))
134
+ zone.filled.setdefault(layer, []).append(_points(filled))
135
+ zones.append(zone)
136
+ return zones
137
+
138
+
139
+ def _project(board: Board) -> dict:
140
+ path = board.path.with_suffix(".kicad_pro")
141
+ try:
142
+ return json.loads(path.read_text(encoding="utf-8"))
143
+ except (OSError, ValueError):
144
+ return {}
145
+
146
+
147
+ def _poly_area(poly: list[Point]) -> float:
148
+ total = 0.0
149
+ for (x1, y1), (x2, y2) in zip(poly, poly[1:] + poly[:1]):
150
+ total += x1 * y2 - x2 * y1
151
+ return abs(total) / 2
152
+
153
+
154
+ def _inside(poly: list[Point], x: float, y: float) -> bool:
155
+ inside = False
156
+ j = len(poly) - 1
157
+ for i, (xi, yi) in enumerate(poly):
158
+ xj, yj = poly[j]
159
+ if (yi > y) != (yj > y) and x < (xj - xi) * (y - yi) / (yj - yi) + xi:
160
+ inside = not inside
161
+ j = i
162
+ return inside
163
+
164
+
165
+ class _Index:
166
+ """Polygons with bounding boxes, for repeated point queries."""
167
+
168
+ def __init__(self, polys: list[list[Point]]):
169
+ self.items = []
170
+ for p in polys:
171
+ if len(p) >= 3:
172
+ xs, ys = [q[0] for q in p], [q[1] for q in p]
173
+ self.items.append((min(xs), min(ys), max(xs), max(ys), p))
174
+
175
+ def contains(self, x: float, y: float) -> bool:
176
+ return any(
177
+ x0 <= x <= x1 and y0 <= y <= y1 and _inside(p, x, y) for x0, y0, x1, y1, p in self.items
178
+ )
179
+
180
+
181
+ def load(board: Board) -> Geometry:
182
+ root = sexpr.parse(board.path.read_text(encoding="utf-8"))
183
+ names = list(board.copper_layers)
184
+ try:
185
+ stack = stackup.read_stackup(board.path)
186
+ except (OSError, ValueError, stackup.StackupError):
187
+ stack = None
188
+ zones = _read_zones(root)
189
+ data = _project(board)
190
+ info = data.get("traceforge") or {}
191
+ roles = dict((info.get("stackup") or {}).get("roles") or {})
192
+ area = 0.0
193
+ if board.outline:
194
+ x0, y0, x1, y1 = board.outline
195
+ area = (x1 - x0) * (y1 - y0)
196
+ if not roles: # infer: an inner layer that is mostly one pour is a plane
197
+ for layer in names[1:-1]:
198
+ poured = sum(
199
+ _poly_area(z.outline)
200
+ for z in zones
201
+ if not z.is_area and layer in z.layers and z.net
202
+ )
203
+ roles[layer] = "plane" if area and poured >= 0.5 * area else "signal"
204
+ for layer in names:
205
+ roles.setdefault(layer, "signal")
206
+ pairs = [tuple(p["nets"]) for p in info.get("diff_pairs") or [] if len(p.get("nets", [])) == 2]
207
+ for pos, neg in diffpair.pair_names(set(board.nets.values()) - {""}):
208
+ if (pos, neg) not in pairs:
209
+ pairs.append((pos, neg))
210
+ return Geometry(board, names, stack, zones, roles, pairs, area) # type: ignore[arg-type]
211
+
212
+
213
+ def _fast_nets(geo: Geometry, extra: set[str] | None) -> set[str]:
214
+ nets = {n for pair in geo.pairs for n in pair}
215
+ return nets | set(extra or ())
216
+
217
+
218
+ # ------------------------------------------------------------------------ reference planes
219
+ def reference_layers(geo: Geometry, layer: str) -> list[str]:
220
+ """Plane layers above and below ``layer``, nearest first."""
221
+ if layer not in geo.names:
222
+ return []
223
+ i = geo.names.index(layer)
224
+ planes = [n for n in geo.names if geo.roles.get(n) == "plane" and n != layer]
225
+ z = geo.z_positions()
226
+
227
+ def distance(name: str) -> float:
228
+ if name in z and layer in z:
229
+ return abs(z[name][0] - z[layer][0])
230
+ return abs(geo.names.index(name) - i)
231
+
232
+ return sorted(planes, key=distance)[:2]
233
+
234
+
235
+ def _coverage(geo: Geometry, layer: str) -> tuple[_Index, list[tuple[str, _Index]], str]:
236
+ """Copper on ``layer`` as polygons: (all copper, per-net copper, how it was derived)."""
237
+ polys: list[list[Point]] = []
238
+ by_net: dict[str, list[list[Point]]] = {}
239
+ source = "filled"
240
+ areas = [
241
+ z
242
+ for z in geo.zones
243
+ if z.is_area and layer in z.layers and z.keepout.get("copperpour") == "not_allowed"
244
+ ]
245
+ for zone in geo.copper_zones(layer):
246
+ if layer in zone.filled:
247
+ shapes = zone.filled[layer]
248
+ else:
249
+ source = "outline (zone not filled)"
250
+ shapes = [zone.outline]
251
+ polys += shapes
252
+ by_net.setdefault(zone.net, []).extend(shapes)
253
+ index = _Index(polys)
254
+ cut = _Index([a.outline for a in areas]) if source != "filled" and areas else None
255
+ if cut is not None:
256
+ original = index.contains
257
+ index.contains = lambda x, y: original(x, y) and not cut.contains(x, y) # type: ignore[method-assign]
258
+ return index, [(n, _Index(p)) for n, p in by_net.items()], source
259
+
260
+
261
+ def _samples(track: Track):
262
+ pieces = [(track.x1, track.y1, track.x2, track.y2)]
263
+ if track.mid is not None:
264
+ mx, my = track.mid
265
+ pieces = [(track.x1, track.y1, mx, my), (mx, my, track.x2, track.y2)]
266
+ for x1, y1, x2, y2 in pieces:
267
+ length = math.hypot(x2 - x1, y2 - y1)
268
+ steps = max(1, math.ceil(length / SAMPLE_MM))
269
+ for k in range(steps + 1):
270
+ t = k / steps
271
+ yield x1 + (x2 - x1) * t, y1 + (y2 - y1) * t, length / steps
272
+
273
+
274
+ # ------------------------------------------------------------------------ checks
275
+ def check_layer_usage(geo: Geometry) -> list[Finding]:
276
+ findings: list[Finding] = []
277
+ board = geo.board
278
+ length: dict[str, float] = {n: 0.0 for n in geo.names}
279
+ for t in board.tracks:
280
+ if t.layer in length:
281
+ length[t.layer] += t.length
282
+ signal = [n for n in geo.names if geo.roles.get(n) != "plane"]
283
+ for layer in signal:
284
+ if length[layer] == 0 and not geo.copper_zones(layer):
285
+ findings.append(
286
+ Finding(
287
+ "P2",
288
+ "ml.layer_usage",
289
+ f"signal layer {layer} carries no copper: it adds cost without use",
290
+ evidence=f"{layer}: 0 mm of track, no pour",
291
+ action="Route on it, make it a plane, or build the board with fewer layers.",
292
+ rule="layer usage",
293
+ )
294
+ )
295
+ total = sum(length[n] for n in signal)
296
+ if total > 50 and len(signal) > 2:
297
+ top = max(signal, key=lambda n: length[n])
298
+ if length[top] / total >= LOPSIDED:
299
+ findings.append(
300
+ Finding(
301
+ "P3",
302
+ "ml.layer_usage",
303
+ f"{length[top] / total:.0%} of the track length is on {top}",
304
+ evidence=", ".join(f"{n} {length[n]:.0f} mm" for n in signal),
305
+ action="Spread routing over the signal layers or drop an unused one.",
306
+ rule="layer balance",
307
+ confidence="medium",
308
+ )
309
+ )
310
+ for layer in geo.plane_layers():
311
+ if not [z for z in geo.copper_zones(layer) if z.net]:
312
+ findings.append(
313
+ Finding(
314
+ "P1",
315
+ "ml.layer_usage",
316
+ f"plane layer {layer} has no copper pour",
317
+ action=f"Pour a net on {layer}, or make it a signal layer.",
318
+ rule="plane layers",
319
+ )
320
+ )
321
+ elif length[layer] > PLANE_TRACKS_MM:
322
+ findings.append(
323
+ Finding(
324
+ "P1",
325
+ "ml.layer_usage",
326
+ f"{length[layer]:.0f} mm of track on plane layer {layer} cuts the plane",
327
+ action="Move the tracks to a signal layer.",
328
+ rule="plane layers",
329
+ )
330
+ )
331
+ elif length[layer] > 0:
332
+ findings.append(
333
+ Finding(
334
+ "P2",
335
+ "ml.layer_usage",
336
+ f"{length[layer]:.1f} mm of track on plane layer {layer}",
337
+ action="Keep signals off plane layers where possible.",
338
+ rule="plane layers",
339
+ )
340
+ )
341
+ return findings
342
+
343
+
344
+ def check_planes(geo: Geometry, fast: set[str]) -> list[Finding]:
345
+ """Reference plane under every fast track: no gap, no crossing between plane nets."""
346
+ findings: list[Finding] = []
347
+ cache: dict[str, tuple[_Index, list[tuple[str, _Index]], str]] = {}
348
+
349
+ def cover(layer: str):
350
+ if layer not in cache:
351
+ cache[layer] = _coverage(geo, layer)
352
+ return cache[layer]
353
+
354
+ tracks: dict[str, list[Track]] = {}
355
+ for t in geo.board.tracks:
356
+ if t.net in fast and geo.roles.get(t.layer) != "plane":
357
+ tracks.setdefault(t.net, []).append(t)
358
+ for net, segments in sorted(tracks.items()):
359
+ by_layer: dict[str, list[Track]] = {}
360
+ for t in segments:
361
+ by_layer.setdefault(t.layer, []).append(t)
362
+ for layer, group in by_layer.items():
363
+ refs = reference_layers(geo, layer)
364
+ if not refs:
365
+ findings.append(
366
+ Finding(
367
+ "P1",
368
+ "ml.plane_gap",
369
+ f"{net} on {layer} has no reference plane on this board",
370
+ nets=[net],
371
+ action="Route it on a layer next to a plane.",
372
+ rule="return path",
373
+ )
374
+ )
375
+ continue
376
+ primary = refs[0]
377
+ allcopper, per_net, source = cover(primary)
378
+ others = [cover(r)[0] for r in refs[1:]]
379
+ gap = 0.0
380
+ gap_at: Point | None = None
381
+ worst = 0.0
382
+ worst_at: Point | None = None
383
+ rescued = 0.0
384
+ signatures: list[frozenset[str]] = []
385
+ end: Point | None = None
386
+ for t in group:
387
+ if end is None or math.hypot(t.x1 - end[0], t.y1 - end[1]) > 1e-3:
388
+ worst, worst_at = _close_run(gap, gap_at, worst, worst_at)
389
+ gap, gap_at = 0.0, None
390
+ end = (t.x2, t.y2)
391
+ for x, y, step in _samples(t):
392
+ if allcopper.contains(x, y):
393
+ worst, worst_at = _close_run(gap, gap_at, worst, worst_at)
394
+ gap, gap_at = 0.0, None
395
+ sig = frozenset(n for n, idx in per_net if idx.contains(x, y))
396
+ if sig and (not signatures or signatures[-1] != sig):
397
+ signatures.append(sig)
398
+ else:
399
+ if any(o.contains(x, y) for o in others):
400
+ rescued += step
401
+ gap += step
402
+ gap_at = gap_at or (x, y)
403
+ worst, worst_at = _close_run(gap, gap_at, worst, worst_at)
404
+ if worst >= GAP_MIN_MM and worst_at is not None:
405
+ findings.append(
406
+ Finding(
407
+ "P1",
408
+ "ml.plane_gap",
409
+ f"{net} on {layer} runs {worst:.1f} mm over a gap in plane {primary}",
410
+ nets=[net],
411
+ evidence=f"gap starts near ({worst_at[0]:.1f}, {worst_at[1]:.1f}); "
412
+ f"plane copper from {source}"
413
+ + (
414
+ f"; {rescued:.1f} mm of it is covered by {', '.join(refs[1:])}"
415
+ if rescued
416
+ else ""
417
+ ),
418
+ action="Close the plane under the signal, or reroute it over solid copper.",
419
+ rule="the return current follows the signal on the nearest plane",
420
+ )
421
+ )
422
+ nets_seen = sorted({n for s in signatures for n in s})
423
+ if len(signatures) > 1 and len(nets_seen) > 1:
424
+ findings.append(
425
+ Finding(
426
+ "P1",
427
+ "ml.plane_split",
428
+ f"{net} on {layer} crosses a split of plane {primary} "
429
+ f"({' / '.join(nets_seen)})",
430
+ nets=[net],
431
+ evidence=f"plane copper from {source}",
432
+ action="Keep the signal over one plane net, or stitch the nets with a "
433
+ "capacitor/via at the crossing.",
434
+ rule="the return current follows the signal on the nearest plane",
435
+ )
436
+ )
437
+ return findings
438
+
439
+
440
+ def _close_run(gap: float, at: Point | None, worst: float, worst_at: Point | None):
441
+ if gap > worst:
442
+ return gap, at
443
+ return worst, worst_at
444
+
445
+
446
+ def _connected_layers(geo: Geometry, via: Via) -> set[str]:
447
+ found: set[str] = set()
448
+ reach = via.size / 2 + 0.01
449
+ for t in geo.board.tracks:
450
+ if t.net != via.net or t.layer not in geo.names:
451
+ continue
452
+ for x, y in ((t.x1, t.y1), (t.x2, t.y2)):
453
+ if math.hypot(x - via.x, y - via.y) <= reach:
454
+ found.add(t.layer)
455
+ for fp in geo.board.footprints:
456
+ for pad in fp.pads:
457
+ if pad.net == via.net and pad.contains(via.x, via.y):
458
+ found |= {n for n in geo.names if pad.on_layer(n)}
459
+ return found
460
+
461
+
462
+ def _span(geo: Geometry, via: Via) -> tuple[int, int]:
463
+ idx = [geo.names.index(n) for n in via.layers if n in geo.names]
464
+ if len(idx) < 2:
465
+ return 0, len(geo.names) - 1
466
+ return min(idx), max(idx)
467
+
468
+
469
+ def check_vias(geo: Geometry, fast: set[str]) -> list[Finding]:
470
+ findings: list[Finding] = []
471
+ z = geo.z_positions()
472
+ plane_nets = {
473
+ zone.net for layer in geo.plane_layers() for zone in geo.copper_zones(layer) if zone.net
474
+ }
475
+ ground = [v for v in geo.board.vias if v.net in plane_nets]
476
+ stubs: list[tuple[float, Via, str]] = []
477
+ no_return: list[Via] = []
478
+ for via in geo.board.vias:
479
+ if via.net not in fast:
480
+ continue
481
+ connected = _connected_layers(geo, via)
482
+ if len(connected) < 2 or not z:
483
+ continue
484
+ first, last = _span(geo, via)
485
+ order = [n for n in geo.names if n in connected]
486
+ top, bottom = order[0], order[-1]
487
+ up = z[top][0] - z[geo.names[first]][0]
488
+ down = z[geo.names[last]][1] - z[bottom][1]
489
+ stub = max(up, down)
490
+ if stub >= STUB_WARN_MM:
491
+ side = "top" if up >= down else "bottom"
492
+ stubs.append(
493
+ (stub, via, f"{side} side, signal leaves at {bottom if side == 'top' else top}")
494
+ )
495
+ near = [g for g in ground if math.hypot(g.x - via.x, g.y - via.y) <= RETURN_VIA_MM]
496
+ if not near:
497
+ no_return.append(via)
498
+ by_net: dict[str, list[tuple[float, Via, str]]] = {}
499
+ for item in stubs:
500
+ by_net.setdefault(item[1].net, []).append(item)
501
+ for net, items in sorted(by_net.items()):
502
+ length, via, where = max(items, key=lambda i: i[0])
503
+ er = 4.4
504
+ f_res = C_MM_PER_NS / (4 * length * math.sqrt(er))
505
+ findings.append(
506
+ Finding(
507
+ "P1" if length >= STUB_ERROR_MM else "P2",
508
+ "ml.via_stub",
509
+ f"{net}: {len(items)} via(s) leave a stub up to {length:.2f} mm",
510
+ nets=[net],
511
+ evidence=f"worst via at ({via.x:.2f}, {via.y:.2f}), {where}; "
512
+ f"quarter-wave resonance about {f_res:.0f} GHz",
513
+ action="Change layers only between the outer layers, or to the layer pair next to "
514
+ "an outer face, or back-drill / use a thinner stackup.",
515
+ rule=f"stubs under {STUB_WARN_MM} mm on fast nets",
516
+ )
517
+ )
518
+ by_net_ret: dict[str, list[Via]] = {}
519
+ for via in no_return:
520
+ by_net_ret.setdefault(via.net, []).append(via)
521
+ for net, vias in sorted(by_net_ret.items()):
522
+ v = vias[0]
523
+ findings.append(
524
+ Finding(
525
+ "P2",
526
+ "ml.return_via",
527
+ f"{net}: {len(vias)} layer change(s) without a plane-net via within "
528
+ f"{RETURN_VIA_MM:g} mm",
529
+ nets=[net],
530
+ evidence=f"first at ({v.x:.2f}, {v.y:.2f})",
531
+ action="Place a ground (reference net) via next to each layer-changing via.",
532
+ rule="the return current changes planes where the signal does",
533
+ )
534
+ )
535
+ return findings
536
+
537
+
538
+ def _layer_copper(geo: Geometry) -> dict[str, float]:
539
+ """Approximate copper fraction per layer (tracks + pads + vias + pours), capped at 1."""
540
+ board = geo.board
541
+ if not geo.area:
542
+ return {}
543
+ area = {n: 0.0 for n in geo.names}
544
+ for t in board.tracks:
545
+ if t.layer in area:
546
+ area[t.layer] += t.length * t.width
547
+ for fp in board.footprints:
548
+ for pad in fp.pads:
549
+ size = pad.width * pad.height * (math.pi / 4 if pad.shape in ("circle", "oval") else 1)
550
+ for n in geo.names:
551
+ if pad.on_layer(n) and pad.kind != "np_thru_hole":
552
+ area[n] += size
553
+ for v in board.vias:
554
+ for n in geo.names:
555
+ area[n] += math.pi / 4 * v.size**2
556
+ for n in geo.names:
557
+ poured = 0.0
558
+ for zone in geo.copper_zones(n):
559
+ if n in zone.filled:
560
+ poured += sum(_poly_area(p) for p in zone.filled[n])
561
+ else:
562
+ poured += _poly_area(zone.outline)
563
+ area[n] = max(area[n], poured) if poured else area[n]
564
+ return {n: min(1.0, a / geo.area) for n, a in area.items()}
565
+
566
+
567
+ def check_balance(geo: Geometry) -> list[Finding]:
568
+ findings: list[Finding] = []
569
+ frac = _layer_copper(geo)
570
+ n = len(geo.names)
571
+ for i in range(n // 2):
572
+ a, b = geo.names[i], geo.names[n - 1 - i]
573
+ if a not in frac or b not in frac:
574
+ continue
575
+ diff = abs(frac[a] - frac[b])
576
+ if diff >= BALANCE_WARN:
577
+ findings.append(
578
+ Finding(
579
+ "P1" if diff >= BALANCE_ERROR else "P2",
580
+ "ml.copper_balance",
581
+ f"copper coverage differs by {diff:.0%} between {a} ({frac[a]:.0%}) and "
582
+ f"{b} ({frac[b]:.0%}): the board can bow or twist",
583
+ action="Pour ground in the empty areas of the sparse layer or rebalance the layers.",
584
+ rule=f"copper area symmetric about the core within about {BALANCE_WARN:.0%}",
585
+ confidence="medium",
586
+ )
587
+ )
588
+ return findings
589
+
590
+
591
+ def check_stackup_balance(geo: Geometry) -> list[Finding]:
592
+ stack = geo.stack
593
+ if stack is None or stack.count < 4:
594
+ return []
595
+ findings: list[Finding] = []
596
+ n = stack.count
597
+ d = stack.dielectrics
598
+ bad = []
599
+ for i in range(len(d) // 2):
600
+ a, b = d[i].thickness, d[len(d) - 1 - i].thickness
601
+ if abs(a - b) > MIRROR_TOLERANCE * max(a, b):
602
+ bad.append(f"dielectric {i + 1} {a:g} mm vs dielectric {len(d) - i} {b:g} mm")
603
+ for i in range(n // 2):
604
+ a, b = stack.copper[i], stack.copper[n - 1 - i]
605
+ if abs(a.thickness - b.thickness) > MIRROR_TOLERANCE * max(a.thickness, b.thickness):
606
+ bad.append(
607
+ f"{a.name} {a.thickness / 0.035:.2g} oz vs {b.name} {b.thickness / 0.035:.2g} oz"
608
+ )
609
+ if bad:
610
+ findings.append(
611
+ Finding(
612
+ "P1",
613
+ "ml.stackup_balance",
614
+ "the stackup is not mirrored about the core: the board will warp",
615
+ evidence="; ".join(bad),
616
+ action="Make dielectric thicknesses and copper weights symmetric about the centre.",
617
+ rule=f"mirrored layers within {MIRROR_TOLERANCE:.0%}",
618
+ )
619
+ )
620
+ return findings
621
+
622
+
623
+ def check_rings(geo: Geometry, fab: FabProfile) -> list[Finding]:
624
+ findings: list[Finding] = []
625
+ cap = capability(fab.name, len(geo.names))
626
+ outer = cap.ring_outer if cap else fab.min_annular_ring
627
+ inner = cap.ring_inner if cap else fab.min_annular_ring + 0.02
628
+ last = len(geo.names) - 1
629
+ tight: dict[str, list[str]] = {}
630
+ for via in geo.board.vias:
631
+ first, end = _span(geo, via)
632
+ ring = (via.size - via.drill) / 2
633
+ if (first, end) == (0, last):
634
+ pair = "through"
635
+ need = max(outer, inner) if last > 1 else outer
636
+ else:
637
+ pair = f"{geo.names[first]}-{geo.names[end]}"
638
+ need = max(outer, inner)
639
+ if not (cap and cap.blind_buried):
640
+ findings.append(
641
+ Finding(
642
+ "P1",
643
+ "ml.annular_ring",
644
+ f"via at ({via.x:.2f}, {via.y:.2f}) spans {pair}: blind and buried vias "
645
+ f"are not in {fab.name}'s standard multilayer service",
646
+ nets=[via.net] if via.net else [],
647
+ action="Use through vias, or order the HDI / blind-via service.",
648
+ rule=f"{fab.name} {len(geo.names)}-layer capabilities",
649
+ confidence="medium",
650
+ )
651
+ )
652
+ if ring < need - 1e-6:
653
+ tight.setdefault(pair, []).append(f"({via.x:.2f}, {via.y:.2f}) ring {ring:.3f} mm")
654
+ for pair, items in tight.items():
655
+ need = max(outer, inner) if pair == "through" and last > 1 else outer
656
+ findings.append(
657
+ Finding(
658
+ "P1",
659
+ "ml.annular_ring",
660
+ f"{len(items)} {pair} via(s) with an annular ring below {need:g} mm"
661
+ + (" (inner layers register worse than outer ones)" if last > 1 else ""),
662
+ evidence=", ".join(items[:12]),
663
+ action="Enlarge the via pad or reduce the drill.",
664
+ rule=f"min ring {outer:g} mm outer, {inner:g} mm inner",
665
+ confidence="medium" if cap else "high",
666
+ )
667
+ )
668
+ small = []
669
+ for fp in geo.board.footprints:
670
+ for pad in fp.pads:
671
+ if pad.kind == "thru_hole" and pad.drill > 0:
672
+ ring = (min(pad.width, pad.height) - pad.drill) / 2
673
+ if ring < outer - 1e-6:
674
+ small.append(f"{fp.reference}.{pad.number} ring {ring:.3f} mm")
675
+ if small:
676
+ findings.append(
677
+ Finding(
678
+ "P1",
679
+ "ml.annular_ring",
680
+ f"{len(small)} plated pad(s) with an annular ring below {outer:g} mm",
681
+ evidence=", ".join(small[:12]),
682
+ action="Enlarge the pad or reduce the drill.",
683
+ rule=f"min ring {outer:g} mm",
684
+ )
685
+ )
686
+ return findings
687
+
688
+
689
+ def check_fab_stackup(geo: Geometry, fab: FabProfile) -> list[Finding]:
690
+ count = len(geo.names)
691
+ if fab.name != "jlcpcb" and capability(fab.name, count) is None:
692
+ return []
693
+ cap = capability(fab.name, count)
694
+ if cap is None:
695
+ return [
696
+ Finding(
697
+ "P1",
698
+ "ml.fab_stackup",
699
+ f"{fab.name} multi-layer capabilities are only tabulated for 4, 6 and 8 layers, "
700
+ f"not {count}",
701
+ confidence="medium",
702
+ )
703
+ ]
704
+ findings: list[Finding] = []
705
+ rule = f"{fab.name} {count}-layer service (typical values; verify on the order page)"
706
+ stack = geo.stack
707
+ board_t = geo.board.thickness
708
+ if stack is not None and abs(stack.thickness - board_t) > 0.1:
709
+ findings.append(
710
+ Finding(
711
+ "P2",
712
+ "ml.fab_stackup",
713
+ f"stackup adds up to {stack.thickness:g} mm but the board says {board_t:g} mm",
714
+ action="Make the stackup and the board thickness agree.",
715
+ rule=rule,
716
+ )
717
+ )
718
+ thickness = stack.thickness if stack is not None else board_t
719
+ if not any(abs(thickness - t) <= 0.1 for t in cap.thicknesses):
720
+ findings.append(
721
+ Finding(
722
+ "P1",
723
+ "ml.fab_stackup",
724
+ f"{thickness:g} mm is not a {fab.name} thickness for {count} layers "
725
+ f"(offered: {', '.join(f'{t:g}' for t in cap.thicknesses)})",
726
+ action="Pick an offered board thickness.",
727
+ rule=rule,
728
+ confidence="medium",
729
+ )
730
+ )
731
+ if stack is not None:
732
+ for i, layer in enumerate(stack.copper):
733
+ oz = layer.thickness / 0.035
734
+ offered = cap.outer_oz if i in (0, count - 1) else cap.inner_oz
735
+ if not any(abs(oz - o) <= 0.1 * o + 0.02 for o in offered):
736
+ findings.append(
737
+ Finding(
738
+ "P1",
739
+ "ml.fab_stackup",
740
+ f"{layer.name} copper of {oz:.2g} oz is not offered "
741
+ f"({'outer' if i in (0, count - 1) else 'inner'} layers: "
742
+ f"{', '.join(f'{o:g}' for o in offered)} oz)",
743
+ action="Choose an offered copper weight.",
744
+ rule=rule,
745
+ confidence="medium",
746
+ )
747
+ )
748
+ try:
749
+ standard = stackup.default_for(count)
750
+ except stackup.StackupError:
751
+ standard = None
752
+ if standard is not None and len(standard.dielectrics) == len(stack.dielectrics):
753
+ off = [
754
+ f"dielectric {i + 1}: {d.thickness:g} mm vs {s.thickness:g} mm"
755
+ for i, (d, s) in enumerate(zip(stack.dielectrics, standard.dielectrics))
756
+ if abs(d.thickness - s.thickness) > cap.stackup_tolerance * s.thickness
757
+ ]
758
+ if off:
759
+ findings.append(
760
+ Finding(
761
+ "P2",
762
+ "ml.fab_stackup",
763
+ f"dielectrics differ from the standard {fab.name} {count}-layer stackup, "
764
+ "so impedance will not match what the fab builds",
765
+ evidence="; ".join(off),
766
+ action="Use the fab's stackup (or ask for a custom one) before relying on "
767
+ "controlled impedance.",
768
+ rule=rule,
769
+ confidence="medium",
770
+ )
771
+ )
772
+ deep = [v for v in geo.board.vias if v.drill > 0 and thickness / v.drill > cap.max_aspect]
773
+ if deep:
774
+ worst = max(deep, key=lambda v: thickness / v.drill)
775
+ findings.append(
776
+ Finding(
777
+ "P1",
778
+ "ml.fab_stackup",
779
+ f"{len(deep)} via(s) are deeper than {cap.max_aspect:g}:1 "
780
+ f"({thickness:g} mm board, {worst.drill:g} mm drill)",
781
+ action="Use a larger drill or a thinner board.",
782
+ rule=rule,
783
+ confidence="medium",
784
+ )
785
+ )
786
+ return findings
787
+
788
+
789
+ # ------------------------------------------------------------------------ entry points
790
+ def multilayer_checks(
791
+ board: Board, fab: FabProfile, fast_nets: set[str] | None = None
792
+ ) -> list[Finding]:
793
+ """All multi-layer findings for a board (empty for boards with two copper layers)."""
794
+ if len(board.copper_layers) <= 2:
795
+ return []
796
+ geo = load(board)
797
+ fast = _fast_nets(geo, fast_nets)
798
+ findings = check_layer_usage(geo)
799
+ findings += check_planes(geo, fast)
800
+ findings += check_vias(geo, fast)
801
+ findings += check_balance(geo)
802
+ findings += check_stackup_balance(geo)
803
+ findings += check_rings(geo, fab)
804
+ findings += check_fab_stackup(geo, fab)
805
+ return findings