quchip.control

Classical control surface: lines, signal chain, and envelopes.

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

Bases: Registrable

Base class for classical control lines attached to one quantum target.

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, BaseCoupling, str, or None) – Target accepted by the concrete drive. A DeviceDrive targets a device; a CouplingDrive targets a coupling. The target may be connected later or resolved by label through Chip.

  • label (str | None) – Optional explicit label; otherwise auto-generated.

  • params (Any)

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: Any
label: Any
connect(target)[source]

Attach this device-drive implementation to target.

If previously attached, the drive is removed from the old device’s _connected_drives list. CouplingDrive overrides this handshake because couplings do not own connected-drive lists.

Parameters:

target (Any)

Return type:

None

parameter_values()[source]

Return drive-owned bindable values declared by the subclass.

Return type:

dict[str, Any]

set_parameter_value(name, value)[source]

Apply one drive-owned value on an isolated drive copy.

Parameters:
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 alias device_label; ParametricDrive resolves its coupling target instead.

dissipation(target, op, p)[source]

Return target-local Lindblad channels contributed by this line.

Parameters:
Return type:

tuple[CollapseChannel, …]

signal(pulse, target)[source]

Build the complete scheduled analytic signal for one pulse.

Parameters:
Return type:

AnalyticSignal

hamiltonian(target, signal)[source]

Map a delivered classical signal to target-local quantum physics.

Parameters:
Return type:

Any

physics_notes()[source]

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

Subclasses append their physical coupling details to the shared target line. Aggregated by Chip.physics_notes().

Return type:

list[str]

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.AnalyticSignal(program, carrier=None, phase_reference=None)[source]

Bases: object

Complete complex classical signal delivered on one control line.

program includes the envelope, schedule timing and phase, and any carrier. Classical equipment transforms this complete value before a drive maps its physical quadratures into the quantum Hamiltonian.

Parameters:
program: SignalNode
carrier: Any | None = None
phase_reference: Any | None = None
classmethod from_pulse(pulse)[source]

Build the complete scheduled signal for one pulse record.

Parameters:

pulse (Any)

Return type:

AnalyticSignal

property i: PhysicsExpr

In-phase physical quadrature of the delivered signal.

property q: PhysicsExpr

Quadrature-phase physical component of the delivered signal.

evaluate(t, *, xp=None)[source]

Evaluate the complete complex signal at time t.

Parameters:
Return type:

Any

shifted(delta_t)[source]

Return the signal delayed by delta_t ns.

Parameters:

delta_t (Any)

Return type:

AnalyticSignal

scaled(factor)[source]

Return the signal multiplied by a complex factor.

Parameters:

factor (Any)

Return type:

AnalyticSignal

polar_scaled(amplitude, theta)[source]

Return the signal multiplied by amplitude * exp(i theta).

Parameters:
Return type:

AnalyticSignal

class quchip.control.CouplingDrive(target=None, *, label=None)[source]

Bases: BaseDrive

Drive authoring base for a two-endpoint coupling Hamiltonian.

Subclasses implement hamiltonian() for the coupling physics they accept. The base class imposes no parametric-interaction requirement.

Parameters:
property device_label: None

Return None because a coupling drive has no device target.

property target_label: str | None

Label of the connected coupling, if any.

connect(target)[source]

Attach this line to a coupling without a device-side handshake.

Parameters:

target (Any)

Return type:

None

class quchip.control.DeviceDrive(target=None, *, label=None)[source]

Bases: BaseDrive

Drive authoring base for a device-local Hamiltonian.

Parameters:
class quchip.control.SignalTransform[source]

Bases: Registrable, ABC

Abstract base for signal-map transforms, auto-registered for serialization.

The type registry, the {"type": ...} to_dict() stamp, and the from_dict dispatch are owned by the shared Registrable mixin; the parameter-less default reconstruction (cls()) covers transforms that carry no persisted state, while payload-carrying transforms override to_dict() / from_dict().

