quantcore_circuits.guiflow ========================== .. py:module:: quantcore_circuits.guiflow .. autoapi-nested-parse:: The KLayout plugin's Simulate / Results / Fab steps as library functions (the CLI and the plugin call these). * **Subset** (:func:`resolve_selection`, :func:`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 (:mod:`quantcore_circuits.sim_tools.subset`). For an eigenmode / driven analysis :func:`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**: :func:`solver_settings` (fast / accurate / custom), passed to the export; after a solve :func:`convergence_feedback` reads AEDT's convergence table and proposes the next run's passes / criterion (``build//convergence.json``, which the plugin's Simulate dialog offers). * **Automatic** (:func:`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** (:func:`export_manual`, ``qcc sim subset``): the job folder plus a README that says what to run and what to bring back; :func:`import_results` (``qcc results import``) reads a solved job folder or a ``results.json`` back. * **Tune** (:func:`propose`, :func:`apply_knobs`; ``qcc results propose`` / ``apply``): ``loop.feedback`` as a preview of old → new knob values, and the design with those knobs set. Attributes ---------- .. autoapisummary:: quantcore_circuits.guiflow.AEDT_PATH_LIMIT quantcore_circuits.guiflow.README quantcore_circuits.guiflow.RESULTS_FORMAT quantcore_circuits.guiflow.SOLVER_MODES Classes ------- .. autoapisummary:: quantcore_circuits.guiflow.Status Functions --------- .. autoapisummary:: quantcore_circuits.guiflow.aedt_path_too_long quantcore_circuits.guiflow.analyse_jobs quantcore_circuits.guiflow.apply_knobs quantcore_circuits.guiflow.check_export quantcore_circuits.guiflow.convergence_feedback quantcore_circuits.guiflow.export_manual quantcore_circuits.guiflow.flow_record quantcore_circuits.guiflow.import_results quantcore_circuits.guiflow.jobs_root quantcore_circuits.guiflow.junctions quantcore_circuits.guiflow.load_routes quantcore_circuits.guiflow.missing_junctions quantcore_circuits.guiflow.now quantcore_circuits.guiflow.pick_groups quantcore_circuits.guiflow.placement_junction quantcore_circuits.guiflow.plan_subset_groups quantcore_circuits.guiflow.preview_groups quantcore_circuits.guiflow.propose quantcore_circuits.guiflow.resolve_selection quantcore_circuits.guiflow.results_template quantcore_circuits.guiflow.run_auto quantcore_circuits.guiflow.run_dir quantcore_circuits.guiflow.save_feedback quantcore_circuits.guiflow.save_results_copies quantcore_circuits.guiflow.selection_group quantcore_circuits.guiflow.short_job_dir quantcore_circuits.guiflow.solver_settings quantcore_circuits.guiflow.stage_import quantcore_circuits.guiflow.validate_results quantcore_circuits.guiflow.write_groups Module Contents --------------- .. py:class:: Status(path, steps: int = 4) ``{"state": running|done|failed, "step", "n", "of", "message", ...}`` written atomically. .. py:method:: set(**kw) -> None .. py:method:: step(n: int, name: str, message: str = '') -> None .. py:method:: write() -> None .. py:attribute:: data .. py:attribute:: path .. py:function:: 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. .. py:function:: 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 ``/build//state.json`` and ``flow.json``. .. py:function:: 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. .. py:function:: check_export(job_dir, say=print, strict: bool = True) -> dict :func:`~quantcore_circuits.sim_tools.geometry_check.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. .. py:function:: 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). .. py:function:: 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. .. py:function:: flow_record(design) -> dict | None What the last automatic run / import analysed (``flow.json``), plus whether the design changed since. .. py:function:: import_results(design, sources, group: str | None = None, readout: bool = True, say=print) -> dict Read solved job folders / results files back: validate, then :func:`analyse_jobs`. .. py:function:: jobs_root(design) -> pathlib.Path ``/build/jobs``. .. py:function:: junctions(design, names=None) -> dict[str, dict] The resolved junction of each component that has one (``names``: only those): the sidecar's ``instances..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). .. py:function:: load_routes(design) -> list[str] .. py:function:: 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``). .. py:function:: now() -> str .. py:function:: 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}``. .. py:function:: 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). .. py:function:: 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. .. py:function:: 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 :func:`~quantcore_circuits.sim_tools.build_simulation` exactly as :func:`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 :func:`export_manual`. .. py:function:: 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). .. py:function:: 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. .. py:function:: 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 :data:`RESULTS_FORMAT`). .. py:function:: 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). .. py:function:: run_dir(design) -> pathlib.Path ``/build/``: where the GUI flow keeps its run (the sidecar finds ``state.json`` there). .. py:function:: save_feedback(design, feedback: dict) -> pathlib.Path ``build//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). .. py:function:: save_results_copies(design, jobs, say=print) -> list[pathlib.Path] Keep what a solve returned under a name that says what it is: ``build//__results.json`` (a copy of the job's ``results/results.json``; the plugin's Simulate > Open results file… reads it back). .. py:function:: 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)``. .. py:function:: short_job_dir(design, group: str, analysis: str) -> pathlib.Path The job folder: ``/build/jobs/__``, or, when that path is too long for AEDT, a short one under the temp folder (``qcc_jobs/__``). .. py:function:: solver_settings(analysis: str, mode: str = 'fast', custom: dict | None = None) -> tuple[bool, dict] ``(fast, settings)`` for the export: ``fast`` = :data:`~quantcore_circuits.sim_tools.export.FAST_SETTINGS` (minutes, not converged), ``accurate`` = the analysis defaults (``DEFAULT_SETTINGS``), ``custom`` = the defaults with ``custom`` on top (e.g. what :func:`convergence_feedback` proposed, or the plugin's Settings). .. py:function:: 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 ``/build/jobs/_imported_/``. .. py:function:: 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. .. py:function:: 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. .. py:data:: AEDT_PATH_LIMIT :value: 250 .. py:data:: README :value: Multiline-String .. raw:: html
Show Value .. code-block:: python """# 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}" ""`. ## Your own results script Any extraction that writes this JSON works (see `results_template.json` here for the net names of this job): ``` {fmt} ``` """ .. raw:: html
.. py:data:: RESULTS_FORMAT :value: Multiline-String .. raw:: html
Show Value .. code-block:: python """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: .island, ., 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). """ .. raw:: html
.. py:data:: SOLVER_MODES :value: ('fast', 'accurate', 'custom')