quantcore_circuits.analysis.results =================================== .. py:module:: quantcore_circuits.analysis.results .. autoapi-nested-parse:: Solver outputs → one result schema (``job/results/results.json``). Schema (all optional except ``analysis``):: {"analysis": "q3d_cmatrix", "design_hash": ..., "group": ..., "cmatrix": {"labels": [...], "unit": "fF", "matrix": [[...]]}, # Maxwell matrix, signal nets only "eigenmodes": [{"f_GHz": 5.1, "Q": 1e6}, ...], "epr": {...}, "raw_files": [...]} Parsers read KQC's job outputs (``_project_results.json``, ``_project_modes.eig``, pyEPR ``QData_*.csv``) and Palace's ``postpro`` CSVs. Functions --------- .. autoapisummary:: quantcore_circuits.analysis.results.collect_results quantcore_circuits.analysis.results.combine_jobs quantcore_circuits.analysis.results.extrapolate_mesh quantcore_circuits.analysis.results.fem_kappa quantcore_circuits.analysis.results.fit_notch quantcore_circuits.analysis.results.fit_notches quantcore_circuits.analysis.results.net_labels quantcore_circuits.analysis.results.parse_cmatrix_json quantcore_circuits.analysis.results.parse_convergence quantcore_circuits.analysis.results.parse_eig quantcore_circuits.analysis.results.parse_palace_eig quantcore_circuits.analysis.results.parse_palace_terminal_c quantcore_circuits.analysis.results.parse_report_csv quantcore_circuits.analysis.results.parse_touchstone quantcore_circuits.analysis.results.read_extras quantcore_circuits.analysis.results.signal_nets quantcore_circuits.analysis.results.smatrix_ports quantcore_circuits.analysis.results.to_maxwell Module Contents --------------- .. py:function:: collect_results(job_dir: str | pathlib.Path) -> dict Parse whatever results exist in ``job_dir`` and write ``results/results.json``. .. py:function:: combine_jobs(primary: str | pathlib.Path, others: list[str | pathlib.Path], out_dir: str | pathlib.Path, same_design: bool = True) -> pathlib.Path A job directory that ``loop.analyse`` / ``circuit.fill`` read as one: the ``primary`` job's ``job.json`` (C-matrix metadata: ports, stub length, stack) with its results, plus the ``eigenmodes`` / ``epr`` / ``sparams`` of the ``others``. E.g. Q3D C-matrix → LOM estimators and eigenmode EPR → pyEPR in one consensus. ``results.json`` records where each part came from (``combined_from``). The others must come from the same design (hash) unless ``same_design=False`` (e.g. a copy that only adds a sim group); mismatches are then listed. .. py:function:: extrapolate_mesh(elements, values, last: int = 5) -> dict | None f(N) = f∞ − C N^(−p) fitted to the last ``last`` adaptive passes (N = solved elements): the mesh-converged estimate of a quantity whose adaptive run stopped before its criterion. None if the fit is not meaningful. .. py:function:: fem_kappa(results: dict, resonators: dict[str, float], max_residual: float = 0.05) -> dict[str, dict] External linewidth κ_ext/2π per resonator from a solved job. Driven jobs: the S_ij notch fit whose f0 is closest to the resonator's expected frequency (``resonators``: name → GHz, e.g. its λ/4 estimate). Eigenmode jobs (feedline terminated in 50 Ω): f/Q_ext of the nearest mode that is not a qubit mode (junction participation < 0.5), with the bulk-dielectric loss removed when the EPR substrate participation is known. Returns name → ``{"kappa_MHz", "f_GHz", "Q_ext", "source"}``. .. py:function:: fit_notch(f_GHz, s21, min_depth: float = 0.001, window: float = 25.0) -> dict Fit a notch (hanger) resonance to complex S21 (Khalil/Probst model, real-coupling approximation). S21 = A e^{iα} [1 − (Q_l/Q_c) e^{iφ} / (1 + 2i Q_l (f/f0 − 1))]. Returns f0, Q_l, Q_c, Q_i and the linewidths κ = f0/Q_l, κ_ext = f0/Q_c (MHz) — κ_ext is what the LOM hanger coupling (``HANGER`` k) predicts. A cable delay is not removed: export S-parameters de-embedded to the ports (KQC does by default). Raises ``ValueError`` when the \|S21\| dip is shallower than ``min_depth`` (no resonance in the band); fits ±``window`` linewidths around the dip when the band is wider. .. py:function:: fit_notches(f_GHz, s21, min_depth: float = 0.01, window: float = 25.0, max_notches: int = 8) -> list[dict] Every notch in a trace (several resonators on one feedline), lowest frequency first: dips of prominence ≥ ``min_depth`` (relative to the baseline), each fitted with :func:`fit_notch` on its own stretch of the band (between the midpoints to its neighbours). .. py:function:: net_labels(job: dict, n: int, rows: list[str] | None = None) -> list[str] Labels for C-matrix rows (KQC excitations 1..n, or the AEDT signal nets ``rows`` such as ``["Net1", "Net2"]`` in matrix order, as recorded by ``qcc_solve.py``; AEDT net ``Net`` is KQC excitation k). Jobs record ``nets`` (excitation → label, probed from KQC's conductor partition at export); older jobs fall back to excitation k ↔ port k. Unlabelled conductors are ``floating_``. .. py:function:: parse_cmatrix_json(path: pathlib.Path) -> numpy.ndarray .. py:function:: parse_convergence(path: pathlib.Path) -> dict AEDT ``ExportConvergence`` text: passes, solved elements, the criterion per pass and whether it converged. .. py:function:: parse_eig(path: pathlib.Path) -> list[dict] HFSS ``ExportEigenmodes`` text. Tolerant: accepts ``idx f [Q]`` rows (GHz or Hz), ``(re, im)`` pairs and AEDT 2024's ``idx f_re + f_im j Q`` rows (``Q`` = f_re / 2 f_im when the column is missing). .. py:function:: parse_palace_eig(path: pathlib.Path) -> list[dict] Palace ``eig.csv``: m, Re{f} (GHz), Im{f} (GHz), Q, ... .. py:function:: parse_palace_terminal_c(path: pathlib.Path) -> numpy.ndarray Palace ``terminal-C.csv``: first column terminal index, then C[i][j] in F. .. py:function:: parse_report_csv(path: pathlib.Path) -> dict[str, list[float]] An AEDT report exported as CSV (e.g. KQC's eigenmode "Solution Convergence": Pass, re(Mode(n))). .. py:function:: parse_touchstone(path: pathlib.Path) -> tuple[numpy.ndarray, numpy.ndarray, float] Touchstone v1 ``.sNp`` (as KQC's ``export_solution_data.py`` writes ``_SMatrix.sNp``). Returns ``(f_GHz, S, z0)`` with ``S[k, i, j]`` complex (S_ij at frequency k, ports 1-based in the file, 0-based here). Handles the ``# S R `` option line and values wrapped over several lines. .. py:function:: read_extras(job_dir: str | pathlib.Path) -> dict ``_project_qcc.json`` written by ``qcc_solve.py`` inside AEDT ({} if absent); ``_file`` = its name. .. py:function:: signal_nets(extras: dict) -> list[str] Q3D signal nets in ``GetExcitations`` order (KQC's ``export_solution_data.py`` C-matrix row order). .. py:function:: smatrix_ports(job: dict, extras: dict, n: int) -> list[int] Port numbers of the S-matrix columns: AEDT's excitation order (``"2"``, ``"3"`` …) when recorded, else the job's non-junction ports (``qcc_solve.py`` turns driven junction ports into lumped L/C). .. py:function:: to_maxwell(c) -> tuple[numpy.ndarray, str] Return the Maxwell form of a capacitance matrix (positive diagonal, non-positive off-diagonal). AEDT Q3D results exported by KQC's scripts carry the mutual capacitances as *positive* off-diagonal entries (diagonal = total capacitance of the net, as in the Maxwell matrix); Palace and Elmer write the Maxwell matrix. Both are accepted; the returned tag says which convention was found ("maxwell" or "mutual").