quchip.chip.transformations¶

Model reduction: eliminate() and its device/coupling target registry.

Public surface only; the extension seams (register_elimination_target() for a new target kind, register_reduction_method() for a new device reduction route) are documented on quchip.chip.transformations.dispatch and quchip.chip.transformations.methods respectively. Importing this package runs the shipped handlers’ self-registration (below) — the same side-effect-import pattern as quchip.chip.retarget’s rule registry.

class quchip.chip.transformations.ActivePatchResult(chip, sequence, active_labels, eliminated_labels, steps, notes)[source]¶

Bases: object

A reduced patch chip, the re-bound sequence, and the reduction’s honesty record.

Parameters:

chip (Any)
sequence (Any)
active_labels (tuple[str, ...])
eliminated_labels (tuple[str, ...])
steps (tuple)
notes (tuple[str, ...])

chip¶

The patch chip: schedule-active devices plus whatever spectators active_patch() could not eliminate (unreachable, or where elimination itself declined — see notes).

Type:: Any

sequence¶

A QuantumSequence bound to chip, replaying the source sequence’s entries verbatim.

Type:: Any

active_labels¶

Sorted schedule-active device labels (never eliminated).

Type:: tuple[str, …]

eliminated_labels¶

Device labels actually folded away, in elimination order (farthest-from-active first).

Type:: tuple[str, …]

steps¶

The EliminationResult from each successful eliminate() call, verbatim and in eliminated_labels order — reshape nothing here; read .validity/.effective_params off the step objects through the convenience properties below.

Type:: tuple

notes¶

Every explicitly dropped or deferred piece of physics: unreachable spectators left in place, control lines stripped as unused, and (if elimination itself couldn’t proceed past some spectator) why the reduction stopped early — plus every step’s own notes.

Type:: tuple[str, …]

chip: Any¶

sequence: Any¶

active_labels: tuple[str, ...]¶

eliminated_labels: tuple[str, ...]¶

steps: tuple¶

notes: tuple[str, ...]¶

