qcc command line

Quantcore circuits: design.json → KQC layout → simulation → parameters → feedback.

Usage:

$ qcc [OPTIONS] COMMAND [ARGS]...

Options:

  • --version: Show version.

  • --install-completion: Install completion for the current shell.

  • --show-completion: Show completion for the current shell, to copy it or customize the installation.

  • --help: Show this message and exit.

Commands:

  • build: Build DESIGN (.json/.py) into a KQC chip…

  • watch: Rebuild on every save and reload KLayout…

  • components: List available components (Quantcore, KQC,…

  • synth: LOM-first synthesis: targets → Lj, C_Σ,…

  • mask: Fab export with the PDK fab rules: layers…

  • review: Open the live dashboard for DESIGN: steps,…

  • dashboard: Live dashboard that follows the notebooks’…

  • analyse: Job results → circuit.json → Metal LOM /…

  • sim: Simulation jobs (HFSS/Q3D, Elmer, Palace).

  • results: Parse, extract and store results.

  • runner: Job runner / filesystem queue (lab server).

  • design: design.json utilities.

  • hfss: Ansys HFSS / Q3D projects (AEDT 2024 R1/R2).

  • circuit: Lumped circuit (LOM): layout →…

qcc build

Build DESIGN (.json/.py) into a KQC chip and write it.

Usage:

$ qcc build [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -o <path>: Output .oas/.gds (default build/<name>.oas)

  • --show / --no-show: Send to KLayout via klive [default: no-show]

  • --keep-going: A route that cannot be built is left out (named in the sidecar’s failed_routes, its last good route kept in <name>.last_good_routes.json) instead of failing the build. The default is strict.

  • --help: Show this message and exit.

qcc watch

Rebuild on every save and reload KLayout (klive).

Usage:

$ qcc watch [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -o <path>

  • --klive / --no-klive: Use klive [default: klive]

  • --extra <path>: More files to watch (e.g. imported modules)

  • --help: Show this message and exit.

qcc components

List available components (Quantcore, KQC, Quantum Metal) by category, or the ports of one.

Usage:

$ qcc components [OPTIONS] [cell]

Arguments:

  • cell: Show ports of this cell (name, dotted path or metal:<Class>)

Options:

  • -c, --category <str>: Only this category (qubit, coupler, launcher, …)

  • -s, --source <str>: Only this source: quantcore, kqc or metal

  • --json: Machine-readable: refs (or ports with CELL)

  • --details: With –json: full catalog records instead of refs

  • --all: Include whole KQC chips and Metal routes (not cells)

  • --outline: With CELL –json: also its bbox and a simplified outline (the KLayout placement ghost)

  • --params <str>: With CELL: PCell parameters as JSON [default: {}]

  • --schema: With CELL: its editable parameters and defaults (JSON)

  • --schemas: Every listed cell’s editable parameters in one JSON (the KLayout PCell library)

  • --oas <path>: With CELL: write its geometry (a static cell) to this OASIS file

  • --design <path>: With CELL –oas: build it as in this design (chip-inherited parameters, PDK junction)

  • --help: Show this message and exit.

qcc synth

LOM-first synthesis: targets → Lj, C_Σ, Cg, λ/4 length.

Usage:

$ qcc synth [OPTIONS]

Options:

  • --f-q <float>: Qubit f01 [GHz] [required]

  • --alpha <float>: α [MHz] [required]

  • --f-r <float>: Resonator [GHz] [required]

  • --g <float>: g [MHz] [required]

  • --a <float>: [default: 10.0]

  • --b <float>: [default: 6.0]

  • --help: Show this message and exit.

qcc mask

Fab export with the PDK fab rules: layers 1/0–4/0, 50–53/0, 100/0, 300/301, 700, 800+, 1000/0+; –positive M1 inverts a layer. Corner rounding is on by default; the cheese is the build’s own (the PDK band unless the design has its own cheese, which wins). Simulation exports never get either.

Usage:

$ qcc mask [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -o <path>

  • --positive <str>

  • --cheese / --no-cheese: Cheese: the build’s (PDK band or the original design’s own); –no-cheese writes none [default: cheese]

  • --round / --no-round: PDK corner rounding (r ∝ shortest dim.) [default: round]

  • --grid / --no-grid: KQC’s whole-area ground grid (with_grid) instead of the PDK band [default: no-grid]

  • --help: Show this message and exit.

qcc review

Open the live dashboard for DESIGN: steps, goal, plots, circuit, Hamiltonian, jobs, screenshots.

Usage:

$ qcc review [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • --port <int>: [default: 8765]

  • --open-browser / --no-open-browser: [default: open-browser]

  • --run-dir <path>: Run directory (default build/<design name>)

  • --help: Show this message and exit.

qcc dashboard

Live dashboard that follows the notebooks’ tracked runs (track.start(...) / QCC_TRACK=1).

Usage:

$ qcc dashboard [OPTIONS] [run]

Arguments:

  • run: Run name (build/<run>); default: follow the run with the latest activity

Options:

  • --port <int>: [default: 8765]

  • --open-browser / --no-open-browser: [default: open-browser]

  • --root <path>: Folder with the run directories (default: <repo>/build)

  • --help: Show this message and exit.

qcc analyse

Job results → circuit.json → Metal LOM / QuCat / SQcircuit / scqubits / QuTiP → consensus vs targets.

Usage:

$ qcc analyse [OPTIONS] {design} {job}

Arguments:

  • design: [required]

  • job: [required]

Options:

  • -g, --group <str>: Sim group (default: the job’s)

  • --run-dir <path>: Dashboard run directory (default build/<design name>)

  • --readout / --no-readout: Simulate the readout (χ from transmission) with QuTiP [default: readout]

  • --feedback: Also propose the next design revision (surrogate)

  • --help: Show this message and exit.

qcc sim

Simulation jobs (HFSS/Q3D, Elmer, Palace).

Usage:

$ qcc sim [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • build: Create a simulation job directory for a…

  • subset: Export the job folder of a subset (no…

  • preview: Print as JSON what qcc sim subset would…

  • auto: Automatic simulation: subset -> export ->…

  • run: Run a job locally (AEDT / Elmer / Palace)…

  • submit

qcc sim build

Create a simulation job directory for a sim group.

Usage:

$ qcc sim build [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -g, --group <str>: [required]

  • -a, --analysis <str>: q3d_cmatrix | hfss_eigenmode | eigenmode_epr | elmer_cap | palace_cap | palace_eig [required]

  • -o <path>: Job directory

  • --overwrite / --no-overwrite: [default: no-overwrite]

  • --help: Show this message and exit.

qcc sim subset

Export the job folder of a subset (no solve): geometry, AEDT scripts, job.json, README.md (what to run and what to bring back) and results_template.json. Solve it by hand or elsewhere; read it back with qcc results import.

Usage:

$ qcc sim subset [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -i, --instances <str>: Components to simulate, comma separated. q3d_cmatrix: qubits and/or their readout routes (Q1,R1), resonators cut to a stub port; eigenmode / driven: exactly these components (plus the routes joining them and the pads at a selected line’s ends), lines leaving the box end in 50 ohm

  • --default: No –instances: the first qubit with its readout

  • --whole: The whole chip (slow, memory hungry)

  • -o <path>: Job folder (one box) or the folder that holds one job per box

  • -a, --analysis <str>: q3d_cmatrix (cheap, fills the LOM) | eigenmode_epr | hfss_eigenmode | hfss_driven [default: q3d_cmatrix]

  • --fast / --full: Fast solver settings (default) or the analysis defaults [default: fast]

  • --margin <float>: Margin (um) around the selection [default: 300.0]

  • --name <str>: Name of the sim group(s) written into the design [default: gui_sim]

  • --write-group / --no-write-group: Store the sim group in the design [default: write-group]

  • --set <str>: Solver setting key=value, repeatable (with –full: on top of the analysis defaults), e.g. –set maximum_passes=12 –set percent_error=1

  • --help: Show this message and exit.

qcc sim preview

Print as JSON what qcc sim subset would render (no file is written): the box, the components and routes in it and every port (50 ohm edge ports, cut stubs, junction ports) with its position. The KLayout plugin draws it.

Usage:

$ qcc sim preview [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -i, --instances <str>: Components, as for qcc sim subset

  • --default: No –instances: the first qubit with its readout

  • --whole: The whole chip

  • -g, --group <str>: A saved sim_groups entry, as it is

  • -a, --analysis <str>: Default q3d_cmatrix; with –group the group’s first

  • --margin <float>: Margin (um) around the selection [default: 300.0]

  • --name <str>: Name of the sim group(s) the export would write [default: gui_sim]

  • --help: Show this message and exit.

qcc sim auto

Automatic simulation: subset -> export -> solve in a NEW AEDT (never the one you have open) -> analyse. Fills the LOM of the simulated components; qcc analyse / the KLayout Results tab show it against the targets.

Usage:

$ qcc sim auto [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -i, --instances <str>: Qubits and/or readout routes, comma separated

  • --default: No –instances: the first qubit with its readout

  • --whole: The whole chip (slow, memory hungry)

  • -a, --analysis <str>: [default: q3d_cmatrix]

  • --aedt <str>: batch (a new non-graphical AEDT, default) | gui (a new window) [default: batch]

  • --fast / --full: Fast solver settings (default) [default: fast]

  • --margin <float>: Margin (um) around the selection [default: 300.0]

  • --name <str>: Name of the sim group(s) written into the design [default: gui_sim]

  • --timeout <float>: Seconds per solve before qcc stops the AEDT it started [default: 3600.0]

  • --status <path>: Status file (JSON) the KLayout plugin polls

  • --set <str>: Solver setting key=value, repeatable (with –full: on top of the analysis defaults), e.g. –set maximum_passes=12 –set percent_error=1

  • --help: Show this message and exit.

qcc sim run

Run a job locally (AEDT / Elmer / Palace) and collect results.

Usage:

$ qcc sim run [OPTIONS] {job}

Arguments:

  • job: [required]

Options:

  • --dry-run / --no-dry-run: Only print the command [default: no-dry-run]

  • --help: Show this message and exit.

qcc sim submit

Usage:

$ qcc sim submit [OPTIONS] {job}

Arguments:

  • job: [required]

Options:

  • --queue <path>: Queue directory [required]

  • --help: Show this message and exit.

qcc results

Parse, extract and store results.

Usage:

$ qcc results [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • collect: Parse solver outputs in JOB into…

  • extract: Extract Hamiltonian parameters from JOB…

  • import: Read solved results back (a job folder,…

  • template: A results.json skeleton with this design’s…

  • propose: Propose the next design revision…

  • apply: DESIGN with the proposal’s knobs set…

  • show

qcc results collect

Parse solver outputs in JOB into results/results.json.

Usage:

$ qcc results collect [OPTIONS] {job}

Arguments:

  • job: [required]

Options:

  • --help: Show this message and exit.

qcc results extract

Extract Hamiltonian parameters from JOB results and compare with design targets.

Usage:

$ qcc results extract [OPTIONS] {design} {job}

Arguments:

  • design: [required]

  • job: [required]

Options:

  • --store <path>: Results store (sqlite)

  • --help: Show this message and exit.

qcc results import

Read solved results back (a job folder, its results/ folder or a results.json: format in qcc results template --format), check them against the design and analyse them (the KLayout Results tab shows the outcome).

Usage:

$ qcc results import [OPTIONS] {design} {sources}...

Arguments:

  • design: [required]

  • sources...: Solved job folder(s) or results.json file(s) [required]

Options:

  • -g, --group <str>: Sim group the results belong to (default: from the job)

  • --help: Show this message and exit.

qcc results template

A results.json skeleton with this design’s net names (with –format: the format description).

Usage:

$ qcc results template [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -o <path>: Write the skeleton here (default: print it)

  • -g, --group <str>: [default: chip]

  • -a, --analysis <str>: [default: q3d_cmatrix]

  • --format: Print the results.json format description instead

  • --help: Show this message and exit.

qcc results propose

Propose the next design revision (loop.feedback: every qubit with a LOM model and a lambda/4 or lambda/2 readout) as old -> new knob values; nothing is written to the design. qcc results apply sets them.

Usage:

$ qcc results propose [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • --job <path>: Job folder(s) to analyse (default: the last run’s, else the layout estimates)

  • -o <path>: Write the proposal (JSON) here

  • --help: Show this message and exit.

qcc results apply

DESIGN with the proposal’s knobs set (refuses when the design changed since the proposal).

Usage:

$ qcc results apply [OPTIONS] {design} {proposal}

Arguments:

  • design: [required]

  • proposal: proposal.json from qcc results propose -o [required]

Options:

  • -o <path>: Write the new design here (default: overwrite DESIGN)

  • --help: Show this message and exit.

qcc results show

Usage:

$ qcc results show [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • --store <path>: [default: results.sqlite]

  • --help: Show this message and exit.

qcc runner

Job runner / filesystem queue (lab server).

Usage:

$ qcc runner [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • serve: Process the filesystem queue (run on the…

  • status

qcc runner serve

Process the filesystem queue (run on the lab server).

Usage:

$ qcc runner serve [OPTIONS] {queue}

Arguments:

  • queue: [required]

Options:

  • --poll <float>: [default: 5.0]

  • --once / --no-once: [default: no-once]

  • --help: Show this message and exit.

qcc runner status

Usage:

$ qcc runner status [OPTIONS] {queue}

Arguments:

  • queue: [required]

Options:

  • --help: Show this message and exit.

qcc design

design.json utilities.

Usage:

$ qcc design [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • validate

  • ports: All resolved ports of a design (absolute…

  • netlist: M3 netlist check: declared connections vs.

  • drc: Connectivity DRC: dangling ports,…

  • to-python: Write a readable Python script (the…

  • hash

qcc design validate

Usage:

$ qcc design validate [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • --help: Show this message and exit.

qcc design ports

All resolved ports of a design (absolute positions), e.g. for the KLayout plugin’s connect dialog.

Usage:

$ qcc design ports [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • --json

  • --help: Show this message and exit.

qcc design netlist

M3 netlist check: declared connections vs. the KQC geometric netlist (opens/shorts with coordinates).

Usage:

$ qcc design netlist [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • --help: Show this message and exit.

qcc design drc

Connectivity DRC: dangling ports, components without LOM, outside chip, overlaps, crossings, opens/shorts.

Usage:

$ qcc design drc [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • --netlist / --no-netlist: Also run the KQC netlist check [default: netlist]

  • --keep-going: Report a route that cannot be built (route_failed) and check the rest, instead of stopping at it

  • --help: Show this message and exit.

qcc design to-python

Write a readable Python script (the Designer API) that rebuilds DESIGN: the GUI prototype continues as code.

The script writes the design.json again (python design.py); the round trip is checked (same qcc design hash). Entries the Designer calls cannot say are written as plain data with a comment.

Usage:

$ qcc design to-python [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -o <path>: Output script (default: <design name>.py next to the design)

  • --check / --no-check: Run the script here and require the same design hash (default on) [default: check]

  • --help: Show this message and exit.

qcc design hash

Usage:

$ qcc design hash [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • --help: Show this message and exit.

qcc hfss

Ansys HFSS / Q3D projects (AEDT 2024 R1/R2).

Usage:

$ qcc hfss [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • render: Render DESIGN (whole chip or a sim group)…

  • solve: Solve an exported Ansys JOB directory (new…

  • check: Read JOB’s rendered .aedt back: stack,…

  • collect: Re-export a solved job from its saved…

qcc hfss render

Render DESIGN (whole chip or a sim group) into an AEDT project: geometry, stack, ports, Lj boundaries.

Usage:

$ qcc hfss render [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -g, --group <str>: ‘chip’ (whole chip) or a sim_groups name [default: chip]

  • -a, --analysis <str>: eigenmode_epr (default) | hfss_eigenmode | q3d_cmatrix | hfss_driven [default: eigenmode_epr]

  • -o <path>: Job directory (default build/jobs/<sim name>)

  • --solve / --no-solve: Also solve (qcc_solve.py in a new non-graphical AEDT) and collect results [default: no-solve]

  • --set <str>: Solver setting key=value (JSON value), repeatable, e.g. –set percent_error=1 –set mesh_size={“1t1_gap”:10}

  • --airbridges / --no-airbridges: Keep airbridges in the simulated geometry (default: the group’s setting, else dropped)

  • --timeout <float>: Seconds before qcc kills the AEDT process tree it started

  • --open: Open the rendered project in a new AEDT GUI

  • --graphical / --no-graphical: Run the render with the AEDT window instead of -ng [default: no-graphical]

  • --aedt <str>: batch (new -ng AEDT, default) | gui (new AEDT window, left open) | attach (the open AEDT)

  • --show / --no-show: Also send the chip to KLayout via klive [default: no-show]

  • --dry-run / --no-dry-run: Export the job and print the AEDT command only [default: no-dry-run]

  • --help: Show this message and exit.

qcc hfss solve

Solve an exported Ansys JOB directory (new batch AEDT, a new window or the open AEDT) and collect results.

Usage:

$ qcc hfss solve [OPTIONS] {job}

Arguments:

  • job: [required]

Options:

  • --timeout <float>: Seconds before qcc kills the AEDT process tree it started

  • --graphical / --no-graphical: Run with the AEDT window instead of -ng [default: no-graphical]

  • --aedt <str>: batch (new -ng AEDT, default) | gui (new AEDT window, left open) | attach (the open AEDT)

  • --help: Show this message and exit.

qcc hfss check

Read JOB’s rendered .aedt back: stack, metal sheets, ports / terminations, nets and every solver setting.

Usage:

$ qcc hfss check [OPTIONS] {job}

Arguments:

  • job: [required]

Options:

  • --help: Show this message and exit.

qcc hfss collect

Re-export a solved job from its saved project as it is now (no solve), e.g. after you changed the setup in AEDT and solved there; then qcc results import DESIGN JOB. Close the project in your own AEDT first, or run scripts/qcc_collect.py in that AEDT (Tools > Run Script) instead.

Usage:

$ qcc hfss collect [OPTIONS] {job}

Arguments:

  • job: [required]

Options:

  • --aedt <str>: batch (a new non-graphical AEDT, default) | gui (a new window) [default: batch]

  • --help: Show this message and exit.

qcc circuit

Lumped circuit (LOM): layout → circuit.json, LOM simulation, circuit → layout.

Usage:

$ qcc circuit [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • export: Layout → LOM netlist: components’ lumped…

  • simulate: LOM simulation: QuCat normal modes +…

  • layout: LOM -> layout: transmon + lambda/4 pairs…

qcc circuit export

Layout → LOM netlist: components’ lumped models joined along routes/snaps (values = component estimates).

Usage:

$ qcc circuit export [OPTIONS] {design}

Arguments:

  • design: [required]

Options:

  • -g, --group <str>: ‘chip’ (all) or a sim_groups name [default: chip]

  • -o <path>: Output circuit.json (default build/<name>.circuit.json)

  • --help: Show this message and exit.

qcc circuit simulate

LOM simulation: QuCat normal modes + kappa, QuTiP dressed spectrum -> f_q, alpha, f_r, chi, kappa.

Usage:

$ qcc circuit simulate [OPTIONS] {source}

Arguments:

  • source: circuit.json, or a design (its layout LOM is used) [required]

Options:

  • --job <path>: Fill capacitances from this simulation job (design input only)

  • -g, --group <str>: [default: chip]

  • --json <path>: Also write the result (modes, params, netlist values) as JSON

  • --png <path>: Also draw the circuit schematic (matplotlib) to this PNG

  • --help: Show this message and exit.

qcc circuit layout

LOM -> layout: transmon + lambda/4 pairs with targets -> knobs -> a laid-out feedline chip.

Usage:

$ qcc circuit layout [OPTIONS] {circuit}

Arguments:

  • circuit: [required]

Options:

  • -o <path>: Output design.json [required]

  • --live / --no-live: Lay it out live in KLayout [default: no-live]

  • --help: Show this message and exit.