quchip.control.drive¶

Drive classes and Hamiltonian channel definitions.

Drives model the classical control lines that couple a quantum device to external fields — microwave charge/phase drives on transmons, real-valued flux drives on tunable devices, and so on. Each drive owns its local Hamiltonian contribution: it exposes an operator and a DriveModulation tag that together describe how its line signal enters the system Hamiltonian. Signal transforms (delays, gains, crosstalk) live separately on ControlEquipment.

Drives are frame-agnostic: they emit a DriveSignalSpec in ordinary GHz and never construct engine IR nodes. Stage 2 of the engine is the sole place where the spec is composed with the resolved rotating frame into a SignalProgram.

Conventions:

Frequencies are GHz; times are ns.
Operators are returned in the device’s computational basis — embedding into the full chip Hilbert space is the engine’s job.

References

Krantz et al., A quantum engineer’s guide to superconducting qubits, APR 6, 021318 (2019) — microwave control of transmons (Sec. IV).
Koch et al., PRA 76, 042319 (2007) — charge vs flux noise and drives in the transmon regime.

Classes

`BaseDrive`([target, label, rwa])	Base class for classical control lines driving a single device.
`ChargeDrive`([target, label, rwa])	Microwave charge drive on a transmon-like device.
`DriveChannel`(operator, modulation)	One Hamiltonian channel exposed by a drive on a target device.
`FluxDrive`([target, label, rwa])	Real-valued flux drive coupling to \(\hat n\).
`ParametricDrive`(coupling, *[, label])	Control line pumping a modulable coupling's strength δ(t) in GHz.
`PhaseDrive`([target, label, rwa])	Microwave phase drive coupling to \(\hat a + \hat a^\dagger\).

class quchip.control.drive.DriveChannel(operator, modulation)[source]¶

Bases: object

One Hamiltonian channel exposed by a drive on a target device.

A channel pairs a local-basis operator with a DriveModulation tag that tells the engine how the channel’s coefficient is built from the drive’s line signal. A drive may expose multiple channels if, for example, it contributes both in-phase and quadrature couplings.

Parameters:

operator (Any)
modulation (DriveModulation)

operator: Any¶

modulation: DriveModulation¶

class quchip.control.drive.BaseDrive(target=None, *, label=None, rwa=None)[source]¶

Bases: Registrable

Base class for classical control lines driving a single device.

Drives own their local Hamiltonian contribution and are auto-labelled from their _type_prefix (e.g. charge_0, flux_0) unless label is given. Subclasses are auto-registered for serialization via the shared Registrable mixin.

Parameters:

target (BaseDevice | None) – Device to attach this drive to. May be connected later via connect().
label (str | None) – Optional explicit label; otherwise auto-generated.
rwa (bool | None) – Per-drive RWA override. None means follow the chip-level setting.

Examples

>>> from quchip import DuffingTransmon, ChargeDrive
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3)
>>> drive = ChargeDrive(target=q)
>>> drive.device_label == q.label
True

target_kind: ClassVar[str] = 'device'¶

"device" for drives targeting a device (the default), "edge" for drives targeting a coupling (see ParametricDrive).

Type:: Structural dispatch key for equipment/chip/sequence code

connect(device)[source]¶

Attach (or re-attach) this drive to device.

If the drive was previously attached to another device, it is detached from that device’s _connected_drives list so that only the new attachment is visible on the chip.

Parameters:: device (BaseDevice)
Return type:: None

property device_label: str | None¶: Label of the connected device, or None if unconnected.

property target_label: str | None¶

Label of this drive’s target, or None if unconnected.

Device-target drives (target_kind == "device") alias device_label; ParametricDrive overrides this to resolve its coupling target instead.

collapse_operators(device)[source]¶

Lindblad collapse operators contributed by this drive.

Default: none. Override to model drive-induced dissipation (e.g. photon loss on a drive line).

Parameters:: device (BaseDevice)
Return type:: list[Any]

local_channels(device)[source]¶

Return the Hamiltonian channels this drive exposes on device.

A simple single-channel drive declares _coupling_protocol, _coupling_accessor, _fallback, and _modulation; this method then dispatches generically — the device’s physical coupling operator when it conforms to the Protocol, the structural fallback otherwise. Returned operators are in the device’s local basis (no chip-wide embedding). Drives with a non-standard decomposition override this method instead.

Parameters:: device (BaseDevice)
Return type:: list[DriveChannel]

physics_notes()[source]¶

Return human-readable declarations of this drive’s approximations.

Returns the shared target/RWA lines plus this drive’s _coupling_note when declared. Subclasses with extra notes super().physics_notes() and append their own. Aggregated by Chip.physics_notes().

Return type:: list[str]

signal_spec(drive_op, device)[source]¶

Build the frame-agnostic signal spec for one scheduled pulse.

Parameters:

drive_op (DriveOp) – Scheduled pulse with envelope, start time, phase offset, and (for microwave drives) carrier frequency. Typed as Any because DriveOp lives in the engine IR, which drives must not import.
device (BaseDevice) – Target device. Unused in the default implementation, kept as an extension hook so subclasses can emit device-aware specs (e.g. flux-tunable drives that query the device’s tuning curve).

