quantcore_circuits.design.schema

Pydantic schema for design.json (schema qcc/0.1).

The design file is the single source of truth: geometry is always regenerated from it. Units are µm and degrees. The structure follows gdsfactory’s Netlist/Instance/Placement ideas, but cells are KQC Elements and connections are KQC refpoint ports (port_<name> + port_<name>_corner).

Port references are strings "<instance>.<port>". The reserved instance name chip refers to chip-level ports (e.g. launchers: "chip.WN").

Attributes

Classes

Chip

Chip-level settings, passed to the KQC Chip base class (box, with_grid, name_chip, ...).

Coupling

A lumped element the layout implies but no route or snap carries, e.g. two qubit arms facing each other.

Design

FreeEnd

A route end that is not a port: a point, a direction (deg) and a termination gap.

HangerEnd

End a route in a coupler running parallel to another route (e.g. a λ/4 resonator hanging off a feedline).

Instance

A placed component.

Junction

Lumped junction values for the LOM and the simulations (not geometry or fab), fixed per component.

Launchers

KQC sample-holder launchers with names: assign maps pad numbers to port names (KQC

Place

Placement of an instance: absolute (at/rot) or port-to-port snap (snap/to).

PortSpec

Explicit port of a static (freeform) cell. Direction is the outward direction in degrees.

Route

A CPW connection between two ports, built with KQC WaveguideComposite.

SimGroup

A simulation sub-problem: the selected instances (plus routes between them) cut out with a margin.

Waypoint

A route waypoint with optional KQC Node extras (airbridge, taper, ...).

Functions

split_port_ref(ref) → tuple[str, str]

Split "Q1.claw_n" into ("Q1", "claw_n").

Module Contents

class quantcore_circuits.design.schema.Chip

Bases: _Model

Chip-level settings, passed to the KQC Chip base class (box, with_grid, name_chip, …).

box: tuple[float, float, float, float] = (0.0, 0.0, 10000.0, 10000.0)
cell: str = 'quantcore_circuits.assembly.DesignChip'
launchers: str | Launchers | None = None
params: dict[str, Any]
class quantcore_circuits.design.schema.Coupling

Bases: _Model

A lumped element the layout implies but no route or snap carries, e.g. two qubit arms facing each other.

between holds two ends, each "<instance>" (its main island), "<instance>.<port>", "<instance>.<LOM node>" or "<route>" (the route’s conductor, e.g. a hanger declared against a routed feedline). The LOM builder adds the element between those nodes; fem: True lets a C-matrix replace the value by island name.

type: "wire" is a galvanic join with no element and no geometry: both ends must be ports ("<instance>.<port>"), their LOM nodes merge into one conductor, and the netlist check counts the pair as a declared connection. It is for cells whose metal overlaps instead of meeting port to port (legacy chips keep their absolute positions, e.g. a resonator end drawn inside an Xmon claw tail).

between: tuple[str, str]
fem: bool = True
note: str = ''
type: Literal['C', 'L', 'wire'] = 'C'
value: float | None = None
class quantcore_circuits.design.schema.Design

Bases: _Model

to_json_dict() → dict[str, Any]
chip: Chip
couplings: dict[str, Coupling]
instances: dict[str, Instance]
name: str = 'design'
nets: Literal['derived'] | list[list[str]] = 'derived'
pdk: str = 'quantcore_nb_sapphire_v1'
routes: dict[str, Route]
schema_: str
sim_groups: dict[str, SimGroup]
targets: dict[str, dict[str, float]]
class quantcore_circuits.design.schema.FreeEnd

Bases: _Model

A route end that is not a port: a point, a direction (deg) and a termination gap.

dir follows the port convention: it points from this end towards the route (for a resonator that ends heading down, dir is 90). term is the KQC termination length: 0 shorts the centre conductor to ground (λ/4 short end), a positive value leaves an open end with that gap.

at: tuple[float, float]
dir: float | None = None
term: float = 0.0
class quantcore_circuits.design.schema.HangerEnd

Bases: _Model

End a route in a coupler running parallel to another route (e.g. a λ/4 resonator hanging off a feedline).

The coupler is centred at arclength s (µm, measured along the target route’s node polyline), on the side (relative to the target route’s direction of travel), separated from it by a ground_gap metal strip between the two CPW gaps. The route approaches the coupler perpendicularly at one end and terminates at the other: direction="forward" terminates downstream (in the target route’s travel direction). end="short" grounds the termination (λ/4 short end), end="open" leaves an open_gap gap. bend=True (default) brings the route into the coupler with a 90° bend (perpendicular to the target route); bend=False enters it straight, along the coupler axis (the route must then arrive in line with the coupler).

Instead of s, near=(x, y) (µm, chip coordinates) centres the coupler at the point of the target route nearest to that point, so it stays put when the target route’s start moves (e.g. a pad moved to the die edge).

coupler_gap / line_gap (µm, None = the CPW’s own gap b) narrow the two gaps that face each other along the coupler: this route’s gap on the line’s side and the line’s gap on this route’s side. The centre lines come closer by what they save (stronger coupling at the same ground_gap strip); the outer gaps keep b. The build draws the extra ground as base_metal_addition over the coupler length.

bend: bool = True
coupler_gap: float | None = None
direction: Literal['forward', 'backward'] = 'forward'
end: Literal['short', 'open'] = 'short'
ground_gap: float = 6.0
hanger: str
length: float
line_gap: float | None = None
near: tuple[float, float] | None = None
open_gap: float = 6.0
s: float | None = None
side: Literal['left', 'right'] = 'left'
class quantcore_circuits.design.schema.Instance

Bases: _Model

A placed component.

cell is a dotted class path ("quantcore_circuits.layouts.Xmon", "kqcircuits.qubits.swissmon.Swissmon"), a short name known to quantcore_circuits.layouts ("Xmon"), or "static:<path.oas>" for freeform cells with ports.

cell: str
junction: Junction | None = None
params: dict[str, Any]
place: Place
ports: list[PortSpec] | None = None
class quantcore_circuits.design.schema.Junction

Bases: _Model

Lumped junction values for the LOM and the simulations (not geometry or fab), fixed per component.

Lj_nH is L_J at zero flux (a SQUID: both junctions in parallel), Cj_fF its capacitance. A SQUID also has flux_phi0 (static flux Φ/Φ0) and asym (d = (I_c1 − I_c2)/(I_c1 + I_c2)); the defaults (0, 0) are a symmetric SQUID at its sweet spot. Each field also takes a list, one value per junction (the first one is used). Without Lj_nH the drawn trilayer junction’s PDK value is used (lom.fragment.effective_junction).

Cj_fF: float | list[float] = 0.0
Lj_nH: float | list[float] | None = None
asym: float | list[float] = 0.0
flux_phi0: float | list[float] = 0.0
class quantcore_circuits.design.schema.Launchers

Bases: _Model

KQC sample-holder launchers with names: assign maps pad numbers to port names (KQC launcher_assignments); only assigned pads are drawn unless enabled lists names to keep.

type is a KQC sample holder (“ARD24”, “SMA8”, “DC24”). Any of n (pads in total, or [top, right, bottom, left] per side), launcher_type (“RF”/”DC”), width, gap, indent, pitch and frame_gap (µm) override that preset, or, with type="custom", define the launchers outright (KQC produce_n_launchers); then the chip keeps its own box.

assign: dict[int, str]
enabled: list[str] | None = None
frame_gap: float | None = None
gap: float | None = None
indent: float | None = None
launcher_type: Literal['RF', 'DC'] | None = None
n: int | list[int] | None = None
pitch: float | None = None
type: str = 'custom'
width: float | None = None
class quantcore_circuits.design.schema.Place

Bases: _Model

Placement of an instance: absolute (at/rot) or port-to-port snap (snap/to).

For a snap, the instance is rotated so that its snap port faces the to port (outward directions anti-parallel) and translated so that both ports coincide; gap then pushes it out along the target port direction. rot is ignored for snaps; mirror is applied before solving the rotation.

edge ("n"/"s"/"e"/"w", or "auto" = the die edge nearest at; absolute placements only) slides the instance perpendicular to that die edge so the outer edge of its etch sits the PDK’s frame.pad_edge (100 µm) from it — the Quantcore pad rule; at keeps the position along the edge.

at: tuple[float, float] | None = None
edge: Literal['n', 's', 'e', 'w', 'auto'] | None = None
gap: float = 0.0
property is_snap: bool
mirror: bool = False
rot: float = 0.0
snap: str | None = None
to: str | None = None
class quantcore_circuits.design.schema.PortSpec

Bases: _Model

Explicit port of a static (freeform) cell. Direction is the outward direction in degrees.

a: float | None = None
at: tuple[float, float]
b: float | None = None
dir: float
name: str
class quantcore_circuits.design.schema.Route

Bases: _Model

A CPW connection between two ports, built with KQC WaveguideComposite.

type="meander" makes a fixed-length route; the meander is inserted on meander_segment (default: the longest straight segment that is not part of a port stub or hanger coupler) using KQC Node(length_increment=...).

waypoints() → list[Waypoint]
a: float | None = None
airbridges: Literal['auto', 'none'] | int = 'none'
b: float | None = None
from_: str | FreeEnd
length: float | None = None
meander_direction: Literal[1, -1] = 1
meander_segment: int | None = None
meanders: int = -1
nodes: list[tuple[float, float] | Waypoint]
params: dict[str, Any]
r: float | None = None
to: RouteEndSpec
type: Literal['cpw', 'meander'] = 'cpw'
class quantcore_circuits.design.schema.SimGroup

Bases: _Model

A simulation sub-problem: the selected instances (plus routes between them) cut out with a margin.

analyses: list[str]
margin_um: float = 300.0
ports: dict[str, Literal['edge', 'internal', 'keep', 'cut']]
select: list[str]
settings: dict[str, Any]
class quantcore_circuits.design.schema.Waypoint

Bases: _Model

A route waypoint with optional KQC Node extras (airbridge, taper, …).

r is the bend radius of the corner at this waypoint only (µm); the route’s r applies to every other corner. None (default) uses the route radius.

a: float | None = None
airbridge: bool = False
at: tuple[float, float]
b: float | None = None
params: dict[str, Any]
r: float | None = None
quantcore_circuits.design.schema.split_port_ref(ref: str) → tuple[str, str]

Split "Q1.claw_n" into ("Q1", "claw_n").

quantcore_circuits.design.schema.CHIP = 'chip'
quantcore_circuits.design.schema.RouteEndSpec
quantcore_circuits.design.schema.SCHEMA_VERSION = 'qcc/0.1'