traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/validate/ipc2221.py

@@ -0,0 +1,350 @@
+"""IPC-2221 conductor width and spacing checks, plus an IEC 60664-1 style creepage/clearance guide.
+
+All tables are reference guides reproduced from the public standards' commonly quoted values; they are not
+a substitute for the standard and not a certification. Currents and voltages come from the design's
+declaration in ``.traceforge/electrical.yaml`` (see :func:`load_electrical`) or from net class names such
+as ``Power_10A`` / ``HV_230V``.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import math
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from traceforge.checks import Finding
+from traceforge.kicad.pcb import Board, Track
+from traceforge.validate import circuits
+
+GUIDE_NOTE = (
+    "Guide values from IPC-2221B (conductor width, Table 6-1 spacing) and IEC 60664-1 (creepage, pollution "
+    "degree 2): a design aid, not a compliance statement. Check the standard that applies to your product."
+)
+
+# IPC-2221B Table 6-1 electrical conductor spacing (mm). Columns:
+# B1 internal, B2 external uncoated <3050 m, B3 external uncoated >3050 m, B4 external with permanent
+# polymer coating, A5 external with conformal coating, A6 component lead/termination (conformal).
+SPACING_COLUMNS = ("B1", "B2", "B3", "B4", "A5", "A6")
+SPACING_TABLE: tuple[tuple[float, tuple[float, ...]], ...] = (
+    (15, (0.05, 0.1, 0.1, 0.05, 0.13, 0.13)),
+    (30, (0.05, 0.1, 0.1, 0.05, 0.13, 0.25)),
+    (50, (0.1, 0.6, 0.6, 0.13, 0.13, 0.4)),
+    (100, (0.1, 0.6, 1.5, 0.13, 0.13, 0.5)),
+    (150, (0.2, 0.6, 3.2, 0.4, 0.4, 0.8)),
+    (170, (0.2, 1.25, 3.2, 0.4, 0.4, 0.8)),
+    (250, (0.2, 1.25, 6.4, 0.4, 0.4, 0.8)),
+    (300, (0.2, 1.25, 12.5, 0.4, 0.4, 0.8)),
+    (500, (0.25, 2.5, 12.5, 0.8, 0.8, 1.5)),
+)
+_ABOVE_500_PER_V = (0.0025, 0.005, 0.025, 0.00305, 0.00305, 0.00305)
+
+# IEC 60664-1 Table F.4 style creepage (mm), pollution degree 2, by working voltage (rms) and material
+# group I / II / III (a+b). FR-4 is typically CTI 175 to 250 = material group IIIa.
+CREEPAGE_TABLE: tuple[tuple[float, tuple[float, float, float]], ...] = (
+    (50, (0.6, 0.9, 1.2)),
+    (100, (0.7, 1.0, 1.4)),
+    (125, (0.8, 1.1, 1.6)),
+    (160, (0.9, 1.3, 1.8)),
+    (200, (1.0, 1.4, 2.0)),
+    (250, (1.25, 1.8, 2.5)),
+    (320, (1.6, 2.2, 3.2)),
+    (400, (2.0, 2.8, 4.0)),
+    (500, (2.5, 3.6, 5.0)),
+    (630, (3.2, 4.5, 6.3)),
+    (800, (4.0, 5.6, 8.0)),
+    (1000, (5.0, 7.1, 10.0)),
+)
+# Basic-insulation clearance (mm), overvoltage category II, pollution degree 2, inhomogeneous field.
+CLEARANCE_TABLE: tuple[tuple[float, float], ...] = (
+    (50, 0.04),
+    (100, 0.1),
+    (150, 0.5),
+    (300, 1.5),
+    (600, 3.0),
+    (1000, 5.5),
+)
+
+
+def spacing_mm(voltage: float, column: str = "B2") -> float:
+    """IPC-2221B minimum spacing between conductors at ``voltage`` (peak DC or AC) for a column."""
+    index = SPACING_COLUMNS.index(column)
+    v = abs(voltage)
+    for limit, values in SPACING_TABLE:
+        if v <= limit:
+            return values[index]
+    last = SPACING_TABLE[-1][1][index]
+    return round(last + (v - 500) * _ABOVE_500_PER_V[index], 3)
+
+
+def creepage_mm(voltage_rms: float, material_group: int = 3) -> float:
+    for limit, values in CREEPAGE_TABLE:
+        if abs(voltage_rms) <= limit:
+            return values[material_group - 1]
+    limit, values = CREEPAGE_TABLE[-1]
+    return round(values[material_group - 1] * abs(voltage_rms) / limit, 2)
+
+
+def clearance_mm(voltage_rms: float) -> float:
+    for limit, value in CLEARANCE_TABLE:
+        if abs(voltage_rms) <= limit:
+            return value
+    limit, value = CLEARANCE_TABLE[-1]
+    return round(value * abs(voltage_rms) / limit, 2)
+
+
+def min_width_mm(
+    current_a: float, *, delta_t: float = 10.0, copper_oz: float = 1.0, internal: bool = False
+) -> float:
+    """IPC-2221 conductor width for ``current_a``: I = k dT^0.44 A^0.725 (A in mil2)."""
+    if current_a <= 0:
+        return 0.0
+    k = 0.024 if internal else 0.048
+    area_mil2 = (current_a / (k * delta_t**0.44)) ** (1 / 0.725)
+    width_mil = area_mil2 / (copper_oz * 1.378)
+    return width_mil * 0.0254
+
+
+def max_current_a(
+    width_mm: float, *, delta_t: float = 10.0, copper_oz: float = 1.0, internal: bool = False
+) -> float:
+    k = 0.024 if internal else 0.048
+    area_mil2 = width_mm / 0.0254 * copper_oz * 1.378
+    return k * delta_t**0.44 * area_mil2**0.725
+
+
+# ------------------------------------------------------------------ declarations
+
+_CLASS_HINT_A = re.compile(r"(?<![\w.])(\d+(?:\.\d+)?)\s*A(?![A-Za-z])")
+_CLASS_HINT_V = re.compile(r"(?<![\w.])(\d+(?:\.\d+)?)\s*V(?![A-Za-z])")
+
+
+def load_electrical(workspace: Path) -> dict[str, Any]:
+    """``.traceforge/electrical.yaml``::
+
+    delta_t: 10            # allowed temperature rise, K
+    copper_oz: {outer: 1, inner: 0.5}
+    coating: uncoated      # uncoated | coated | conformal  (selects the spacing column)
+    nets:
+      VBUS: {current_a: 10, voltage_v: 5}
+      "HV_*": {voltage_v: 230}
+    """
+    path = workspace / ".traceforge" / "electrical.yaml"
+    if not path.is_file():
+        return {}
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return data if isinstance(data, dict) else {}
+
+
+def declared(
+    board: Board, spec: dict[str, Any], netclasses: dict[str, str] | None = None
+) -> tuple[dict[str, float], dict[str, float]]:
+    """(net -> declared current in A, net -> voltage in V) for the nets on the board."""
+    nets = {n for n in board.nets.values() if n}
+    currents: dict[str, float] = {}
+    volts: dict[str, float] = {}
+    for net in nets:  # net class names such as Power_10A, HV_230V
+        cls = (netclasses or {}).get(net, "")
+        if cls:
+            a, v = _CLASS_HINT_A.search(cls), _CLASS_HINT_V.search(cls)
+            if a:
+                currents[net] = float(a.group(1))
+            if v:
+                volts[net] = float(v.group(1))
+    for pattern, item in (spec.get("nets") or {}).items():
+        if not isinstance(item, dict):
+            continue
+        for net in nets:
+            if (
+                net == pattern
+                or net.lstrip("/") == pattern.lstrip("/")
+                or fnmatch.fnmatchcase(net, pattern)
+            ):
+                if item.get("current_a") is not None:
+                    currents[net] = float(item["current_a"])
+                if item.get("voltage_v") is not None:
+                    volts[net] = float(item["voltage_v"])
+    for net in nets:  # rails implied by the name, only where nothing was declared
+        if net not in volts:
+            inferred = circuits.rail_voltage(net)
+            if inferred is not None:
+                volts[net] = inferred
+    return currents, volts
+
+
+def netclasses_of(project: Path | None) -> dict[str, str]:
+    """net -> net class name from a ``.kicad_pro`` (patterns and explicit assignments)."""
+    if project is None or not project.is_file():
+        return {}
+    import json
+
+    data = json.loads(project.read_text(encoding="utf-8"))
+    settings = data.get("net_settings") or {}
+    out: dict[str, str] = {}
+    for item in settings.get("netclass_patterns") or []:
+        out[item.get("pattern", "")] = item.get("netclass", "")
+    for net, name in (settings.get("netclass_assignments") or {}).items():
+        out[net] = name if isinstance(name, str) else (name[0] if name else "")
+    return out
+
+
+def _expand_classes(board: Board, patterns: dict[str, str]) -> dict[str, str]:
+    out = {}
+    for net in {n for n in board.nets.values() if n}:
+        for pattern, name in patterns.items():
+            if net == pattern or fnmatch.fnmatchcase(net, pattern):
+                out[net] = name
+    return out
+
+
+# ---------------------------------------------------------------------- checks
+
+
+def _is_internal(layer: str) -> bool:
+    return layer.endswith(".Cu") and layer not in {"F.Cu", "B.Cu"}
+
+
+def _seg_distance(a: Track, b: Track) -> float:
+    """Distance between two straight segments (centre lines)."""
+
+    def point_seg(px, py, x1, y1, x2, y2):
+        dx, dy = x2 - x1, y2 - y1
+        length = dx * dx + dy * dy
+        t = 0.0 if length == 0 else max(0.0, min(1.0, ((px - x1) * dx + (py - y1) * dy) / length))
+        return math.hypot(px - (x1 + t * dx), py - (y1 + t * dy))
+
+    def cross(o, p, q):
+        return (p[0] - o[0]) * (q[1] - o[1]) - (p[1] - o[1]) * (q[0] - o[0])
+
+    p1, p2, q1, q2 = (a.x1, a.y1), (a.x2, a.y2), (b.x1, b.y1), (b.x2, b.y2)
+    if cross(p1, p2, q1) * cross(p1, p2, q2) < 0 and cross(q1, q2, p1) * cross(q1, q2, p2) < 0:
+        return 0.0
+    return min(
+        point_seg(*p1, *q1, *q2),
+        point_seg(*p2, *q1, *q2),
+        point_seg(*q1, *p1, *p2),
+        point_seg(*q2, *p1, *p2),
+    )
+
+
+def check_board(
+    board: Board,
+    spec: dict[str, Any] | None = None,
+    netclasses: dict[str, str] | None = None,
+    *,
+    currents: dict[str, float] | None = None,
+    voltages: dict[str, float] | None = None,
+) -> list[Finding]:
+    spec = spec or {}
+    declared_i, declared_v = declared(board, spec, _expand_classes(board, netclasses or {}))
+    declared_i.update(currents or {})
+    declared_v.update(voltages or {})
+    delta_t = float(spec.get("delta_t", 10.0))
+    oz = spec.get("copper_oz", 1.0)
+    outer_oz = float(oz.get("outer", 1.0)) if isinstance(oz, dict) else float(oz)
+    inner_oz = float(oz.get("inner", 0.5)) if isinstance(oz, dict) else float(oz)
+    column = {"uncoated": "B2", "coated": "B4", "conformal": "A5"}.get(
+        str(spec.get("coating", "uncoated")), "B2"
+    )
+    findings: list[Finding] = []
+
+    by_net: dict[str, list[Track]] = {}
+    for track in board.tracks:
+        by_net.setdefault(track.net, []).append(track)
+    for net, current in sorted(declared_i.items()):
+        narrow: dict[str, list[Track]] = {}
+        for track in by_net.get(net, []):
+            internal = _is_internal(track.layer)
+            need = min_width_mm(
+                current,
+                delta_t=delta_t,
+                copper_oz=inner_oz if internal else outer_oz,
+                internal=internal,
+            )
+            if track.width < need * 0.98:
+                narrow.setdefault(f"{track.layer}|{need:.3f}", []).append(track)
+        for key, tracks in narrow.items():
+            layer, need = key.split("|")
+            worst = min(tracks, key=lambda t: t.width)
+            allowed = max_current_a(
+                worst.width,
+                delta_t=delta_t,
+                copper_oz=inner_oz if _is_internal(layer) else outer_oz,
+                internal=_is_internal(layer),
+            )
+            findings.append(
+                Finding(
+                    "P0" if current / allowed > 1.5 else "P1",
+                    "pcb.ipc2221",
+                    f"net {net} carries {current:g} A but {len(tracks)} track segment(s) on {layer} are only "
+                    f"{worst.width:g} mm wide; IPC-2221 needs {float(need):.2f} mm for a {delta_t:g} K rise "
+                    f"({max_current_a(worst.width, delta_t=delta_t, copper_oz=inner_oz if _is_internal(layer) else outer_oz, internal=_is_internal(layer)):.1f} A at {worst.width:g} mm)",
+                    nets=[net],
+                    evidence=f"first segment at ({worst.x1:g}, {worst.y1:g})-({worst.x2:g}, {worst.y2:g}) mm on {layer}; "
+                    f"I = k*dT^0.44*A^0.725, k=0.048 external / 0.024 internal, {outer_oz:g} oz outer",
+                    rule="IPC-2221B section 6.2 conductor sizing (guide value)",
+                    action=f"Widen the track to at least {float(need):.2f} mm, pour copper, or add parallel layers; allowed "
+                    f"current at {allowed:.1f} A for {worst.width:g} mm.",
+                )
+            )
+    findings += _clearance_findings(board, declared_v, column, spec)
+    return findings
+
+
+def _clearance_findings(
+    board: Board, volts: dict[str, float], column: str, spec: dict
+) -> list[Finding]:
+    """Track-to-track clearance on the same layer against the voltage between the two nets."""
+    live = {n for n, v in volts.items() if abs(v) > 15}
+    if not live:
+        return []
+    tracks = [t for t in board.tracks if t.mid is None and t.net]
+    cell = 5.0
+    grid: dict[tuple[str, int, int], list[int]] = {}
+    for index, t in enumerate(tracks):
+        for gx in range(int(min(t.x1, t.x2) // cell) - 1, int(max(t.x1, t.x2) // cell) + 2):
+            for gy in range(int(min(t.y1, t.y2) // cell) - 1, int(max(t.y1, t.y2) // cell) + 2):
+                grid.setdefault((t.layer, gx, gy), []).append(index)
+    seen: set[tuple[int, int]] = set()
+    worst: dict[tuple[str, str, str], tuple[float, float, Track, Track]] = {}
+    for members in grid.values():
+        for i in members:
+            for j in members:
+                if j <= i or (i, j) in seen:
+                    continue
+                seen.add((i, j))
+                a, b = tracks[i], tracks[j]
+                if a.net == b.net or not (a.net in live or b.net in live):
+                    continue
+                va, vb = volts.get(a.net), volts.get(b.net)
+                if va is not None and vb is not None:
+                    diff = abs(va - vb)
+                else:
+                    diff = max(abs(v) for v in (va, vb) if v is not None)
+                internal = _is_internal(a.layer)
+                need = spacing_mm(diff, "B1" if internal else column)
+                gap = _seg_distance(a, b) - a.width / 2 - b.width / 2
+                if gap < need - 1e-6:
+                    key = (a.layer, *sorted((a.net, b.net)))
+                    if key not in worst or gap < worst[key][0]:
+                        worst[key] = (gap, need, a, b)
+    findings = []
+    for (layer, n1, n2), (gap, need, a, b) in sorted(worst.items()):
+        diff = abs((volts.get(n1) or 0) - (volts.get(n2) or 0)) or max(
+            abs(volts.get(n1, 0)), abs(volts.get(n2, 0))
+        )
+        findings.append(
+            Finding(
+                "P0" if gap < need / 2 else "P1",
+                "pcb.ipc2221",
+                f"{n1} and {n2} are {max(gap, 0):.2f} mm apart on {layer}; IPC-2221 needs {need:g} mm at {diff:g} V",
+                nets=[n1, n2],
+                evidence=f"closest segments near ({a.x1:g}, {a.y1:g}) and ({b.x1:g}, {b.y1:g}) mm; table column {column}",
+                rule="IPC-2221B Table 6-1 (guide value); for mains-class voltages also see creepage_mm()",
+                action=f"Increase spacing to at least {need:g} mm or slot the board.",
+            )
+        )
+    return findings