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 (external)

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

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

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

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

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

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

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

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

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

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

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

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

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)