parameter_values()[source]

Return transform-owned bindable values declared by the subclass.

Return type:

dict[str, Any]

with_parameter_value(name, value)[source]

Return this transform with one declared numerical value replaced.

Parameters:
Return type:

SignalTransform

abstractmethod apply(signals)[source]

Return the transformed signal map.

Parameters:

signals (dict[tuple[str, int], AnalyticSignal])

Return type:

dict[tuple[str, int], AnalyticSignal]

referenced_lines()[source]

Return control-line labels referenced by this transform.

Return type:

tuple[str, …]

without_line(line)[source]

Return this transform without line, or None when it must be dropped.

Parameters:

line (str)

Return type:

SignalTransform | None

class quchip.control.Crosstalk(source, victim, beta, theta=0.0, delay=0.0)[source]

Bases: SignalTransform

Linear crosstalk from a source drive line onto a victim line.

For each scheduled operation on the source line, adds

\[\beta\, e^{i\theta}\, s_\mathrm{src}(t - \Delta t)\]

onto the victim line. \(s_\mathrm{src}\) is the complete source signal, including its carrier, phase, and both quadratures. Delaying it therefore includes the carrier phase \(2\pi f\Delta t\) without a separate correction (Balewski et al., arXiv:2502.05362; Sheldon et al., PRA 93, 060302 (2016); Sarovar et al., Quantum 4, 321 (2020)).

Parameters:

  • source (str | BaseDrive) – Source drive or its label.

  • victim (str | BaseDrive) – Victim drive or its label.

  • beta (float) – Leakage amplitude (dimensionless).

  • theta (float) – Phase shift applied to the leaked signal, radians.

  • delay (float) – Time shift of the leaked signal relative to the source, ns.

source: str
victim: str
beta: float
theta: float = 0.0
delay: float = 0.0
apply(signals)[source]

Add the phase-rotated, delayed source signal onto the victim line.

Parameters:

signals (dict[tuple[str, int], AnalyticSignal])

Return type:

dict[tuple[str, int], AnalyticSignal]

referenced_lines()[source]

Return control-line labels referenced by this transform.

Return type:

tuple[str, …]

to_dict()[source]

Serialize into a JSON-safe dictionary.

Return type:

dict[str, Any]

classmethod from_dict(d)[source]

Reconstruct from to_dict() output.

On the registry root, dispatch to the concrete subclass named by data["type"] (forwarding *args / **kwargs). On a concrete subclass, defer to _from_dict_payload(). Concrete subclasses that carry payload override this method directly.

Parameters:

d (dict[str, Any])

Return type:

Crosstalk

class quchip.control.Delay(line, delta_t)[source]

Bases: SignalTransform

Shift every signal on line in time by delta_t ns.

Parameters:
line: str
delta_t: float
apply(signals)[source]

Time-shift every signal on line by delta_t ns.

Parameters:

signals (dict[tuple[str, int], AnalyticSignal])

Return type:

dict[tuple[str, int], AnalyticSignal]

referenced_lines()[source]

Return control-line labels referenced by this transform.

Return type:

tuple[str, …]

to_dict()[source]

Serialize into a JSON-safe dictionary.

Return type:

dict[str, Any]

classmethod from_dict(d)[source]

Reconstruct from to_dict() output.

On the registry root, dispatch to the concrete subclass named by data["type"] (forwarding *args / **kwargs). On a concrete subclass, defer to _from_dict_payload(). Concrete subclasses that carry payload override this method directly.

Parameters:

d (dict[str, Any])

Return type:

Delay

class quchip.control.Gain(line, factor)[source]

Bases: SignalTransform

Scale every signal on line by a complex factor.

Parameters:
line: str
factor: complex
apply(signals)[source]

Scale every signal on line by the complex factor.

Parameters:

signals (dict[tuple[str, int], AnalyticSignal])

Return type:

dict[tuple[str, int], AnalyticSignal]

referenced_lines()[source]

