qcc_kplugin.design_io

GUI ↔ design.json synchronisation, standard library + pya only (runs inside KLayout’s own Python).

The GUI never becomes the source of truth: edits are written back into design.json and the chip is rebuilt by qcc. Instances built by qcc carry their design name in the KQC id instance property.

Attributes

Functions

add_instance(design, name, cell, at[, rot, params, ...]) → dict

Add instance name; extra holds further entry keys (e.g. junction) copied from a duplicated one.

add_route(design, name, src, dst[, kind, length, ...]) → dict

Add (or replace) route name; dst is a port reference or a hanger/free-end dict. a / b give the

angle_deg(v) → float

branch_text(b) → str

One line for a LOM branch value: C in fF, L_J / C_J, a resonator line, a hanger's κ, a port.

changed_params(schema, values) → dict

values (name → value) minus those equal to the schema defaults.

compare_targets(params, targets) → list[dict]

LOM params (keys like "Q1.f_q_GHz") against the design's targets.

delete_instance(design, name) → tuple[dict, list[str]]

Remove an instance and every route touching it; returns the removed route names.

delete_route(design, name) → list[str]

Remove route name and the routes that hang on it (their coupler sits on its line); returns the removed

delete_route_node(design, route, index) → dict

design_fingerprint(design) → str

A short hash of the design (a dict, or the path of a design.json) without FINGERPRINT_SKIP: the Flow

duplicate_spec(design, inst) → dict

