quchip.chip.couplings¶

Coupling models for two-body interactions between devices.

Couplers own their local Hamiltonians. A coupling defines the interaction Hamiltonian on the two-device subspace H_int ∈ L(H_a ⊗ H_b); the engine embeds it into the full chip space at assembly time. Coupling strengths are in GHz.

References

Blais, A., Huang, R.-S., Wallraff, A., Girvin, S. M., & Schoelkopf, R. J.: Cavity quantum electrodynamics for superconducting electrical circuits: An architecture for quantum computation. PRA 69, 062320 (2004), Eq. 11.
Krantz, P., Kjaergaard, M., Yan, F., Orlando, T. P., Gustavsson, S., &: Oliver, W. D. A quantum engineer’s guide to superconducting qubits. Applied Physics Reviews 6, 021318 (2019), §V.
Blais, A., Grimsmo, A. L., Girvin, S. M., & Wallraff, A. Circuit quantum: electrodynamics. Rev. Mod. Phys. 93, 025005 (2021).

Classes

`Capacitive`(device_a, device_b[, g, label])	Capacitive (charge-charge) coupling between two devices.
`Coupling`(device_a, device_b, g, *[, op_a, ...])	Generic two-body coupling with a user-supplied interaction.
`CrossKerr`(device_a, device_b[, chi, label])	Cross-Kerr (dispersive) coupling `H_int = χ · n̂_a n̂_b`.
`TunableCapacitive`(device_a, device_b[, g_0, ...])	Capacitive coupling with a scheduled parametric pump.

class quchip.chip.couplings.Capacitive(device_a, device_b, g=unbound, *, label=None)[source]¶

Bases: CouplingModel

Capacitive (charge-charge) coupling between two devices.

The capacitive interaction between two electromagnetic modes takes the canonical dipole-dipole form in the raising/lowering basis:

Full form: H_int = g · (a + a†)(b + b†)
Band-RWA form: H_int = g · (a†b + a b†) (derived, not authored)

The coupling authors only the full form; RWA retaining the Δa + Δb == 0 bands of it, which is exactly g · (a†b + a b†). The RWA drops the counter-rotating terms a b and a† b†, valid when ω_a + ω_b ≫ g — the sum-frequency condition that makes those terms fast-rotating and hence negligible. This is distinct from the dispersive condition |ω_a − ω_b| ≫ g, which instead governs whether the retained exchange term g · (a†b + a b†) can be treated perturbatively (see TunableCapacitive / eliminate() for the dispersive reduction). Approximation is selected on the chip or for one solve, never on the coupling.

Parameters:

device_a (BaseDevice or str) – The two coupled devices, given as objects or label strings. Label-string references are late-bound via Chip.
device_b (BaseDevice or str) – The two coupled devices, given as objects or label strings. Label-string references are late-bound via Chip.
g (float) – Coupling strength in GHz. May be a traced JAX scalar for sweeps / autodiff.
label (str, optional) – Human-readable label; defaults to "cap_{n}".

References

Blais et al., PRA 69, 062320 (2004), Eq. 11. Krantz et al., Appl. Phys. Rev. 6, 021318 (2019), §V.B. Blais et al., Rev. Mod. Phys. 93, 025005 (2021), §II.B.

Examples

>>> from quchip import DuffingTransmon, Resonator, Capacitive
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q")
>>> r = Resonator(freq=7.0, levels=5, label="r")
>>> coupling = Capacitive(q, r, g=0.05)

folds_exchange: ClassVar[bool] = True¶

reduces_to_crosskerr: ClassVar[bool] = True¶

default_fit_observable: ClassVar[str] = 'cross_kerr'¶: Observable represented by this coupling’s declared scalar when the enclosing chip is passed to fit_a_dress as a dressed specification. Concrete coupling models override this when their inverse-design quantity is a dressed interaction observable.

g: Any = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='g', noise=False, kw_only=False, required=False)¶

default_dressed_target()[source]¶

Use exchange rate for an edge between non-computational modes.

Return type:: tuple[str, Any]

interaction(a, b, p)[source]¶

Return the full capacitive interaction g * (a + a†)(b + b†).

