quchip.devices.protocols

Runtime-checkable Protocols for physical-operator drive dispatch.

Circuit-level devices (fluxonium, charge-basis transmon) expose their physical charge / phase / flux operators in the truncated eigenbasis. Drives prefer these over the structural Fock-ladder fallback so that drive matrix elements are physically correct.

These Protocols are typing.runtime_checkable() so that isinstance(device, ChargeCoupled) works at runtime. A device conforms by defining the named method — no explicit subclassing required (matches EigenbasisDevice and any future third-party device).

The accessors return the operator as a dense, trace-safe array-like — not a backend-native operator — so a traced device parameter flows through the eigenbasis projection without concretization. Backend composition entry points (Backend.tensor, Backend.dag) coerce array-likes via coerce_operator(), so the accessors’ output composes directly with native operators.

See docs/superpowers/specs/2026-04-21-circuit-level-devices-design.md for the full rationale.

Classes

ChargeCoupled(*args, **kwargs)	Device exposes the physical charge operator in its truncated eigenbasis.
FluxCoupled(*args, **kwargs)	Device exposes the physical flux-line coupling operator.
FrequencyControlled(*args, **kwargs)	Device exposes a frequency-vs-flux relation, i.e. it is frequency-tunable.
PhaseCoupled(*args, **kwargs)	Device exposes the physical phase-space coupling operator.

class quchip.devices.protocols.ChargeCoupled(*args, **kwargs)

Bases: Protocol

Device exposes the physical charge operator in its truncated eigenbasis.

ChargeDrive dispatches against this Protocol and emits drives using charge_coupling_operator() rather than the structural 1j*(a - a†) from BaseDevice.lowering_operator().

charge_coupling_operator()

Return the physical charge operator in the truncated eigenbasis.

Return type:

Any

class quchip.devices.protocols.PhaseCoupled(*args, **kwargs)

Bases: Protocol

Device exposes the physical phase-space coupling operator.

Returns \(V^\dagger \sin\hat\varphi V\) on a charge-basis transmon (where \(\hat\varphi\) is not single-valued in the integer charge basis) or \(V^\dagger \hat\varphi V\) on a fluxonium (where \(\hat\varphi\) is well-defined). Used by PhaseDrive.

phase_coupling_operator()

Return the physical phase-space coupling operator in the eigenbasis.

Return type:

Any

class quchip.devices.protocols.FluxCoupled(*args, **kwargs)

Bases: Protocol

Device exposes the physical flux-line coupling operator.

For a fluxonium this is \(V^\dagger \hat\varphi V\); for a flux-tunable transmon (future follow-up) it will be a flux-modulated term. Used by FluxDrive.

flux_coupling_operator()

Return the physical flux-line coupling operator in the eigenbasis.

Return type:

Any

class quchip.devices.protocols.FrequencyControlled(*args, **kwargs)

Bases: Protocol

Device exposes a frequency-vs-flux relation, i.e. it is frequency-tunable.

reduce_device() uses isinstance(mode, FrequencyControlled) to decide whether an eliminated mode’s mediated-exchange fold should stay tunable — emitting a TunableCapacitive — rather than a fixed Capacitive. FluxTunableTransmon satisfies this Protocol structurally, with no explicit subclassing.

frequency_at(flux)

Return the device’s transition frequency at the given flux bias.

Parameters:

flux (Any)

Return type:

Any