Return control-line labels referenced by this transform.

Return type:

tuple[str, …]

to_dict()[source]

Serialize into a JSON-safe dictionary.

Return type:

dict[str, Any]

classmethod from_dict(d)[source]

Reconstruct from to_dict() output.

On the registry root, dispatch to the concrete subclass named by data["type"] (forwarding *args / **kwargs). On a concrete subclass, defer to _from_dict_payload(). Concrete subclasses that carry payload override this method directly.

Parameters:

d (dict[str, Any])

Return type:

Gain

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

Bases: DeviceDrive

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 in-phase quadrature of the complete delivered classical signal. 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
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3)
>>> drive = ChargeDrive(target=q)
>>> drive.target_label == q.label
True
Parameters:
hamiltonian(device, signal)[source]

Map a delivered classical signal to target-local quantum physics.

Parameters:
Return type:

Any

physics_notes()[source]

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

Subclasses append their physical coupling details to the shared target line. Aggregated by Chip.physics_notes().

Return type:

list[str]

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

Bases: DeviceDrive

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

The delivered signal’s in-phase quadrature modulates the device frequency through its flux-coupling operator (Koch et al. 2007, Sec. II; Krantz et al. 2019, Sec. V.A on flux tunability).

Examples

>>> from quchip import DuffingTransmon, FluxDrive
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3)
>>> flux = FluxDrive(target=q)
>>> flux.target_label == q.label
True
Parameters:
hamiltonian(device, signal)[source]

Map a delivered classical signal to target-local quantum physics.

Parameters:
Return type:

Any

physics_notes()[source]

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

Subclasses append their physical coupling details to the shared target line. Aggregated by Chip.physics_notes().

Return type:

list[str]

class quchip.control.ParametricDrive(target=None, *, label=None)[source]

Bases: CouplingDrive

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 carrier the pump is δ(t) = A(t)·cos(2π·freq·t - phase); with freq omitted the pump is carrier-free, δ(t) = A(t) directly. Approximation belongs to the chip’s selected engine strategy, not to the drive.

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".

  • target (Any)

Raises:

TypeError – coupling does not implement parametric_interaction() (a static coupling), or an unexpected keyword argument is passed.

connect(coupling)[source]

Attach this line after confirming that the coupling is modulable.

Parameters:

coupling (Any)

Return type:

None

hamiltonian(coupling, signal)[source]

Map a delivered classical signal to target-local quantum physics.

Parameters:
Return type:

Any

physics_notes()[source]

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

Subclasses append their physical coupling details to the shared target line. Aggregated by Chip.physics_notes().

Return type:

list[str]

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

Bases: DeviceDrive

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 modelling 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:
hamiltonian(device, signal)[source]

Map a delivered classical signal to target-local quantum physics.

Parameters:
Return type:

Any

physics_notes()[source]

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

Subclasses append their physical coupling details to the shared target line. Aggregated by Chip.physics_notes().

Return type:

list[str]

class quchip.control.TwoPhotonDrive(target=None, *, label=None)[source]

Bases: DeviceDrive

Parametric two-photon drive for Kerr-cat qubit stabilisation.

Coupling operator: a^2 + a_dag^2

The drive should be scheduled at twice the cavity frequency (freq = 2 * cavity.freq) so that in the rotating frame the interaction is static: eps2(t) * (a_dag^2 + a^2). This combination of Kerr nonlinearity and two-photon drive creates and stabilises cat states.

The engine band-decomposes a^2 + a_dag^2 into excitation weights Delta_n = +2 and Delta_n = -2 and combines them with the delivered signal’s carrier.

The real-field projection contributes only half the scheduled envelope amplitude to each band: the coefficient landing on a_dag^2 + a^2 in the rotating frame is A(t)/2, where A(t) is the amplitude scheduled on this drive’s envelope. Schedule amplitude=2*eps2(t) to realize the target two-photon drive strength eps2(t) used above and in alpha^2 = eps2/K.

