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 their matrix elements remain physically explicit; the engine then applies the device’s resolved local-basis transformation with every other attached operator.

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. This includes EigenbasisDevice and external devices.

The accessors follow the common operator extension contract: symbolic expressions are preferred, while matrices and pure JAX callables remain 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().

charge_coupling_operator()

Return the physical charge operator in the authored local basis.

Return type:

Any

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.

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 \(\hat\varphi\). Used by FluxDrive.

flux_coupling_operator()

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

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