quantcore_circuits.codesign

Surrogates (M11) and the co-design loop (M12): extracted parameters → new knob values → new design revision.

Elements. Every transmon–readout pair of the filled circuit (fill(): grounded and floating qubits, λ/4 and λ/2 readouts) reduces to the same 2-node network: C_island (island → ground, the qubit mode of a floating transmon), Cg (island ↔ coupler) and C_coupler (coupler → ground), plus the junction Lj_nH and the resonator line (length_um, λ/4 or λ/2).

Surrogate (knob → element value). Each capacitance gets a power law in the geometry knobs, v = v0 (k/k0)^p · Π (k_j/k_j0)^p_j, anchored at the latest point (space mapping: the anchor is the measurement — FEM, or the layout’s own estimates — so the surrogate is exact there). The exponents are the local sensitivities of the component’s own LOM model (its fragment re-evaluated at ±2 % of each knob, the branch values scaled by estimate(k)/estimate(k0) and reduced to the pair), so they hold for every qubit class with a LOM model; an Xmon’s are its calibration exponents (1.0, 1.0, 0.8). With two or more FEM points at different knob values the primary exponent is refitted (log–log least squares). Junction inductance and resonator length are knobs themselves.

Knobs per class (QUBIT_KNOBS: the island-capacitance knob, the coupler knob for C_g; <node> is the readout coupler’s node in the qubit’s LOM, e.g. claw_n, cplr1, readout):

class

island (C_Σ)

coupler (C_g)

Xmon

cross_length

claw_length

Swissmon

arm_length.* (all four arms)

cpl_length.<i>

CircularTransmonSingleIsland

r_island

couplers_arc_amplitude.<i>

ConcentricTransmon

r_inner

couplers_arc_amplitude.<i>

DoublePads(Splines)

island_island_gap

coupler_extent.0

TwoPadTransmon

pad_height

its coupler cell (below)

Flipmon

top_circle_radius

coupler_length

Gatemon

island_size.*

its coupler cell (below)

TransmonTaperedInsets

pad_width

connection_pads.<node>.pad_width

metal:TransmonPocket (CL, 6, Teeth)

pad_width

connection_pads.<node>.pad_width

metal:TransmonCross (FL)

cross_length

connection_pads.<node>.claw_length

metal:TransmonStar

arm_length

connection_pads.<node>.claw_length

metal:TransmonConcentric

gap

res_s

metal:TransmonConcentricType2

gap

finger_<NE|NW|SW>_length

metal:TransmonInterdigitated

finger_height

cc_width (bus: cc_top*_width)

metal:StarQubit

center_radius

gap_readout / gap_couplers

coupler cells (COUPLER_KNOBS)

PadCoupler.pad_height

GatemonCoupler.coupling_capacitance

L_J: <Q>.junction.Lj_nH when the design sets it (a drawn junction without a design value is not tuned). Resonator: the TLres knob (<R>.length, a line cell’s resonator_length / cpw_len), or the one meander route with a length on the resonator’s conductor; the rest of the line is a constant extra_length_um. A knob that is missing, not a number or without effect in the LOM is left out and the surrogate says why (notes).

Forward model. Elements → the same 2-node network the estimators quantise (TransmonReadout, λ/4 or λ/2) → the dressed spectrum of quantcore_circuits.circuit.hamiltonian (transmon in the charge basis + resonator, no RWA; diagonalised with numpy, the same matrices as the QuTiP model) → f_q, α, f_r, g, χ.

Proposal (L0 + L1). Bounded least squares over the knobs on (predicted − target)/tol for the four targets; a knob whose target is not set stays where it is (no α target: the island knob is kept, and so on). When the surrogate can re-evaluate the LOM (surrogate_from_fill on a real circuit), the solution is checked against the LOM at the proposed knobs and the exponents corrected along the move (secant), up to three times, and if that does not settle the last solve runs on the LOM itself: a large move stays accurate for non-power-law estimates. (The LOM rounds its estimates to 2–3 significant figures; a rebuilt revision can differ from the proposal by that, and a second Propose closes the gap.) The result is a new design revision (build/<name>/revisions/rev<k>.json); the source design is never touched unless accept() is called.

Loop (L2). run() repeats evaluate → update surrogates → propose until every target is within tolerance or max_iter; evaluate(design) -> FilledCircuit is the FEM step (Q3D/Palace job → circuit.fill.fill()), or any stand-in for testing.

Attributes

Classes

ElementModel

LoopStep

PairSurrogate

Surrogate for one transmon + λ/4 or λ/2 readout pair (module docstring).

Proposal

Functions

accept(revision, design_path) → pathlib.Path

Copy an accepted revision over the source design file (keeps a .bak).

