"""Label and layout QC for planar capacitance data: one set of rules for contributions, dataset builds and training shards.
Every check reports instead of raising; ``QCReport.ok`` is False when any check failed (an error). The rules are those of the
dataset (``PLAN_DATASET_HF.md`` §4.2):
- reject: matrix not square over ``net_order``, missing / duplicate / misplaced net names, non-finite entries, asymmetry
(rel > 1e-3; Q3D exports are exactly symmetric, other solvers such as Palace are not; > 1e-6 warns, the matrix is then
symmetrized), diagonal <= 0, off-diagonal >= 0 (a zero only when flagged), signal block not positive definite, a conductor
count from the GDS that differs from the matrix size (nets are never merged), unreadable GDS, a duplicate of a held-out
test design (it would leak the test label);
- warn: signal-row closure ``|sum_j C_ij| / C_ii`` > 5 %, not converged, non-monotone pass history, unusual stack, duplicates
of non-test designs, label entries far from ``optimized_physics_prior`` (physics sanity; never a rejection).
Only numpy is imported at module level; gdstk / shapely are imported by the GDS checks, the physics prior by
``prior_sanity`` (needs ``pip install 'squadds[ml]'``).
"""
from __future__ import annotations
import csv
import hashlib
import math
import re
from dataclasses import dataclass, field
from pathlib import Path
import numpy as np
GROUND = "G"
TO_FF = {"F": 1e15, "nF": 1e6, "pF": 1e3, "fF": 1.0, "aF": 1e-3}
SYM_RTOL = 1e-3
SYM_WARN = 1e-6
CLOSURE_WARN = 0.05
PRIOR_FLOOR_FF = 0.1
PRIOR_RATIO_BAND = (0.5, 2.0)
TRAINING_STACK = {"eps_r": 11.45, "substrate_um": 350.0}
STACK_RANGES = {"eps_r": (1.0, 30.0), "substrate_um": (5.0, 2000.0), "freq_GHz": (0.1, 50.0)}
GDS_UNITS_M = (1e-6, 1e-9)
DEFAULT_LAYERS = {"ground": [(1, 0)], "conductor": [(1, 10)]}
_HEADER = re.compile(r"\s*C\(([^,]+),([^)]+)\)(\*1e15)?\s*\[(\w+)\]")
[docs]
@dataclass
class QCReport:
"""Result of a QC run: ``ok`` (no error), ``errors``, ``warnings``, ``fixes`` (applied automatically) and the measured
values in ``info``. ``to_markdown()`` renders it for a validation report."""
subject: str = ""
errors: list[str] = field(default_factory=list)
warnings: list[str] = field(default_factory=list)
fixes: list[str] = field(default_factory=list)
info: dict = field(default_factory=dict)
children: list = field(default_factory=list)
@property
def ok(self) -> bool:
return not self.errors and all(c.ok for c in self.children)
[docs]
def error(self, msg: str) -> None:
self.errors.append(msg)
[docs]
def warn(self, msg: str) -> None:
self.warnings.append(msg)
[docs]
def extend(self, other: QCReport, prefix: str = "") -> QCReport:
"""Fold another report's errors / warnings / fixes / info into this one (messages prefixed)."""
p = f"{prefix}: " if prefix else ""
self.errors += [p + m for m in other.errors]
self.warnings += [p + m for m in other.warnings]
self.fixes += [p + m for m in other.fixes]
self.info.update(other.info)
return self
[docs]
def all_errors(self) -> list[str]:
return self.errors + [f"{c.subject}: {m}" for c in self.children for m in c.all_errors()]
[docs]
def all_warnings(self) -> list[str]:
return self.warnings + [f"{c.subject}: {m}" for c in self.children for m in c.all_warnings()]
[docs]
def to_dict(self) -> dict:
return {
"subject": self.subject,
"ok": self.ok,
"errors": self.errors,
"warnings": self.warnings,
"fixes": self.fixes,
"info": _jsonable(self.info),
"children": [c.to_dict() for c in self.children],
}
[docs]
def to_markdown(self, title: str | None = None) -> str:
n_err, n_warn = len(self.all_errors()), len(self.all_warnings())
out = [f"# {title or 'QC report: ' + (self.subject or '')}".rstrip(), ""]
out.append(f"**Result: {'PASS' if self.ok else 'FAIL'}** ({n_err} errors, {n_warn} warnings)")
out.append("")
out += _md_block(self, level=2)
for c in self.children:
out.append(f"## {c.subject}: {'pass' if c.ok else 'FAIL'}")
out.append("")
out += _md_block(c, level=3)
return "\n".join(out).rstrip() + "\n"
def __repr__(self) -> str:
return (
f"QCReport({self.subject!r}, ok={self.ok}, errors={len(self.all_errors())}, "
f"warnings={len(self.all_warnings())})"
)
def _md_block(r: QCReport, level: int) -> list[str]:
out = []
for name, items in (("Errors", r.errors), ("Warnings", r.warnings), ("Fixed automatically", r.fixes)):
if items:
out.append(f"{'#' * level} {name}")
out += [f"- {m}" for m in items]
out.append("")
if r.info:
out.append(f"{'#' * level} Measured")
out += [f"- `{k}`: {_fmt(v)}" for k, v in r.info.items()]
out.append("")
return out
def _fmt(v) -> str:
if isinstance(v, float):
return f"{v:.6g}"
return str(_jsonable(v))
def _jsonable(o):
if isinstance(o, dict):
return {str(k): _jsonable(v) for k, v in o.items()}
if isinstance(o, (list, tuple)):
return [_jsonable(v) for v in o]
if isinstance(o, np.ndarray):
return o.tolist()
if isinstance(o, np.generic):
return o.item()
if isinstance(o, float) and not math.isfinite(o):
return None
return o
# ---------------------------------------------------------------------------------------------------------------- units
[docs]
def to_fF(values, unit: str) -> np.ndarray:
"""Values in ``unit`` (F, nF, pF, fF, aF; ``"pF*1e15"`` = the exp12 re-export header ``C(a,b)*1e15 [pF]``, whose values
are pF x 1e15) converted to fF."""
u = str(unit).strip()
x15 = u.endswith("*1e15")
u = u.replace("*1e15", "").strip("[] ")
if u not in TO_FF:
raise ValueError(f"unknown capacitance unit {unit!r}; use one of {sorted(TO_FF)}")
return np.asarray(values, float) * TO_FF[u] * (1e-15 if x15 else 1.0)
[docs]
def unit_plausibility(C_fF, declared: str) -> str | None:
"""A warning when a matrix in fF looks like it was given in another unit (entries of ~1e-15 or ~1e3 x the usual size)."""
a = np.abs(np.asarray(C_fF, float))
a = a[np.isfinite(a) & (a > 0)]
if not a.size:
return None
m = float(np.median(a))
if m < 1e-9:
return f"median |C| = {m:.3g} fF after conversion from {declared}: the values look like farads"
if m > 1e5:
return f"median |C| = {m:.3g} fF after conversion from {declared}: implausibly large for a planar component"
return None
# ---------------------------------------------------------------------------------------------------------------- readers
[docs]
def read_cap_matrix(path) -> dict:
"""Q3D ``cap_matrix.csv`` (one row per adaptive pass; ``C(a,b) [unit]`` columns in any unit, also the ``*1e15`` header)
-> ``{"names" (G first, then first appearance), "passes" [(pass index, N x N fF)], "units", "freq_GHz"}``. Incomplete rows
(pre-allocated passes) are kept as NaN matrices and skipped by the QC."""
rows = [r for r in csv.reader(open(path, encoding="utf-8")) if r]
if not rows:
raise ValueError(f"{path}: empty file")
hdr, data = rows[0], rows[1:]
cols, order, units = {}, [], set()
i_pass = i_freq = None
for j, h in enumerate(hdr):
hs = h.strip().strip('"')
if hs.lower().startswith("pass"):
i_pass = j
elif hs.lower().startswith("freq"):
i_freq = j
m = _HEADER.match(hs)
if not m:
continue
a, b = m.group(1).strip(), m.group(2).strip()
unit = m.group(4) + ("*1e15" if m.group(3) else "")
units.add(unit)
cols[(a, b)] = (j, float(to_fF(1.0, unit)))
for x in (a, b):
if x not in order:
order.append(x)
if not cols:
raise ValueError(f"{path}: no C(a,b) [unit] columns")
names = ([GROUND] if GROUND in order else []) + [x for x in order if x != GROUND]
passes, freq = [], None
for k, r in enumerate(data):
C = np.full((len(names), len(names)), np.nan)
for ia, a in enumerate(names):
for ib, b in enumerate(names):
jj = cols.get((a, b)) or cols.get((b, a))
if jj is None:
continue
try:
C[ia, ib] = float(r[jj[0]]) * jj[1]
except (ValueError, IndexError):
pass
try:
p = int(float(r[i_pass])) if i_pass is not None else k + 1
except (ValueError, IndexError):
p = k + 1
if i_freq is not None:
try:
freq = float(r[i_freq])
except (ValueError, IndexError):
pass
passes.append((p, C))
return {"names": names, "passes": passes, "units": sorted(units), "freq_GHz": freq}
[docs]
def read_conv(path) -> dict:
"""Q3D ``.conv`` convergence file -> pass history, passes completed, delta target and final delta (%)."""
t = Path(path).read_text(encoding="utf-8")
def g(k, f=float):
m = re.search(rf"{k}\s*:\s*(\S+)", t)
try:
return f(m.group(1)) if m else None
except ValueError:
return None
hist = []
for m in re.finditer(r"^\s*(\d+)\|\s*(\d+)\|\s*([^|]+)\|", t, re.M):
d = m.group(3).strip()
hist.append(
{"pass": int(m.group(1)), "n_triangles": int(m.group(2)), "delta_pct": None if d == "N/A" else float(d)}
)
return {
"pass_history": hist,
"passes_completed": g("Completed", int),
"delta_target_pct": g("Target"),
"delta_pct_final": g("Current"),
}
# ---------------------------------------------------------------------------------------------------------------- labels
[docs]
def label_qc(
C,
names,
net_order=None,
unit: str = "fF",
passes=None,
convergence: dict | None = None,
flagged_zero=(),
sym_rtol: float = SYM_RTOL,
closure_warn: float = CLOSURE_WARN,
subject: str = "",
) -> QCReport:
"""QC of one Maxwell matrix ``C`` (``names`` = its row order; any unit, converted to fF).
net_order: the declared net order (G first); the matrix must be square over exactly these names. passes: optional
``[(pass index, matrix in the same names / unit)]``, the last complete pass must equal ``C``. convergence: optional
``{"delta_pct_final", "delta_target_pct", "passes_completed"}``. flagged_zero: pairs ``(a, b)`` whose exact zero is
explained (e.g. a lattice entry below the solver floor). ``info["matrix_fF"]`` holds the matrix in ``net_order``."""
r = QCReport(subject)
names = [str(x) for x in names]
try:
C = to_fF(C, unit)
except ValueError as e:
r.error(str(e))
return r
if C.ndim != 2 or C.shape[0] != C.shape[1]:
r.error(f"matrix is not square: shape {C.shape}")
return r
if C.shape[0] != len(names):
r.error(f"matrix size {C.shape[0]} does not match {len(names)} net names {names}")
return r
if len(set(names)) != len(names):
r.error(f"duplicate net names {names}")
return r
order = [str(x) for x in (net_order if net_order is not None else names)]
if GROUND not in order:
r.error(f"ground net {GROUND!r} missing from the net order {order}")
return r
if order[0] != GROUND:
r.error(f"ground net {GROUND!r} must be first in the net order (got {order})")
if set(order) != set(names) or len(order) != len(names):
r.error(f"matrix nets {sorted(names)} differ from the declared net order {order}")
return r
ix = [names.index(n) for n in order]
C = C[np.ix_(ix, ix)]
names = order
n = len(names)
r.info["n_conductors"] = n
r.info["net_order"] = names
if not np.isfinite(C).all():
r.error("non-finite entries in the matrix")
return r
w = unit_plausibility(C, unit)
if w:
r.warn(w)
scale = float(np.abs(C).max()) or 1.0
sym = float(np.abs(C - C.T).max() / scale)
r.info["symmetry_rel"] = sym
if sym > sym_rtol:
r.error(f"asymmetric: max |C - C^T| / max |C| = {sym:.3g} > {sym_rtol:g}")
elif sym > SYM_WARN:
r.warn(f"slightly asymmetric (max |C - C^T| / max |C| = {sym:.3g}); symmetrized as (C + C^T) / 2")
Cs = 0.5 * (C + C.T)
d = np.diag(Cs)
if not np.all(d > 0):
r.error(f"non-positive diagonal entries on {[names[i] for i in np.flatnonzero(d <= 0)]}")
flagged = {frozenset((str(a), str(b))) for a, b in flagged_zero}
pos, zero = [], []
for i in range(n):
for j in range(i + 1, n):
if Cs[i, j] > 0:
pos.append(f"{names[i]}-{names[j]} ({Cs[i, j]:.4g} fF)")
elif Cs[i, j] == 0 and frozenset((names[i], names[j])) not in flagged:
zero.append(f"{names[i]}-{names[j]}")
if pos:
r.error(f"positive off-diagonal entries (Maxwell signs need C_ij < 0): {pos[:5]}")
if zero:
r.error(f"exactly-zero off-diagonal entries not flagged as explained: {zero[:5]}")
sig = np.array([x != GROUND for x in names])
if sig.any() and np.all(d[sig] > 0):
clo = np.abs(Cs.sum(1)[sig]) / d[sig]
r.info["closure_max_rel"] = float(clo.max())
if clo.max() > closure_warn:
worst = names[int(np.flatnonzero(sig)[int(np.argmax(clo))])]
r.warn(f"signal-row closure |sum_j C_ij| / C_ii = {clo.max():.3g} on {worst} (> {closure_warn:.0%})")
eig = float(np.linalg.eigvalsh(Cs[np.ix_(sig, sig)]).min())
r.info["signal_block_min_eig_fF"] = eig
if eig <= 0:
r.error(f"signal block not positive definite (min eigenvalue {eig:.4g} fF)")
if passes is not None:
_pass_history(r, passes, C, unit, names, ix)
if convergence:
_convergence(r, convergence)
r.info["matrix_fF"] = Cs
return r
def _pass_history(r: QCReport, passes, C, unit, order, ix) -> None:
idx = [int(p) for p, _ in passes]
r.info["passes"] = len(idx)
if idx != sorted(idx) or len(set(idx)) != len(idx):
r.warn(f"pass indices are not strictly increasing: {idx}")
complete = [(p, to_fF(M, unit)) for p, M in passes if np.isfinite(np.asarray(M, float)).all()]
if not complete:
r.error("no complete adaptive pass in the pass history")
return
last = complete[-1][1][np.ix_(ix, ix)]
if not np.allclose(last, C, rtol=1e-9, atol=1e-12):
r.error("the label is not the last complete pass of the pass history")
if len(complete) >= 2:
prev = complete[-2][1][np.ix_(ix, ix)]
big = np.abs(last) >= 0.1
if big.any():
r.info["last_pass_change_max_pct"] = float(np.max(np.abs(last - prev)[big] / np.abs(last)[big]) * 100)
def _convergence(r: QCReport, conv: dict) -> None:
fin, tgt = conv.get("delta_pct_final"), conv.get("delta_target_pct")
r.info["delta_pct_final"], r.info["delta_target_pct"] = fin, tgt
if conv.get("passes_completed") is not None:
r.info["passes_completed"] = conv["passes_completed"]
if fin is None or tgt is None:
r.warn("convergence not recorded (final delta or target missing)")
elif fin > tgt:
r.warn(f"not converged: final delta {fin:g} % > target {tgt:g} %")
r.info["converged"] = None if fin is None or tgt is None else bool(fin <= tgt)
# ---------------------------------------------------------------------------------------------------------------- layouts
[docs]
def geom_hash(path) -> str:
"""``"sha256:<hex>"`` of the canonical polygon multiset of a GDS (layer, datatype, vertices rounded to 1 nm, sorted): the
dataset's duplicate key, identical to the ``geom_hash`` column of ``SQuADDS/SQuADDS_PlanarCapacitance``."""
import gdstk
lib = gdstk.read_gds(str(path))
s = lib.unit / 1e-9
polys = [p for c in lib.top_level() for p in c.polygons]
key = sorted((p.layer, p.datatype, np.round(p.points * s).astype(np.int64).tobytes()) for p in polys)
h = hashlib.sha256()
for la, dt, b in key:
h.update(f"{la}/{dt}:".encode())
h.update(b)
return "sha256:" + h.hexdigest()
def _components(polys) -> list[list[int]]:
import shapely
n = len(polys)
parent = list(range(n))
def find(a):
while parent[a] != a:
parent[a] = parent[parent[a]]
a = parent[a]
return a
if n > 1:
ii, jj = shapely.STRtree(polys).query(polys, predicate="intersects")
for a, b in zip(ii, jj):
ra, rb = find(int(a)), find(int(b))
if ra != rb:
parent[max(ra, rb)] = min(ra, rb)
groups: dict = {}
for i in range(n):
groups.setdefault(find(i), []).append(i)
return sorted(groups.values(), key=lambda g: g[0])
def _layers(x) -> list[tuple[int, int]]:
return [tuple(int(v) for v in la) for la in x]
[docs]
def gds_qc(path, layer_map: dict | None = None, nets: dict | None = None, subject: str = "") -> QCReport:
"""GDS readback: readable by gdstk, one top cell, unit 1 um or 1 nm, declared layers present, every polygon valid, and the
conductor count (``info["n_conductors"]``, ground included) inferred from the layout.
Conductors: the connected bodies of the conductor-layer polygons (touching polygons are one metal body, hence one net), in
file order, unless ``nets`` = ``{net name: [conductor-layer polygon indices in file order]}`` assigns polygons explicitly.
Bodies touching the ground metal are at ground potential (warned). ``info["geom_hash"]`` is the dataset duplicate key."""
r = QCReport(subject or str(path))
try:
import gdstk
import shapely
from shapely.geometry import Polygon
except ImportError as e:
r.error(f"GDS checks need gdstk and shapely ({e}); install them with pip install 'squadds[ml]'")
return r
lm = layer_map or DEFAULT_LAYERS
gl, cl = set(_layers(lm.get("ground", []))), set(_layers(lm.get("conductor", [])))
try:
lib = gdstk.read_gds(str(path))
except Exception as e: # noqa: BLE001
r.error(f"gdstk cannot read the file: {e}")
return r
tops = lib.top_level()
r.info["top_cells"] = [c.name for c in tops]
if len(tops) != 1:
r.error(f"{len(tops)} top cells ({[c.name for c in tops][:5]}); exactly one is required")
if not tops:
return r
r.info["unit_m"], r.info["precision_m"] = lib.unit, lib.precision
if not any(math.isclose(lib.unit, u, rel_tol=1e-9) for u in GDS_UNITS_M):
r.error(f"GDS user unit {lib.unit:g} m: use 1 um or 1 nm")
if not (1e-12 <= lib.precision <= 1e-9):
r.warn(f"GDS precision {lib.precision:g} m (expected 1 nm or finer)")
top = tops[0]
raw = (
top.get_polygons(apply_repetitions=True, include_paths=True) if (top.references or top.paths) else top.polygons
)
u = lib.unit / 1e-6
present = sorted({(p.layer, p.datatype) for p in raw})
r.info["layers"] = present
missing = sorted((gl | cl) - set(present))
if missing:
r.error(f"declared layers {missing} have no polygons (layers present: {present})")
gpolys, cpolys, invalid = [], [], 0
for p in raw:
key = (p.layer, p.datatype)
if key not in gl and key not in cl:
continue
if len(p.points) < 3:
invalid += 1
continue
g = Polygon(p.points * u)
if g.area <= 0 or (not g.is_valid and abs(shapely.make_valid(g).area - g.area) > 1e-6 * g.area):
invalid += 1 # keyhole polygons (ground planes with holes) touch themselves without changing area: accepted
(gpolys if key in gl else cpolys).append(g)
if invalid:
r.error(
f"{invalid} invalid polygon(s) on the ground / conductor layers (self-intersecting, degenerate or < 3 vertices)"
)
r.info["n_polygons"] = len(gpolys) + len(cpolys)
if not gpolys or not cpolys:
if not gpolys:
r.error("no ground polygons")
if not cpolys:
r.error("no conductor polygons")
r.info["n_conductors"] = 1 if gpolys else 0
return r
cvalid = [shapely.make_valid(g) if not g.is_valid else g for g in cpolys]
if nets:
idx = sorted(i for v in nets.values() for i in v)
if idx != list(range(len(cvalid))):
r.error(f"nets map must assign every conductor-layer polygon exactly once (0..{len(cvalid) - 1})")
bodies = [shapely.union_all([cvalid[i] for i in v if 0 <= i < len(cvalid)]) for v in nets.values()]
r.info["conductor_names"] = list(nets)
else:
bodies = [shapely.union_all([cvalid[i] for i in comp]) for comp in _components(cvalid)]
if len(bodies) < len(cvalid):
r.info["touching_polygons_joined"] = len(cvalid) - len(bodies)
G = shapely.union_all([shapely.make_valid(g) if not g.is_valid else g for g in gpolys])
shorted = [i for i, b in enumerate(bodies) if shapely.intersects(b, G)]
if shorted:
r.warn(
f"{len(shorted)} conductor body(ies) touch the ground metal (bodies {shorted}): they are at ground potential"
)
r.info["n_conductors"] = 1 + len(bodies) - len(shorted)
r.info["n_conductors_raw"] = 1 + len(bodies)
metals = [G] + [b for i, b in enumerate(bodies) if i not in set(shorted)]
if len(metals) > 1:
gap = min(shapely.distance(metals[i], metals[j]) for i in range(len(metals)) for j in range(i + 1, len(metals)))
r.info["min_gap_um"] = float(gap)
try:
r.info["geom_hash"] = geom_hash(path)
except Exception as e: # noqa: BLE001
r.warn(f"geom_hash not computed: {e}")
return r
[docs]
def conductor_count_qc(n_layout: int, net_order, subject: str = "") -> QCReport:
"""The matrix must cover every conductor of the layout: N from the GDS (ground included) == len(net_order)."""
r = QCReport(subject)
if int(n_layout) != len(net_order):
r.error(
f"the layout has {n_layout} conductors (ground included) but the matrix has {len(net_order)} nets {list(net_order)}: "
"every conductor must be its own net (nets are never merged)"
)
return r
# ---------------------------------------------------------------------------------------------------------------- dataset
[docs]
def reference_hashes(db=None, local_dir=None, revision: str | None = None):
"""``design_id`` / ``geom_hash`` / ``split`` of every design of the dataset (``PlanarCapacitanceDB``; HF or a local copy)."""
if db is None:
from .dataset import PlanarCapacitanceDB
db = PlanarCapacitanceDB(revision=revision, local_dir=local_dir)
return db.read("designs", columns=["design_id", "geom_hash", "split"])
[docs]
def duplicate_qc(hashes: dict, reference=None, subject: str = "duplicates") -> QCReport:
"""hashes: ``{design: geom_hash}`` of a batch; reference: a DataFrame with ``design_id``, ``geom_hash``, ``split`` (the
dataset), or None (only duplicates inside the batch are checked; warned). A duplicate of a ``test`` design is an error."""
r = QCReport(subject)
seen: dict = {}
for d, h in hashes.items():
if h is None:
continue
if h in seen:
r.warn(f"{d} has the same geometry as {seen[h]} in this batch")
else:
seen[h] = d
if reference is None:
r.warn("no dataset reference given: duplicates against SQuADDS_PlanarCapacitance were not checked")
return r
ref = reference[reference["geom_hash"].isin(set(seen))]
test_dups, other_dups = [], []
for h, sub in ref.groupby("geom_hash"):
d = seen[h]
ids = sorted(map(str, sub["design_id"]))
if (sub["split"] == "test").any():
test_dups.append(f"{d} = {ids[:3]}")
else:
other_dups.append(f"{d} = {ids[:3]} ({', '.join(sorted(set(map(str, sub['split']))))})")
if test_dups:
r.error(f"duplicate of a held-out test design (would leak its label): {test_dups}")
if other_dups:
r.warn(f"exact duplicates of dataset designs (kept, same group): {other_dups}")
r.info["dataset_duplicates"] = len(test_dups) + len(other_dups)
return r
[docs]
def stack_qc(stack: dict, freq_GHz: float | None = None, subject: str = "stack") -> QCReport:
"""eps_r in [1, 30], substrate in [5, 2000] um, frequency in [0.1, 50] GHz; a stack other than the training stack
(Si 11.45, 350 um) is accepted and recorded (warned: the released models are served for the training stack)."""
r = QCReport(subject)
vals = {"eps_r": stack.get("eps_r"), "substrate_um": stack.get("substrate_um"), "freq_GHz": freq_GHz}
for k, (lo, hi) in STACK_RANGES.items():
v = vals.get(k)
if v is None:
if k != "freq_GHz":
r.error(f"stack field {k!r} missing")
continue
try:
v = float(v)
except (TypeError, ValueError):
r.error(f"stack field {k!r} is not a number: {v!r}")
continue
r.info[k] = v
if not lo <= v <= hi:
r.warn(f"{k} = {v:g} outside the usual range [{lo:g}, {hi:g}]")
eps, t = r.info.get("eps_r"), r.info.get("substrate_um")
if eps is not None and t is not None:
on = math.isclose(eps, TRAINING_STACK["eps_r"], rel_tol=1e-3) and math.isclose(
t, TRAINING_STACK["substrate_um"], rel_tol=1e-3
)
r.info["training_stack"] = on
if not on:
r.warn(
f"stack eps_r {eps:g}, {t:g} um differs from the training stack (Si 11.45, 350 um): recorded as off-stack"
)
return r
[docs]
def prior_sanity(
C_fF,
net_order,
gds,
layer_map: dict | None = None,
band=PRIOR_RATIO_BAND,
floor_fF: float = PRIOR_FLOOR_FF,
threads: int = 2,
prior=None,
subject: str = "physics sanity",
) -> QCReport:
"""Ratio of each label entry to ``optimized_physics_prior`` of the layout (report only, never an error).
The label's conductors (``net_order[1:]``) are matched to the layout's in GDS file order. Entries with ``|C| >= floor_fF``
whose ratio falls outside ``band`` are warned. prior: a precomputed ``PriorResult`` (else computed here, needs [ml])."""
r = QCReport(subject)
C = np.asarray(C_fF, float)
if prior is None:
try:
from . import priors
lm = layer_map or DEFAULT_LAYERS
prior = priors.optimized_physics_prior(
str(gds),
threads=threads,
ground_layers=_layers(lm.get("ground", [])),
conductor_layers=_layers(lm.get("conductor", [])),
)
except ImportError as e:
r.warn(f"physics sanity skipped (needs pip install 'squadds[ml]'): {e}")
return r
except Exception as e: # noqa: BLE001
r.warn(f"physics sanity skipped: the prior could not be computed ({e})")
return r
P = np.asarray(prior.C_fF, float)
if P.shape != C.shape:
r.warn(f"physics sanity skipped: prior is {P.shape[0]} x {P.shape[0]}, label {C.shape[0]} x {C.shape[0]}")
return r
names = list(net_order)
with np.errstate(divide="ignore", invalid="ignore"):
ratio = C / P
iu = np.triu_indices(len(C))
far = []
for i, j in zip(*iu):
if abs(C[i, j]) < floor_fF or not np.isfinite(ratio[i, j]):
continue
if not band[0] <= ratio[i, j] <= band[1]:
far.append(f"{names[i]}-{names[j]}: label {C[i, j]:.4g} fF, prior {P[i, j]:.4g} fF (x{ratio[i, j]:.3g})")
mut = [(i, j) for i, j in zip(*iu) if i != j and abs(C[i, j]) >= floor_fF and np.isfinite(ratio[i, j])]
if mut:
rel = np.array([abs(ratio[i, j] - 1) for i, j in mut]) * 100
r.info["prior_median_rel_diff_pct"] = float(np.median(rel))
r.info["prior_mae_fF"] = float(np.mean([abs(C[i, j] - P[i, j]) for i, j in mut]))
r.info["prior_rmse_fF"] = float(np.sqrt(np.mean([(C[i, j] - P[i, j]) ** 2 for i, j in mut])))
r.info["prior_version"] = getattr(prior, "prior_version", "")
r.info["prior_s"] = (getattr(prior, "timing_s", {}) or {}).get("total_s")
r.info["prior_machine"] = getattr(prior, "machine", "")
r.info["prior_threads"] = getattr(prior, "threads", None)
if far:
r.warn(
f"{len(far)} label entries outside x{band[0]:g}..x{band[1]:g} of the physics prior (check nets / units): {far[:5]}"
)
return r