quantcore_circuits.analysis.results

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 (<sim>_project_results.json, <sim>_project_modes.eig, pyEPR QData_*.csv) and Palace’s postpro CSVs.

Functions

collect_results(job_dir) → dict

Parse whatever results exist in job_dir and write results/results.json.

combine_jobs(primary, others, out_dir[, same_design]) → pathlib.Path

A job directory that loop.analyse / circuit.fill read as one: the primary job's job.json

extrapolate_mesh(elements, values[, last]) → dict | None

f(N) = f∞ − C N^(−p) fitted to the last last adaptive passes (N = solved elements): the mesh-converged

fem_kappa(results, resonators[, max_residual]) → dict[str, dict]

External linewidth κ_ext/2π per resonator from a solved job.

fit_notch(f_GHz, s21[, min_depth, window]) → dict

Fit a notch (hanger) resonance to complex S21 (Khalil/Probst model, real-coupling approximation).

fit_notches(f_GHz, s21[, min_depth, window, max_notches]) → list[dict]

Every notch in a trace (several resonators on one feedline), lowest frequency first: dips of prominence

net_labels(job, n[, rows]) → list[str]

Labels for C-matrix rows (KQC excitations 1..n, or the AEDT signal nets rows such as ["Net1", "Net2"]

parse_cmatrix_json(path) → numpy.ndarray

parse_convergence(path) → dict

AEDT ExportConvergence text: passes, solved elements, the criterion per pass and whether it converged.

parse_eig(path) → list[dict]

HFSS ExportEigenmodes text. Tolerant: accepts idx f [Q] rows (GHz or Hz), (re, im) pairs and AEDT

parse_palace_eig(path) → list[dict]

Palace eig.csv: m, Re{f} (GHz), Im{f} (GHz), Q, ...

parse_palace_terminal_c(path) → numpy.ndarray

Palace terminal-C.csv: first column terminal index, then C[i][j] in F.

parse_report_csv(path) → dict[str, list[float]]

An AEDT report exported as CSV (e.g. KQC's eigenmode "Solution Convergence": Pass, re(Mode(n))).

parse_touchstone(path) → tuple[numpy.ndarray, numpy.ndarray, float]

Touchstone v1 .sNp (as KQC's export_solution_data.py writes <sim>_SMatrix.sNp).

read_extras(job_dir) → dict

<sim>_project_qcc.json written by qcc_solve.py inside AEDT ({} if absent); _file = its name.

signal_nets(extras) → list[str]

Q3D signal nets in GetExcitations order (KQC's export_solution_data.py C-matrix row order).

smatrix_ports(job, extras, n) → list[int]

Port numbers of the S-matrix columns: AEDT's excitation order ("2", "3" …) when recorded, else the

to_maxwell(c) → tuple[numpy.ndarray, str]

Return the Maxwell form of a capacitance matrix (positive diagonal, non-positive off-diagonal).

Module Contents

quantcore_circuits.analysis.results.collect_results(job_dir: str | pathlib.Path) → dict

Parse whatever results exist in job_dir and write results/results.json.

quantcore_circuits.analysis.results.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.

quantcore_circuits.analysis.results.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.

quantcore_circuits.analysis.results.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"}.

quantcore_circuits.analysis.results.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.

quantcore_circuits.analysis.results.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 fit_notch() on its own stretch of the band (between the midpoints to its neighbours).

quantcore_circuits.analysis.results.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<k> 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_<k>.

quantcore_circuits.analysis.results.parse_cmatrix_json(path: pathlib.Path) → numpy.ndarray
quantcore_circuits.analysis.results.parse_convergence(path: pathlib.Path) → dict

AEDT ExportConvergence text: passes, solved elements, the criterion per pass and whether it converged.

quantcore_circuits.analysis.results.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).

quantcore_circuits.analysis.results.parse_palace_eig(path: pathlib.Path) → list[dict]

Palace eig.csv: m, Re{f} (GHz), Im{f} (GHz), Q, …

quantcore_circuits.analysis.results.parse_palace_terminal_c(path: pathlib.Path) → numpy.ndarray

Palace terminal-C.csv: first column terminal index, then C[i][j] in F.

quantcore_circuits.analysis.results.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))).

quantcore_circuits.analysis.results.parse_touchstone(path: pathlib.Path) → tuple[numpy.ndarray, numpy.ndarray, float]

Touchstone v1 .sNp (as KQC’s export_solution_data.py writes <sim>_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 # <unit> S <MA|DB|RI> R <z0> option line and values wrapped over several lines.

quantcore_circuits.analysis.results.read_extras(job_dir: str | pathlib.Path) → dict

<sim>_project_qcc.json written by qcc_solve.py inside AEDT ({} if absent); _file = its name.

quantcore_circuits.analysis.results.signal_nets(extras: dict) → list[str]

Q3D signal nets in GetExcitations order (KQC’s export_solution_data.py C-matrix row order).

quantcore_circuits.analysis.results.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).

quantcore_circuits.analysis.results.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”).