Skip to content

qoolqit.drive

drive

Classes:

  • DetuningMapModulator –

    A weighted detuning for the Detuning Map Modulator (DMM).

  • Drive –

    The drive Hamiltonian acting over a duration.

DetuningMapModulator dataclass 

DetuningMapModulator(
    waveform: Waveform, weights: dict[Any, float]
)

A weighted detuning for the Detuning Map Modulator (DMM).

Parameters:

  • waveform (Waveform) –

    The waveform for this detuning. Must be negative for all times.

  • weights (dict[Any, float]) –

    A dictionary associating detuning weights to qubits. Each weight must be in [0, 1], where 0 means that the waveform is ignored for this qubit and 1 means that the waveform is fully applied to this qubit.

See https://docs.pasqal.com/pulser/tutorials/dmm/ for details on DMM.

Returned by: Used by:

Drive 

Drive(
    *,
    amplitude: Waveform,
    detuning: Waveform | None = None,
    dmm: DetuningMapModulator | None = None,
    phase: float = 0.0,
)

The drive Hamiltonian acting over a duration.

The Drive specifies the control parameters for the time-dependent drive Hamiltonian in the Rydberg model (see https://docs.pasqal.com/qoolqit/get_started/qoolqit_model/ for details),

H_drive(t) = Σᵢ [Ω(t)/2 (cos φ(t) σˣᵢ - sin φ(t) σʸᵢ)] - Σᵢ [δ(t) + εᵢ Δ(t)] nᵢ

representing: - Amplitude Ω(t): Controls the Rabi frequency that drives qubits. - Detuning δ(t): Controls the energy offset of the Rydberg state. - dmm εᵢ, Δ(t): Detuning Map Modulator (DMM) for additional qubit-specific detunings. - Phase φ: Global phase applied to the amplitude term.

Parameters:

  • amplitude (Waveform) –

    Time-dependent amplitude waveform Ω(t) representing the Rabi frequency. Controls the strength of the coupling between ground and Rydberg states. Must be positive for all times.

  • detuning (Waveform | None, default: None ) –

    Time-dependent detuning waveform δ(t) representing the energy offset of the Rydberg state relative to resonance. If None, defaults to zero detuning (Delay waveform) for the duration of the amplitude.

  • dmm (DetuningMapModulator | None, default: None ) –

    DetuningMapModulator instance for additional negative detuning waveform Δ(t) ≤ 0 applied to individual qubits as specified by its weights attribute εᵢ.

  • phase (float, default: 0.0 ) –

    Global phase φ applied to the amplitude term in the Hamiltonian. Defaults to 0.0 (no phase). Normalized to [0, 2π) and stored as a ConstantWaveform spanning the full duration of the drive.

Raises:

  • TypeError –

    If amplitude or detuning are not Waveform instances.

  • ValueError –

    If the amplitude waveform has negative values, or if the phase is not finite.

Note
  • All arguments must be passed as keyword arguments.
  • If amplitude and detuning have different durations, the shorter one is automatically extended with a Delay to match the longer duration.
  • DetuningMapModulator waveform must be negative for all times (≤ 0) as it represents energy shifts below the resonance.
Example

from qoolqit import Drive from qoolqit.waveforms import ConstantWaveform, RampWaveform

Simple constant drive

drive = Drive(amplitude=ConstantWaveform(10.0, 1.5))

Drive with time-varying amplitude and detuning

amp = RampWaveform(5.0, 0.0, 2.0) det = ConstantWaveform(5.0, -1.0) drive = Drive(amplitude=amp, detuning=det, phase=0.5)

Returned by: Used by:

Methods:

  • draw –

    Draw the amplitude, detuning, phase and DMM of the Drive.

Attributes:

Source code in qoolqit/drive.py 
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
def __init__(
    self,
    *,
    amplitude: Waveform,
    detuning: Waveform | None = None,
    dmm: DetuningMapModulator | None = None,
    phase: float = 0.0,
) -> None:
    """Initialize a Drive.

    The Drive specifies the control parameters for the time-dependent drive Hamiltonian
    in the Rydberg model
    (see https://docs.pasqal.com/qoolqit/get_started/qoolqit_model/ for details),

    H_drive(t) = Σᵢ [Ω(t)/2 (cos φ(t) σˣᵢ - sin φ(t) σʸᵢ)] - Σᵢ [δ(t) + εᵢ Δ(t)] nᵢ

    representing:
    - Amplitude Ω(t): Controls the Rabi frequency that drives qubits.
    - Detuning δ(t): Controls the energy offset of the Rydberg state.
    - dmm εᵢ, Δ(t): Detuning Map Modulator (DMM) for additional qubit-specific detunings.
    - Phase φ: Global phase applied to the amplitude term.

    Args:
        amplitude: Time-dependent amplitude waveform Ω(t) representing the Rabi frequency.
            Controls the strength of the coupling between ground and Rydberg states.
            Must be positive for all times.
        detuning: Time-dependent detuning waveform δ(t) representing the energy offset
            of the Rydberg state relative to resonance. If None, defaults to zero
            detuning (Delay waveform) for the duration of the amplitude.
        dmm: DetuningMapModulator instance for additional negative detuning waveform Δ(t) ≤ 0
            applied to individual qubits as specified by its `weights` attribute εᵢ.
        phase: Global phase φ applied to the amplitude term in the Hamiltonian.
            Defaults to 0.0 (no phase). Normalized to [0, 2π) and stored as a
            ConstantWaveform spanning the full duration of the drive.

    Raises:
        TypeError: If amplitude or detuning are not Waveform instances.
        ValueError: If the amplitude waveform has negative values, or if the phase
            is not finite.

    Note:
        - All arguments must be passed as keyword arguments.
        - If amplitude and detuning have different durations, the shorter one is
          automatically extended with a Delay to match the longer duration.
        - DetuningMapModulator waveform must be negative for all times
            (≤ 0) as it represents energy shifts below the resonance.

    Example:
        >>> from qoolqit import Drive
        >>> from qoolqit.waveforms import ConstantWaveform, RampWaveform
        >>>
        >>> # Simple constant drive
        >>> drive = Drive(amplitude=ConstantWaveform(10.0, 1.5))
        >>>
        >>> # Drive with time-varying amplitude and detuning
        >>> amp = RampWaveform(5.0, 0.0, 2.0)
        >>> det = ConstantWaveform(5.0, -1.0)
        >>> drive = Drive(amplitude=amp, detuning=det, phase=0.5)
    """

    for arg in [amplitude, detuning]:
        if arg is not None and not isinstance(arg, Waveform):
            raise TypeError("'amplitude' and 'detuning' must be of type Waveform.")

    if amplitude.min() < 0.0:
        raise ValueError("'amplitude' must be positive.")

    if not math.isfinite(phase):
        raise ValueError("'phase' must be finite.")

    self._amplitude = amplitude
    self._detuning = detuning if detuning is not None else DelayWaveform(amplitude.duration)

    self._amplitude_orig = self._amplitude
    self._detuning_orig = self._detuning

    # adjust amplitude and detuning waveforms to match the duration
    if self._amplitude.duration > self._detuning.duration:
        extra_duration = self._amplitude.duration - self._detuning.duration
        self._detuning = CompositeWaveform(self._detuning, DelayWaveform(extra_duration))
    elif self._detuning.duration > self._amplitude.duration:
        extra_duration = self._detuning.duration - self._amplitude.duration
        self._amplitude = CompositeWaveform(self._amplitude, DelayWaveform(extra_duration))

    self._duration = self._amplitude.duration
    if dmm is not None and not isinstance(dmm, DetuningMapModulator):
        raise TypeError("'dmm' must be of type DetuningMapModulator.")
    self._dmm = dmm
    self._phase = ConstantWaveform(self.duration, _mod_2pi(phase))

amplitude property 

amplitude: Waveform

The amplitude waveform in the drive.

detuning property 

detuning: Waveform

The detuning waveform in the drive.

dmm property 

dmm: DetuningMapModulator | None

Detuning Map Modulator (DMM) applied to individual qubits.

phase property 

phase: ConstantWaveform

The phase waveform in the drive.

draw 

draw(fig: FigureBase | None = None) -> None

Draw the amplitude, detuning, phase and DMM of the Drive.

The phase is drawn only if it is non-zero, and the DMM only if one is set.

Parameters:

  • fig (FigureBase | None, default: None ) –

    The figure or subfigure to draw into. If None, a new pyplot figure is created.

Source code in qoolqit/drive.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
def draw(self, fig: FigureBase | None = None) -> None:
    """Draw the amplitude, detuning, phase and DMM of the Drive.

    The phase is drawn only if it is non-zero, and the DMM only if one is set.

    Args:
        fig: The figure or subfigure to draw into. If None, a new pyplot figure is
            created.
    """
    if fig is None:
        fig = plt.figure()

    # setup subplots
    nrows = 2
    if self.dmm is not None:
        nrows += 1
    has_phase = self.phase.value != 0
    if has_phase:
        nrows += 1

    axs = fig.subplots(nrows, 1, sharex=True)

    # samples
    times = np.linspace(0.0, self.duration, 250)
    amplitude = self.amplitude(times)
    detuning = self.detuning(times)

    # draw amplitude
    axs[0].set_ylabel("Amplitude")
    axs[0].plot(times, amplitude, color="darkgreen")
    axs[0].fill_between(times, amplitude, color="darkgreen", alpha=0.4)

    # draw detuning
    axs[1].set_axisbelow(True)
    axs[1].set_ylabel("Detuning")
    axs[1].plot(times, detuning, color="darkmagenta")
    axs[1].fill_between(times, detuning, color="darkmagenta", alpha=0.4)

    # draw phase if present
    if has_phase:
        phase = self.phase(times) / (2 * np.pi)
        axs[2].set_ylabel(r"Phase $/ \ 2\pi$")
        axs[2].plot(times, phase, color="darkorange")
        axs[2].fill_between(times, phase, color="darkorange", alpha=0.4)

    # draw DMM if present
    if self.dmm is not None:
        y_dmm = self.dmm.waveform(times)
        axs[-1].set_ylabel("DMM")
        axs[-1].plot(times, y_dmm, color="darkblue")
        axs[-1].fill_between(times, y_dmm, color="darkblue", alpha=0.4)

    axs[-1].set_xlabel("Time t")

    # add grids
    for ax in axs:
        ax.grid(True, color="lightgray", linestyle="--", linewidth=0.7)