Skip to content

qoolqit.waveforms

waveforms

Modules:

  • base_waveforms –
  • utils –
  • waveforms –

Classes:

  • Blackman –

    A Blackman window of a specified duration and area under the curve.

  • Constant –

    A constant waveform over a given duration.

  • Delay –

    An empty waveform.

  • Interpolated –

    A waveform created from shape-preserving interpolation of data points.

  • PiecewiseLinear –

    A piecewise linear waveform.

  • Ramp –

    A ramp that linearly interpolates between an initial and final value.

  • Sin –

    An arbitrary sine over a given duration.

Blackman(duration: float, area: float)

A Blackman window of a specified duration and area under the curve.

Implements the Blackman window shaped waveform blackman(t) = A(0.42 - 0.5cos(αt) + 0.08cos(2αt)) A = area/(0.42duration) α = 2π/duration

See: https://en.wikipedia.org/wiki/Window_function#:~:text=Blackman%20window

Parameters:

  • duration

    (float) –

    The waveform duration.

  • area

    (float) –

    The integral of the waveform.

Example 
blackman_wf = Blackman(100.0, area=3.14)

Attributes:

  • duration (float) –

    Returns the duration of the waveform.

  • params (dict[str, float | ndarray]) –

    Dictionary of parameters used by the waveform.

Source code in qoolqit/waveforms/waveforms.py 
117
118
119
def __init__(self, duration: float, area: float) -> None:
    """Initializes a new Blackman waveform."""
    super().__init__(duration, area=area)

duration: float property

Returns the duration of the waveform.

params: dict[str, float | np.ndarray] property

Dictionary of parameters used by the waveform.

Constant(duration: float, value: float)

A constant waveform over a given duration.

Parameters:

  • duration

    (float) –

    the total duration.

  • value

    (float) –

    the value to take during the duration.

Attributes:

  • duration (float) –

    Returns the duration of the waveform.

  • params (dict[str, float | ndarray]) –

    Dictionary of parameters used by the waveform.

Source code in qoolqit/waveforms/waveforms.py 
74
75
76
77
78
79
def __init__(
    self,
    duration: float,
    value: float,
) -> None:
    super().__init__(duration, value=value)

duration: float property

Returns the duration of the waveform.

params: dict[str, float | np.ndarray] property

Dictionary of parameters used by the waveform.

Delay(duration: float, *args: float, **kwargs: float | np.ndarray)

An empty waveform.

Parameters:

  • duration

    (float) –

    the total duration of the waveform.

Attributes:

  • duration (float) –

    Returns the duration of the waveform.

  • params (dict[str, float | ndarray]) –

    Dictionary of parameters used by the waveform.

Source code in qoolqit/waveforms/base_waveforms.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def __init__(
    self,
    duration: float,
    *args: float,
    **kwargs: float | np.ndarray,
) -> None:
    """Initializes the Waveform.

    Arguments:
        duration: the total duration of the waveform.
    """

    if duration <= 0:
        raise ValueError("Duration needs to be a positive non-zero value.")

    if len(args) > 0:
        raise ValueError(
            f"Extra arguments in {type(self).__name__} need to be passed as keyword arguments"
        )

    self._duration = duration
    self._params_dict = kwargs

    self._max: float | None = None
    self._min: float | None = None

    for key, value in kwargs.items():
        setattr(self, key, value)

duration: float property

Returns the duration of the waveform.

params: dict[str, float | np.ndarray] property

Dictionary of parameters used by the waveform.

Interpolated(duration: float, values: ArrayLike, times: ArrayLike | None = None)

A waveform created from shape-preserving interpolation of data points.

This class creates a smooth waveform by interpolating between specified data points using PCHIP (Piecewise Cubic Hermite Interpolating Polynomial) interpolation. The interpolating curve preserves the shape of the input data: bounds (avoiding under/overshooting), monotonicity, and convexity.

Uses scipy's PchipInterpolator for the interpolation.

Attributes:

  • duration (float) –

    The waveform duration.

  • values (float) –

    Array-like sequence of waveform values at the interpolation points. Must be convertible to float. These values define the amplitude of the waveform at the corresponding time points.

  • times (float) –

    Optional array-like sequence of fractional times in the range [0, 1] indicating where to place each value on the time axis. Must have the same length as values. If not provided, values are distributed evenly across the waveform duration. Default is None.

ValueError: If times contains values outside [0, 1] or if times and values have different lengths.

Example

Create a waveform with 4 points over 100ns

values = [0.0, 1.0, 0.5, 0.0] wf = Interpolated(100, values)

Create with custom timing