Parameters:

  • target (BaseDevice | None) – Device to connect this drive to. None means unconnected.

  • label (str | None) – Optional explicit label; otherwise auto-generated.

References

Examples

>>> from quchip.devices.kerr_cavity import KerrCavity
>>> from quchip.control.drives_two_photon import TwoPhotonDrive
>>> cav = KerrCavity(freq=5.0, kerr=1.0, levels=10, label="cav")
>>> d2 = TwoPhotonDrive(target=cav)
>>> d2.target_label == cav.label
True
hamiltonian(device, signal)[source]

Return the two-photon coupling channel a^2 + a_dag^2.

Parameters:
physics_notes()[source]

Return the base drive notes plus the two-photon coupling declaration.

Return type:

list[str]

class quchip.control.ControlEquipment(lines, *, signal_chain=None)[source]

Bases: object

Ordered drive lines plus a sequence of signal-chain transforms.

The equipment pipes complete analytic signals through signal_chain before destination drives author Hamiltonian terms.

Parameters:
property lines: list[BaseDrive]

Ordered drive lines (defensive copy).

property signal_chain: list[SignalTransform]

Signal-chain transforms (defensive copy).

apply_signal_chain(signals)[source]

Apply every signal-chain transform to signals, in order.

Each transform receives the previous transform’s output, so transforms compose sequentially: reordering signal_chain changes the result (e.g. a Delay applied before a Gain sees the undelayed signal).

Parameters:

signals (SignalMap) – {(line_label, source_index): AnalyticSignal} map. source_index distinguishes scheduled pulses through mixing.

Returns:

Transformed signal map. May contain keys absent from signals: a Crosstalk transform, for example, adds an entry under the victim drive’s label for every source entry it leaks from.

Return type:

SignalMap

property crosstalks: list[Crosstalk]

Directed crosstalk edges represented by the signal chain.

crosstalk_matrix()[source]

Return a dense matrix view of the Crosstalk transforms.

The matrix uses wiring order (self.lines) as the stable axis ordering. Column index = source drive, row index = victim drive. Diagonal entries are beta=1, theta=0, delay=0 by convention (self-coupling). Off-diagonal entries aggregate every Crosstalk transform present in the signal chain; lines with no corresponding transform contribute zeros.

Non-Crosstalk transforms (Gain, Delay) are ignored here; this is strictly a view of the crosstalk edges.

Returns:

labels (wiring order), beta, theta, delay as [n, n] arrays. Arrays use jax.numpy when any stored entry is a JAX tracer or array, otherwise numpy.

Return type:

CrosstalkMatrix

set_crosstalk_matrix(beta, theta=None, delay=None, *, labels=None)[source]

Rehydrate the crosstalk edges from dense matrices.

Removes every crosstalk transform currently in the signal chain and replaces them with one CrosstalkMatrix. Other signal-chain transforms (Gain, Delay, and user-defined subclasses) are preserved in order.

Parameters:

  • beta (Any) – [n, n] amplitude matrix. beta[i, j] is emitted as the leakage amplitude from source labels[j] onto victim labels[i]. Diagonal entries are ignored (self-coupling belongs to the drive itself, not to a crosstalk edge).

  • theta (Any, optional) – [n, n] phase matrix (radians). Defaults to zeros.

  • delay (Any, optional) – [n, n] delay matrix (ns). Defaults to zeros.

  • labels (tuple[str, ...] | list[str] | None, optional) – Axis ordering. Defaults to wiring order (self.lines). Must match beta.shape[0].

Return type:

None

Notes

Traced JAX entries flow unchanged into CrosstalkMatrix and therefore into the signal-program IR. No concretization occurs.

copy(device_map, coupling_map=None)[source]

Return a structural copy with drive lines rebound to device_map / coupling_map.

Coupling-target lines rebind via coupling_map, keyed by coupling label; device-target lines rebind via device_map.

Parameters:
Return type:

