quchip.chip.transformations.dispatch¶

Elimination target registry and the public eliminate dispatcher.

The unifying abstraction is the Chip type itself, not a base class: a transformation consumes a chip and produces a new one, so transformations compose through Chip (e.g. eliminate(fit_a_dress(chip).chip, "r").chip). ChipTransform is a thin structural protocol capturing only the .chip output that every transformation result exposes; FitADressResult already satisfies it with no changes.

eliminate performs model reduction: it removes a far-detuned mode (or an edge coupling) and replaces its effect on the survivors with ordinary owned-Hamiltonian physics — a Lamb shift folded into freq, Purcell decay folded into T1, mediated exchange folded into a coupling — so the engine never special-cases the reduction. The approximation is declared in EliminationResult.notes and EliminationResult.validity.

Each target kind is an EliminationTarget — a pair of (claims, reduce) closures registered in _ELIMINATION_TARGETS. The dispatcher scans the registry, hands the target to the first kind that claims it, and falls through to a clear error otherwise. The reductions themselves live in the sibling handler modules (quchip.chip.transformations.eliminate_device, quchip.chip.transformations.eliminate_coupling), which register at import time; the generic P/Q partitioning physics lives in quchip.chip.sw. This module owns only the registry and the dispatch, so a new reducible target kind registers here without touching either.

Functions

`eliminate`(chip, target, *[, method])	Reduce a far-detuned device or an edge coupling, returning a reduced chip.
`register_elimination_target`(target)	Register an `EliminationTarget` kind for `eliminate()` to dispatch on.

Classes

EliminationTarget(kind, claims, reduce)

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

class quchip.chip.transformations.dispatch.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.dispatch.register_elimination_target(target)[source]¶

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

quchip.chip.transformations.dispatch.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']