Source code for jitxexamples.patterns.layout_qfn_escape

"""Step a power trace down to fit a QFN pad, with the width read from the pad.

Use this pattern when a power trace is wider than the pads it reaches.
A 0.8 mm trace centred on a 0.17 mm QFN pad at 0.5 mm pitch reaches
0.4 mm to each side, and the next pads start 0.415 mm from that centre: a
0.015 mm gap, under the 0.127 mm fab floor of the sample substrate. So the
last stretch into the pad is a separate escape segment at a narrower width.

Three pieces compose, on the priority ladder of the layout-constraints
skill (net-tag rules at 2, escape segments at 4):

1. A rule on the net's tag:
   ``design_constraint(PowerTag(), priority=2).trace_width(0.8)``.
2. A transition. The net is routed as two code routes that meet at a
   ``RoutePoint`` 1.0 mm outside the pad: the trunk from the source to the
   transition and the escape from the transition into the pad.
3. A rule on a tag assigned to the escape ``Route`` object, at a higher
   priority: ``design_constraint(QfnEscapeTag(), priority=4)
   .trace_width(escape_width)``. Both rules match the escape segment and the
   higher priority wins there; the trunk keeps the ``PowerTag`` width.

The escape width is derived, not typed. :py:func:`derive_escape` reads the
placed QFN's pad geometry and the substrate's fab constraints, and takes the
escape clearance s_e the caller chose: the clearance that governs the net,
or a lower one at or above ``min_copper_copper_space``. It finds:

- the pad width across the escape direction, and the pad gap: the smallest
  distance from the pad's copper to any other pad's copper. It raises if
  that gap is below ``min_copper_copper_space``;
- c, the smallest distance from the escape's centreline (pad centre to
  transition) to any other pad. The escape leaves along the pad's long
  axis, so c is half the pad width plus the gap to the adjacent pad;
- the escape width, from :py:func:`escape_width`: below the pad width by
  ``ESCAPE_PAD_INSET`` (0.02 mm), at most 2·(c - s_e), rounded down to
  ``WIDTH_GRID`` (0.01 mm), and at or above ``min_copper_width``. Wherever
  the pad gap is at or above s_e, the pad bound decides: a trace narrower
  than the pad and running straight out of it is never closer to a
  neighbouring pad than the pads are to each other.

For this placeholder QFN on :py:class:`jitx.sample.SampleSubstrate`, the
generator's pads come out 0.17 mm wide (0.25 mm leads, density level C), the
gap between pads is 0.33 mm, c is 0.415 mm, and with s_e at the 0.127 mm fab
floor (the design writes no clearance rule) the pad bound gives a 0.15 mm
escape.

Measured on jitx 4.6, building :py:class:`layout_qfn_escape_design`: the
escape realized 0.15 mm wide and the trunk 0.8 mm, the escape's copper came
no closer than 0.34 mm to any of the other 15 QFN pads (0.33 mm between the
pads, plus half the 0.02 mm the escape is narrower than its pad), and the
design's issues listed routing as satisfied.

A ``Route.Config(trace_width=...)`` on the escape would also set its width.
Measured on jitx 4.6, a ``Route.Config`` won over a width rule and a
clearance rule, both at the default priority. That puts a number on one
route, out of reach of those rules; prefer the tag.

The test, ``tests/test_layout_qfn_escape.py``, checks the derivation and the
rules offline. With ``JITX_PATTERN_RUNTIME=1`` and a runtime started at the
project root, it builds the design and measures each segment's width and the
escape's distance to the neighbouring pads.
"""

from __future__ import annotations

from dataclasses import dataclass
from decimal import ROUND_FLOOR, Decimal

import jitx
from jitx import RoutePoint
from jitx.circuit import Circuit, Route
from jitx.component import Component
from jitx.constraints import Tag, design_constraint
from jitx.feature import Soldermask
from jitx.inspect import visit
from jitx.landpattern import Landpattern, Pad, PadMapping, PadShape
from jitx.net import Net, Port
from jitx.sample import SampleDesign
from jitx.shapes.composites import rectangle
from jitx.substrate import FabricationConstraints
from jitx.toleranced import Toleranced
from jitxlib.landpatterns.generators.qfn import QFN, QFNLead
from jitxlib.landpatterns.ipc import DensityLevel
from jitxlib.landpatterns.leads import LeadProfile
from jitxlib.landpatterns.package import RectanglePackage
from jitxlib.symbols.box import BoxSymbol
from shapely.geometry import LineString
from shapely.geometry.base import BaseGeometry