apply(design_source, knobs[, follow_ports, reach_um, plan])

Design with knobs set (instances' params, junction fields, route fields; the paths of

copy_targets(targets) → dict

dressed_levels(ej_GHz, ec_GHz, f_r_GHz, g_n_MHz[, nq, ...]) → dict

quantcore_circuits.circuit.hamiltonian.dressed() of the same model (charge-basis transmon truncated to

forward(el, cj_fF, a_um, b_um, pdk[, qubit, ...]) → dict

Element values → dressed parameters, keyed like the targets. el["length_um"] is the whole line; kind

propose(s, targets[, bounds, anchor, refine]) → Proposal

Bounded least squares on the surrogate: knobs that put every target inside its tolerance.

propose_all(surrogates, targets[, bounds, anchor]) → Proposal

propose() for every pair, merged into one proposal.

run(design_source, evaluate, targets[, max_iter, ...]) → list[LoopStep]

Co-design loop (module docstring). evaluate(design) -> FilledCircuit; on_step(LoopStep) is called

surrogate_from_fill(filled[, pair_index, cache]) → PairSurrogate

Anchor a surrogate at the point of filled (FEM or the layout's estimates; knob values read from its design).

surrogates_from_fill(filled[, notes]) → list[PairSurrogate]

One surrogate per qubit (its first, readout, pair) — multi-qubit chips. A pair whose surrogate cannot be built

unpaired_notes(filled) → list[str]

A line for every qubit (junction) of the circuit that has no readout pair (nothing reads it out, or only a bus

update_surrogate(s, filled, knobs[, pair_index]) → None

write_revision(design, run_dir, iteration) → pathlib.Path

Module Contents

class quantcore_circuits.codesign.ElementModel
add(k: float | None, v: float, knobs: dict[str, float] | None = None) → None

New FEM point: re-anchor, and refit the exponent when the knob has moved (the sign of the prior is kept: a gap knob lowers its capacitance). knobs: the point’s other knob values (re-anchors others).

invert(v: float) → float
predict(k: float) → float
value(knobs: dict[str, float]) → float

The element at knobs (primary and secondary knobs; a knob missing from knobs stays at its k0).

element: str
k0: float
knob: str | None
others: dict[str, list[float]]
p: float = 1.0
prior_p: float = 1.0
samples: list[tuple[float, float]] = []
v0: float
class quantcore_circuits.codesign.LoopStep
iteration: int
knobs: dict[str, float]
measured: dict[str, float]
objective: float
proposal: Proposal | None
residuals: dict[str, float]
revision: str | None
class quantcore_circuits.codesign.PairSurrogate

Surrogate for one transmon + λ/4 or λ/2 readout pair (module docstring).

elements(knobs: dict[str, float]) → dict[str, float]
predict(knobs: dict[str, float]) → dict[str, float]
to_json() → dict
a_um: float
b_um: float
c_coupler: ElementModel
c_island: ElementModel
cell: str = ''
cg: ElementModel
cj_fF: float
extra_length_um: float = 0.0
kind: str = 'lambda/4'
property knobs: dict[str, float]
length_knob: str | None = ''
length_um: float
lj_knob: str | None = ''
lj_nH: float
lj_scale: float = 1.0
notes: list[str] = []
pdk: str
qubit: str
resonator: str
class quantcore_circuits.codesign.Proposal
at_bounds: list[str] = []
elements: dict[str, float]
knobs: dict[str, float]
notes: list[str] = []
objective: float
predicted: dict[str, float]
residuals: dict[str, float]
start_knobs: dict[str, float]
quantcore_circuits.codesign.accept(revision: str | pathlib.Path, design_path: str | pathlib.Path) → pathlib.Path

Copy an accepted revision over the source design file (keeps a .bak).

quantcore_circuits.codesign.apply(design_source, knobs: dict[str, float], follow_ports: bool = True, reach_um: float = 300.0, plan=None)

Design with knobs set (instances’ params, junction fields, route fields; the paths of quantcore_circuits.optimise.get_knob()).

follow_ports: a geometry knob can move a port (a longer Xmon cross moves its flux port). Waypoints that sit on such a port’s axis within reach_um of it (e.g. a taper just before the port) move with the port, so the route keeps its shape instead of folding back. Only the instances whose parameters change (and those snapped to them) are planned again; plan: the source design’s plan when the caller has it (else it is planned here).

quantcore_circuits.codesign.copy_targets(targets: dict) → dict
quantcore_circuits.codesign.dressed_levels(ej_GHz: float, ec_GHz: float, f_r_GHz: float, g_n_MHz: float, nq: int = 5, nr: int = 5, ncut: int = 20) → dict

quantcore_circuits.circuit.hamiltonian.dressed() of the same model (charge-basis transmon truncated to nq levels + resonator + g_n n̂(a + a†), no RWA), built and diagonalised with numpy instead of QuTiP objects (the surrogate’s forward model runs it hundreds of times; same matrices, same bare-state labelling).

quantcore_circuits.codesign.forward(el: dict, cj_fF: float, a_um: float, b_um: float, pdk: str, qubit: str = 'Q', resonator: str = 'R', kind: str = 'lambda/4') → dict

Element values → dressed parameters, keyed like the targets. el["length_um"] is the whole line; kind its mode ("lambda/2": twice the λ/4 frequency of the same line, the λ/2 equivalent LC).

quantcore_circuits.codesign.propose(s: PairSurrogate, targets: dict, bounds: dict[str, tuple[float, float]] | None = None, anchor: dict[str, float] | None = None, refine: int = 3) → Proposal

Bounded least squares on the surrogate: knobs that put every target inside its tolerance.

anchor: values measured at the current knobs (e.g. the consensus’ chosen estimator). The surrogate’s predictions are scaled by measured / predicted at the start, so it corrects the measured gap even when its own model (the dressed spectrum) and the chosen estimator differ (a surrogate bias correction).

refine: a surrogate that can re-evaluate its LOM (surrogate_from_fill()) checks the solution there; when an element differs by more than REFINE_TOL its exponents are corrected along the move (a secant through the anchor and the proposal, so the anchor stays exact) and the problem is solved again, at most refine times. If it still differs (two knobs that interact strongly, e.g. a floating qubit’s pads and its connection pad), the last solve uses the LOM itself (ratio-scaled to the anchor) as the forward model, from the surrogate’s solution.

Only the knobs this pair’s targets ask for move (_free_knobs()); the others keep their value.

quantcore_circuits.codesign.propose_all(surrogates: list[PairSurrogate], targets: dict, bounds: dict[str, tuple[float, float]] | None = None, anchor: dict[str, float] | None = None) → Proposal

propose() for every pair, merged into one proposal.

The pairs share no knobs and the surrogate has no qubit–qubit terms, so each pair is solved on its own; the merged objective is the norm over all targets. Cross-couplings (buses, ZZ) need a joint model.

quantcore_circuits.codesign.run(design_source, evaluate, targets: dict, max_iter: int = 5, run_dir: str | pathlib.Path = 'build/codesign', bounds=None, estimator='scqubits', on_step=None) → list[LoopStep]

Co-design loop (module docstring). evaluate(design) -> FilledCircuit; on_step(LoopStep) is called after every iteration (e.g. to update the dashboard).

quantcore_circuits.codesign.surrogate_from_fill(filled: quantcore_circuits.circuit.fill.FilledCircuit, pair_index: int = 0, cache: dict | None = None) → PairSurrogate

Anchor a surrogate at the point of filled (FEM or the layout’s estimates; knob values read from its design).

A real circuit (filled.model) gets the generic surrogate of the module docstring; a bare FilledCircuit without a model (a test stand-in for the FEM step) the Xmon one: cross / claw with the prior exponents. cache: shared between the pairs of one circuit (each component’s LOM fragment is built once).

quantcore_circuits.codesign.surrogates_from_fill(filled: quantcore_circuits.circuit.fill.FilledCircuit, notes: list[str] | None = None) → list[PairSurrogate]

One surrogate per qubit (its first, readout, pair) — multi-qubit chips. A pair whose surrogate cannot be built is left out with a line in notes (when given; else the error is raised).

quantcore_circuits.codesign.unpaired_notes(filled: quantcore_circuits.circuit.fill.FilledCircuit) → list[str]

A line for every qubit (junction) of the circuit that has no readout pair (nothing reads it out, or only a bus that several qubits share): Propose cannot tune it.

quantcore_circuits.codesign.update_surrogate(s: PairSurrogate, filled: quantcore_circuits.circuit.fill.FilledCircuit, knobs: dict[str, float], pair_index: int = 0) → None
quantcore_circuits.codesign.write_revision(design, run_dir: str | pathlib.Path, iteration: int) → pathlib.Path
quantcore_circuits.codesign.COUPLER_KNOBS: dict[str, str]
quantcore_circuits.codesign.MIN_EXPONENT = 0.02
quantcore_circuits.codesign.PRIORS
quantcore_circuits.codesign.QUBIT_KNOBS: dict[str, tuple]
quantcore_circuits.codesign.REFINE_TOL = 0.001
quantcore_circuits.codesign.SENSITIVITY_STEP = 0.02
quantcore_circuits.codesign.TARGET_OF