qat.experimental.waveforms.evaluate module

Implements the entry point for evaluating waveform shapes, along with their amplitude, width, phase multiplier and DRAG coefficients.

evaluate_waveform(*, width, sample_time, shape, amplitude=1.0, phase=0.0, drag_coefficients=None, allow_numerical_derivative=True)

Evaluates the samples of a waveform.

Requires the width of the waveform to be given, and a sample time which must multiply into the width by an integer multiple N. That is,

\[N = \frac{t_{d}}{\delta t}\]

must be an integer. The discrete times at which the waveform is sampled at is decided by splitting the width into \(N\) equal intervals, and sampling at the center of those intervals, i.e. at times

\[t_{n} = \left(n + \frac{1}{2}\right) \delta t.\]

The waveform shape must also be provided. Optionally, an amplitude to scale the waveform can be given, and a phase which acts as a global rotation in complex space can also be provided. DRAG coefficients can also be provided to implement the DRAG technique up to the desired order if the waveform shape supports derivatives up to that order. The full waveform is implemented as

\[A(t) = A e^{i \theta} \left( 1 + \sum_{j=1}^{M} \beta_{j} (i)**j \frac{d^{j}}{dt^{j}}\right) S\left(\frac{2t}{T} - 1\right)\]

Note that practically, the waveform shapes are implemented as a function of \(x \in [-1, 1]\), which we map onto \(t \in [0, T]\) for width \(T\),so evaluating the derivative through that means we have to apply the chain rule.

Analytical implementation of derivatives takes precedence, but if the derivative is known to be mathematically defined but not implemented, then a numerical derivative is used instead. If the derivative is mathematically undefined, then a ValueError is raised.

Parameters:

  • width (int) – The width of the waveform in picoseconds

  • sample_time (int) – The time between samples in picoseconds.

  • shape (WaveformShape) – The waveform shape to evaluate.

  • amplitude (float) – The amplitude to scale the waveform.

  • phase (float) – The global phase rotation in complex space.

  • drag_coefficients (Union[float, list[float], None]) – The DRAG coefficients to implement the DRAG technique. Use 0.0, or an empty list to not implement DRAG. Every entry represents the ith order of DRAG to implement, starting from order 1. A float only implements first order.

  • allow_numerical_derivative (bool) – Whether to allow numerical derivatives if the derivative is mathematically defined but not implemented. If False, a DerivativeOrderNotImplementedError is raised instead.

Raises:

  • ValueError – If the width is not an integer multiple of the sample time.

  • DerivativeOrderUndefinedError – If a derivative order is mathematically undefined for the waveform shape.

Return type:

ndarray[tuple[int, ...], dtype[complexfloating]]

Returns:

The evaluated waveform samples at the discrete sample times.