Returns:

Frame-agnostic description of the pulse — envelope, start time, duration, phase offset, and carrier frequency (or None for baseband drives) — built directly from drive_op, with no frame or IR commitment.

Return type:

DriveSignalSpec

Notes

The default implementation produces a DriveSignalSpec describing a phase-rotated, time-shifted, finite-duration envelope. Stage 2 of the engine turns the spec into the raw SignalProgram Scale(Shift(Window(env, 0, duration), start), exp(i·phi)) before applying the modulation dispatch.

copy(*, target=None)[source]¶

Return a shallow copy, optionally rebound to a new target.

Parameters:: target (BaseDevice | None)
Return type:: BaseDrive

to_dict()[source]¶

Serialize into a JSON-safe dictionary.

Return type:: dict[str, Any]

class quchip.control.drive.ChargeDrive(target=None, *, label=None, rwa=None)[source]¶

Bases: BaseDrive

Microwave charge drive on a transmon-like device.

Contributes the standard charge-coupling Hamiltonian

\[H_d(t) = \epsilon(t)\, i(\hat a - \hat a^\dagger)\]

with \(\epsilon(t)\) the (real-projected) mixed signal built by the SINGLE_TONE dispatch in stage 2. This is the canonical transmon microwave drive (Koch et al., PRA 76, 042319 (2007); Krantz et al., APR 6, 021318 (2019), Eq. 90).

Examples

>>> from quchip import DuffingTransmon, ChargeDrive, Gaussian
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3)
>>> drive = ChargeDrive(target=q)
>>> channels = drive.local_channels(q)
>>> len(channels) == 1
True

Parameters:

target (BaseDevice | None)
label (str | None)
rwa (bool | None)

class quchip.control.drive.PhaseDrive(target=None, *, label=None, rwa=None)[source]¶

Bases: BaseDrive

Microwave phase drive coupling to \(\hat a + \hat a^\dagger\).

Same carrier machinery as ChargeDrive but with an in-phase (rather than quadrature) coupling. Useful when modeling phase-noise channels or drives whose physical coupling is already referenced to the field quadrature. See Krantz et al. 2019, Sec. IV.A for the two conventions.

Parameters:

target (BaseDevice | None)
label (str | None)
rwa (bool | None)

class quchip.control.drive.FluxDrive(target=None, *, label=None, rwa=None)[source]¶

Bases: BaseDrive

Real-valued flux drive coupling to \(\hat n\).

Uses DIRECT_REAL — no carrier, no RWA — as appropriate for a baseband flux line that modulates the device frequency through its number operator (Koch et al. 2007, Sec. II; Krantz et al. 2019, Sec. V.A on flux tunability).

The rwa kwarg is rejected: applying RWA to a baseband drive is ill-defined.

Examples

>>> from quchip import DuffingTransmon, FluxDrive
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3)
>>> flux = FluxDrive(target=q)
>>> flux.rwa is None
True

Parameters:

target (BaseDevice | None)
label (str | None)
rwa (bool | None)

class quchip.control.drive.ParametricDrive(coupling, *, label=None, **kwargs)[source]¶

Bases: BaseDrive

Control line pumping a modulable coupling’s strength δ(t) in GHz.

Targets a coupling (object or label string; labels late-bind via Chip.connect()). The scheduled envelope is the real amplitude A(t): with an explicit freq the pump is δ(t) = A(t)·cos(2π·freq·t - phase); with freq omitted the pump is baseband, δ(t) = A(t) directly. The pump tone is never RWA-split — the coupling’s RWA policy selects the operator structure via its parametric hook; the tone keeps both sidebands (declared, the solver integrates the fast one).

Accepted couplings implement parametric_interaction(); a static coupling raises TypeError naming the hook.

Parameters:

coupling (BaseCoupling | str) – Modulable coupling to pump, given as the coupling object or its label. A string label late-binds to the coupling instance via Chip.connect().
label (str | None) – Optional explicit label; otherwise auto-generated from "parametric".
kwargs (Any)

Raises:

TypeError – coupling does not implement parametric_interaction() (a static coupling), or an unexpected keyword argument is passed.
ValueError – An explicit rwa keyword argument is passed — the RWA policy is fixed by the coupling’s parametric hook, not per-drive.

target_kind: ClassVar[str] = 'edge'¶

"device" for drives targeting a device (the default), "edge" for drives targeting a coupling (see ParametricDrive).

Type:: Structural dispatch key for equipment/chip/sequence code

property device_label: None¶

an edge pump has no device target.

Device-keyed paths (drive-noise collection, device-line bookkeeping) treat None as “skip this line”; edge code reads target_label instead.

Type:: Always None

property target_label: str¶: Label of the pumped coupling (resolves objects and label strings).

connect(coupling)[source]¶

Rebind to coupling (no device-side handshake — couplings hold no drive list).

Parameters:: coupling (Any)
Return type:: None

local_channels(device)[source]¶

Edge pumps have no device channel; stage 2 compiles them from the coupling’s hook.

Parameters:: device (Any)
Return type:: list[DriveChannel]