POWER_WIDTH = 0.8
"""The power nets' trace width (the ``PowerTag`` width), in mm."""

ESCAPE_PAD_INSET = Decimal("0.02")
"""How much narrower than the pad the escape is, before rounding, in mm."""

WIDTH_GRID = Decimal("0.01")
"""The grid the escape width is rounded down to, in mm."""

ESCAPE_RUN = 1.0
"""From the pad's outer edge to the transition, in mm."""

QFN_LEADS = 16


[docs] class PowerTag(Tag): """Power nets: routed at ``POWER_WIDTH``."""
[docs] class QfnEscapeTag(Tag): """Escape segments into a QFN pad."""
[docs] class PlaceholderQfn16(Component): """A placeholder 16-lead, 0.5 mm pitch QFN. Not an orderable part. Pad 1 is ``VDD``; the rest are unused. """ manufacturer = "Fictional" mpn = "EXAMPLE-QFN16" reference_designator_prefix = "U" VDD = Port() NC = [Port() for _ in range(QFN_LEADS - 1)] landpattern = ( QFN(num_leads=QFN_LEADS) .lead_profile( LeadProfile( span=Toleranced.exact(3.0), pitch=0.5, type=QFNLead( length=Toleranced.exact(0.4), width=Toleranced.exact(0.25) ), ) ) .package_body( RectanglePackage( width=Toleranced.exact(3.0), length=Toleranced.exact(3.0), height=Toleranced.exact(0.9), ) ) .density_level(DensityLevel.C) ) symbol = BoxSymbol() def __init__(self) -> None: pads = self.landpattern.p entries: list[tuple[Port, Pad]] = [(self.VDD, pads[1])] entries += [(port, pads[i]) for i, port in enumerate(self.NC, start=2)] self.mappings = [PadMapping(entries)] for port in self.NC: port.no_connect()
[docs] class SourcePad(Pad): shape = rectangle(1.0, 1.0) soldermask = Soldermask(rectangle(1.1, 1.1))
[docs] class SourceLandpattern(Landpattern): pad = SourcePad().at(0, 0)
[docs] class PowerSource(Component): """A fictional one-pin power source. Not a real product.""" manufacturer = "Fictional" mpn = "EXAMPLE-PWR-PAD" reference_designator_prefix = "J" out = Port() landpattern = SourceLandpattern() symbol = BoxSymbol() def __init__(self) -> None: self.mappings = [PadMapping({self.out: self.landpattern.pad})]
[docs] def pad_geometry(pad: Pad) -> BaseGeometry: """The pad's copper in its landpattern's frame.""" shape = pad.shape if isinstance(shape, PadShape): shape = shape.shape assert pad.transform is not None return (pad.transform * shape).to_shapely().g
[docs] @dataclass(frozen=True) class Escape: """The derived escape for one QFN pad, in the landpattern's frame.""" pad_width: float pad_gap: float centreline_clearance: float """c: the smallest distance from the escape's centreline to another pad.""" escape_clearance: float """s_e: the clearance the escape keeps to the other pads.""" width: float pad_center: tuple[float, float] outward: tuple[float, float] transition: tuple[float, float]
[docs] def strictly_inside_width(pad_width: float, floor: float) -> float: """``pad_width`` less the inset, rounded down to the grid; checked against the pad and the fab floor.""" steps = (Decimal(str(pad_width)) - ESCAPE_PAD_INSET) / WIDTH_GRID width = float(steps.to_integral_value(rounding=ROUND_FLOOR) * WIDTH_GRID) if not width < pad_width: raise ValueError(f"escape {width} is not narrower than the {pad_width} pad") if width < floor: raise ValueError(f"escape {width} is below the fab floor {floor}") return width
[docs] def escape_width( pad_width: float, centreline_clearance: float, escape_clearance: float, fab: FabricationConstraints, *, grid: Decimal = WIDTH_GRID, ) -> float: """The width of an escape segment that leaves a pad past other pads. ``pad_width`` is the narrowest pad the escape rule selects, measured across the escape; ``centreline_clearance`` is c, the smallest distance from the escape's centreline (pad centre to transition) to any other pad; ``escape_clearance`` is s_e, the clearance the escape keeps, either the clearance that governs the net or a lower one at or above the fab's ``min_copper_copper_space``. The width is: - strictly below ``pad_width``, by ``ESCAPE_PAD_INSET`` before rounding; - at most ``2 * (c - s_e)``, so the escape's edge keeps s_e from every other pad; - rounded down to ``grid``, and at or above ``min_copper_width``. Raises ``ValueError`` when ``escape_clearance`` is below ``min_copper_copper_space`` or the width that results is below ``min_copper_width``. On a BGA at 1.0 pitch with 0.5 balls, the channel between the balls is 0.5 and c 0.25, so the escape is 0.3 at s_e 0.1 and 0.26 at s_e 0.12. """ if escape_clearance < fab.min_copper_copper_space: raise ValueError( f"escape clearance {escape_clearance} is below min_copper_copper_space " f"{fab.min_copper_copper_space}" ) def exact(value: float) -> Decimal: return Decimal(str(round(value, 6))) by_pad = exact(pad_width) - ESCAPE_PAD_INSET by_neighbours = 2 * (exact(centreline_clearance) - exact(escape_clearance)) steps = min(by_pad, by_neighbours) / grid width = float(steps.to_integral_value(rounding=ROUND_FLOOR) * grid) if not width < pad_width: raise ValueError(f"escape {width} is not narrower than the {pad_width} pad") if width < fab.min_copper_width: raise ValueError( f"escape {width} is below min_copper_width {fab.min_copper_width}: the " f"pad is {pad_width} wide and the nearest other pad {centreline_clearance} " f"from the escape's centreline" ) return width
[docs] def derive_escape( landpattern: Landpattern, target: Pad, fab: FabricationConstraints, *, escape_clearance: float, ) -> Escape: """Read the pads of ``landpattern`` and derive the escape for ``target``. The escape leaves along the pad's long axis, away from the body centre, to a transition ``ESCAPE_RUN`` past the pad's outer edge. Its width is :py:func:`escape_width` of the pad width across that axis, c (the smallest distance from the centreline to another pad) and ``escape_clearance``. Raises ``ValueError`` if two pads sit closer than ``min_copper_copper_space``, or as :py:func:`escape_width` does. """ pads = [p for _, p in visit(landpattern, Pad)] shapes = {id(p): pad_geometry(p) for p in pads} copper = shapes[id(target)] cx, cy = copper.centroid.x, copper.centroid.y minx, miny, maxx, maxy = copper.bounds along_x = (maxx - minx) > (maxy - miny) if along_x: outward = (-1.0 if cx < 0 else 1.0, 0.0) pad_width, depth = maxy - miny, maxx - minx else: outward = (0.0, -1.0 if cy < 0 else 1.0) pad_width, depth = maxx - minx, maxy - miny others = [g for k, g in shapes.items() if k != id(target)] gap = min(copper.distance(g) for g in others) if gap < fab.min_copper_copper_space: raise ValueError(f"pads {gap} apart, under the fab floor") run = depth / 2 + ESCAPE_RUN transition = (cx + outward[0] * run, cy + outward[1] * run) centreline = LineString([(cx, cy), transition]) c = min(centreline.distance(g) for g in others) return Escape( pad_width=round(pad_width, 6), pad_gap=round(gap, 6), centreline_clearance=round(c, 6), escape_clearance=escape_clearance, width=escape_width(round(pad_width, 6), c, escape_clearance, fab), pad_center=(cx, cy), outward=outward, transition=transition, )
[docs] class QfnPowerEscape(Circuit): """A power source feeding the QFN's VDD pad: a trunk at the ``PowerTag`` width and a derived escape.""" def __init__(self) -> None: self.u1 = PlaceholderQfn16().at(0, 0) target = self.u1.landpattern.p[1] fab = jitx.current.substrate.constraints # The design writes no clearance rule, so the escape keeps the fab # floor, the lowest escape clearance the derivation accepts. self.escape_geometry = derive_escape( self.u1.landpattern, target, fab, escape_clearance=fab.min_copper_copper_space, ) tx, ty = self.escape_geometry.transition self.source = PowerSource().at(tx - 4.0, ty) self.transition = RoutePoint(layer=0).at(tx, ty) self.vdd = Net([self.source.out, self.u1.VDD], name="VDD") self.vdd += self.transition.port PowerTag().assign(self.vdd) self.trunk = Route(self.source.out, self.transition.pad, layer=0) self.escape = Route(self.transition.pad, self.u1.VDD, layer=0) QfnEscapeTag().assign(self.escape) # Priority ladder: 2 net-tag rules, 4 escape segments. self.power_rule = design_constraint(PowerTag(), priority=2).trace_width( POWER_WIDTH ) self.escape_rule = design_constraint(QfnEscapeTag(), priority=4).trace_width( self.escape_geometry.width )
[docs] class layout_qfn_escape_design(SampleDesign): """The QFN power escape on the sample board.""" circuit = QfnPowerEscape()