quantcore_circuits.codesign =========================== .. py:module:: quantcore_circuits.codesign .. autoapi-nested-parse:: 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 (:func:`~quantcore_circuits.circuit.fill.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 (:data:`QUBIT_KNOBS`: the island-capacitance knob, the coupler knob for C_g; ```` 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.`` ``CircularTransmonSingleIsland`` ``r_island`` ``couplers_arc_amplitude.`` ``ConcentricTransmon`` ``r_inner`` ``couplers_arc_amplitude.`` ``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..pad_width`` ``metal:TransmonPocket`` (CL, 6, Teeth) ``pad_width`` ``connection_pads..pad_width`` ``metal:TransmonCross`` (FL) ``cross_length`` ``connection_pads..claw_length`` ``metal:TransmonStar`` ``arm_length`` ``connection_pads..claw_length`` ``metal:TransmonConcentric`` ``gap`` ``res_s`` ``metal:TransmonConcentricType2`` ``gap`` ``finger__length`` ``metal:TransmonInterdigitated`` ``finger_height`` ``cc_width`` (bus: ``cc_top*_width``) ``metal:StarQubit`` ``center_radius`` ``gap_readout`` / ``gap_couplers`` coupler cells (:data:`COUPLER_KNOBS`) ``PadCoupler.pad_height`` ``GatemonCoupler.coupling_capacitance`` ======================================= ================================ ======================================= ``L_J``: ``.junction.Lj_nH`` when the design sets it (a drawn junction without a design value is not tuned). Resonator: the TLres knob (``.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 (:class:`~quantcore_circuits.circuit. fill.TransmonReadout`, λ/4 or λ/2) → the dressed spectrum of :mod:`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//revisions/rev.json``); the source design is never touched unless :func:`accept` is called. **Loop (L2).** :func:`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 → :func:`circuit.fill.fill`), or any stand-in for testing. Attributes ---------- .. autoapisummary:: quantcore_circuits.codesign.COUPLER_KNOBS quantcore_circuits.codesign.MIN_EXPONENT quantcore_circuits.codesign.PRIORS quantcore_circuits.codesign.QUBIT_KNOBS quantcore_circuits.codesign.REFINE_TOL quantcore_circuits.codesign.SENSITIVITY_STEP quantcore_circuits.codesign.TARGET_OF Classes ------- .. autoapisummary:: quantcore_circuits.codesign.ElementModel quantcore_circuits.codesign.LoopStep quantcore_circuits.codesign.PairSurrogate quantcore_circuits.codesign.Proposal Functions --------- .. autoapisummary:: quantcore_circuits.codesign.accept quantcore_circuits.codesign.apply quantcore_circuits.codesign.copy_targets quantcore_circuits.codesign.dressed_levels quantcore_circuits.codesign.forward quantcore_circuits.codesign.propose quantcore_circuits.codesign.propose_all quantcore_circuits.codesign.run quantcore_circuits.codesign.surrogate_from_fill quantcore_circuits.codesign.surrogates_from_fill quantcore_circuits.codesign.unpaired_notes quantcore_circuits.codesign.update_surrogate quantcore_circuits.codesign.write_revision Module Contents --------------- .. py:class:: ElementModel .. py:method:: 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``). .. py:method:: invert(v: float) -> float .. py:method:: predict(k: float) -> float .. py:method:: value(knobs: dict[str, float]) -> float The element at ``knobs`` (primary and secondary knobs; a knob missing from ``knobs`` stays at its k0). .. py:attribute:: element :type: str .. py:attribute:: k0 :type: float .. py:attribute:: knob :type: str | None .. py:attribute:: others :type: dict[str, list[float]] .. py:attribute:: p :type: float :value: 1.0 .. py:attribute:: prior_p :type: float :value: 1.0 .. py:attribute:: samples :type: list[tuple[float, float]] :value: [] .. py:attribute:: v0 :type: float .. py:class:: LoopStep .. py:attribute:: iteration :type: int .. py:attribute:: knobs :type: dict[str, float] .. py:attribute:: measured :type: dict[str, float] .. py:attribute:: objective :type: float .. py:attribute:: proposal :type: Proposal | None .. py:attribute:: residuals :type: dict[str, float] .. py:attribute:: revision :type: str | None .. py:class:: PairSurrogate Surrogate for one transmon + λ/4 or λ/2 readout pair (module docstring). .. py:method:: elements(knobs: dict[str, float]) -> dict[str, float] .. py:method:: predict(knobs: dict[str, float]) -> dict[str, float] .. py:method:: to_json() -> dict .. py:attribute:: a_um :type: float .. py:attribute:: b_um :type: float .. py:attribute:: c_coupler :type: ElementModel .. py:attribute:: c_island :type: ElementModel .. py:attribute:: cell :type: str :value: '' .. py:attribute:: cg :type: ElementModel .. py:attribute:: cj_fF :type: float .. py:attribute:: extra_length_um :type: float :value: 0.0 .. py:attribute:: kind :type: str :value: 'lambda/4' .. py:property:: knobs :type: dict[str, float] .. py:attribute:: length_knob :type: str | None :value: '' .. py:attribute:: length_um :type: float .. py:attribute:: lj_knob :type: str | None :value: '' .. py:attribute:: lj_nH :type: float .. py:attribute:: lj_scale :type: float :value: 1.0 .. py:attribute:: notes :type: list[str] :value: [] .. py:attribute:: pdk :type: str .. py:attribute:: qubit :type: str .. py:attribute:: resonator :type: str .. py:class:: Proposal .. py:attribute:: at_bounds :type: list[str] :value: [] .. py:attribute:: elements :type: dict[str, float] .. py:attribute:: knobs :type: dict[str, float] .. py:attribute:: notes :type: list[str] :value: [] .. py:attribute:: objective :type: float .. py:attribute:: predicted :type: dict[str, float] .. py:attribute:: residuals :type: dict[str, float] .. py:attribute:: start_knobs :type: dict[str, float] .. py:function:: accept(revision: str | pathlib.Path, design_path: str | pathlib.Path) -> pathlib.Path Copy an accepted revision over the source design file (keeps a ``.bak``). .. py:function:: 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 :func:`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). .. py:function:: copy_targets(targets: dict) -> dict .. py:function:: 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 :func:`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). .. py:function:: 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). .. py:function:: 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 (:func:`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 (:func:`_free_knobs`); the others keep their value. .. py:function:: propose_all(surrogates: list[PairSurrogate], targets: dict, bounds: dict[str, tuple[float, float]] | None = None, anchor: dict[str, float] | None = None) -> Proposal :func:`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. .. py:function:: 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). .. py:function:: 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). .. py:function:: 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). .. py:function:: 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. .. py:function:: update_surrogate(s: PairSurrogate, filled: quantcore_circuits.circuit.fill.FilledCircuit, knobs: dict[str, float], pair_index: int = 0) -> None .. py:function:: write_revision(design, run_dir: str | pathlib.Path, iteration: int) -> pathlib.Path .. py:data:: COUPLER_KNOBS :type: dict[str, str] .. py:data:: MIN_EXPONENT :value: 0.02 .. py:data:: PRIORS .. py:data:: QUBIT_KNOBS :type: dict[str, tuple] .. py:data:: REFINE_TOL :value: 0.001 .. py:data:: SENSITIVITY_STEP :value: 0.02 .. py:data:: TARGET_OF