qiskit-documentation/docs/api/qiskit/0.26/qiskit.pulse.library.discre...

437 lines
20 KiB
Plaintext
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: discrete (v0.26)
description: API reference for qiskit.pulse.library.discrete in qiskit v0.26
in_page_toc_min_heading_level: 2
python_api_type: module
python_api_name: qiskit.pulse.library.discrete
---
<span id="module-qiskit.pulse.library.discrete" />
<span id="qiskit-pulse-library-discrete" />
# qiskit.pulse.library.discrete
Module for builtin discrete pulses.
Note the sampling strategy use for all discrete pulses is `midpoint`.
**Functions**
| | |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [`constant`](#qiskit.pulse.library.discrete.constant "qiskit.pulse.library.discrete.constant")(duration, amp\[, name]) | Generates constant-sampled [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`cos`](#qiskit.pulse.library.discrete.cos "qiskit.pulse.library.discrete.cos")(duration, amp\[, freq, phase, name]) | Generates cosine wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`drag`](#qiskit.pulse.library.discrete.drag "qiskit.pulse.library.discrete.drag")(duration, amp, sigma, beta\[, name, …]) | Generates Y-only correction DRAG [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform") for standard nonlinear oscillator (SNO) \[1]. |
| [`gaussian`](#qiskit.pulse.library.discrete.gaussian "qiskit.pulse.library.discrete.gaussian")(duration, amp, sigma\[, name, zero\_ends]) | Generates unnormalized gaussian [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`gaussian_deriv`](#qiskit.pulse.library.discrete.gaussian_deriv "qiskit.pulse.library.discrete.gaussian_deriv")(duration, amp, sigma\[, name]) | Generates unnormalized gaussian derivative [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`gaussian_square`](#qiskit.pulse.library.discrete.gaussian_square "qiskit.pulse.library.discrete.gaussian_square")(duration, amp, sigma\[, …]) | Generates gaussian square [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`sawtooth`](#qiskit.pulse.library.discrete.sawtooth "qiskit.pulse.library.discrete.sawtooth")(duration, amp\[, freq, phase, name]) | Generates sawtooth wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`sech`](#qiskit.pulse.library.discrete.sech "qiskit.pulse.library.discrete.sech")(duration, amp, sigma\[, name, zero\_ends]) | Generates unnormalized sech [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`sech_deriv`](#qiskit.pulse.library.discrete.sech_deriv "qiskit.pulse.library.discrete.sech_deriv")(duration, amp, sigma\[, name]) | Generates unnormalized sech derivative [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`sin`](#qiskit.pulse.library.discrete.sin "qiskit.pulse.library.discrete.sin")(duration, amp\[, freq, phase, name]) | Generates sine wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`square`](#qiskit.pulse.library.discrete.square "qiskit.pulse.library.discrete.square")(duration, amp\[, freq, phase, name]) | Generates square wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`triangle`](#qiskit.pulse.library.discrete.triangle "qiskit.pulse.library.discrete.triangle")(duration, amp\[, freq, phase, name]) | Generates triangle wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
| [`zero`](#qiskit.pulse.library.discrete.zero "qiskit.pulse.library.discrete.zero")(duration\[, name]) | Generates zero-sampled [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform"). |
### constant
<Function id="qiskit.pulse.library.discrete.constant" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="constant(duration, amp, name=None)">
Generates constant-sampled [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp`, samples from the function:
$$
f(x) = A
$$
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Complex pulse amplitude.
* **name** (`Optional`\[`str`]) Name of pulse.
**Return type**
`Waveform`
</Function>
### cos
<Function id="qiskit.pulse.library.discrete.cos" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="cos(duration, amp, freq=None, phase=0, name=None)">
Generates cosine wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp`, $\omega=$ `freq`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = A \cos(2 \pi \omega x + \phi)
$$
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude.
* **freq** (`Optional`\[`float`]) Pulse frequency, units of 1/dt. If `None` defaults to single cycle.
* **phase** (`float`) Pulse phase.
* **name** (`Optional`\[`str`]) Name of pulse.
**Return type**
`Waveform`
</Function>
### drag
<Function id="qiskit.pulse.library.discrete.drag" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="drag(duration, amp, sigma, beta, name=None, zero_ends=True)">
Generates Y-only correction DRAG [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform") for standard nonlinear oscillator (SNO) \[1].
For $A=$ `amp`, $\sigma=$ `sigma`, and $\beta=$ `beta`, applies the `midpoint` sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = g(x) + i \beta h(x),
$$
where $g(x)$ is the function sampled in [`gaussian()`](#qiskit.pulse.library.discrete.gaussian "qiskit.pulse.library.discrete.gaussian"), and $h(x)$ is the function sampled in [`gaussian_deriv()`](#qiskit.pulse.library.discrete.gaussian_deriv "qiskit.pulse.library.discrete.gaussian_deriv").
If `zero_ends == True`, the samples from $g(x)$ are remapped as in [`gaussian()`](#qiskit.pulse.library.discrete.gaussian "qiskit.pulse.library.discrete.gaussian").
**References**
1. [*Gambetta, J. M., Motzoi, F., Merkel, S. T. & Wilhelm, F. K. “Analytic control methods for high-fidelity unitary operations in a weakly nonlinear oscillator.” Phys. Rev. A 83, 012308 (2011).*](http://dx.doi.org/10.1103/PhysRevA.83.012308)
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude at center `duration/2`.
* **sigma** (`float`) Width (standard deviation) of pulse.
* **beta** (`float`) Y correction amplitude. For the SNO this is $\beta=-\frac{\lambda_1^2}{4\Delta_2}$. Where $\lambda_1$ is the relative coupling strength between the first excited and second excited states and $\Delta_2$ is the detuning between the respective excited states.
* **name** (`Optional`\[`str`]) Name of pulse.
* **zero\_ends** (`bool`) If True, zero ends at `x = -1, x = duration + 1`, but rescale to preserve amp.
**Return type**
`Waveform`
</Function>
### gaussian
<Function id="qiskit.pulse.library.discrete.gaussian" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="gaussian(duration, amp, sigma, name=None, zero_ends=True)">
Generates unnormalized gaussian [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp` and $\sigma=$ `sigma`, applies the `midpoint` sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = A\exp\left(\left(\frac{x - \mu}{2\sigma}\right)^2 \right),
$$
with the center $\mu=$ `duration/2`.
If `zero_ends==True`, each output sample $y$ is modified according to:
$$
y \mapsto A\frac{y-y^*}{A-y^*},
$$
where $y^*$ is the value of the endpoint samples. This sets the endpoints to $0$ while preserving the amplitude at the center. If $A=y^*$, $y$ is set to $1$. By default, the endpoints are at `x = -1, x = duration + 1`.
Integrated area under the full curve is `amp * np.sqrt(2*np.pi*sigma**2)`
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude at `duration/2`.
* **sigma** (`float`) Width (standard deviation) of pulse.
* **name** (`Optional`\[`str`]) Name of pulse.
* **zero\_ends** (`bool`) If True, zero ends at `x = -1, x = duration + 1`, but rescale to preserve amp.
**Return type**
`Waveform`
</Function>
### gaussian\_deriv
<Function id="qiskit.pulse.library.discrete.gaussian_deriv" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="gaussian_deriv(duration, amp, sigma, name=None)">
Generates unnormalized gaussian derivative [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp` and $\sigma=$ `sigma` applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = A\frac{(x - \mu)}{\sigma^2}\exp\left(\left(\frac{x - \mu}{2\sigma}\right)^2 \right)
$$
i.e. the derivative of the Gaussian function, with center $\mu=$ `duration/2`.
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude of corresponding Gaussian at the pulse center (`duration/2`).
* **sigma** (`float`) Width (standard deviation) of pulse.
* **name** (`Optional`\[`str`]) Name of pulse.
**Return type**
`Waveform`
</Function>
### gaussian\_square
<Function id="qiskit.pulse.library.discrete.gaussian_square" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="gaussian_square(duration, amp, sigma, risefall=None, width=None, name=None, zero_ends=True)">
Generates gaussian square [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $d=$ `duration`, $A=$ `amp`, $\sigma=$ `sigma`, and $r=$ `risefall`, applies the `midpoint` sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
\begin{split}f(x) = \begin{cases}
g(x - r) ) & x\leq r \\
A & r\leq x\leq d-r \\
g(x - (d - r)) & d-r\leq x
\end{cases}\end{split}
$$
where $g(x)$ is the Gaussian function sampled from in [`gaussian()`](#qiskit.pulse.library.discrete.gaussian "qiskit.pulse.library.discrete.gaussian") with $A=$ `amp`, $\mu=1$, and $\sigma=$ `sigma`. I.e. $f(x)$ represents a square pulse with smooth Gaussian edges.
If `zero_ends == True`, the samples for the Gaussian ramps are remapped as in [`gaussian()`](#qiskit.pulse.library.discrete.gaussian "qiskit.pulse.library.discrete.gaussian").
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude.
* **sigma** (`float`) Width (standard deviation) of Gaussian rise/fall portion of the pulse.
* **risefall** (`Optional`\[`float`]) Number of samples over which pulse rise and fall happen. Width of square portion of pulse will be `duration-2*risefall`.
* **width** (`Optional`\[`float`]) The duration of the embedded square pulse. Only one of `width` or `risefall` should be specified as the functional form requires `width = duration - 2 * risefall`.
* **name** (`Optional`\[`str`]) Name of pulse.
* **zero\_ends** (`bool`) If True, zero ends at `x = -1, x = duration + 1`, but rescale to preserve amp.
**Raises**
[**PulseError**](qiskit.pulse.PulseError "qiskit.pulse.PulseError") If `risefall` and `width` arguments are inconsistent or not enough info.
**Return type**
`Waveform`
</Function>
### sawtooth
<Function id="qiskit.pulse.library.discrete.sawtooth" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="sawtooth(duration, amp, freq=None, phase=0, name=None)">
Generates sawtooth wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp`, $T=$ `period`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = 2 A \left( g(x) - \left\lfloor \frac{1}{2} + g(x) \right\rfloor\right)
$$
where $g(x) = x/T + \phi/\pi$.
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude. Wave range is $[-$ `amp` $,$ `amp` $]$.
* **freq** (`Optional`\[`float`]) Pulse frequency, units of 1./dt. If `None` defaults to 1./duration.
* **phase** (`float`) Pulse phase.
* **name** (`Optional`\[`str`]) Name of pulse.
**Example**
```python
import matplotlib.pyplot as plt
from qiskit.pulse.library import sawtooth
import numpy as np
duration = 100
amp = 1
freq = 1 / duration
sawtooth_wave = np.real(sawtooth(duration, amp, freq).samples)
plt.plot(range(duration), sawtooth_wave)
```
```
[<matplotlib.lines.Line2D at 0x7f47cc2fe090>]
```
![../\_images/qiskit.pulse.library.discrete\_0\_1.png](/images/api/qiskit/0.26/qiskit.pulse.library.discrete_0_1.png)
**Return type**
`Waveform`
</Function>
### sech
<Function id="qiskit.pulse.library.discrete.sech" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="sech(duration, amp, sigma, name=None, zero_ends=True)">
Generates unnormalized sech [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp` and $\sigma=$ `sigma`, applies the `midpoint` sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = A\text{sech}\left(\frac{x-\mu}{\sigma} \right)
$$
with the center $\mu=$ `duration/2`.
If `zero_ends==True`, each output sample $y$ is modified according to:
$$
y \mapsto A\frac{y-y^*}{A-y^*},
$$
where $y^*$ is the value of the endpoint samples. This sets the endpoints to $0$ while preserving the amplitude at the center. If $A=y^*$, $y$ is set to $1$. By default, the endpoints are at `x = -1, x = duration + 1`.
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude at duration/2.
* **sigma** (`float`) Width (standard deviation) of pulse.
* **name** (`Optional`\[`str`]) Name of pulse.
* **zero\_ends** (`bool`) If True, zero ends at `x = -1, x = duration + 1`, but rescale to preserve amp.
**Return type**
`Waveform`
</Function>
### sech\_deriv
<Function id="qiskit.pulse.library.discrete.sech_deriv" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="sech_deriv(duration, amp, sigma, name=None)">
Generates unnormalized sech derivative [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp`, $\sigma=$ `sigma`, and center $\mu=$ `duration/2`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = \frac{d}{dx}\left[A\text{sech}\left(\frac{x-\mu}{\sigma} \right)\right],
$$
i.e. the derivative of $\text{sech}$.
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude at center.
* **sigma** (`float`) Width (standard deviation) of pulse.
* **name** (`Optional`\[`str`]) Name of pulse.
**Return type**
`Waveform`
</Function>
### sin
<Function id="qiskit.pulse.library.discrete.sin" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="sin(duration, amp, freq=None, phase=0, name=None)">
Generates sine wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp`, $\omega=$ `freq`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = A \sin(2 \pi \omega x + \phi)
$$
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude.
* **freq** (`Optional`\[`float`]) Pulse frequency, units of 1/dt. If `None` defaults to single cycle.
* **phase** (`float`) Pulse phase.
* **name** (`Optional`\[`str`]) Name of pulse.
**Return type**
`Waveform`
</Function>
### square
<Function id="qiskit.pulse.library.discrete.square" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="square(duration, amp, freq=None, phase=0, name=None)">
Generates square wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp`, $T=$ `period`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = A \text{sign}\left[ \sin\left(\frac{2 \pi x}{T} + 2\phi\right) \right]
$$
with the convention $\text{sign}(0) = 1$.
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude. Wave range is $[-$ `amp` $,$ `amp` $]$.
* **freq** (`Optional`\[`float`]) Pulse frequency, units of 1./dt. If `None` defaults to 1./duration.
* **phase** (`float`) Pulse phase.
* **name** (`Optional`\[`str`]) Name of pulse.
**Return type**
`Waveform`
</Function>
### triangle
<Function id="qiskit.pulse.library.discrete.triangle" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="triangle(duration, amp, freq=None, phase=0, name=None)">
Generates triangle wave [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
For $A=$ `amp`, $T=$ `period`, and $\phi=$ `phase`, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:
$$
f(x) = A \left(-2\left|\text{sawtooth}(x, A, T, \phi)\right| + 1\right)
$$
This a non-sinusoidal wave with linear ramping.
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **amp** (`complex`) Pulse amplitude. Wave range is $[-$ `amp` $,$ `amp` $]$.
* **freq** (`Optional`\[`float`]) Pulse frequency, units of 1./dt. If `None` defaults to 1./duration.
* **phase** (`float`) Pulse phase.
* **name** (`Optional`\[`str`]) Name of pulse.
**Example**
```python
import matplotlib.pyplot as plt
from qiskit.pulse.library import triangle
import numpy as np
duration = 100
amp = 1
freq = 1 / duration
triangle_wave = np.real(triangle(duration, amp, freq).samples)
plt.plot(range(duration), triangle_wave)
```
```
[<matplotlib.lines.Line2D at 0x7f47cbe3a790>]
```
![../\_images/qiskit.pulse.library.discrete\_1\_1.png](/images/api/qiskit/0.26/qiskit.pulse.library.discrete_1_1.png)
**Return type**
`Waveform`
</Function>
### zero
<Function id="qiskit.pulse.library.discrete.zero" github="https://github.com/qiskit/qiskit/tree/stable/0.17/qiskit/pulse/library/discrete.py" signature="zero(duration, name=None)">
Generates zero-sampled [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform").
Samples from the function:
$$
f(x) = 0
$$
**Parameters**
* **duration** (`int`) Duration of pulse. Must be greater than zero.
* **name** (`Optional`\[`str`]) Name of pulse.
**Return type**
`Waveform`
</Function>