"""Faithful Qiskit Metal GDS export with explicit two-terminal port markers.
Qiskit Metal stores component geometry in millimetres. SQuADDS layout GDS
files use micrometres and reserve ``(1, 0)`` for a ground plane with one etched
hole, ``(1, 10)`` for signal metal, and ``(2, 0)`` / ``(3, 0)`` for the ordered
terminals. The helpers here keep those concerns in one place so generated
datasets and their validation use exactly the same geometry contract.
"""
from __future__ import annotations
from collections.abc import Iterable
from dataclasses import dataclass
from pathlib import Path
from typing import Any
import numpy as np
MM_TO_UM = 1000.0
#: Per-side ground-plane margin in micrometres.
#:
#: Measured from 120 published ``GeneralizedCapNInterdigital`` files, whose
#: padding is essentially uncorrelated with conductor width (Pearson -0.10), so
#: that sweep uses a fixed absolute margin rather than a multiple of the device.
#: A proportional rule would place the ground plane furthest from the *largest*
#: device, which is the opposite of what an absolutely anchored coupling
#: spectrum needs. 169 um is the pooled median of the per-side paddings.
GROUND_DOMAIN_PADDING_UM = 169.0
PORT_LENGTH_UM = 2.0
_BRIDGE_HALF_WIDTH_MM = 1e-6
[docs]
@dataclass(frozen=True)
class PortMarker:
"""One ordered GDS terminal marker expressed in Qiskit Metal millimetres."""
semantic: str
layer: int
polygon: Any
source: str
datatype: int = 0
def _require_klayout():
try:
import klayout.db as kdb
except ImportError as exc: # pragma: no cover - depends on optional extra
raise ImportError(
"GDS generation needs the gds extra: pip install 'squadds[gds]' (with uv: uv sync --extra gds)"
) from exc
return kdb
[docs]
def each_polygon(geometry: Any):
"""Yield polygonal leaves from a Shapely geometry."""
if geometry is None or geometry.is_empty:
return
if geometry.geom_type == "Polygon":
yield geometry
elif hasattr(geometry, "geoms"):
for child in geometry.geoms:
yield from each_polygon(child)
[docs]
def qgeometry_role(design: Any, *, subtract: bool) -> Any:
"""Return the union of rendered poly/path qgeometry in Metal's mm units."""
from shapely import union_all
geometries = []
for table_name in ("poly", "path"):
table = design.qgeometry.tables[table_name]
for row in table.itertuples(index=False):
if bool(row.helper) or bool(row.subtract) != subtract:
continue
geometry = row.geometry
if table_name == "path":
geometry = geometry.buffer(float(row.width) / 2, cap_style="flat", join_style="round")
geometries.append(geometry)
return union_all(geometries)
[docs]
def marker_from_pin(
pin: Any,
*,
semantic: str,
layer: int,
source: str,
length_um: float = PORT_LENGTH_UM,
) -> PortMarker:
"""Extend a Metal pin cross-section outward by ``length_um``."""
from shapely.geometry import Polygon
points = np.asarray(pin["points"], dtype=float)
normal = np.asarray(pin["normal"], dtype=float)
if points.shape != (2, 2):
raise ValueError(f"Port source {source!r} does not have a two-point pin cross-section.")
magnitude = float(np.linalg.norm(normal))
if magnitude <= 0:
raise ValueError(f"Port source {source!r} has a zero normal.")
extension = normal / magnitude * (float(length_um) / MM_TO_UM)
polygon = Polygon([points[0], points[1], points[1] + extension, points[0] + extension])
if polygon.is_empty or not polygon.is_valid or polygon.area <= 0:
raise ValueError(f"Port source {source!r} produced an invalid marker.")
return PortMarker(semantic=semantic, layer=layer, polygon=polygon, source=source)
[docs]
def marker_from_junction(
junction: Any,
conductor: Any,
*,
width_mm: float,
semantic: str,
layer: int,
source: str,
length_um: float = PORT_LENGTH_UM,
) -> PortMarker:
"""Place a marker outside the conductor at the connected junction endpoint."""
from shapely.geometry import Point, Polygon
coordinates = np.asarray(junction.coords, dtype=float)
if len(coordinates) != 2:
raise ValueError(f"Junction source {source!r} must be a two-point line.")
distances = [float(conductor.distance(Point(point))) for point in coordinates]
connected_index = int(np.argmin(distances))
connected = coordinates[connected_index]
outside = coordinates[1 - connected_index]
direction = outside - connected
magnitude = float(np.linalg.norm(direction))
if magnitude <= 0:
raise ValueError(f"Junction source {source!r} has zero length.")
normal = direction / magnitude
tangent = np.array([-normal[1], normal[0]])
half_width = float(width_mm) / 2
extension = normal * (float(length_um) / MM_TO_UM)
polygon = Polygon(
[
connected - tangent * half_width,
connected + tangent * half_width,
connected + tangent * half_width + extension,
connected - tangent * half_width + extension,
]
)
if polygon.is_empty or not polygon.is_valid or polygon.area <= 0:
raise ValueError(f"Junction source {source!r} produced an invalid marker.")
return PortMarker(semantic=semantic, layer=layer, polygon=polygon, source=source)
def _parsed_length_um(component: Any, value: Any) -> float:
"""Parse one Qiskit Metal length option and return micrometres."""
length_um = float(component.design.parse_value(value)) * MM_TO_UM
if length_um <= 0:
raise ValueError(f"Expected a positive component clearance; got {value!r}.")
return length_um
[docs]
def transmon_cross_port_markers(component: Any, design: Any) -> list[PortMarker]:
"""Return native-clearance cross and claw bridges to ground."""
junctions = design.qgeometry.tables["junction"]
rows = junctions[(junctions.component == component.id) & (junctions.name == "rect_jj")]
if len(rows) != 1:
raise ValueError(f"Expected one rect_jj junction for {component.name!r}; found {len(rows)}.")
row = rows.iloc[0]
cross_clearance_um = _parsed_length_um(component, component.options.cross_gap)
claw_clearance_um = _parsed_length_um(
component,
component.options.connection_pads["readout"]["claw_gap"],
)
cross = marker_from_junction(
row.geometry,
qgeometry_role(design, subtract=False),
width_mm=float(row.width),
semantic="cross_junction_port",
layer=2,
source="junction:rect_jj",
length_um=cross_clearance_um,
)
readout = marker_from_pin(
component.pins["readout"],
semantic="readout_claw_port",
layer=3,
source="pin:readout",
length_um=claw_clearance_um,
)
return [cross, readout]
[docs]
def capn_interdigital_tee_port_markers(component: Any) -> list[PortMarker]:
"""Return one marker for each electrical conductor in the legacy CapN tee.
``prime_start`` and ``prime_end`` are two routing ends of the same prime/top
conductor. Only ``prime_start`` is marked so the file remains a two-terminal
capacitance layout; ``second_end`` marks the other (second/bottom) conductor.
"""
return [
marker_from_pin(
component.pins["prime_start"],
semantic="prime_top_port",
layer=2,
source="pin:prime_start",
length_um=_parsed_length_um(component, component.options.prime_gap),
),
marker_from_pin(
component.pins["second_end"],
semantic="second_bottom_port",
layer=3,
source="pin:second_end",
length_um=_parsed_length_um(component, component.options.second_gap),
),
]
[docs]
def minimum_ground_clearance_um(component: Any) -> float:
"""Return the smallest native signal-to-ground clearance for a component."""
if component.__class__.__name__ == "TransmonCross":
return min(
_parsed_length_um(component, component.options.cross_gap),
_parsed_length_um(component, component.options.connection_pads["readout"]["claw_gap"]),
)
if component.__class__.__name__ == "CapNInterdigitalTee":
clearance = component.options.get("cap_gap_ground")
if not isinstance(clearance, (str, int, float)):
clearance = min(
component.design.parse_value(component.options.prime_gap),
component.design.parse_value(component.options.second_gap),
)
return _parsed_length_um(component, clearance)
raise ValueError(f"No standardized ground clearance for {component.__class__.__name__!r}.")
def _insert_polygon(cell: Any, layer_index: int, polygon: Any, kdb: Any) -> None:
shell = [kdb.DPoint(float(x) * MM_TO_UM, float(y) * MM_TO_UM) for x, y in polygon.exterior.coords[:-1]]
if len(shell) < 3:
return
target = kdb.DPolygon(shell)
for interior in polygon.interiors:
hole = [kdb.DPoint(float(x) * MM_TO_UM, float(y) * MM_TO_UM) for x, y in interior.coords[:-1]]
if len(hole) >= 3:
target.insert_hole(hole)
cell.shapes(layer_index).insert(target)
[docs]
def insert_port_markers(layout: Any, cell: Any, markers: Iterable[PortMarker]) -> None:
"""Insert markers into an existing KLayout layout/cell."""
kdb = _require_klayout()
for marker in markers:
layer_index = layout.layer(int(marker.layer), int(marker.datatype))
for polygon in each_polygon(marker.polygon):
_insert_polygon(cell, layer_index, polygon, kdb)
def _single_connected_hole(geometry: Any) -> Any:
"""Join disjoint QMetal etch polygons with grid-scale, minimum-length bridges."""
from shapely import union_all
from shapely.geometry import LineString
from shapely.ops import nearest_points
hole = geometry.buffer(0)
while hole.geom_type == "MultiPolygon":
parts = list(hole.geoms)
best: tuple[float, int, int] | None = None
for first in range(len(parts)):
for second in range(first + 1, len(parts)):
candidate = (float(parts[first].distance(parts[second])), first, second)
if best is None or candidate < best:
best = candidate
if best is None: # pragma: no cover - an empty MultiPolygon is not produced here
break
_, first, second = best
start, end = nearest_points(parts[first], parts[second])
bridge = LineString([start, end]).buffer(
_BRIDGE_HALF_WIDTH_MM,
cap_style="square",
join_style="mitre",
)
hole = union_all([hole, bridge]).buffer(0)
if hole.geom_type != "Polygon" or hole.is_empty or not hole.is_valid:
raise ValueError("The standardized subtractive geometry did not form one valid hole.")
return hole
[docs]
def standardized_ground_geometry(
design: Any,
markers: Iterable[PortMarker],
*,
minimum_clearance_um: float,
domain_padding_um: float = GROUND_DOMAIN_PADDING_UM,
) -> tuple[Any, Any]:
"""Return a centered dynamic ground and its single QMetal-derived hole.
The native subtractive qgeometry remains authoritative. A minimum buffer
closes the flat CPW ends emitted by Qiskit Metal, terminal bridge polygons
make the two lumped ports reach the ground boundary, and only disjoint etch
islands receive negligible-width bridges so the ground has one hole.
"""
from shapely import union_all
from shapely.geometry import box
conductor = qgeometry_role(design, subtract=False)
clearance_mm = float(minimum_clearance_um) / MM_TO_UM
if conductor.is_empty or clearance_mm <= 0:
raise ValueError("Standardized ground generation requires conductor geometry and positive clearance.")
native_etch = qgeometry_role(design, subtract=True)
marker_shapes = [marker.polygon for marker in markers]
hole = _single_connected_hole(
union_all(
[
native_etch,
conductor.buffer(clearance_mm, join_style="mitre"),
*marker_shapes,
]
)
)
left, bottom, right, top = conductor.bounds
center_x = 0.5 * (left + right)
center_y = 0.5 * (bottom + top)
padding_mm = float(domain_padding_um) / MM_TO_UM
if padding_mm <= 0 or max(right - left, top - bottom) <= 0:
raise ValueError("Cannot size a ground plane around zero-span conductor geometry.")
# A fixed per-side margin, matching the reference sweep. The plane is square
# so the margin never depends on device orientation, and it must still clear
# the etch hole for devices whose subtractive geometry extends past the
# conductor bounds.
hole_left, hole_bottom, hole_right, hole_top = hole.bounds
half_side = padding_mm + 0.5 * max(right - left, top - bottom)
half_side = max(
half_side,
abs(hole_left - center_x),
abs(hole_right - center_x),
abs(hole_bottom - center_y),
abs(hole_top - center_y),
)
domain = box(center_x - half_side, center_y - half_side, center_x + half_side, center_y + half_side)
if not domain.contains(hole):
raise ValueError("The dynamic ground domain does not contain the complete etch hole.")
return domain.difference(hole), hole
def _write_without_timestamps(layout: Any, path: Path, kdb: Any) -> None:
"""Write deterministic GDS bytes by omitting volatile creation timestamps."""
options = kdb.SaveLayoutOptions()
options.gds2_write_timestamps = False
layout.write(str(path), options)
[docs]
def export_qgeometry_gds(
design: Any,
destination: Path,
*,
markers: Iterable[PortMarker] = (),
include_ground_domain: bool = False,
minimum_ground_clearance_um: float | None = None,
) -> None:
"""Write Metal qgeometry and optional ordered terminal markers atomically.
When requested, the ground follows the GeneralizedCapNInterdigital
convention: a dynamic square domain on ``(1, 0)`` with one subtractive hole
and no filled ``(1, 11)`` etch layer.
"""
kdb = _require_klayout()
markers = list(markers)
if include_ground_domain and minimum_ground_clearance_um is None:
raise ValueError("Ground-domain export requires minimum_ground_clearance_um.")
layout = kdb.Layout()
layout.dbu = 0.001
top = layout.create_cell("TOP")
for table_name in ("poly", "path"):
table = design.qgeometry.tables[table_name]
for row in table.itertuples(index=False):
if row.helper:
continue
if include_ground_domain and row.subtract:
continue
geometry = row.geometry
if table_name == "path":
geometry = geometry.buffer(float(row.width) / 2, cap_style="flat", join_style="round")
layer_index = layout.layer(int(row.layer), 11 if row.subtract else 10)
for polygon in each_polygon(geometry):
_insert_polygon(top, layer_index, polygon, kdb)
if include_ground_domain:
domain_layer = layout.layer(1, 0)
domain, _ = standardized_ground_geometry(
design,
markers,
minimum_clearance_um=float(minimum_ground_clearance_um),
)
for polygon in each_polygon(domain):
_insert_polygon(top, domain_layer, polygon, kdb)
insert_port_markers(layout, top, markers)
temporary = destination.with_suffix(".tmp.gds")
_write_without_timestamps(layout, temporary, kdb)
temporary.replace(destination)
[docs]
def add_port_markers_to_gds(source: Path, destination: Path, markers: Iterable[PortMarker]) -> None:
"""Copy a rendered GDS while adding markers, using an atomic destination."""
kdb = _require_klayout()
layout = kdb.Layout()
layout.read(str(source))
top = layout.top_cell()
if top is None:
raise ValueError(f"GDS file has no top cell: {source}")
insert_port_markers(layout, top, markers)
temporary = destination.with_suffix(".tmp.gds")
_write_without_timestamps(layout, temporary, kdb)
temporary.replace(destination)
[docs]
def read_layer_geometry(path: str | Path) -> dict[tuple[int, int], Any]:
"""Return one Shapely geometry per ``(layer, datatype)`` pair, holes included."""
import shapely
kdb = _require_klayout()
layout = kdb.Layout()
layout.read(str(path))
top_cell = layout.top_cell()
if top_cell is None:
raise ValueError(f"GDS file has no top cell: {path}")
dbu = float(layout.dbu)
geometry: dict[tuple[int, int], Any] = {}
for layer_index in layout.layer_indices():
info = layout.get_info(layer_index)
region = kdb.Region(top_cell.begin_shapes_rec(layer_index))
region.merge()
polygons = []
for polygon in region.each():
shell = [(point.x * dbu, point.y * dbu) for point in polygon.each_point_hull()]
if len(shell) < 3:
continue
holes = []
for hole_index in range(polygon.holes()):
ring = [(point.x * dbu, point.y * dbu) for point in polygon.each_point_hole(hole_index)]
if len(ring) >= 3:
holes.append(ring)
polygons.append(shapely.Polygon(shell, holes))
if polygons:
geometry[(int(info.layer), int(info.datatype))] = shapely.union_all(polygons)
return geometry
[docs]
def validate_ported_gds(
design: Any,
path: Path,
markers: Iterable[PortMarker],
*,
minimum_ground_clearance_um: float,
) -> dict[str, Any]:
"""Validate the unified layer, ground-hole, and two-terminal contract."""
from shapely.affinity import scale
from shapely.geometry import Polygon
markers = list(markers)
geometry = read_layer_geometry(path)
checks: dict[str, bool] = {}
role_metrics: dict[str, dict[str, float]] = {}
for name, key, subtract in (("conductor", (1, 10), False),):
expected_mm = qgeometry_role(design, subtract=subtract)
expected = scale(expected_mm, xfact=MM_TO_UM, yfact=MM_TO_UM, origin=(0, 0))
actual = geometry.get(key)
if actual is None:
role_metrics[name] = {
"expected_area_um2": float(expected.area),
"actual_area_um2": 0.0,
"xor_area_um2": float(expected.area),
}
checks[f"{name}_roundtrip"] = False
continue
xor_area = float(expected.symmetric_difference(actual).area)
tolerance = max(0.01, float(expected.area) * 1e-5)
role_metrics[name] = {
"expected_area_um2": float(expected.area),
"actual_area_um2": float(actual.area),
"xor_area_um2": xor_area,
"tolerance_um2": tolerance,
}
checks[f"{name}_roundtrip"] = xor_area <= tolerance
expected_ground_mm, _ = standardized_ground_geometry(
design,
markers,
minimum_clearance_um=minimum_ground_clearance_um,
)
expected_ground = scale(expected_ground_mm, xfact=MM_TO_UM, yfact=MM_TO_UM, origin=(0, 0))
ground = geometry.get((1, 0))
ground_xor = (
float(expected_ground.symmetric_difference(ground).area) if ground is not None else float(expected_ground.area)
)
ground_tolerance = max(0.1, float(expected_ground.area) * 1e-7)
role_metrics["ground"] = {
"expected_area_um2": float(expected_ground.area),
"actual_area_um2": float(ground.area) if ground is not None else 0.0,
"xor_area_um2": ground_xor,
"tolerance_um2": ground_tolerance,
}
checks["ground_roundtrip"] = ground_xor <= ground_tolerance
checks["exact_layer_set"] = set(geometry) == {(1, 0), (1, 10), (2, 0), (3, 0)}
checks["etch_layer_absent"] = (1, 11) not in geometry
conductor = geometry.get((1, 10))
ground_polygons = list(getattr(ground, "geoms", [ground])) if ground is not None else []
ground_holes = [interior for polygon in ground_polygons for interior in getattr(polygon, "interiors", [])]
checks["one_ground_polygon"] = len(ground_polygons) == 1
checks["one_ground_hole"] = len(ground_holes) == 1
actual_hole = Polygon(ground_holes[0]) if len(ground_holes) == 1 else None
checks["hole_contains_conductor"] = (
conductor is not None and actual_hole is not None and bool(actual_hole.covers(conductor))
)
if ground is not None and conductor is not None:
ground_width = float(ground.bounds[2] - ground.bounds[0])
ground_height = float(ground.bounds[3] - ground.bounds[1])
conductor_width = float(conductor.bounds[2] - conductor.bounds[0])
conductor_height = float(conductor.bounds[3] - conductor.bounds[1])
ground_aspect = ground_width / ground_height
# A fixed per-side margin, so validate the margin rather than a ratio.
ground_padding_um = 0.5 * (max(ground_width, ground_height) - max(conductor_width, conductor_height))
ground_center_offset = [
0.5 * (ground.bounds[0] + ground.bounds[2] - conductor.bounds[0] - conductor.bounds[2]),
0.5 * (ground.bounds[1] + ground.bounds[3] - conductor.bounds[1] - conductor.bounds[3]),
]
else:
ground_aspect = ground_padding_um = float("nan")
ground_center_offset = [float("nan"), float("nan")]
checks["ground_aspect"] = 0.9 <= ground_aspect <= 2.0
# The published GeneralizedCapNInterdigital sweep spans 55 to 273 um per side;
# accept that band rather than a single value so the etch-clearance floor
# can enlarge the plane for devices with wide subtractive geometry.
checks["ground_padding"] = 50.0 <= ground_padding_um <= 400.0
checks["ground_centered"] = max(abs(value) for value in ground_center_offset) <= 0.001
checks["two_markers"] = len(markers) == 2 and all((marker.layer, marker.datatype) in geometry for marker in markers)
expected_layers = [(2, 0), (3, 0)]
checks["ordered_layers"] = [(marker.layer, marker.datatype) for marker in markers] == expected_layers
assignments: list[int] = []
conductor_distances: list[float] = []
ground_distances: list[float] = []
component_count = 0
if conductor is not None:
parts = [part for part in getattr(conductor, "geoms", [conductor]) if part.area > 0]
component_count = len(parts)
for marker in markers:
port = geometry.get((marker.layer, marker.datatype))
if port is None or not parts:
continue
part_distances = [float(part.distance(port)) for part in parts]
assignments.append(int(np.argmin(part_distances)))
conductor_distances.append(float(min(part_distances)))
ground_distances.append(float(ground.distance(port)) if ground is not None else float("inf"))
checks["two_signal_terminals"] = component_count == 2
checks["unique_terminal_assignment"] = len(assignments) == 2 and len(set(assignments)) == 2
checks["markers_touch_signal"] = len(conductor_distances) == 2 and max(conductor_distances) <= 0.001
checks["markers_touch_ground"] = len(ground_distances) == 2 and max(ground_distances) <= 0.001
port_metrics = []
for marker in markers:
expected = scale(marker.polygon, xfact=MM_TO_UM, yfact=MM_TO_UM, origin=(0, 0))
actual = geometry.get((marker.layer, marker.datatype))
xor = float(expected.symmetric_difference(actual).area) if actual is not None else float(expected.area)
port_metrics.append(
{
"semantic": marker.semantic,
"source": marker.source,
"layer": marker.layer,
"datatype": marker.datatype,
"area_um2": float(expected.area),
"xor_area_um2": xor,
}
)
checks["marker_roundtrip"] = all(item["xor_area_um2"] <= 0.01 for item in port_metrics)
return {
"path": str(path),
"valid": all(checks.values()),
"checks": checks,
"qgeometry": role_metrics,
"ports": port_metrics,
"signal_component_count": component_count,
"port_component_assignments": assignments,
"port_conductor_distances_um": conductor_distances,
"port_ground_distances_um": ground_distances,
"ground_aspect": ground_aspect,
"ground_padding_um": ground_padding_um,
"ground_center_offset_um": ground_center_offset,
"ground_hole_count": len(ground_holes),
}