qoolqit.drive

drive

Drive Hamiltonian (amplitude, detuning, phase) and its Detuning Map Modulator (DMM).

Classes:

DetuningMapModulator –

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

The drive Hamiltonian acting over a duration.

DetuningMapModulator `dataclass`

DetuningMapModulator(
    waveform:             Waveform (qoolqit.waveforms.Waveform)" href="../waveforms/#qoolqit.waveforms.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/ (external) for details on DMM.

Returned by:

API reference
- qoolqit qoolqit Drive dmm
- qoolqit.drive drive Drive dmm

Used by:

API reference
- qoolqit qoolqit Drive
- qoolqit.drive drive Drive

Drive

Drive(
    *,
    amplitude:             Waveform (qoolqit.waveforms.Waveform)" href="../waveforms/#qoolqit.waveforms.Waveform">Waveform,
    detuning:             Waveform (qoolqit.waveforms.Waveform)" href="../waveforms/#qoolqit.waveforms.Waveform">Waveform | None = None,
    dmm:             DetuningMapModulator



      dataclass
   (qoolqit.drive.DetuningMapModulator)" href="./#qoolqit.drive.DetuningMapModulator">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/ (external) 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:

API reference
- qoolqit qoolqit QuantumProgram drive
- qoolqit.program program QuantumProgram drive

Used by:

API reference
- qoolqit qoolqit
  - QuantumProgram
  - SequenceCompiler
- qoolqit.program program QuantumProgram

Methods:

draw –

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

Attributes:

amplitude (Waveform) –

The amplitude waveform in the drive.
detuning (Waveform) –

The detuning waveform in the drive.
dmm (DetuningMapModulator | None) –

Detuning Map Modulator (DMM) applied to individual qubits.
phase (ConstantWaveform) –

The phase waveform in the drive.

Source code in qoolqit/drive.py

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 (qoolqit.waveforms.Waveform)" href="../waveforms/#qoolqit.waveforms.Waveform">Waveform

The amplitude waveform in the drive.

detuning `property`

detuning:             Waveform (qoolqit.waveforms.Waveform)" href="../waveforms/#qoolqit.waveforms.Waveform">Waveform

The detuning waveform in the drive.

dmm `property`

dmm:             DetuningMapModulator



      dataclass
   (qoolqit.drive.DetuningMapModulator)" href="./#qoolqit.drive.DetuningMapModulator">DetuningMapModulator | None

Detuning Map Modulator (DMM) applied to individual qubits.

phase `property`

phase:             ConstantWaveform (qoolqit.waveforms.ConstantWaveform)" href="../waveforms/#qoolqit.waveforms.ConstantWaveform">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

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π/ \ 2\pi/ 2π")
        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)

Previous
qoolqit.waveforms Next
qoolqit.program

qoolqit.drive

drive

DetuningMapModulator dataclass

Drive

Simple constant drive

Drive with time-varying amplitude and detuning

amplitude property

detuning property

dmm property

phase property

draw

DetuningMapModulator `dataclass`

amplitude `property`

detuning `property`

dmm `property`

phase `property`