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 analysisselection_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:defaulttakes the first qubit with a readout;wholethe built-inchipgroup (slow).Solver settings:
solver_settings()(fast / accurate / custom), passed to the export; after a solveconvergence_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 aresults.jsonback.Tune (
propose(),apply_knobs();qcc results propose/apply):loop.feedbackas a preview of old → new knob values, and the design with those knobs set.
Attributes¶
Classes¶
|
Functions¶
|
AEDT fails with "Failed to copy local file ... The system cannot find the path specified" when the project's |
|
|
|
The design with the proposal's knobs set ( |
|
|
|
What AEDT's adaptive meshing did in a solved job and what the next run should use: |
|
Write the job folder(s) of the subset (no solve): KQC export, AEDT scripts, |
|
What the last automatic run / import analysed ( |
|
Read solved job folders / results files back: validate, then |
|
|
|
The resolved junction of each component that has one ( |
|
|
|
|
|
|
|
Decide what to simulate and ( |
|
The simulation / LOM junction a new |
|
|
|
What an export of the same arguments renders, for drawing it in KLayout ( |
|
|
|
|
|
A |
|
Subset → export → solve in a new AEDT → analyse. Returns |
|
|
|
|
|
Keep what a solve returned under a name that says what it is: |
|
The sim group of exactly the selected components ( |
|
The job folder: |
|
|
|
Make |
|
|
|
Put the sim groups |
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
*.aedtresultsfolders 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.analyseof the whole-chip circuit filled fromjobs(subset jobs fill their own components, the rest keeps the layout’s estimates), recorded in<design>/build/<name>/state.jsonandflow.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) raiseRuntimeError(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.mdandresults_template.json.out: the folder for one box, or the parent of several.group: a savedsim_groupsentry, 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’sinstances.<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 amongnames(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
cellgets when it is placed:{"Lj_nH", "Cj_fF", "source"}, or None for a component without a junction, plusdrawn: 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 intodesign.jsonat 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)forqubits; 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 runsbuild_simulation()exactly asexport_manual()does (same group, same box, same ports;export_jobthen writes them as files), and writes nothing.grouppreviews a savedsim_groupsentry as it is (analysisNone: its first analysis). Otherwise the group comes fromnames/default/wholeandanalysislike inexport_manual().
- quantcore_circuits.guiflow.propose(design, jobs=None, out=None, say=print) dict¶
loop.analyse+loop.feedback: the next revision as a preview.jobsNone: 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": [...]};outalso gets it as JSON. Every qubit with a LOM model and a λ/4 or λ/2 readout pair is tuned;notessay 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)fromnames(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 innames, 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.jsonskeleton: the net names of the design’s circuit, a zero matrix (seeRESULTS_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 (thestatusfile then says which).
- quantcore_circuits.guiflow.run_dir(design) pathlib.Path¶
<design folder>/build/<name>: where the GUI flow keeps its run (the sidecar findsstate.jsonthere).
- 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’sresults/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) foranalysis: 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 withcustomon top (e.g. whatconvergence_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 withoutresults/results.jsonis 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
specsinto the design.json (only that key is touched) and drop the earlierprefixgroups that are not inspecs. 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')¶