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 interpolation of a set 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 
118
119
120
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 
75
76
77
78
79
80
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: Optional[ArrayLike] = None, interpolator: str = 'PchipInterpolator', **interpolator_kwargs: Any)

A waveform created from interpolation of a set of data points.

Parameters:

  • duration

    (int) –

    The waveform duration (in ns).

  • values

    (ArrayLike) –

    Values of the interpolation points. Must be a list of castable to float or a parametrized object.

  • times

    (ArrayLike, default: None ) –

    Fractions of the total duration (between 0 and 1), indicating where to place each value on the time axis. Must be a list of castable to float or a parametrized object. If not given, the values are spread evenly throughout the full duration of the waveform.

  • interpolator

    (str, default: 'PchipInterpolator' ) –

    The SciPy interpolation class to use. Supports "PchipInterpolator" and "interp1d".

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 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
def __init__(
    self,
    duration: float,
    values: ArrayLike,
    times: Optional[ArrayLike] = None,
    interpolator: str = "PchipInterpolator",
    **interpolator_kwargs: Any,
):
    """Initializes a new Interpolated waveform."""
    super().__init__(duration)
    self._values = np.array(values, dtype=float)
    if times:  # fractional times in [0,1]
        if any([(ft < 0) or (ft > 1) for ft in times]):
            raise ValueError("All values in `times` must be in [0,1].")
        self._times = np.array(times, dtype=float)
        if len(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))

    if interpolator not in self._valid_interpolators:
        raise ValueError(
            f"Invalid interpolator '{interpolator}', only "
            "accepts: " + ", ".join(self._valid_interpolators)
        )
    self._interpolator = interpolator
    self._interpolator_kwargs = interpolator_kwargs

    interp_cls = getattr(interpolate, interpolator)
    self._interp_func = interp_cls(duration * self._times, self._values, **interpolator_kwargs)

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 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
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 
43
44
45
46
47
48
49
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 
272
273
274
275
276
277
278
279
280
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)