ControlEquipment

to_dict()[source]

Serialize into a JSON-safe dictionary.

Return type:

dict[str, Any]

classmethod from_dict(d, dev_map, coupling_map=None)[source]

Reconstruct from to_dict() output, rebinding drives via dev_map / coupling_map.

Each line’s target_label is resolved against dev_map first, then coupling_map — device and coupling labels are disjoint by Chip construction, so at most one map holds the label.

Parameters:
Return type:

ControlEquipment

class quchip.control.CrosstalkMatrix(labels, beta, theta, delay)[source]

Bases: SignalTransform

Dense crosstalk transform and matrix view in control-line order.

Parameters:
labels

Drive labels in wiring order (the order drives appear in ControlEquipment.lines). Row / column i corresponds to labels[i].

Type:

tuple[str, …]

beta

[n, n] amplitude matrix. beta[i, j] is the leakage amplitude from source labels[j] onto victim labels[i] (column = source, row = victim). Diagonals represent self-coupling and are conventionally 1.0.

Type:

Any

theta

[n, n] phase matrix (radians), same indexing as beta.

Type:

Any

delay

[n, n] delay matrix (ns), same indexing as beta.

Type:

Any

Notes

Every off-diagonal edge reads the same input signal map, so reciprocal entries form one linear mixing stage without recursively leaking one another’s output. Matrix entries flow directly into the signal-program IR (PolarScale/Shift), preserving end-to-end JAX traceability.

labels: tuple[str, ...]
beta: Any
theta: Any
delay: Any
apply(signals)[source]

Apply all directed leakage edges to one shared input snapshot.

Parameters:

signals (dict[tuple[str, int], AnalyticSignal])

Return type:

dict[tuple[str, int], AnalyticSignal]

referenced_lines()[source]

Return control-line labels referenced by this transform.

Return type:

tuple[str, …]

without_line(line)[source]

Return this transform without line, or None when it must be dropped.

Parameters:

line (str)

Return type:

CrosstalkMatrix | None

edges()[source]

Return the directed-edge view used by topology and visualization.

Return type:

list[Crosstalk]

to_dict()[source]

Serialize into a JSON-safe dictionary.

Return type:

dict[str, Any]

classmethod from_dict(d)[source]

Reconstruct from to_dict() output.

On the registry root, dispatch to the concrete subclass named by data["type"] (forwarding *args / **kwargs). On a concrete subclass, defer to _from_dict_payload(). Concrete subclasses that carry payload override this method directly.

Parameters:

d (dict[str, Any])

Return type:

CrosstalkMatrix

class quchip.control.Envelope(**params)[source]

Bases: Registrable, ABC

Local complex pulse shape evaluated relative to its scheduled start.

Parameters:

params (Any)

duration: Any
validate()[source]

Validate relations between concrete parameters.

Return type:

None

abstractmethod value(local_time)[source]

Return complex I/Q shape at time relative to the pulse start.

Parameters:

local_time (Any)

Return type:

Any

sample(local_time, *, real=False)[source]

Evaluate the shape on an array, optionally returning only I.

Parameters:
Return type:

Any

to_dict()[source]

Serialize the concrete type and its declared parameters.

Return type:

dict[str, Any]

class quchip.control.Gaussian(duration, sigmas=3, amplitude=1.0)[source]

Bases: Envelope

Centered Gaussian pulse.

\[E(t) = A \exp\!\left[-\frac{(t - \tau/2)^2}{2 \sigma^2}\right], \qquad \sigma = \frac{\tau}{2 N_\sigma}.\]

The sigmas parameter \(N_\sigma\) is the number of standard deviations from the pulse center to its edge at t = 0 or t = duration. Gaussian pulses minimize spectral leakage onto higher transmon levels and are the starting point for DRAG corrections (Motzoi et al., PRL 103, 110501 (2009)).