Parameters:

Return type:

PhysicsExpr

physics_notes()[source]¶

Return the declared capacitive interaction.

Return type:: list[str]

classmethod from_dict(d, device_a, device_b)[source]¶

Reconstruct a capacitive coupling from serialized state.

Parameters:

d (dict[str, Any])
device_a (BaseDevice)
device_b (BaseDevice)

Return type:

Capacitive

class quchip.chip.couplings.Coupling(device_a, device_b, g, *, op_a=None, op_b=None, interaction=None, label=None)[source]¶

Bases: BaseCoupling

Generic two-body coupling with a user-supplied interaction.

Use this escape hatch when no concrete coupling class models the desired physics (inductive, longitudinal, cross-Kerr test forms, synthetic spin-spin couplings, photonics-style beam-splitters, …). The user supplies the operator structure; this class only provides the g scaling, RWA pass-through, and bookkeeping.

Two mutually exclusive modes:

Product form — H_int = g · op_a(device_a) ⊗ op_b(device_b):

Coupling(q, r, g=0.02,
    op_a=lambda d: d.number_operator(),
    op_b=lambda d: d.number_operator())

Callable form — H_int = g · interaction(device_a, device_b, backend):

Coupling(q, r, g=0.02,
    interaction=lambda a, b, bk: (
        bk.tensor(bk.dag(a.lowering_operator()), b.lowering_operator())
        + bk.tensor(a.lowering_operator(), bk.dag(b.lowering_operator()))
    ))

The selected chip approximation is applied to the complete user-supplied operator after authored physics is assembled.

Parameters:

device_a (BaseDevice | str)
device_b (BaseDevice | str)
g (float)
op_a (Callable[[BaseDevice], Operator] | None)
op_b (Callable[[BaseDevice], Operator] | None)
interaction (Callable[[BaseDevice, BaseDevice, 'Backend'], Operator] | None)
label (str | None)

property coupling_strength: float¶: Scalar prefactor g supplied by the user.

interaction_hamiltonian()[source]¶

User-defined interaction on H_a ⊗ H_b, scaled by g.

Return type:: Any

physics_notes()[source]¶

Return notes describing the user-supplied interaction mode.

Return type:: list[str]

to_dict()[source]¶

Reject serialization because callables cannot be made persistent.

Return type:: dict[str, Any]

classmethod from_dict(d, device_a, device_b)[source]¶

Reject deserialization because callables cannot be reconstructed.

Parameters:

d (dict[str, Any])
device_a (BaseDevice)
device_b (BaseDevice)

Return type:

Coupling

class quchip.chip.couplings.CrossKerr(device_a, device_b, chi=unbound, *, label=None)[source]¶

Bases: CouplingModel

Cross-Kerr (dispersive) coupling H_int = χ · n̂_a n̂_b.

The effective diagonal interaction left when an exchange coupling is reduced in the dispersive regime — the natural coupling for effective readout chips (qubit + resonator + CrossKerr probed by an ordinary charge line) and static-ZZ modelling. Diagonal in both endpoints, so the RWA and full forms coincide and the term is frame-trivial.

Declared approximation: this is a uniform-pull model — one χ per edge, the same shift per endpoint excitation; per-level χ differences, dispersive breakdown at the critical photon number, and Purcell decay are not represented (fold Purcell into endpoint T1 via eliminate() when it matters).

Parameters:

device_a (BaseDevice or str) – The two coupled devices, as objects or label strings.
device_b (BaseDevice or str) – The two coupled devices, as objects or label strings.
chi (float) – Cross-Kerr shift in GHz per excitation pair, sign included (convention: full pull E₁₁ − E₁₀ − E₀₁ + E₀₀). May be a JAX tracer.
label (str, optional) – Defaults to "crosskerr_{n}".

is_effective: ClassVar[bool] = True¶

default_fit_observable: ClassVar[str] = 'cross_kerr'¶: Observable represented by this coupling’s declared scalar when the enclosing chip is passed to fit_a_dress as a dressed specification. Concrete coupling models override this when their inverse-design quantity is a dressed interaction observable.