times = [0.0, 0.2, 0.8, 1.0] # Non-uniform spacing wf = Interpolated(100, values, times)

Parameters:

  • duration

    (float) –

    The total duration of the waveform. Must be positive.

  • values

    (ArrayLike) –

    Array-like sequence of waveform values at interpolation points. Can be a list, tuple, numpy array, or any sequence convertible to float.

  • times

    (ArrayLike | None, default: None ) –

    Optional array-like sequence of fractional times in [0, 1]. If provided, must have the same length as values. If None, values are evenly spaced across the duration. Default is None.

Raises:

  • ValueError –

    If any value in times is outside [0, 1], or if times and values have different lengths.

Source code in qoolqit/waveforms/waveforms.py 
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
def __init__(
    self,
    duration: float,
    values: ArrayLike,
    times: ArrayLike | None = None,
):
    """Initialize an Interpolated waveform.

    Args:
        duration: The total duration of the waveform. Must be positive.
        values: Array-like sequence of waveform values at interpolation points.
            Can be a list, tuple, numpy array, or any sequence convertible to float.
        times: Optional array-like sequence of fractional times in [0, 1]. If provided,
            must have the same length as `values`. If None, values are evenly spaced
            across the duration. Default is None.

    Raises:
        ValueError: If any value in `times` is outside [0, 1], or if `times` and
            `values` have different lengths.
    """
    super().__init__(duration)
    self._values = np.array(values, dtype=float)
    if times is not None:
        self._times = np.array(times, dtype=float)
        if any([(ft < 0) or (ft > 1) for ft in self._times]):
            raise ValueError("All values in `times` must be in [0,1].")
        if len(self._times) != len(self._values):
            raise ValueError(
                "Arguments `values` and `times` must be arrays of the same length."
            )
    else:
        self._times = np.linspace(0, 1, num=len(self._values))

    self._interp_func = PchipInterpolator(duration * self._times, values)

duration: float property

Returns the duration of the waveform.

params: dict[str, float | np.ndarray] property

Dictionary of parameters used by the waveform.

PiecewiseLinear(durations: list | tuple, values: list | tuple)

A piecewise linear waveform.

Creates a composite waveform of N ramps that linearly interpolate through the given N+1 values.

Parameters:

  • durations

    (list | tuple) –

    list or tuple of N duration values.

  • values

    (list | tuple) –

    list or tuple of N+1 waveform values.

Methods:

  • function –

    Identifies the right waveform in the composition and evaluates it at time t.

  • max –

    Get the maximum value of the waveform.

  • min –

    Get the approximate minimum value of the waveform.

Attributes:

  • duration (float) –

    Returns the duration of the waveform.

  • durations (list[float]) –

    Returns the list of durations of each individual waveform.

  • n_waveforms (int) –

    Returns the number of waveforms.

  • params (dict[str, float | ndarray]) –

    Dictionary of parameters used by the waveform.

  • times (list[float]) –

    Returns the list of times when each individual waveform starts.

  • waveforms (list[Waveform]) –

    Returns a list of the individual waveforms.

Source code in qoolqit/waveforms/waveforms.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def __init__(
    self,
    durations: list | tuple,
    values: list | tuple,
) -> None:
    if not (isinstance(durations, (list, tuple)) or isinstance(values, (list, tuple))):
        raise TypeError(
            "A PiecewiseLinear waveform requires a list or tuple of durations and values."
        )

    if len(durations) + 1 != len(values) or len(durations) == 1:
        raise ValueError(
            "A PiecewiseLinear waveform requires N durations and N + 1 values, for N >= 2."
        )

    for duration in durations:
        if duration == 0.0:
            raise ValueError("A PiecewiseLinear interval cannot have zero duration.")

    self.values = values

    wfs = [Ramp(dur, values[i], values[i + 1]) for i, dur in enumerate(durations)]

    super().__init__(*wfs)

duration: float property

Returns the duration of the waveform.

durations: list[float] property

Returns the list of durations of each individual waveform.

n_waveforms: int property

Returns the number of waveforms.

params: dict[str, float | np.ndarray] property

Dictionary of parameters used by the waveform.

times: list[float] property

Returns the list of times when each individual waveform starts.

waveforms: list[Waveform] property

Returns a list of the individual waveforms.

function(t: float) -> float

Identifies the right waveform in the composition and evaluates it at time t.

Source code in qoolqit/waveforms/base_waveforms.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
def function(self, t: float) -> float:
    """Identifies the right waveform in the composition and evaluates it at time t."""
    idx = np.searchsorted(self.times, t, side="right") - 1
    if idx == -1:
        return 0.0
    if idx == self.n_waveforms:
        if t == self.times[-1]:
            idx = idx - 1
        else:
            return 0.0

    local_t = t - self.times[idx]
    value: float = self.waveforms[idx](local_t)
    return value

