"""Bridges from the planar capacitance models into the existing SQuADDS workflows.
- ``MLSimulator``: the call and result shape of the capacitance (Q3D / LOM) path of ``AnsysSimulator``
(``simulate(device_dict)`` -> ``{"design", "sim_options", "sim_results"}``) plus ``fidelity="ml:<model>"`` and ``timing``.
Input: a Qiskit Metal design or component, a SQuADDS row (rebuilt with the component registry) or a GDS path.
- ``predict_dataframe``: predictions for the rows of an Analyzer result (``Analyzer.predict_capacitance`` calls it).
- ``transmon_cross_capacitances`` / ``EC_MHz`` / ``g_MHz`` / ``EC_MHz_from_matrix``: feed ``squadds.calcs``.
Export (``export=``): ``"auto"`` (default) writes a component of a dataset family (``squadds.layouts.dataset_export``:
interdigital / paddle, concentric, star, Xmon, TransmonPocket, shielded concentric) exactly as the dataset was exported,
so the model sees the input it was trained on; any other layout (e.g. quantum-metal ``TransmonCross``, several
components) goes through ``export_qgeometry_gds`` (square ground domain, 169 um padding). ``"dataset"`` / ``"qgeometry"``
force one. The result records it in ``export``. Star rows of the SQuADDS view carry their style in
``notes.export_style``. Conductor bodies are named from the qgeometry they overlap (``planar_capacitance_view.QGEOMETRY_NETS``), so the
``sim_results`` keys match the SQuADDS configs (``north_to_south``, ``cross_to_claw``, ...).
"""
from __future__ import annotations
import importlib
import os
import tempfile
import time
from copy import deepcopy
from pathlib import Path
from typing import Any
import numpy as np
from squadds.database.planar_capacitance_view import QGEOMETRY_NETS, net_name, sim_results_from_matrix
QISKIT_METAL_CLASSES = {
"TransmonCross": "qiskit_metal.qlibrary.qubits.transmon_cross",
"TransmonPocket": "qiskit_metal.qlibrary.qubits.transmon_pocket",
}
GAP_OPTION_KEYS = ("cpw_gap", "claw_gap", "ground_spacing", "gap_ground", "ground_gap", "min_trace_gap", "cross_gap")
DEFAULT_CLEARANCE_UM = 5.0
EXPORTS = ("auto", "dataset", "qgeometry")
# ------------------------------------------------------------------------------------------------ rows -> components
def _clean(value):
"""Drop ``None`` / NaN entries (union-schema padding of HF rows) and numpy scalars from an options tree."""
if isinstance(value, dict):
return {k: _clean(v) for k, v in value.items() if not _is_missing(v)}
if isinstance(value, (list, tuple)):
return [_clean(v) for v in value]
if isinstance(value, np.generic):
return value.item()
return value
def _is_missing(v) -> bool:
return v is None or (isinstance(v, float) and np.isnan(v))
[docs]
def row_options_and_class(row, component_name: str | None = None) -> tuple[dict, str]:
"""(design_options, component class name) of a SQuADDS row: nested HF record, flattened DataFrame row (Series or
dict) or an ``AnsysSimulator`` device dict."""
from squadds.core.json_utils import deserialize_json_like
if hasattr(row, "to_dict"):
row = row.to_dict()
rec = row["design"] if isinstance(row.get("design"), dict) else row
opts = deserialize_json_like(rec.get("design_options", row.get("design_options")))
if not isinstance(opts, dict):
raise ValueError("row has no design_options")
cls = component_name
for key in ("component_class", "component_name", "coupler_type"):
if cls is None and isinstance(rec.get(key), str) and rec.get(key):
cls = rec[key]
if cls is None and "cross_length" in opts:
cls = "TransmonCross"
if cls is None:
raise ValueError("cannot tell the component class of this row: pass component_name=")
return _clean(opts), cls
[docs]
def component_class(name: str):
"""Qiskit Metal class of a dataset component name (SQuADDS registry first, then quantum-metal qubits)."""
from squadds.components import get_component_class
try:
return get_component_class(name)
except ValueError:
if name in QISKIT_METAL_CLASSES:
return getattr(importlib.import_module(QISKIT_METAL_CLASSES[name]), name)
raise
[docs]
def build_component(row, component_name: str | None = None, design=None, name: str = "component"):
"""Rebuild the component of a SQuADDS row in ``design`` (a new ``DesignPlanar`` by default)."""
from qiskit_metal import designs
opts, cls = row_options_and_class(row, component_name)
design = design if design is not None else designs.DesignPlanar({}, overwrite_enabled=True)
comp = component_class(cls)(design, name, options=opts)
design.rebuild()
return comp
# ------------------------------------------------------------------------------------------------ rendering and naming
def _length_um(design, value) -> float | None:
try:
v = float(design.parse_value(value)) * 1e3
except Exception: # noqa: BLE001
return None
return v if v > 0 else None
[docs]
def default_clearance_um(design) -> float:
"""Signal-to-ground clearance for the exported ground: the smallest lead / claw / ground gap option of the components
(the native etch stays authoritative; the clearance only closes open CPW ends)."""
found = []
def scan(opts):
for k, v in opts.items():
if isinstance(v, dict):
scan(v)
elif any(k.endswith(g) for g in GAP_OPTION_KEYS) and isinstance(v, (str, int, float)):
for part in str(v).split(","):
um = _length_um(design, part.strip()) if part.strip() else None
if um:
found.append(um)
for comp in design.components.values():
scan(dict(comp.options))
return min(found) if found else DEFAULT_CLEARANCE_UM
[docs]
def render_gds(design, path, clearance_um: float | None = None) -> Path:
"""Export ``design`` to a GDS in the training layer convention (ground (1, 0), conductors (1, 10))."""
from squadds.layouts.qmetal_gds import export_qgeometry_gds
path = Path(path)
clearance = float(clearance_um or default_clearance_um(design))
export_qgeometry_gds(design, path, include_ground_domain=True, minimum_ground_clearance_um=clearance)
return path
def _qgeometry_elements(design) -> list[tuple[str, str, str, Any]]:
"""(component class, component name, element name, geometry in µm) of every conductor qgeometry element."""
from shapely import affinity
out = []
for table in ("poly", "path"):
for r in design.qgeometry.tables[table].itertuples(index=False):
if bool(r.helper) or bool(r.subtract):
continue
g = r.geometry
if table == "path":
g = g.buffer(float(r.width) / 2, cap_style="flat", join_style="round")
comp = design._components[r.component]
out.append((type(comp).__name__, comp.name, r.name, affinity.scale(g, 1e3, 1e3, origin=(0, 0))))
return out
[docs]
def body_labels(conductors, design) -> tuple[list[str], str | None]:
"""Dataset net label (``N``, ``S``, ``P1``, ...) of each conductor body, and the component class when the layout has a
single component. Unmapped bodies keep the predictor's name ``C<k>``; with several components the labels are
``<component>:<element>``."""
elems = _qgeometry_elements(design)
classes = {e[0] for e in elems}
single = next(iter(classes)) if len({e[1] for e in elems}) == 1 else None
labels = []
for k, body in enumerate(conductors):
hits = [e for e in elems if body.intersection(e[3]).area > 1e-6 * max(e[3].area, 1e-12)]
lab = None
if single and hits:
cands = {QGEOMETRY_NETS.get(single, {}).get(e[2]) for e in hits}
cands.discard(None)
lab = cands.pop() if len(cands) == 1 else None
elif hits:
lab = "+".join(sorted({f"{e[1]}:{e[2]}" for e in hits}))
lab = lab or f"C{k + 1}"
while lab in labels:
lab = f"{lab}'"
labels.append(lab)
return labels, single
# ------------------------------------------------------------------------------------------------ simulator
[docs]
class MLSimulator:
"""Capacitance from the planar capacitance models, in the result shape of ``AnsysSimulator``'s capacitance path.
sim = MLSimulator(analyzer, device_dict) # like AnsysSimulator(analyzer, device_dict)
res = sim.simulate() # {"design", "sim_options", "sim_results", ...}
MLSimulator(model="QCap-Fast").predict("chip.gds") # or a component, a design or a SQuADDS row
model: ``"QCap"`` (default), ``"QCap-Fast"`` or a loaded ``CapacitanceModel``. ``predictor``: any object with ``predict(layout) -> CapacitanceResult`` (tests).
export: ``"auto"`` (dataset export for the dataset families, else ``"qgeometry"``), ``"dataset"`` or
``"qgeometry"``; ``export_style`` / ``margin_gaps`` / ``ground_gap_um`` override the dataset export
(``squadds.layouts.dataset_export.export_dataset_gds``; a row's ``notes.export_style`` is used when not set).
"""
def __init__(
self,
analyzer=None,
design_options=None,
model="QCap",
threads: int | None = None,
predictor=None,
clearance_um: float | None = None,
workdir=None,
export: str = "auto",
export_style: str | None = None,
margin_gaps: float | None = None,
ground_gap_um: float | None = None,
tier=None,
**predict_kwargs,
):
from .models import no_tier
no_tier(tier)
self.analyzer = analyzer
self.device_dict = deepcopy(design_options) if design_options is not None else None
self.model, self.threads = model or "QCap", threads
self.clearance_um = clearance_um
if export not in EXPORTS:
raise ValueError(f"export must be one of {EXPORTS}")
self.export, self.export_style = export, export_style
self.margin_gaps, self.ground_gap_um = margin_gaps, ground_gap_um
self.workdir = Path(workdir) if workdir is not None else None
self.predict_kwargs = predict_kwargs
self._predictor = predictor
def __repr__(self) -> str:
return f"MLSimulator(model={getattr(self.model, 'name', self.model)!r})"
@property
def predictor(self):
if self._predictor is None:
from squadds.ml.capacitance import CapacitancePredictor
self._predictor = CapacitancePredictor(self.model, threads=self.threads)
return self._predictor
@property
def fidelity(self) -> str:
from .models import DISPLAY_NAMES, is_model_name, model_key
m = getattr(self._predictor, "model", None) or self.model
m = getattr(m, "name", m)
return f"ml:{DISPLAY_NAMES[model_key(m)] if is_model_name(m) else m}"
[docs]
def simulate(self, device_dict=None, run_async: bool = False) -> dict:
"""``AnsysSimulator.simulate`` for single components (capacitance only)."""
if run_async:
raise NotImplementedError("MLSimulator predicts synchronously (about a second per design).")
if self.analyzer is not None and isinstance(getattr(self.analyzer, "selected_system", None), list):
raise NotImplementedError(
"MLSimulator predicts capacitance matrices of single components; the eigenmode part of a qubit-cavity "
"system stays with AnsysSimulator."
)
device_dict = device_dict if device_dict is not None else self.device_dict
if device_dict is None:
raise ValueError("no device dict: pass design_options= to MLSimulator or device_dict= to simulate()")
name = None
if self.analyzer is not None and not _row_declares_class(device_dict):
name = getattr(self.analyzer, "selected_coupler", None) or getattr(
self.analyzer, "selected_component_name", None
)
return self.predict(device_dict, component_name=name)
[docs]
def predict(self, obj, component_name: str | None = None) -> dict:
"""Prediction for a GDS path, a Qiskit Metal design or component, or a SQuADDS row / device dict."""
from qiskit_metal.designs import QDesign
from qiskit_metal.qlibrary.core import QComponent
t0 = time.perf_counter()
design, options, cls_name, gds, notes = None, None, None, None, {}
if isinstance(obj, (str, os.PathLike)):
gds = Path(obj)
elif isinstance(obj, QComponent):
design, options, cls_name = obj.design, dict(obj.options), type(obj).__name__
elif isinstance(obj, QDesign):
design = obj
else:
comp = build_component(obj, component_name)
design, options, cls_name = comp.design, dict(comp.options), type(comp).__name__
notes = row_notes(obj)
warnings = []
if notes.get("geometry_reproducible") is False:
warnings.append(
f"{notes.get('design_id', 'this row')}: the stored options do not rebuild the solved GDS exactly; the "
"prediction is for the rebuilt layout"
)
with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as tmp:
export = {"convention": "gds", "path": str(gds)} if gds is not None else None
if gds is None:
out = (self.workdir or Path(tmp)) / f"{cls_name or 'design'}_{int(time.time() * 1e6)}.gds"
gds, design, export = self._export(obj if isinstance(obj, QComponent) else design, out, notes)
render_s = time.perf_counter() - t0
from squadds.ml.capacitance._runtime import prepare_layout
lay = prepare_layout(str(gds))
res = self.predictor.predict(lay, **self.predict_kwargs)
if design is not None:
bodies, single = body_labels(lay.conductors, design)
labels = ["G", *bodies]
else:
labels, single = list(res.names), None
sim_results = sim_results_from_matrix(labels, res.matrix_fF, single or "")
timing = {"render_s": render_s, **dict(res.timing_s), "wall_s": time.perf_counter() - t0}
return {
"design": {
"design_options": _clean(options) if options is not None else None,
"design_tool": "qiskit-metal",
"component_class": cls_name,
"gds": str(gds) if self.workdir is not None or export["convention"] == "gds" else None,
"export": export,
},
"sim_options": {
"sim_type": "cap_matrix",
"setup": {"model": res.model, "threads": res.threads, "prior": res.prior_version},
"layer_stack": dict(res.substrate),
"simulator": f"squadds.ml.capacitance ({res.model})",
},
"sim_results": sim_results,
"fidelity": f"ml:{res.model}",
"timing": timing,
"net_names": {lab: net_name(single or "", lab) for lab in labels},
"checks": dict(res.checks),
"warnings": warnings + list(res.warnings),
"export": export,
"prediction": res,
}
def _export(self, obj, out: Path, notes: dict):
"""Write ``obj`` (a component or a design) to ``out``: ``(gds, design whose qgeometry names the bodies, export
record)``."""
from qiskit_metal.designs import QDesign
from squadds.layouts.dataset_export import dataset_export_layout, family_of, write_dataset_gds
out.parent.mkdir(parents=True, exist_ok=True)
family = family_of(obj)
if self.export == "dataset" and family is None:
raise ValueError("export='dataset' needs one component of a dataset family; use export='qgeometry'")
if self.export == "qgeometry" or family is None:
design = obj if isinstance(obj, QDesign) else obj.design
clearance = float(self.clearance_um or default_clearance_um(design))
gds = render_gds(design, out, clearance)
return gds, design, {"convention": "qgeometry", "clearance_um": clearance}
style = self.export_style or (notes.get("export_style") if family == "star" else None)
gap = self.ground_gap_um if self.ground_gap_um is not None else notes.get("ground_gap_um")
cell, design, settings = dataset_export_layout(obj, None, self.margin_gaps, style, gap)
return write_dataset_gds(cell, out), design, settings
[docs]
def row_notes(row) -> dict:
"""``notes`` of a SQuADDS row (nested record or flattened DataFrame row); {} for a device dict without notes."""
if hasattr(row, "to_dict"):
row = row.to_dict()
if not isinstance(row, dict):
return {}
notes = row.get("notes")
if isinstance(notes, dict):
return notes
keys = ("design_id", "export_style", "geometry_reproducible", "ground_gap_um")
return {k: row[k] for k in keys if k in row and not _is_missing(row[k])}
def _row_declares_class(row) -> bool:
if hasattr(row, "to_dict"):
row = row.to_dict()
rec = row["design"] if isinstance(row.get("design"), dict) else row
return any(
isinstance(rec.get(k), str) and rec.get(k) for k in ("component_class", "component_name", "coupler_type")
)
[docs]
def predict_dataframe(df, model="QCap", component_name=None, simulator=None, **kwargs):
"""One prediction per row of a SQuADDS DataFrame (closest designs, interpolated designs): a DataFrame with the same
index, the predicted ``sim_results`` columns (suffix ``_ml``), ``fidelity``, ``ml_total_s`` and ``ml_result``."""
import pandas as pd
sim = simulator or MLSimulator(model=model, **kwargs)
if isinstance(df, dict):
df = pd.DataFrame([df])
out = []
for _, row in df.iterrows():
name = component_name if not _row_declares_class(row) else None
r = sim.predict(row, component_name=name)
rec = {f"{k}_ml": v for k, v in r["sim_results"].items() if k not in ("maxwell_matrix", "units")}
rec.update(
maxwell_matrix_ml=r["sim_results"]["maxwell_matrix"],
fidelity=r["fidelity"],
ml_total_s=r["timing"].get("wall_s"),
ml_result=r,
)
out.append(rec)
return pd.DataFrame(out, index=df.index)
# ------------------------------------------------------------------------------------------------ calcs helpers
def _sim_results_of(x) -> dict:
if hasattr(x, "to_sim_results"):
return x.to_sim_results()
if hasattr(x, "to_dict"):
x = x.to_dict()
return x["sim_results"] if isinstance(x.get("sim_results"), dict) else x
[docs]
def transmon_cross_capacitances(x) -> dict:
"""``cross_to_claw`` and ``cross_to_ground`` (fF) of a TransmonCross / Xmon prediction or row, the inputs of
``squadds.calcs.transmon_cross`` (EC, g). x: an MLSimulator result, a ``sim_results`` dict or a DataFrame row."""
sr = _sim_results_of(x)
missing = [k for k in ("cross_to_claw", "cross_to_ground") if sr.get(k) is None]
if missing:
raise KeyError(f"not a TransmonCross / Xmon result (missing {missing})")
return {"cross_to_claw": float(sr["cross_to_claw"]), "cross_to_ground": float(sr["cross_to_ground"])}
[docs]
def EC_MHz(x) -> float:
"""Charging energy (MHz) with the existing SQuADDS convention ``C_sum = cross_to_ground + cross_to_claw``
(``squadds.calcs.transmon_cross.EC_numba``). A second claw is not included: use ``EC_MHz_from_matrix`` for it."""
from squadds.calcs.transmon_cross import EC_numba
c = transmon_cross_capacitances(x)
return 1e3 * float(EC_numba(c["cross_to_claw"], c["cross_to_ground"]))
[docs]
def g_MHz(x, EJ_GHz: float, f_r_GHz: float, res_type: str = "quarter", Z0: float = 50.0) -> float:
"""Qubit-claw coupling g (MHz) from ``squadds.calcs.transmon_cross.g_from_cap_matrix_numba`` with the predicted
``cross_to_ground`` (C_Q) and ``cross_to_claw`` (C_g)."""
from squadds.calcs.transmon_cross import g_from_cap_matrix_numba
c = transmon_cross_capacitances(x)
return float(g_from_cap_matrix_numba(c["cross_to_ground"], c["cross_to_claw"], EJ_GHz, f_r_GHz, res_type, Z0))
[docs]
def EC_MHz_from_matrix(C, names, nodes) -> float:
"""Charging energy (MHz) of a qubit mode from a full Maxwell matrix (fF, every other conductor held at ground).
nodes: one conductor name (grounded transmon: C_sum = C_ii, every coupling included) or two (floating transmon, the
differential mode: 1 / C_eff = (C^-1)_aa + (C^-1)_bb - 2 (C^-1)_ab of the two-pad block)."""
from scipy.constants import Planck, e
C = np.asarray(C, float)
names = list(names)
nodes = [nodes] if isinstance(nodes, str) else list(nodes)
idx = [names.index(n) for n in nodes]
if len(idx) == 1:
c_eff = C[idx[0], idx[0]]
elif len(idx) == 2:
inv = np.linalg.inv(C[np.ix_(idx, idx)])
c_eff = 1.0 / (inv[0, 0] + inv[1, 1] - 2 * inv[0, 1])
else:
raise ValueError("nodes: one conductor (grounded) or two (floating pair)")
return e**2 / (2 * c_eff * 1e-15) / Planck * 1e-6