quantcore_circuits.guiflow

The KLayout plugin’s Simulate / Results / Fab steps as library functions (the CLI and the plugin call these).

  • Subset (resolve_selection(), plan_subset_groups()): for a capacitance analysis (Q3D) the qubits among the components selected in KLayout (a selected readout route names its qubit), each with its couplers; the resonators are cut to a short stub port (quantcore_circuits.sim_tools.subset). For an eigenmode / driven analysis selection_group(): exactly what is selected (qubit, resonator, feedline, pads), plus the routes that join two selected parts and the pads at the ends of a selected line; junctions are lumped L‖C ports, lines leaving the box end in 50 Ω. Nothing selected: default takes the first qubit with a readout; whole the built-in chip group (slow).

  • Solver settings: solver_settings() (fast / accurate / custom), passed to the export; after a solve convergence_feedback() reads AEDT’s convergence table and proposes the next run’s passes / criterion (build/<name>/convergence.json, which the plugin’s Simulate dialog offers).

  • Automatic (run_auto(), qcc sim auto): subset → export → solve in a new non-graphical AEDT (never the user’s open one) → loop.analyse → the dashboard run state that the plugin’s Results tab reads. Progress goes to a small status file the plugin polls.

  • Manual (export_manual(), qcc sim subset): the job folder plus a README that says what to run and what to bring back; import_results() (qcc results import) reads a solved job folder or a results.json back.

  • Tune (propose(), apply_knobs(); qcc results propose / apply): loop.feedback as a preview of old → new knob values, and the design with those knobs set.

Attributes

Classes

Status

{"state": running|done|failed, "step", "n", "of", "message", ...} written atomically.

Functions

aedt_path_too_long(job_dir[, analysis]) → bool

AEDT fails with "Failed to copy local file ... The system cannot find the path specified" when the project's

analyse_jobs(design, jobs[, st, readout, source, say]) → dict

loop.analyse of the whole-chip circuit filled from jobs (subset jobs fill their own components, the rest

apply_knobs(design, proposal[, out]) → dict

The design with the proposal's knobs set (codesign.apply: moves the waypoints that follow a port too), as a

check_export(job_dir[, say, strict]) → dict

check_job() on an exported job: warnings become notes; errors

convergence_feedback(job_dir) → dict

What AEDT's adaptive meshing did in a solved job and what the next run should use: {"analysis", "converged", "passes", "last_delta", "target", "settings" (the job's), "next" (proposed settings, empty when it converged), "message"}. Not converged: one and a half times the passes (at least +4), and the criterion kept; converged in fewer passes than allowed: the settings stay. Never raises (a job without a convergence table says so).

export_manual(design[, names, default, whole, out, ...]) → list[pathlib.Path]

Write the job folder(s) of the subset (no solve): KQC export, AEDT scripts, job.json, README.md and

flow_record(design) → dict | None

What the last automatic run / import analysed (flow.json), plus whether the design changed since.

import_results(design, sources[, group, readout, say]) → dict

Read solved job folders / results files back: validate, then analyse_jobs().

jobs_root(design) → pathlib.Path

<design folder>/build/jobs.

junctions(design[, names]) → dict[str, dict]

The resolved junction of each component that has one (names: only those): the sidecar's

load_routes(design) → list[str]

missing_junctions(design[, names]) → dict[str, str]

{name: message}: the components among names (None: all) whose junction has no L_J for an eigenmode /

now() → str

pick_groups(design[, names, default, whole, name, ...]) → dict

Decide what to simulate and (write) store the sim groups in the design.json. Returns {"groups": [...], "whole": bool, "notes": [...], "describe": markdown}.

placement_junction(cell[, params, pdk]) → dict | None

The simulation / LOM junction a new cell gets when it is placed: {"Lj_nH", "Cj_fF", "source"}, or None

plan_subset_groups(design, qubits[, name, margin_um, ...])

(group names, {group: spec dict}, SubsetGroup plan) for qubits; the design file is not changed.

preview_groups(design[, names, default, whole, ...]) → dict