The scheduled window [0, duration] starts and ends at amplitude * exp(-sigmas**2 / 2), not zero — about 0.011 * amplitude at the default sigmas=3. The pulse turns on and off with that jump; the Gaussian waveform itself is unchanged.

Parameters:

  • duration (Any)

  • sigmas (Any)

  • amplitude (Any)

duration: Any = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=True)
sigmas: Any = Parameter(default=3, positive=True, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
amplitude: Any = Parameter(default=1.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
value(t)[source]

Evaluate the centered Gaussian envelope at time points t.

Parameters:

t (Any)

Return type:

Any

class quchip.control.GaussianDRAG(duration, sigmas=3, amplitude=1.0, beta=0.0)[source]

Bases: Envelope

Gaussian pulse with a derivative quadrature.

\[E(t) = I(t) + i\,\beta\,\frac{dI}{dt}, \qquad I(t) = A\exp\!\left[-\frac{(t-\tau/2)^2}{2\sigma^2}\right].\]

beta is signed and measured in ns. Its sign therefore owns the quadrature convention without an additional polarity flag.

Parameters:
duration: Any = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=True)
sigmas: Any = Parameter(default=3, positive=True, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
amplitude: Any = Parameter(default=1.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
beta: Any = Parameter(default=0.0, positive=False, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=False)
value(t)[source]

Return complex I/Q shape at time relative to the pulse start.

Parameters:

t (Any)

Return type:

Any

class quchip.control.GaussianEdge(duration, edge_duration, sigmas=3, amplitude=1.0)[source]

Bases: Envelope

Flat-top pulse with Gaussian ramp-up and ramp-down edges.

Each edge is a Gaussian of width \(\sigma = \tau_e / (2 N_\sigma)\) where \(\tau_e\) = edge_duration; the plateau between edges holds a constant amplitude \(A\). Total duration includes both edges. Commonly used for two-qubit gates (Krantz et al. 2019, Sec. IV.C) because the flat top sets the gate area while the Gaussian edges suppress spectral leakage.

Parameters:

  • duration (float) – Total pulse length, including both edges, in ns.

  • edge_duration (float) – Ramp time \(\tau_e\) per edge, in ns. Must satisfy 2 * edge_duration <= duration.

  • sigmas (float) – Number of standard deviations spanned by each edge.

  • amplitude (float) – Plateau amplitude \(A\).

See also

SquareWithGaussianEdges

Same shape parameterized by edge_frac (fraction) instead of absolute edge_duration.

References

  • Krantz et al., APR 6, 021318 (2019), Sec. IV.C.

duration: Any = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=True)
edge_duration: Any = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=True)
sigmas: Any = Parameter(default=3, positive=True, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
amplitude: Any = Parameter(default=1.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
validate()[source]

Reject edges that overrun the pulse (2 * edge_duration > duration).

Return type:

None

value(t)[source]

Evaluate the flat-top Gaussian-edge envelope at time points t.

Parameters:

t (Any)

Return type:

Any

class quchip.control.LinearRamp(duration, ramp_duration, amplitude=1.0)[source]

Bases: Envelope

Linearly rising ramp that holds at peak amplitude.

The envelope rises linearly from 0 to amplitude over the first ramp_duration nanoseconds, then holds constant at amplitude for the remainder of the pulse.

\[E(t) = A \cdot \min\!\left(\frac{t}{\tau_r},\, 1\right), \qquad 0 \le t \le \tau,\]

where \(\tau_r\) is ramp_duration and \(\tau\) is duration.

Parameters:

  • duration (float) – Total pulse duration in ns. Must be > 0.

  • ramp_duration (float) – Duration of the linear rise in ns. Must satisfy 0 < ramp_duration <= duration.

  • amplitude (float) – Peak amplitude \(A\) (default 1.0).

Notes

For an adiabatic ramp into a Kerr-cat qubit, choose ramp_duration long compared to 1 / (2 * K) (the inverse gap at the bifurcation point). See Grimm et al., Nature 584, 205 (2020).

The waveform is JAX-traceable: ramp_duration and amplitude may be JAX tracers so the ramp parameters are differentiable.

Examples

>>> from quchip.control.envelopes import LinearRamp
>>> ramp = LinearRamp(duration=60.0, ramp_duration=50.0, amplitude=4.0)
>>> import numpy as np
>>> t = np.array([0.0, 25.0, 50.0, 55.0])
>>> np.real(ramp.value(t)).tolist()
[0.0, 2.0, 4.0, 4.0]
duration: Any = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=True)
ramp_duration: Any = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=True)
amplitude: Any = Parameter(default=1.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
validate()[source]

Reject ramps longer than the pulse (ramp_duration > duration).

Return type:

None

value(t)[source]

Evaluate the linear-ramp envelope at time points t (ns).

Parameters:

t (array-like) – 1-D array of time points in nanoseconds.

Returns:

Complex-valued waveform: rises linearly over ramp_duration, holds constant at amplitude afterward.

Return type:

array

class quchip.control.Square(duration, amplitude=1.0)[source]

Bases: Envelope

Constant-amplitude pulse.

\[E(t) = A, \qquad 0 \le t \le \tau.\]
Parameters:

  • duration (float) – Pulse length \(\tau\) in ns.

  • amplitude (float) – Real amplitude \(A\) applied on top of value().

duration: Any = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=True)
amplitude: Any = Parameter(default=1.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
value(t)[source]

Evaluate the constant envelope at time points t.

Parameters:

t (Any)

Return type:

Any

class quchip.control.SquareWithGaussianEdges(duration, amplitude=1.0, edge_frac=0.25, sigmas=3)[source]

Bases: Envelope

Flat-top pulse with Gaussian ramp-up and ramp-down edges.

Each ramp has duration \(\tau_e = f_e \cdot \tau\) with \(f_e\) = edge_frac; the plateau between ramps holds amplitude \(A\). Total duration includes both edges. The Gaussian width is \(\sigma = \tau_e / (2 N_\sigma)\) with \(N_\sigma\) = sigmas.

This is the canonical shape used in Krantz et al. 2019 (Sec. IV.C) for two-qubit gates — the flat top sets the gate area while the Gaussian edges suppress spectral leakage. Parametrizing the ramp as a fraction of the total duration makes the shape shape-invariant under changes of duration.

Parameters:

  • duration (float) – Total pulse length in ns (includes both ramps).

  • amplitude (float) – Plateau amplitude \(A\).

  • edge_frac (float) – Ramp length as a fraction of the total duration. Must satisfy 0 < edge_frac and 2 * edge_frac <= 1.

  • sigmas (float) – Number of standard deviations spanned by each ramp.

duration: Any = Parameter(default=unbound, positive=True, nonnegative=False, serialize=True, unit='ns', symbol=None, noise=False, kw_only=False, required=True)
amplitude: Any = Parameter(default=1.0, positive=False, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
edge_frac: Any = Parameter(default=0.25, positive=True, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
sigmas: Any = Parameter(default=3, positive=True, nonnegative=False, serialize=True, unit=None, symbol=None, noise=False, kw_only=False, required=False)
validate()[source]

Reject ramps that overrun the pulse (2 * edge_frac > 1).

Return type:

None

property edge_duration: float

Ramp duration in ns (edge_frac * duration).

value(t)[source]

Evaluate the fraction-parameterized Gaussian-edge envelope.

Parameters:

t (Any)

Return type:

Any

Modules

batch

Batch / sweep-axis machinery for QuantumSequence.

drive

Classical control lines and their quantum Hamiltonian couplings.

drives_two_photon

TwoPhotonDrive -- parametric two-photon drive for Kerr-cat qubits.

envelopes

Pulse envelope models for quantum control.

equipment

Control-equipment container: drive lines and signal chain.

sequence

Declarative pulse programming for a Chip.

signal

Signal-chain transforms for control equipment.