"""Build portable metadata records for immutable GDS layout artifacts."""
from __future__ import annotations
import hashlib
import json
from pathlib import Path
from typing import Any
import pandas as pd
DEFAULT_LAYOUT_REPOSITORY = "SQuADDS/SQuADDS_Layouts"
MANIFEST_SCHEMA_VERSION = "1.0.0"
def _canonical_json(value: Any) -> str:
return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
def _sha256(value: bytes) -> str:
return hashlib.sha256(value).hexdigest()
[docs]
def canonical_design_id(component_name: str, design_options: dict[str, Any]) -> str:
"""Return a stable ID for a parametric component design."""
payload = {"component_name": component_name, "design_options": design_options}
return f"design:sha256:{_sha256(_canonical_json(payload).encode())}"
[docs]
def infer_layout_component_name(design: dict[str, Any]) -> str | None:
"""Infer the canonical layout family represented by a SQuADDS DB row.
Simulation datasets predate the layout registry and do not consistently
store a component class. Recognize their stable design-option schemas
before falling back to the explicit component metadata used by couplers.
"""
options = design.get("design_options")
if not isinstance(options, dict):
return None
if {"claw_opts", "cpw_opts", "cplr_opts"}.issubset(options):
return "CavityClawRouteMeander"
if {"cross_width", "cross_length", "cross_gap"}.issubset(options):
return "TransmonCross"
return (
design.get("component_class")
or design.get("component_name")
or design.get("component")
or design.get("coupler_type")
)
[docs]
def sha256_file(path: str | Path) -> str:
"""Return the SHA-256 checksum of an exact artifact file."""
digest = hashlib.sha256()
with Path(path).open("rb") as source:
for chunk in iter(lambda: source.read(1024 * 1024), b""):
digest.update(chunk)
return digest.hexdigest()
def _require_klayout():
try:
import klayout.db as kdb
except ImportError as exc:
raise ImportError(
"GDS inspection needs the gds extra: pip install 'squadds[gds]' (with uv: uv sync --extra gds)"
) from exc
return kdb
def _bbox_um(box, dbu_um: float) -> dict[str, float] | None:
if box.empty():
return None
return {
"left": box.left * dbu_um,
"bottom": box.bottom * dbu_um,
"right": box.right * dbu_um,
"top": box.top * dbu_um,
}
def _canonical_polygon(points: list[tuple[int, int]]) -> tuple[tuple[int, int], ...]:
"""Normalize polygon orientation and starting vertex for geometry hashing."""
if not points:
return ()
rotations = []
for sequence in (points, list(reversed(points))):
rotations.extend(tuple(sequence[index:] + sequence[:index]) for index in range(len(sequence)))
return min(rotations)
def _layout_id(layout, top_cell, dbu_um: float) -> str:
layers = []
for layer_index in layout.layer_indices():
info = layout.get_info(layer_index)
region = _require_klayout().Region(top_cell.begin_shapes_rec(layer_index))
polygons = []
for polygon in region.each():
points = [(point.x, point.y) for point in polygon.each_point_hull()]
polygons.append(_canonical_polygon(points))
layers.append({"layer": info.layer, "datatype": info.datatype, "polygons": sorted(polygons)})
payload = {"dbu_um": dbu_um, "layers": sorted(layers, key=lambda item: (item["layer"], item["datatype"]))}
return f"layout:sha256:{_sha256(_canonical_json(payload).encode())}"
[docs]
def parse_gds_summary(path: str | Path) -> dict[str, Any]:
"""Extract deterministic geometry metadata from a GDS file in micrometers."""
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_um = float(layout.dbu)
layers = []
for layer_index in layout.layer_indices():
info = layout.get_info(layer_index)
region = kdb.Region(top_cell.begin_shapes_rec(layer_index))
layers.append(
{
"layer": int(info.layer),
"datatype": int(info.datatype),
"polygon_count": int(region.count()),
"area_um2": float(region.area() * dbu_um**2),
"bbox_um": _bbox_um(region.bbox(), dbu_um),
}
)
return {
"layout_id": _layout_id(layout, top_cell, dbu_um),
"top_cell": top_cell.name,
"cell_count": int(layout.cells()),
"dbu_um": dbu_um,
"bbox_um": _bbox_um(top_cell.bbox(), dbu_um),
"layers": sorted(layers, key=lambda item: (item["layer"], item["datatype"])),
"polygon_count": sum(item["polygon_count"] for item in layers),
}
[docs]
def parse_gds_polygons(
path: str | Path,
*,
layer: int | None = None,
datatype: int | None = None,
) -> list[dict[str, Any]]:
"""Extract polygon vertices and metrics in micrometers from a GDS file."""
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}")
polygons = []
dbu_um = float(layout.dbu)
for layer_index in layout.layer_indices():
info = layout.get_info(layer_index)
if layer is not None and info.layer != layer:
continue
if datatype is not None and info.datatype != datatype:
continue
region = kdb.Region(top_cell.begin_shapes_rec(layer_index))
for index, polygon in enumerate(region.each()):
polygons.append(
{
"layer": int(info.layer),
"datatype": int(info.datatype),
"polygon_index": index,
"points_um": [
{"x": point.x * dbu_um, "y": point.y * dbu_um} for point in polygon.each_point_hull()
],
"area_um2": float(polygon.area() * dbu_um**2),
"bbox_um": _bbox_um(polygon.bbox(), dbu_um),
}
)
return polygons
[docs]
def build_layout_record(
path: str | Path,
*,
component_name: str,
component: str = "coupler",
gds_path: str,
source_id: str | None = None,
design_options: dict[str, Any] | None = None,
simulation_config: str | None = None,
campaign: str | None = None,
) -> dict[str, Any]:
"""Build one layout-manifest row from a GDS artifact and its provenance."""
artifact_path = Path(path)
summary = parse_gds_summary(artifact_path)
return {
"layout_id": summary.pop("layout_id"),
"artifact_id": f"sha256:{sha256_file(artifact_path)}",
"design_id": canonical_design_id(component_name, design_options) if design_options else None,
"component": component,
"component_name": component_name,
"artifact_format": "gds",
"gds_path": gds_path,
"size_bytes": artifact_path.stat().st_size,
"source_id": source_id,
"campaign": campaign,
"simulation_repo": "SQuADDS/SQuADDS_DB" if simulation_config else None,
"simulation_config": simulation_config,
"has_simulation": simulation_config is not None,
"manifest_schema_version": MANIFEST_SCHEMA_VERSION,
**summary,
}
[docs]
def write_manifest(records: list[dict[str, Any]], output_path: str | Path) -> None:
"""Write a deterministic, viewer-friendly Parquet manifest."""
if not records:
raise ValueError("Cannot write an empty layout manifest.")
output = Path(output_path)
output.parent.mkdir(parents=True, exist_ok=True)
pd.DataFrame(records).sort_values("gds_path").to_parquet(output, index=False)