What an export of the same arguments renders, for drawing it in KLayout (qcc sim preview): per box its

propose(design[, jobs, out, say]) → dict

loop.analyse + loop.feedback: the next revision as a preview. jobs None: the last run's jobs

resolve_selection(design, names[, default]) → tuple[list[str], list[str]]

(qubits, notes) from names (instance and route names, e.g. what is selected in KLayout). A qubit stands for

results_template(design[, group, analysis, meta]) → dict

A results.json skeleton: the net names of the design's circuit, a zero matrix (see RESULTS_FORMAT).

run_auto(design[, names, default, whole, analysis, ...]) → dict

Subset → export → solve in a new AEDT → analyse. Returns {"groups", "jobs", "seconds", "rows", "run_dir"};

run_dir(design) → pathlib.Path

<design folder>/build/<name>: where the GUI flow keeps its run (the sidecar finds state.json there).

save_feedback(design, feedback) → pathlib.Path

build/<name>/convergence.json: the last solve's convergence and the proposed next settings, per analysis

save_results_copies(design, jobs[, say]) → list[pathlib.Path]

Keep what a solve returned under a name that says what it is: build/<name>/<name>_<group>_results.json (a

selection_group(design, names[, analysis, margin_um]) → tuple[dict, list[str]]

The sim group of exactly the selected components (names: instances and routes) for analysis: plus the

short_job_dir(design, group, analysis) → pathlib.Path

The job folder: <design folder>/build/jobs/<design>_<group>_<analysis>, or, when that path is too long for

solver_settings(analysis[, mode, custom]) → tuple[bool, dict]

(fast, settings) for the export: fast = FAST_SETTINGS

stage_import(design, source[, group]) → tuple[pathlib.Path, list[str], list[str]]

Make source (a solved job folder, its results/ folder or a results.json) an analysable job folder:

validate_results(design, results[, group]) → tuple[list[str], list[str]]

(errors, warnings) of a results dict against the design's circuit nets.

write_groups(design, specs[, prefix]) → bool

Put the sim groups specs into the design.json (only that key is touched) and drop the earlier prefix

Module Contents

class quantcore_circuits.guiflow.Status(path, steps: int = 4)

{"state": running|done|failed, "step", "n", "of", "message", ...} written atomically.

set(**kw) → None
step(n: int, name: str, message: str = '') → None
write() → None
data
path
quantcore_circuits.guiflow.aedt_path_too_long(job_dir, analysis: str = 'q3d_cmatrix') → bool

AEDT fails with “Failed to copy local file … The system cannot find the path specified” when the project’s *.aedtresults folders pass Windows’ 260-character limit; the job folder name is repeated in them.

quantcore_circuits.guiflow.analyse_jobs(design, jobs, st: Status | None = None, readout: bool = True, source: str = 'auto', say=print) → dict

loop.analyse of the whole-chip circuit filled from jobs (subset jobs fill their own components, the rest keeps the layout’s estimates), recorded in <design>/build/<name>/state.json and flow.json.

quantcore_circuits.guiflow.apply_knobs(design, proposal: dict, out=None) → dict

The design with the proposal’s knobs set (codesign.apply: moves the waypoints that follow a port too), as a design.json dict. Raises when a knob no longer has the value the proposal started from.

quantcore_circuits.guiflow.check_export(job_dir, say=print, strict: bool = True) → dict

check_job() on an exported job: warnings become notes; errors (what AEDT would reject or solve wrongly) raise RuntimeError (strict) or are printed as warnings.

quantcore_circuits.guiflow.convergence_feedback(job_dir) → dict

What AEDT’s adaptive meshing did in a solved job and what the next run should use: {"analysis", "converged", "passes", "last_delta", "target", "settings" (the job's), "next" (proposed settings, empty when it converged), "message"}. Not converged: one and a half times the passes (at least +4), and the criterion kept; converged in fewer passes than allowed: the settings stay. Never raises (a job without a convergence table says so).

quantcore_circuits.guiflow.export_manual(design, names=None, default: bool = False, whole: bool = False, out=None, analysis: str = 'q3d_cmatrix', name: str = 'gui_sim', margin_um: float = 300.0, fast: bool = True, write_group: bool = True, say=print, settings: dict | None = None, group: str | None = None) → list[pathlib.Path]

Write the job folder(s) of the subset (no solve): KQC export, AEDT scripts, job.json, README.md and results_template.json. out: the folder for one box, or the parent of several. group: a saved sim_groups entry, exported as it is (nothing is written to the design). Returns the job folders.

quantcore_circuits.guiflow.flow_record(design) → dict | None

What the last automatic run / import analysed (flow.json), plus whether the design changed since.

quantcore_circuits.guiflow.import_results(design, sources, group: str | None = None, readout: bool = True, say=print) → dict

Read solved job folders / results files back: validate, then analyse_jobs().

quantcore_circuits.guiflow.jobs_root(design) → pathlib.Path

<design folder>/build/jobs.

quantcore_circuits.guiflow.junctions(design, names=None) → dict[str, dict]

The resolved junction of each component that has one (names: only those): the sidecar’s instances.<name>.junction — {"kind", "Lj0_nH", "Cj_fF", "flux_phi0", "asym", "Lj_eff_nH", "source"} (the LOM’s values, which the eigenmode / driven exports put on the lumped sheet).

quantcore_circuits.guiflow.load_routes(design) → list[str]
quantcore_circuits.guiflow.missing_junctions(design, names=None) → dict[str, str]

{name: message}: the components among names (None: all) whose junction has no L_J for an eigenmode / driven run (no design value and no drawn trilayer junction, or a symmetric SQUID at Φ = ½); the message says where to set it (the plugin’s pre-check; qcc design junctions).

quantcore_circuits.guiflow.now() → str
quantcore_circuits.guiflow.pick_groups(design, names=None, default: bool = False, whole: bool = False, name: str = 'gui_sim', margin_um: float = 300.0, analysis: str = 'q3d_cmatrix', write: bool = True) → dict

Decide what to simulate and (write) store the sim groups in the design.json. Returns {"groups": [...], "whole": bool, "notes": [...], "describe": markdown}.

quantcore_circuits.guiflow.placement_junction(cell: str, params: dict | None = None, pdk=None) → dict | None

The simulation / LOM junction a new cell gets when it is placed: {"Lj_nH", "Cj_fF", "source"}, or None for a component without a junction, plus drawn: the trilayer junction the cell draws (same keys), or None. A drawn trilayer junction gives its PDK-rule value (also a KQC cell left at its default junction: the build draws it as the PDK trilayer); a chosen non-trilayer type (KQC Manhattan, Sim, …) has no PDK value, so it gets the PDK nominal SQUID ("Quantcore Squid"). The plugin writes it into design.json at placement (the value is a simulation value, fixed per component).

quantcore_circuits.guiflow.plan_subset_groups(design, qubits, name: str = 'gui_sim', margin_um: float = 300.0, analysis: str = 'q3d_cmatrix', split: str = 'auto')

(group names, {group: spec dict}, SubsetGroup plan) for qubits; the design file is not changed.

quantcore_circuits.guiflow.preview_groups(design, names=None, default: bool = False, whole: bool = False, analysis: str = 'q3d_cmatrix', margin_um: float = 300.0, name: str = 'gui_sim', group: str | None = None) → dict

What an export of the same arguments renders, for drawing it in KLayout (qcc sim preview): per box its rectangle, the components and routes in it, and every port (50 Ω edge ports, cut stubs, junction ports) with its position. It runs build_simulation() exactly as export_manual() does (same group, same box, same ports; export_job then writes them as files), and writes nothing.

group previews a saved sim_groups entry as it is (analysis None: its first analysis). Otherwise the group comes from names / default / whole and analysis like in export_manual().

quantcore_circuits.guiflow.propose(design, jobs=None, out=None, say=print) → dict

loop.analyse + loop.feedback: the next revision as a preview. jobs None: the last run’s jobs (flow.json), else the layout’s estimates. Returns {"tunable", "message", "knobs": [{knob, old, new}], "moved": [...], "predicted": {...}, "objective", "revision", "basis", "notes": [...]}; out also gets it as JSON. Every qubit with a LOM model and a λ/4 or λ/2 readout pair is tuned; notes say what is not and why. The revision is written but not built (Apply rebuilds).

quantcore_circuits.guiflow.resolve_selection(design, names, default: bool = False) → tuple[list[str], list[str]]

(qubits, notes) from names (instance and route names, e.g. what is selected in KLayout). A qubit stands for itself, a readout route for its qubit; pads, couplers and other lines come in with their qubit and are ignored. default: with no qubit in names, the first qubit that has a readout resonator.

quantcore_circuits.guiflow.results_template(design, group: str = 'chip', analysis: str = 'q3d_cmatrix', meta: dict | None = None) → dict

A results.json skeleton: the net names of the design’s circuit, a zero matrix (see RESULTS_FORMAT).

quantcore_circuits.guiflow.run_auto(design, names=None, default: bool = False, whole: bool = False, analysis: str = 'q3d_cmatrix', name: str = 'gui_sim', margin_um: float = 300.0, aedt: str | None = 'batch', fast: bool = True, timeout: float = 3600.0, status=None, progress: float = 10.0, readout: bool = True, say=print, settings: dict | None = None) → dict

Subset → export → solve in a new AEDT → analyse. Returns {"groups", "jobs", "seconds", "rows", "run_dir"}; raises on a failed step (the status file then says which).

quantcore_circuits.guiflow.run_dir(design) → pathlib.Path

<design folder>/build/<name>: where the GUI flow keeps its run (the sidecar finds state.json there).

quantcore_circuits.guiflow.save_feedback(design, feedback: dict) → pathlib.Path

build/<name>/convergence.json: the last solve’s convergence and the proposed next settings, per analysis (the plugin’s Simulate dialog shows it and can use the proposal).

quantcore_circuits.guiflow.save_results_copies(design, jobs, say=print) → list[pathlib.Path]

Keep what a solve returned under a name that says what it is: build/<name>/<name>_<group>_results.json (a copy of the job’s results/results.json; the plugin’s Simulate > Open results file… reads it back).

quantcore_circuits.guiflow.selection_group(design, names, analysis: str = 'hfss_eigenmode', margin_um: float = 300.0) → tuple[dict, list[str]]

The sim group of exactly the selected components (names: instances and routes) for analysis: plus the routes that join two selected parts (a hanger from a selected qubit onto a selected line counts) and the instances at the ends of a selected route (a feedline’s bond pads). Returns (spec, notes).

quantcore_circuits.guiflow.short_job_dir(design, group: str, analysis: str) → pathlib.Path

The job folder: <design folder>/build/jobs/<design>_<group>_<analysis>, or, when that path is too long for AEDT, a short one under the temp folder (qcc_jobs/<design>_<group>_<analysis>).

quantcore_circuits.guiflow.solver_settings(analysis: str, mode: str = 'fast', custom: dict | None = None) → tuple[bool, dict]

(fast, settings) for the export: fast = FAST_SETTINGS (minutes, not converged), accurate = the analysis defaults (DEFAULT_SETTINGS), custom = the defaults with custom on top (e.g. what convergence_feedback() proposed, or the plugin’s Settings).

quantcore_circuits.guiflow.stage_import(design, source, group: str | None = None) → tuple[pathlib.Path, list[str], list[str]]

Make source (a solved job folder, its results/ folder or a results.json) an analysable job folder: (job dir, errors, warnings). A folder without results/results.json is collected from its raw AEDT outputs; a loose results file is copied into <design folder>/build/jobs/<design>_imported_<stem>/.

quantcore_circuits.guiflow.validate_results(design, results: dict, group: str | None = None) → tuple[list[str], list[str]]

(errors, warnings) of a results dict against the design’s circuit nets.

quantcore_circuits.guiflow.write_groups(design, specs: dict, prefix: str = 'gui_sim') → bool

Put the sim groups specs into the design.json (only that key is touched) and drop the earlier prefix groups that are not in specs. Returns whether the file changed.

quantcore_circuits.guiflow.AEDT_PATH_LIMIT = 250
quantcore_circuits.guiflow.README = Multiline-String
Show Value
"""# Simulation job: {design} / {group} ({analysis})

Made by Quantcore (`qcc sim subset`) on {when}. The design is `{design}`, the box simulates: {select}.
Settings: {settings}.

## Solve it

**On this machine, in AEDT {aedt}:**

1. Double-click `simulation.bat` (Windows) or run `bash simulation.sh`. It starts a new non-graphical AEDT, solves
   the job and writes `results/results.json`. (Or: `qcc hfss solve "{job}"`.)
2. By hand: open AEDT, *Tools > Run Script...* and run `scripts/qcc_solve.py` with the argument
   `{sim}.json` (the script is in the `scripts` folder; it imports the geometry, adds the ports, solves and
   exports the results next to it). `scripts/qcc_render.py` does the same without solving: it saves the project so
   you can look at the mesh and ports first.

**A finer solve:** open `{sim}_project.aedt` in AEDT, change the setup (passes, convergence, mesh), solve, then run
`scripts/qcc_collect.py` there (*Tools > Run Script...*, no arguments): it exports what you solved (results and the
convergence table) into this folder without solving again or saving. Or close the project and run
`qcc hfss collect "{job}"`. Then import the folder (below).

**On another machine:** copy this whole folder over, run `scripts/qcc_solve.py` in AEDT as above (AEDT 2024 R1 or newer;
quantcore-circuits is only needed for `simulation.bat`'s last line, the results collection), and bring the folder back.

## Bring back

The whole job folder (you can leave out the `*.aedtresults` folders, they are large), or at least:

- `results/results.json` (written by `simulation.bat` / `qcc results collect`), or
- `{sim}_project_results.json`, `{sim}_project_qcc.json` and the `.eig` / `.sNp` files AEDT exported (then Quantcore
  collects the results itself).

Then in KLayout: *Quantcore > Simulate > Import results...* and pick the folder or the `results.json`, or on the
command line: `qcc results import "{design_path}" "<folder or results.json>"`.

## Your own results script

Any extraction that writes this JSON works (see `results_template.json` here for the net names of this job):

```
{fmt}
```
"""
quantcore_circuits.guiflow.RESULTS_FORMAT = Multiline-String
Show Value
"""results/results.json  (what `qcc results import` reads; every key except "analysis" is optional)

{
  "analysis": "q3d_cmatrix",              # q3d_cmatrix | hfss_eigenmode | eigenmode_epr | hfss_driven | ...
  "group": "gui_sim",                     # the sim group the job simulated (default: the job.json's, else "chip")
  "cmatrix": {                            # capacitance matrix, MAXWELL form, one row / column per metal net
    "labels": ["Q1.island", "Q1.claw_n", "FL"],   # net names: <instance>.island, <instance>.<port>, or a route name
    "unit": "fF",
    "matrix": [[ 85.2, -4.1, -1.2],       # positive diagonal, non-positive off-diagonal; ground = the rest
               [ -4.1, 22.0, -0.3],
               [ -1.2, -0.3, 310.0]]
  },
  "eigenmodes": [                         # linear modes of an eigenmode run (GHz; Q optional)
    {"mode": 1, "f_GHz": 5.31, "Q": 1.2e6},
    {"mode": 2, "f_GHz": 7.04, "Q": 4.0e4}
  ]
}

The labels must be the net names of the design's circuit (`qcc results template DESIGN` writes them, with a zero
matrix, as a starting point). Row / column order is yours. Matrices in "mutual" form (positive off-diagonals) are
converted. A whole solved job folder works too: `qcc results import DESIGN JOB_FOLDER` (it collects the raw AEDT
outputs itself when results/results.json is missing).
"""
quantcore_circuits.guiflow.SOLVER_MODES = ('fast', 'accurate', 'custom')