quchip.devices.protocols

Runtime-checkable Protocols for physical-operator drive dispatch.

Devices expose their physical charge / phase / flux operators in their authored local basis. Drives require these declarations so that their matrix elements stay physically explicit. The engine then applies the device’s resolved local-basis transformation together with every other attached operator.

These Protocols are typing.runtime_checkable(), so isinstance(device, ChargeCoupled) works at runtime. A device conforms when it defines the named method, without explicit subclassing. This includes EigenbasisDevice and external devices.

The accessors follow the common operator extension contract. Symbolic expressions are preferred, but matrices and pure JAX callables stay valid. The engine resolves every form through the same local-basis boundary.

Classes

ChargeCoupled(*args, **kwargs)	Device exposes the physical charge operator in its authored local basis.
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 authored local basis.

ChargeDrive dispatches against this Protocol and emits drives using charge_coupling_operator(). Capacitive couplings use the same operator through charge.

charge_coupling_operator()

Return the physical charge operator in the authored local basis.

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

Bases: Protocol

Device exposes the physical phase-space coupling operator.

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

phase_coupling_operator()

Return the physical phase-space coupling operator in the authored basis.

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

Bases: Protocol

Device exposes the physical flux-line coupling operator.

For a fluxonium this is \(\hat\varphi\). Used by FluxDrive.

flux_coupling_operator()

Return the physical flux-line coupling operator in the authored basis.

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. If so, it emits a TunableCapacitive, not a fixed Capacitive. FluxTunableTransmon satisfies this Protocol structurally, with no explicit subclassing.

frequency_at(flux)

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

Parameters:

flux (float or array-like) – Reduced flux bias in units of Phi_0.