max() -> float

Get the maximum value of the waveform.

Source code in qoolqit/waveforms/base_waveforms.py 
245
246
247
def max(self) -> float:
    """Get the maximum value of the waveform."""
    return max([wf.max() for wf in self.waveforms])

min() -> float

Get the approximate minimum value of the waveform.

This is a brute-force method that samples the waveform over a pre-defined number of points to find the minimum value in the duration. Custom waveforms that have an easy to compute maximum value should override this method.

Source code in qoolqit/waveforms/base_waveforms.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def min(self) -> float:
    """Get the approximate minimum value of the waveform.

    This is a brute-force method that samples the waveform over a
    pre-defined number of points to find the minimum value in the
    duration. Custom waveforms that have an easy to compute
    maximum value should override this method.
    """
    if self._min is None:
        self._approximate_min_max()
    return cast(float, self._min)

Ramp(duration: float, initial_value: float, final_value: float)

A ramp that linearly interpolates between an initial and final value.

Parameters:

  • duration

    (float) –

    the total duration.

  • initial_value

    (float) –

    the initial value at t = 0.

  • final_value

    (float) –

    the final value at t = duration.

Attributes:

  • duration (float) –

    Returns the duration of the waveform.

  • params (dict[str, float | ndarray]) –

    Dictionary of parameters used by the waveform.

Source code in qoolqit/waveforms/waveforms.py 
42
43
44
45
46
47
48
def __init__(
    self,
    duration: float,
    initial_value: float,
    final_value: float,
) -> None:
    super().__init__(duration, initial_value=initial_value, final_value=final_value)

duration: float property

Returns the duration of the waveform.

params: dict[str, float | np.ndarray] property

Dictionary of parameters used by the waveform.

Sin(duration: float, amplitude: float = 1.0, omega: float = 1.0, phi: float = 0.0, shift: float = 0.0)

An arbitrary sine over a given duration.

Parameters:

  • duration

    (float) –

    the total duration.

  • amplitude

    (float, default: 1.0 ) –

    the amplitude of the sine wave.

  • omega

    (float, default: 1.0 ) –

    the frequency of the sine wave.

  • phi

    (float, default: 0.0 ) –

    the phase of the sine wave.

  • shift

    (float, default: 0.0 ) –

    the vertical shift of the sine wave.

Methods:

  • max –

    Get the approximate maximum value of the waveform.

  • min –

    Get the approximate minimum value of the waveform.

Attributes:

  • duration (float) –

    Returns the duration of the waveform.

  • params (dict[str, float | ndarray]) –

    Dictionary of parameters used by the waveform.

Source code in qoolqit/waveforms/waveforms.py 
284
285
286
287
288
289
290
291
292
def __init__(
    self,
    duration: float,
    amplitude: float = 1.0,
    omega: float = 1.0,
    phi: float = 0.0,
    shift: float = 0.0,
) -> None:
    super().__init__(duration, amplitude=amplitude, omega=omega, phi=phi, shift=shift)

duration: float property

Returns the duration of the waveform.

params: dict[str, float | np.ndarray] property

Dictionary of parameters used by the waveform.

max() -> float

Get the approximate maximum value of the waveform.

This is a brute-force method that samples the waveform over a pre-defined number of points to find the maximum value in the duration. Custom waveforms that have an easy to compute maximum value should override this method.

Source code in qoolqit/waveforms/base_waveforms.py 
79
80
81
82
83
84
85
86
87
88
89
def max(self) -> float:
    """Get the approximate maximum value of the waveform.

    This is a brute-force method that samples the waveform over a
    pre-defined number of points to find the maximum value in the
    duration. Custom waveforms that have an easy to compute
    maximum value should override this method.
    """
    if self._max is None:
        self._approximate_min_max()
    return cast(float, self._max)

min() -> float

Get the approximate minimum value of the waveform.

This is a brute-force method that samples the waveform over a pre-defined number of points to find the minimum value in the duration. Custom waveforms that have an easy to compute maximum value should override this method.

Source code in qoolqit/waveforms/base_waveforms.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def min(self) -> float:
    """Get the approximate minimum value of the waveform.

    This is a brute-force method that samples the waveform over a
    pre-defined number of points to find the minimum value in the
    duration. Custom waveforms that have an easy to compute
    maximum value should override this method.
    """
    if self._min is None:
        self._approximate_min_max()
    return cast(float, self._min)