qcc_kplugin.design_io ===================== .. py:module:: qcc_kplugin.design_io .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: qcc_kplugin.design_io.FINGERPRINT_SKIP qcc_kplugin.design_io.JSON_DICT_PARAMS qcc_kplugin.design_io.PHI0_2PI_NH_NA qcc_kplugin.design_io.QUBIT_TARGETS qcc_kplugin.design_io.RESONATOR_TARGETS qcc_kplugin.design_io.TARGET_TOL qcc_kplugin.design_io.TOL Functions --------- .. autoapisummary:: qcc_kplugin.design_io.add_instance qcc_kplugin.design_io.add_route qcc_kplugin.design_io.angle_deg qcc_kplugin.design_io.branch_text qcc_kplugin.design_io.changed_params qcc_kplugin.design_io.compare_targets qcc_kplugin.design_io.delete_instance qcc_kplugin.design_io.delete_route qcc_kplugin.design_io.delete_route_node qcc_kplugin.design_io.design_fingerprint qcc_kplugin.design_io.duplicate_spec qcc_kplugin.design_io.editable_route qcc_kplugin.design_io.find_chip_cell qcc_kplugin.design_io.flow_status qcc_kplugin.design_io.follow_hangers qcc_kplugin.design_io.free_end qcc_kplugin.design_io.hanger_end qcc_kplugin.design_io.ic_from_lj qcc_kplugin.design_io.ic_from_rn qcc_kplugin.design_io.insert_route_node qcc_kplugin.design_io.junction_triplet qcc_kplugin.design_io.lj_from_ic qcc_kplugin.design_io.lom_rows qcc_kplugin.design_io.marks_path qcc_kplugin.design_io.materialize_nodes qcc_kplugin.design_io.mirror_instance qcc_kplugin.design_io.move_route_node qcc_kplugin.design_io.netlist_rows qcc_kplugin.design_io.new_design qcc_kplugin.design_io.new_pcell_instances qcc_kplugin.design_io.node_props qcc_kplugin.design_io.parse_targets qcc_kplugin.design_io.parse_value qcc_kplugin.design_io.placed_instances qcc_kplugin.design_io.read_design qcc_kplugin.design_io.read_marks qcc_kplugin.design_io.refresh_free_end_dir qcc_kplugin.design_io.results_rows qcc_kplugin.design_io.rn_from_ic qcc_kplugin.design_io.route_from_path qcc_kplugin.design_io.scrub_references qcc_kplugin.design_io.set_instance qcc_kplugin.design_io.set_mark qcc_kplugin.design_io.set_meander_segment qcc_kplugin.design_io.set_node qcc_kplugin.design_io.set_place_at qcc_kplugin.design_io.set_place_snap qcc_kplugin.design_io.set_route_options qcc_kplugin.design_io.set_targets qcc_kplugin.design_io.sync_placements qcc_kplugin.design_io.target_keys qcc_kplugin.design_io.target_tolerance qcc_kplugin.design_io.unique_name qcc_kplugin.design_io.write_design Module Contents --------------- .. py:function:: 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. .. py:function:: 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'). .. py:function:: angle_deg(v) -> float .. py:function:: 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. .. py:function:: changed_params(schema: list[dict], values: dict) -> dict ``values`` (name → value) minus those equal to the schema defaults. .. py:function:: 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 :func:`target_tolerance`) or ``""`` when there is no target. .. py:function:: delete_instance(design: dict, name: str) -> tuple[dict, list[str]] Remove an instance and every route touching it; returns the removed route names. .. py:function:: 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. .. py:function:: delete_route_node(design: dict, route: str, index: int) -> dict .. py:function:: design_fingerprint(design) -> str A short hash of the design (a dict, or the path of a design.json) without :data:`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. .. py:function:: 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. .. py:function:: 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 :func:`materialize_nodes`); the design's own nodes stay in ``real_*``. .. py:function:: find_chip_cell(top: pya.Cell) -> pya.Cell The DesignChip cell under the written top cell (or the top cell itself). .. py:function:: 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//lom.json``, out of date when the design changed since (fingerprint in :func:`marks_path`, else file times); * simulate: an analysed simulation (``build//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/_fab.oas``, ``warn`` when the design changed since the export. .. py:function:: 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). .. py:function:: 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. .. py:function:: 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). .. py:function:: ic_from_lj(lj_nh: float) -> float I_c (nA) of a junction (or a symmetric SQUID's sum) with L_J ``lj_nh``. .. py:function:: 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). .. py:function:: insert_route_node(design: dict, route: str, index: int, xy) -> dict .. py:function:: 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). .. py:function:: lj_from_ic(ic_na: float) -> float .. py:function:: 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``). .. py:function:: marks_path(design_path) -> pathlib.Path ``/build/.flow/marks.json``: the design fingerprint each Flow step last ran on. .. py:function:: materialize_nodes(design: dict, route: str, built: dict) -> list[int] | None Make every corner of the built route (sidecar ``built``, or its :func:`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). .. py:function:: 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. .. py:function:: move_route_node(design: dict, route: str, index: int, xy) -> dict .. py:function:: 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, ...). .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: parse_targets(texts: dict[str, str]) -> dict[str, float] ``{key: text}`` → numbers; empty texts are dropped, a non-number raises ``ValueError`` naming the key. .. py:function:: 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. .. py:function:: placed_instances(chip: pya.Cell) -> dict[str, pya.DCplxTrans] .. py:function:: read_design(path) -> dict .. py:function:: read_marks(design_path) -> dict .. py:function:: 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. .. py:function:: 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. .. py:function:: rn_from_ic(ic_na: float, gap_mev: float = 1.4) -> float .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: set_mark(design_path, step: str, fingerprint: str) -> None Record that ``step`` ran on the design with ``fingerprint`` (see :func:`flow_status`). .. py:function:: 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``). .. py:function:: 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]``. .. py:function:: set_place_at(design: dict, inst: str, at, rot: float | None = None, mirror: bool | None = None) -> dict .. py:function:: 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). .. py:function:: set_route_options(design: dict, route: str, **options) -> dict Set ``type``/``length``/``r``/``meander_segment`` etc.; ``None`` removes the key. .. py:function:: 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. .. py:function:: 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)``. .. py:function:: 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. .. py:function:: 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"``): :data:`TARGET_TOL`, else 1 % of ``target`` (None without one). .. py:function:: unique_name(design: dict, base: str) -> str .. py:function:: write_design(path, data: dict) -> None .. py:data:: FINGERPRINT_SKIP :value: ('targets', 'sim_groups') .. py:data:: JSON_DICT_PARAMS :value: ('options', 'junction_params') .. py:data:: PHI0_2PI_NH_NA :value: 329.1059 .. py:data:: QUBIT_TARGETS .. py:data:: RESONATOR_TARGETS .. py:data:: TARGET_TOL .. py:data:: TOL :value: 0.001