What a copy of inst needs: {"cell", "params", "rot", "extra"} (extra = every entry key besides

editable_route(built) → dict

The sidecar route as Route handles edits it: waypoints / waypoint_index / waypoint_r list every

find_chip_cell(top) → pya.Cell

The DesignChip cell under the written top cell (or the top cell itself).

flow_status(design_path, sidecar) → dict[str, str]

Which flow steps have been done for the design: {step: "done" | "warn" | "todo"} for

follow_hangers(design, inst, delta) → list[str]

A component moved by delta: the hanger couplers of its routes (to: {"hanger": ..., "near": [x, y]})

free_end(at[, direction, end, gap]) → dict

A free route end (FreeEnd) at at: open leaves a gap µm gap (KQC term), short grounds it

hanger_end(route, near, length[, side, end, ...]) → dict

A hanger route end (HangerEnd): a length µm coupler on route centred at the point nearest near.

ic_from_lj(lj_nh) → float

I_c (nA) of a junction (or a symmetric SQUID's sum) with L_J lj_nh.

ic_from_rn(rn_kohm[, gap_mev]) → float

I_c (nA) from the normal resistance: I_c·R_n = πΔ/2e (Δ = gap_mev, the PDK's Nb gap 1.4 meV).

insert_route_node(design, route, index, xy) → dict

junction_triplet([gap_mev, lj_nh, ic_na, rn_kohm]) → dict

{"Lj_nH", "Ic_nA", "Rn_kohm"} from whichever one is given (the first that is not None).

lj_from_ic(ic_na) → float

lom_rows(sidecar, element) → list[tuple[str, str, str]]

[(branch, type, value text)] of the LOM branches that belong to element (an instance or a route): its

marks_path(design_path) → pathlib.Path

<design folder>/build/<stem>.flow/marks.json: the design fingerprint each Flow step last ran on.

materialize_nodes(design, route, built) → list[int] | None

Make every corner of the built route (sidecar built, or its editable_route()) a node in design.json,

mirror_instance(design, inst) → bool

Toggle place.mirror of inst (a mirror about its local x axis, applied before its rotation or snap).

move_route_node(design, route, index, xy) → dict

netlist_rows(result) → list[tuple[str, str, str, str]]

(element, kind, nodes, value) rows of a LOM result's netlist (C in fF, L / Lj in nH, ...).

new_design(name[, box, pdk]) → dict

An empty design: the PDK die (frame, pad-edge rule, cheese band come from the build) and nothing on it.

new_pcell_instances(design, cell) → tuple[dict, list[str]]

Add PCell instances placed by hand in cell (no id yet) to the design as absolute instances.

node_props(node) → dict

{"at", "r", "airbridge", "a", "b"} of a route node (a plain [x, y] or a Waypoint dict); a / b

parse_targets(texts) → dict[str, float]

{key: text} → numbers; empty texts are dropped, a non-number raises ValueError naming the key.

parse_value(text, default[, name])

A table cell's text as a parameter value of the default's type (strings stay strings; others JSON). The JSON

placed_instances(chip) → dict[str, pya.DCplxTrans]

read_design(path) → dict

read_marks(design_path) → dict

refresh_free_end_dir(route) → None

A free end's dir points from the end back along the segment that arrives at it (what the Connect tool wrote);

results_rows(sidecar[, instance]) → list[tuple[str, str, str, str]]

Panel rows from the sidecar's per-instance results: (element, parameter, value, target · status).

rn_from_ic(ic_na[, gap_mev]) → float

route_from_path(points, ports, capture)

A drawn path → (from_port, to_port, waypoints): end points snap to the nearest ports within capture.

scrub_references(design[, built]) → list[str]

Remove what refers to instances / routes that no longer exist, so design.json stays valid: routes ending on a

set_instance(design, inst, params[, rot]) → dict

Replace an instance's PCell params (only the values that differ from the cell defaults belong here) and,

set_mark(design_path, step, fingerprint) → None

Record that step ran on the design with fingerprint (see flow_status()).

set_meander_segment(design, route, segment) → dict

Put the meander of route on polyline segment (1-based, the segment ending at node segment).

set_node(design, route, index, **props) → dict

Change node index of route: at (x, y), r (this corner's bend radius; None = the route's) and/or

set_place_at(design, inst, at[, rot, mirror]) → dict

set_place_snap(design, inst, port, to[, gap]) → dict

place.snap: inst.port sits on to facing it (the rebuild solves the rotation).

set_route_options(design, route, **options) → dict

Set type/length/r/meander_segment etc.; None removes the key.

set_targets(design, element, values) → bool

Write values as design["targets"][element] (the schema's per-element {key: float}); an empty dict

sync_placements(design, chip[, built])

Write moved instances back to design['instances'][*]['place'].

target_keys(kind[, cell, existing, category]) → dict[str, str]

Target keys offered for an element, {key: description}: kind is "route" (resonators and lines) or

target_tolerance(key[, target]) → float | None

Absolute tolerance of target key (e.g. "f_q_GHz" or "Q1.f_q_GHz"): TARGET_TOL, else 1 % of

unique_name(design, base) → str

write_design(path, data) → None

Module Contents

qcc_kplugin.design_io.add_instance(design: dict, name: str, cell: str, at, rot: float = 0.0, params: dict | None = None, mirror: bool = False, extra: dict | None = None) → dict

Add instance name; extra holds further entry keys (e.g. junction) copied from a duplicated one.

qcc_kplugin.design_io.add_route(design: dict, name: str, src: str, dst, kind: str = 'cpw', length: float | None = None, nodes: list | None = None, r: float | None = None, a: float | None = None, b: float | None = None) → dict

Add (or replace) route name; dst is a port reference or a hanger/free-end dict. a / b give the route its own CPW width and gap (None: the ports’).

qcc_kplugin.design_io.angle_deg(v) → float
qcc_kplugin.design_io.branch_text(b: dict) → str

One line for a LOM branch value: C in fF, L_J / C_J, a resonator line, a hanger’s κ, a port.

qcc_kplugin.design_io.changed_params(schema: list[dict], values: dict) → dict

values (name → value) minus those equal to the schema defaults.

qcc_kplugin.design_io.compare_targets(params: dict, targets: dict) → list[dict]

LOM params (keys like "Q1.f_q_GHz") against the design’s targets.

Returns rows {key, element, name, value, target, tol, status} for every simulated parameter and for every target without a value (status "no value"). Status: "within tolerance", "off" (beyond the absolute tolerance of target_tolerance()) or "" when there is no target.

qcc_kplugin.design_io.delete_instance(design: dict, name: str) → tuple[dict, list[str]]

Remove an instance and every route touching it; returns the removed route names.

qcc_kplugin.design_io.delete_route(design: dict, name: str) → list[str]

Remove route name and the routes that hang on it (their coupler sits on its line); returns the removed names, name first.

qcc_kplugin.design_io.delete_route_node(design: dict, route: str, index: int) → dict
qcc_kplugin.design_io.design_fingerprint(design) → str

A short hash of the design (a dict, or the path of a design.json) without FINGERPRINT_SKIP: the Flow strip compares it with the one recorded when a step ran, so writing a sim group or a target does not make the Check, LOM or Fab marks look out of date. “” when the file cannot be read.

qcc_kplugin.design_io.duplicate_spec(design: dict, inst: str) → dict

What a copy of inst needs: {"cell", "params", "rot", "extra"} (extra = every entry key besides cell/params/place, e.g. junction), for placing it again with the placement ghost.

qcc_kplugin.design_io.editable_route(built: dict) → dict

The sidecar route as Route handles edits it: waypoints / waypoint_index / waypoint_r list every corner (the router’s own too, see materialize_nodes()); the design’s own nodes stay in real_*.

qcc_kplugin.design_io.find_chip_cell(top: pya.Cell) → pya.Cell

The DesignChip cell under the written top cell (or the top cell itself).

qcc_kplugin.design_io.flow_status(design_path, sidecar: dict | None) → dict[str, str]

Which flow steps have been done for the design: {step: "done" | "warn" | "todo"} for design check lom simulate results fab (cheap file checks; warn = done but out of date or with issues).

  • check: the sidecar’s fast DRC (the panel adds its full check on top);

  • lom: build/<stem>/lom.json, out of date when the design changed since (fingerprint in marks_path(), else file times);

  • simulate: an analysed simulation (build/<name>/flow.json, written by the automatic run and by Import results), warn when the design changed since (stale results);

  • results: values in the sidecar’s results, warn when stale or when a target fails (tune: Propose);

  • fab: build/<stem>_fab.oas, warn when the design changed since the export.

qcc_kplugin.design_io.follow_hangers(design: dict, inst: str, delta) → list[str]

A component moved by delta: the hanger couplers of its routes (to: {"hanger": ..., "near": [x, y]}) move with it, so a readout hanging from a feedline keeps its geometry instead of failing to route (a fixed coupler 100 µm off the claw needs an S-jog shorter than two bend radii).

qcc_kplugin.design_io.free_end(at, direction: float | None = None, end: str = 'open', gap: float = 6.0) → dict

A free route end (FreeEnd) at at: open leaves a gap µm gap (KQC term), short grounds it (term 0). direction (degrees) points from the end into the route; None lets the route leave freely.

qcc_kplugin.design_io.hanger_end(route: str, near, length: float, side: str = 'left', end: str = 'short', ground_gap: float = 6.0, direction: str = 'forward', coupler_gap: float | None = None, line_gap: float | None = None) → dict

A hanger route end (HangerEnd): a length µm coupler on route centred at the point nearest near. coupler_gap / line_gap: the two facing gaps narrowed along the coupler (None: the CPW’s own).

qcc_kplugin.design_io.ic_from_lj(lj_nh: float) → float

I_c (nA) of a junction (or a symmetric SQUID’s sum) with L_J lj_nh.

qcc_kplugin.design_io.ic_from_rn(rn_kohm: float, gap_mev: float = 1.4) → float

I_c (nA) from the normal resistance: I_c·R_n = πΔ/2e (Δ = gap_mev, the PDK’s Nb gap 1.4 meV).

qcc_kplugin.design_io.insert_route_node(design: dict, route: str, index: int, xy) → dict
qcc_kplugin.design_io.junction_triplet(gap_mev: float = 1.4, lj_nh=None, ic_na=None, rn_kohm=None) → dict

{"Lj_nH", "Ic_nA", "Rn_kohm"} from whichever one is given (the first that is not None).

qcc_kplugin.design_io.lj_from_ic(ic_na: float) → float
qcc_kplugin.design_io.lom_rows(sidecar: dict, element: str) → list[tuple[str, str, str]]

[(branch, type, value text)] of the LOM branches that belong to element (an instance or a route): its own nodes (Q1, Q1.claw_n) or its name in the branch’s (C_Q1, K_R1, R1).

qcc_kplugin.design_io.marks_path(design_path) → pathlib.Path

<design folder>/build/<stem>.flow/marks.json: the design fingerprint each Flow step last ran on.

qcc_kplugin.design_io.materialize_nodes(design: dict, route: str, built: dict) → list[int] | None

Make every corner of the built route (sidecar built, or its editable_route()) a node in design.json, keeping the existing nodes (and their extras). The router adds its own corners only where the user gave none, so a node inserted there would otherwise replace them all and the route would no longer look like its preview. Port stubs and hanger couplers stay the router’s. Returns the polyline index of each node, or None when the existing nodes cannot be matched to the polyline (left unchanged).

qcc_kplugin.design_io.mirror_instance(design: dict, inst: str) → bool

Toggle place.mirror of inst (a mirror about its local x axis, applied before its rotation or snap). Returns the new state.

qcc_kplugin.design_io.move_route_node(design: dict, route: str, index: int, xy) → dict
qcc_kplugin.design_io.netlist_rows(result: dict) → list[tuple[str, str, str, str]]

(element, kind, nodes, value) rows of a LOM result’s netlist (C in fF, L / Lj in nH, …).

qcc_kplugin.design_io.new_design(name: str, box=(0.0, 0.0, 7500.0, 7500.0), pdk: str = 'quantcore_nb_sapphire_v1') → dict

An empty design: the PDK die (frame, pad-edge rule, cheese band come from the build) and nothing on it.

qcc_kplugin.design_io.new_pcell_instances(design: dict, cell: pya.Cell) → tuple[dict, list[str]]

Add PCell instances placed by hand in cell (no id yet) to the design as absolute instances.

qcc_kplugin.design_io.node_props(node) → dict

{"at", "r", "airbridge", "a", "b"} of a route node (a plain [x, y] or a Waypoint dict); a / b are the line width / gap from this node on (a taper), None = unchanged.

qcc_kplugin.design_io.parse_targets(texts: dict[str, str]) → dict[str, float]

{key: text} → numbers; empty texts are dropped, a non-number raises ValueError naming the key.

qcc_kplugin.design_io.parse_value(text: str, default, name: str | None = None)

A table cell’s text as a parameter value of the default’s type (strings stay strings; others JSON). The JSON text of options (Quantum Metal components) and junction_params becomes the dict the notebooks write: the string form builds the same layout but the LOM export does not read Metal options from it.

qcc_kplugin.design_io.placed_instances(chip: pya.Cell) → dict[str, pya.DCplxTrans]
qcc_kplugin.design_io.read_design(path) → dict
qcc_kplugin.design_io.read_marks(design_path) → dict
qcc_kplugin.design_io.refresh_free_end_dir(route: dict) → None

A free end’s dir points from the end back along the segment that arrives at it (what the Connect tool wrote); after the node next to the end was moved, inserted or deleted it is derived from the new last node again.

qcc_kplugin.design_io.results_rows(sidecar: dict, instance: str | None = None) → list[tuple[str, str, str, str]]

Panel rows from the sidecar’s per-instance results: (element, parameter, value, target · status).

instance limits the rows to one element (the selected instance or route). Values computed for another revision of the design carry (stale) in the status column.

qcc_kplugin.design_io.rn_from_ic(ic_na: float, gap_mev: float = 1.4) → float
qcc_kplugin.design_io.route_from_path(points: list, ports: dict[str, dict], capture: float)

A drawn path → (from_port, to_port, waypoints): end points snap to the nearest ports within capture.

Interior vertices become waypoints (the rebuild bends each corner to the route radius). Waypoints that sit on the port stubs’ axis are kept; the router then replaces the stub with them.

qcc_kplugin.design_io.scrub_references(design: dict, built: dict | None = None) → list[str]

Remove what refers to instances / routes that no longer exist, so design.json stays valid: routes ending on a removed instance or hanging from a removed route (repeatedly), names in sim groups (a group left empty goes), targets, couplings; an instance snapped to a removed one becomes an absolute placement at its last built position (built = the sidecar’s instances). Returns what changed, one line each.

qcc_kplugin.design_io.set_instance(design: dict, inst: str, params: dict, rot: float | None = None) → dict

Replace an instance’s PCell params (only the values that differ from the cell defaults belong here) and, when the instance is placed by at, its rotation.

qcc_kplugin.design_io.set_mark(design_path, step: str, fingerprint: str) → None

Record that step ran on the design with fingerprint (see flow_status()).

qcc_kplugin.design_io.set_meander_segment(design: dict, route: str, segment: int | None) → dict

Put the meander of route on polyline segment (1-based, the segment ending at node segment).

qcc_kplugin.design_io.set_node(design: dict, route: str, index: int, **props) → dict

Change node index of route: at (x, y), r (this corner’s bend radius; None = the route’s) and/or airbridge, a / b (line width / gap from this node on: a taper; None = removed). Other waypoint extras (params) are kept; a node left with only its position is written as a plain [x, y].

qcc_kplugin.design_io.set_place_at(design: dict, inst: str, at, rot: float | None = None, mirror: bool | None = None) → dict
qcc_kplugin.design_io.set_place_snap(design: dict, inst: str, port: str, to: str, gap: float = 0.0) → dict

place.snap: inst.port sits on to facing it (the rebuild solves the rotation).

qcc_kplugin.design_io.set_route_options(design: dict, route: str, **options) → dict

Set type/length/r/meander_segment etc.; None removes the key.

qcc_kplugin.design_io.set_targets(design: dict, element: str, values: dict[str, float]) → bool

Write values as design["targets"][element] (the schema’s per-element {key: float}); an empty dict removes the entry. Returns True when design.json changed.

qcc_kplugin.design_io.sync_placements(design: dict, chip: pya.Cell, built: dict[str, pya.DCplxTrans] | None = None)

Write moved instances back to design['instances'][*]['place'].

built are the transforms of the last qcc build (to detect moves); if omitted every absolute placement is compared with its place entry. Snap-placed instances that were moved become absolute placements (reported). Returns (design, report_lines).

qcc_kplugin.design_io.target_keys(kind: str, cell: str = '', existing: dict | None = None, category: str | None = None) → dict[str, str]

Target keys offered for an element, {key: description}: kind is "route" (resonators and lines) or "instance". An instance gets them by its catalog class category (every qubit the qubit targets, every resonator the resonator targets); without a class, by its cell name. Keys already in existing are always kept.

qcc_kplugin.design_io.target_tolerance(key: str, target: float | None = None) → float | None

Absolute tolerance of target key (e.g. "f_q_GHz" or "Q1.f_q_GHz"): TARGET_TOL, else 1 % of target (None without one).

qcc_kplugin.design_io.unique_name(design: dict, base: str) → str
qcc_kplugin.design_io.write_design(path, data: dict) → None
qcc_kplugin.design_io.FINGERPRINT_SKIP = ('targets', 'sim_groups')
qcc_kplugin.design_io.JSON_DICT_PARAMS = ('options', 'junction_params')
qcc_kplugin.design_io.PHI0_2PI_NH_NA = 329.1059
qcc_kplugin.design_io.QUBIT_TARGETS
qcc_kplugin.design_io.RESONATOR_TARGETS
qcc_kplugin.design_io.TARGET_TOL
qcc_kplugin.design_io.TOL = 0.001