property validity: dict[str, Any]¶: {eliminated label: that step's .validity} — verbatim, per-coupling shape untouched.

property effective_params: dict[str, Any]¶: {eliminated label: that step's .effective_params} — verbatim, per-survivor shape untouched.

simulate(**kwargs)[source]¶

Solve the patch sequence (automatic partitioning still applies inside).

Parameters:: kwargs (Any)
Return type:: Any

quchip.chip.transformations.active_patch(sequence, *, hops=1, method='sw')[source]¶

Reduce a chip to its schedule-active patch by eliminating spectators.

Spectators are eliminated one at a time via eliminate(), farthest-from-active first; every step’s validity metrics ride on the result untouched. Explicit opt-in — this approximates (Schrieffer-Wolff, or the exact dressed-spectrum route under method="exact"), unlike the exact automatic partitioning simulate() performs internally at solve time.

The elimination order and reachability are recomputed from the current reduced chip before every step, not just once up front: a fold can only ever add a bridging edge between the eliminated mode’s neighbors, never remove one, so a label’s distance from the active set can shorten but never make a previously reachable label unreachable — still, reading the graph fresh each time means a label that has already been folded away is never re-considered, and the order always reflects what eliminate will actually see. Bridging edges created by earlier folds may be Capacitive edges carrying g or TunableCapacitive edges carrying g_0. Both fold onward, so cycles among spectators reduce all the way down. If eliminate still declines a step (its typed NotImplementedError signal for an unsupported elimination — e.g. a Purcell decay fold onto a survivor that carries thermal occupation, which no collapse-channel API can represent without inventing physics that was never present), the reduction stops there: everything eliminated so far stays folded, and the remaining spectators — including the one that failed — are left on the patch chip untouched, with the reason recorded in notes.

Parameters:

sequence (QuantumSequence) – The schedule to reduce around.
hops (int) – Coupling-graph hops the active set expands beyond the scheduled targets (see active_labels()).
method (str) – Forwarded to eliminate() for every device elimination.

Return type:

ActivePatchResult

class quchip.chip.transformations.ChipTransform(*args, **kwargs)[source]¶

Bases: Protocol

Structural protocol for any transformation result that yields a chip.

property chip: Chip¶

class quchip.chip.transformations.EliminationResult(chip, effective_params, validity, notes=<factory>)[source]¶

Bases: object

Store the result of eliminate().

Parameters:

chip (Chip)
effective_params (dict[str, Any])
validity (dict[str, Any])
notes (list[str])

chip¶

The reduced chip (eliminated mode removed; effect folded into ordinary surviving devices). The input chip is never mutated.

Type:: Chip

effective_params¶

Derived quantities per survivor: {label: {"lamb_shift", "purcell_rate", "freq_after", "chi", "kappa"}} (GHz for frequencies, 1/ns for rates). chi is the dispersive pull χ_pull ≡ f_mode(survivor in |1⟩) − f_mode(survivor in |0⟩) — the full resonator pull per survivor excitation, i.e. 2× the σ_z-convention χ of H_disp = (ω_r + χσ_z)a†a. For a mode touching more than one survivor, the mode is a bus / coupler, not a readout mode, so chi is reported as 0.0 for every survivor. Otherwise chi is a deferred entry: computed from the input chip’s dressed spectrum (one full-chip diagonalization) on the first ["chi"] access and cached, so reductions that never read it stay pure algebra (LazyEffectiveParams); gradients through it follow Chip.dispersive_shift’s backend rule, while every other entry remains backend-independent algebra. kappa is the eliminated mode’s own decay rate, from its intrinsic_decay_rate() (e.g. a resonator’s combined 2π·f_mode/Q photon loss plus 1/T1), or 0.0 when the mode declares no decay channel.

A mode touching two or more survivors additionally emits an "exchange" entry describing the mediated survivor-survivor coupling(s) derived from the Sylvester/exact pair extraction (quchip.chip.sw). For exactly two survivors (the bridge case) this is a single dict: {"j_eff", "dJ_domega_c", "between", "folded_into", "zz", "pathways"}. For three or more survivors, every survivor pair induces its own mediated exchange, so "exchange" is instead a dict keyed by the pair (label_a, label_b), each value the same per-pair schema. In both cases: j_eff is the mediated exchange J = g_a g_b / 2 · (1/Δ_a + 1/Δ_b) (F. Yan et al., Phys. Rev. Applied 10, 054062 (2018)), read off the method="sw"/"exact" pair extraction; dJ_domega_c is its analytic derivative w.r.t. the eliminated mode’s frequency (used by the flux-drive retarget rule); folded_into is the label of the effective edge the exchange landed on (an existing direct coupling between the pair, or a freshly emitted Capacitive or TunableCapacitive); zz is the exact residual ZZ between the pair (method="exact" only — None under "sw", where it is a higher-order correction not represented); pathways is the top virtual-state attribution of the exchange (method="sw" only, from quchip.chip.sw.pathway_attribution() — None under "exact", which has no perturbative generator to attribute).

Type:: dict[str, Any]

validity¶

Per eliminated coupling: {coupling_label: {"g_over_delta", "is_valid", "min_block_gap"}}. min_block_gap is the smallest bare-energy gap the Sylvester generator crossed for this mode (quchip.chip.sw.sylvester_generator()), shared across every coupling touching the mode. When eliminate runs under jax.jit/grad, is_valid (g_over_delta < 0.1) is a traced boolean, not a Python bool — read it outside the traced region, or branch on it with jnp.where rather than if.

Type:: dict[str, Any]

notes¶

Explicitly dropped physics (counter-rotating, transients, higher order).

Type:: list[str]

Every mapping above is a :class:`~quchip.utils.labeling.LabelKeyedDict`

the device or coupling *object* is as good a key as its label, and pair

keys match in either order —

``res.effective_params[q1]``, ``res.validity[leg]``, and

``exchange[(q1, q0)]`` all resolve.

chip: Chip¶

effective_params: dict[str, Any]¶

validity: dict[str, Any]¶

notes: list[str]¶

describe()[source]¶

Plain-text fold report: every fold stated explicitly, before -> after.

Per survivor: freq (and T1 when either side carries one), each Lamb-shifted/Purcell-folded value read back from effective_params rather than a stored “before” chip — freq_before = freq_after - lamb_shift and T1_before from purcell_rate are exact identities of how eliminate() derives freq_after/T1, not an approximation. Multi-survivor targets add the emitted exchange edge (Yan-formula tag) and a ZZ line (placeholder under method="sw", the exact residual under method="exact"); any control-line retarget and the per-coupling validity verdict follow. Traced parameters render as <traced> and are never concretized; for use outside jit/grad regions, like every other describe() in the package.

Return type:: str

quchip.chip.transformations.eliminate(chip, target, *, method='sw')[source]¶

Reduce a far-detuned device or an edge coupling, returning a reduced chip.

target is resolved against the chip’s device and coupling namespaces (disjoint by construction — Chip rejects a coupling label that collides with a device label) and dispatches to one of two model reductions:

Device target — adiabatic elimination of a far-detuned mode, via quchip.chip.sw. A mode touching one survivor folds into a Lamb shift (and a Purcell channel when the mode dissipates). A mode touching two or more survivors — bus / tunable-coupler (bridge) or several at once — additionally induces a mediated exchange J = g_a g_b / 2 · (1/Δ_a + 1/Δ_b) between every survivor pair (with ∂J/∂ω_c recorded alongside it), folded into the direct coupling between that pair when one exists or added as a new edge otherwise. A fixed eliminated mode emits a Capacitive; a mode that declares frequency control, has a retargeted flux line, or folds into an already-modulable edge emits a TunableCapacitive. At a tunable coupler’s idle point, its g_0 is the net coupling the pair feels, including any direct-edge cancellation. Eliminating several couplers is sequential composition: eliminate(eliminate(chip, "TC1").chip, "TC2").
Coupling target — dispersive reduction of an exchange edge to its dressed cross-Kerr shift: both endpoint devices survive (Lamb-shifted), and the coupling itself is replaced by a CrossKerr carrying the dressed pull (see reduce_coupling()). This is the effective-readout-chip flow — reduce a qubit-resonator exchange edge to the diagonal interaction an ordinary charge line probes. method has no effect here: no mode is removed, so the reduction always reads the chip’s exact dressed spectrum.

Parameters:

chip (Chip) – Source chip (never mutated).
target (Any) – The device or coupling to eliminate — label string or object.
method (str) – Device targets only. "sw" (default) is the 2nd-order Schrieffer-Wolff reduction (Bravyi, DiVincenzo & Loss, Ann. Phys. 326, 2793 (2011)) — cheap, differentiable, and what every effective parameter above is derived from perturbatively. "exact" instead reads the reduced parameters off the chip’s exact dressed spectrum (exact-from-dressing, quchip.chip.sw.exact_reduction()) — exact kept-block energies (what residual ZZ needs) at the cost of a full diagonalization, and it raises when near-degenerate dressed states make the bare labeling ambiguous. Any other value raises ValueError.

Return type:

EliminationResult

Examples

>>> from quchip import DuffingTransmon, Resonator, Capacitive, Chip
>>> from quchip.chip.transformations import eliminate
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q")
>>> r = Resonator(freq=7.0, levels=5, label="r")
>>> chip = Chip([q, r], couplings=[Capacitive(q, r, g=0.05)])
>>> result = eliminate(chip, r)          # r removed; Lamb shift folded into q.freq
>>> reduced = result.chip
>>> [d.label for d in reduced.devices]
['q']

class quchip.chip.transformations.EliminationTarget(kind, claims, reduce)[source]¶

Bases: object

One registered elimination target kind — how it recognizes a target and reduces it.

A new kind registers an instance with register_elimination_target() at its handler module’s bottom; that module must be imported for the side effect (the package __init__ does this for the shipped handlers) — the same registration ritual as register_retarget_rule().

Parameters:

kind (str)
claims (Callable[[Any, Any], bool])
reduce (Callable[[Any, Any, str], EliminationResult])

kind¶

A short label for the target kind ("device", "coupling"), for diagnostics.

Type:: str

claims¶

claims(chip, target) -> bool: whether this kind owns target on chip (e.g. the label names a device, or a coupling). The device and coupling namespaces are disjoint by construction, so at most one kind claims any target.

Type:: Callable[[Any, Any], bool]

reduce¶

reduce(chip, target, method) -> EliminationResult: performs the reduction. method is the already-validated route string (a handler that has no notion of a route ignores it).

Type:: Callable[[Any, Any, str], quchip.chip.transformations.result.EliminationResult]

kind: str¶

claims: Callable[[Any, Any], bool]¶

reduce: Callable[[Any, Any, str], EliminationResult]¶

quchip.chip.transformations.register_elimination_target(target)[source]¶

Parameters:: target (EliminationTarget)
Return type:: None

quchip.chip.transformations.register_reduction_method(method)[source]¶

Parameters:: method (ReductionMethod)
Return type:: None

Modules

`active_patch`(sequence, *[, hops, method])	Reduce a chip to its schedule-active patch by eliminating spectators.
`dispatch`	Elimination target registry and the public `eliminate` dispatcher.
`eliminate_coupling`	Coupling-target elimination: reduce an exchange edge to its dressed cross-Kerr.
`eliminate_device`	Device-target elimination: adiabatic reduction of a far-detuned mode.
`methods`	Reduction-method registry for device elimination (extension seam).
`plumbing`	Shared control-plane and chip-rebuild plumbing for `quchip.chip.transformations`.
`result`	Result and typing layer for `quchip.chip.transformations`.