chi: Any = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='\\chi', noise=False, kw_only=False, required=False)¶

interaction(a, b, p)[source]¶

Full form χ · n̂_a n̂_b (diagonal; identical under RWA).

Parameters:

Return type:

PhysicsExpr

parametric_interaction(a, b, p)[source]¶

Modulable structure n̂_a n̂_b — δχ(t) pumps ride this.

Parameters:

Return type:

PhysicsExpr

physics_notes()[source]¶

Return the declared dispersive-approximation provenance.

Return type:: list[str]

class quchip.chip.couplings.TunableCapacitive(device_a, device_b, g_0=unbound, *, label=None)[source]¶

Bases: CouplingModel

Capacitive coupling with a scheduled parametric pump.

Effective two-body interaction with a static mean coupling strength:

\[H_{\text{int}} \;=\; g_0\,\hat Q_a\hat Q_b\]

where \(\hat Q\) is each endpoint’s physical charge-like coupling operator (the position quadrature for a Fock model). The engine applies any requested RWA after local-basis materialization. \(g_0\) is the static coupling strength in GHz; it may be a JAX tracer and flows through jax.grad() without concretization.

Time-dependence is not a construction-time parameter: a ParametricDrive wired onto this coupling schedules a pump δ(t) via pump(), multiplying the same operator structure the static term uses (parametric_interaction()).

Parameters:

device_a (BaseDevice) – The two coupled devices.
device_b (BaseDevice) – The two coupled devices.
g_0 (float) – Static (mean) coupling strength in GHz. May be a JAX tracer.
label (str, optional) – Human-readable label; defaults to "tunable_cap_{n}".

Notes

The pump multiplies parametric_interaction(); frame and RWA logic stay in the engine. A pump tone at the qubits’ difference frequency |ω_a − ω_b| activates the parametric beam-splitter / iSWAP exchange, while a tone at the sum frequency ω_a + ω_b instead activates two-mode-squeezing (a†b†) terms. Either is expressed via the drive’s freq argument, not a coupling-side carrier.

References

McKay, Filipp, Mezzacapo, Magesan, Chow & Gambetta, Universal Gate for Fixed-Frequency Qubits via a Tunable Bus, Phys. Rev. Applied 6, 064007 (2016) — parametric two-qubit gates via coupler flux modulation.

Krantz et al., A quantum engineer’s guide to superconducting qubits, Appl. Phys. Rev. 6, 021318 (2019), §V.D — tunable couplers.

Examples

>>> from quchip import Chip, ControlEquipment, DuffingTransmon, ParametricDrive, TunableCapacitive
>>> q0 = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q0")
>>> q1 = DuffingTransmon(freq=5.2, anharmonicity=-0.22, levels=3, label="q1")
>>> tc = TunableCapacitive(q0, q1, g_0=0.0, label="tc")
>>> pump = ParametricDrive(tc, label="pump")
>>> chip = Chip([q0, q1], couplings=[tc], control_equipment=ControlEquipment([pump]))
>>> # seq.pump(tc, envelope=..., freq=...) schedules δg(t); see QuantumSequence.pump.

is_effective: ClassVar[bool] = True¶

folds_exchange: ClassVar[bool] = True¶

reduces_to_crosskerr: ClassVar[bool] = True¶

default_fit_observable: ClassVar[str] = 'cross_kerr'¶: Observable represented by this coupling’s declared scalar when the enclosing chip is passed to fit_a_dress as a dressed specification. Concrete coupling models override this when their inverse-design quantity is a dressed interaction observable.

g_0: Any = Parameter(default=unbound, positive=False, nonnegative=False, serialize=True, unit='GHz', symbol='g_0', noise=False, kw_only=False, required=False)¶

interaction(a, b, p)[source]¶

Static contribution g_0 · (a + a†)(b + b†).

Parameters:

Return type:

PhysicsExpr

parametric_interaction(a, b, p)[source]¶

Modulable charge-charge structure a scheduled pump multiplies.

Parameters:

Return type:

PhysicsExpr

physics_notes()[source]¶

Return the tunable-coupling and effective-model assumptions.

Return type:: list[str]