qiskit-documentation/docs/api/qiskit/0.26/pulse.mdx

350 lines
32 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: pulse (v0.26)
description: API reference for qiskit.pulse in qiskit v0.26
in_page_toc_min_heading_level: 2
python_api_type: module
python_api_name: qiskit.pulse
---
<span id="module-qiskit.pulse" />
<span id="qiskit-pulse" />
<span id="pulse-qiskit-pulse" />
# Pulse
`qiskit.pulse`
Qiskit-Pulse is a pulse-level quantum programming kit. This lower level of programming offers the user more control than programming with [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") s.
Extracting the greatest performance from quantum hardware requires real-time pulse-level instructions. Pulse answers that need: it enables the quantum physicist *user* to specify the exact time dynamics of an experiment. It is especially powerful for error mitigation techniques.
The input is given as arbitrary, time-ordered signals (see: [Instructions (qiskit.pulse.instructions)](#pulse-insts)) scheduled in parallel over multiple virtual hardware or simulator resources (see: [Channels (qiskit.pulse.channels)](#pulse-channels)). The system also allows the user to recover the time dynamics of the measured output.
This is sufficient to allow the quantum physicist to explore and correct for noise in a quantum system.
<span id="instructions-qiskit-pulse-instructions" />
<span id="pulse-insts" />
## Instructions
`qiskit.pulse.instructions`
| | |
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`instructions`](qiskit.pulse.instructions#module-qiskit.pulse.instructions "qiskit.pulse.instructions") | The `instruction` module holds the various `Instruction` s which are supported by Qiskit Pulse. |
| [`Acquire`](qiskit.pulse.Acquire "qiskit.pulse.Acquire")(duration, channel\[, mem\_slot, …]) | The Acquire instruction is used to trigger the ADC associated with a particular qubit; e.g. |
| [`Call`](qiskit.pulse.Call "qiskit.pulse.Call")(subroutine\[, value\_dict, name]) | Pulse `Call` instruction. |
| [`Delay`](qiskit.pulse.Delay "qiskit.pulse.Delay")(duration, channel\[, name]) | A blocking instruction with no other effect. |
| [`Play`](qiskit.pulse.Play "qiskit.pulse.Play")(pulse, channel\[, name]) | This instruction is responsible for applying a pulse on a channel. |
| [`SetFrequency`](qiskit.pulse.SetFrequency "qiskit.pulse.SetFrequency")(frequency, channel\[, name]) | Set the channel frequency. |
| [`ShiftFrequency`](qiskit.pulse.ShiftFrequency "qiskit.pulse.ShiftFrequency")(frequency, channel\[, name]) | Shift the channel frequency away from the current frequency. |
| [`SetPhase`](qiskit.pulse.SetPhase "qiskit.pulse.SetPhase")(phase, channel\[, name]) | The set phase instruction sets the phase of the proceeding pulses on that channel to `phase` radians. |
| [`ShiftPhase`](qiskit.pulse.ShiftPhase "qiskit.pulse.ShiftPhase")(phase, channel\[, name]) | The shift phase instruction updates the modulation phase of proceeding pulses played on the same [`Channel`](qiskit.pulse.channels#channel "qiskit.pulse.channels.Channel"). |
| [`Snapshot`](qiskit.pulse.Snapshot "qiskit.pulse.Snapshot")(label\[, snapshot\_type, name]) | An instruction targeted for simulators, to capture a moment in the simulation. |
<span id="pulse-library-waveforms-qiskit-pulse-library" />
## Pulse Library (waveforms )
`qiskit.pulse.library`
| | |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| [`library`](qiskit.pulse.library#module-qiskit.pulse.library "qiskit.pulse.library") | This library provides Pulse users with convenient methods to build Pulse waveforms. |
| [`library.discrete`](qiskit.pulse.library.discrete#module-qiskit.pulse.library.discrete "qiskit.pulse.library.discrete") | Module for builtin discrete pulses. |
| [`Waveform`](qiskit.pulse.Waveform "qiskit.pulse.Waveform")(samples\[, name, epsilon]) | A pulse specified completely by complex-valued samples; each sample is played for the duration of the backend cycle-time, dt. |
| [`Constant`](qiskit.pulse.Constant "qiskit.pulse.Constant")(duration, amp\[, name]) | A simple constant pulse, with an amplitude value and a duration: |
| [`Drag`](qiskit.pulse.Drag "qiskit.pulse.Drag")(duration, amp, sigma, beta\[, name]) | The Derivative Removal by Adiabatic Gate (DRAG) pulse is a standard Gaussian pulse with an additional Gaussian derivative component. |
| [`Gaussian`](qiskit.pulse.Gaussian "qiskit.pulse.Gaussian")(duration, amp, sigma\[, name]) | A truncated pulse envelope shaped according to the Gaussian function whose mean is centered at the center of the pulse (duration / 2): |
| [`GaussianSquare`](qiskit.pulse.GaussianSquare "qiskit.pulse.GaussianSquare")(duration, amp, sigma, width) | A square pulse with a Gaussian shaped risefall on either side: |
<span id="channels-qiskit-pulse-channels" />
<span id="pulse-channels" />
## Channels
`qiskit.pulse.channels`
Pulse is meant to be agnostic to the underlying hardware implementation, while still allowing low-level control. Therefore, our signal channels are *virtual* hardware channels. The backend which executes our programs is responsible for mapping these virtual channels to the proper physical channel within the quantum control hardware.
Channels are characterized by their type and their index. See each channel type below to learn more.
| | |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [`channels`](qiskit.pulse.channels#module-qiskit.pulse.channels "qiskit.pulse.channels") | This module defines Pulse Channels. |
| [`DriveChannel`](qiskit.pulse.DriveChannel "qiskit.pulse.DriveChannel")(index) | Drive channels transmit signals to qubits which enact gate operations. |
| [`MeasureChannel`](qiskit.pulse.MeasureChannel "qiskit.pulse.MeasureChannel")(index) | Measure channels transmit measurement stimulus pulses for readout. |
| [`AcquireChannel`](qiskit.pulse.AcquireChannel "qiskit.pulse.AcquireChannel")(index) | Acquire channels are used to collect data. |
| [`ControlChannel`](qiskit.pulse.ControlChannel "qiskit.pulse.ControlChannel")(index) | Control channels provide supplementary control over the qubit to the drive channel. |
| [`RegisterSlot`](qiskit.pulse.RegisterSlot "qiskit.pulse.RegisterSlot")(index) | Classical resister slot channels represent classical registers (low-latency classical memory). |
| [`MemorySlot`](qiskit.pulse.MemorySlot "qiskit.pulse.MemorySlot")(index) | Memory slot channels represent classical memory storage. |
## Schedules
Schedules are Pulse programs. They describe instruction sequences for the control hardware.
| | |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule")(\*schedules\[, name, metadata]) | A quantum program *schedule* with exact time constraints for its instructions, operating over all input signal *channels* and supporting special syntaxes for building. |
| [`ScheduleBlock`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock")(\[name, metadata, …]) | A `ScheduleBlock` is a time-ordered sequence of instructions and transform macro to manage their relative timing. |
| [`Instruction`](qiskit.pulse.Instruction "qiskit.pulse.Instruction")(operands\[, duration, channels, name]) | The smallest schedulable unit: a single instruction. |
## Configuration
| | |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`InstructionScheduleMap`](qiskit.pulse.InstructionScheduleMap "qiskit.pulse.InstructionScheduleMap")() | Mapping from [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") [`qiskit.circuit.Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") names and qubits to [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") s. In particular, the mapping is formatted as type::. |
## Schedule Transforms
Schedule transforms take [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") s as input and return modified [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") s.
| | |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| [`transforms.align_measures`](qiskit.pulse.transforms.align_measures "qiskit.pulse.transforms.align_measures")(schedules\[, …]) | Return new schedules where measurements occur at the same physical time. |
| [`transforms.add_implicit_acquires`](qiskit.pulse.transforms.add_implicit_acquires "qiskit.pulse.transforms.add_implicit_acquires")(schedule, …) | Return a new schedule with implicit acquires from the measurement mapping replaced by explicit ones. |
| [`transforms.pad`](qiskit.pulse.transforms.pad "qiskit.pulse.transforms.pad")(schedule\[, channels, until, …]) | Pad the input Schedule with `Delay``s on all unoccupied timeslots until ``schedule.duration` or `until` if not `None`. |
## Exceptions
| | |
| ---------------------------------------------------------------------------- | ---------------------------------- |
| [`PulseError`](qiskit.pulse.PulseError "qiskit.pulse.PulseError")(\*message) | Errors raised by the pulse module. |
## Pulse Builder (builder)
<Admonition title="Warning" type="caution">
The pulse builder interface is still in active development. It may have breaking API changes without deprecation warnings in future releases until otherwise indicated.
</Admonition>
The pulse builder provides an imperative API for writing pulse programs with less difficulty than the [`Schedule`](qiskit.pulse.Schedule "qiskit.pulse.Schedule") API. It contextually constructs a pulse schedule and then emits the schedule for execution. For example to play a series of pulses on channels is as simple as:
```python
from qiskit import pulse
dc = pulse.DriveChannel
d0, d1, d2, d3, d4 = dc(0), dc(1), dc(2), dc(3), dc(4)
with pulse.build(name='pulse_programming_in') as pulse_prog:
pulse.play([1, 1, 1, 0, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 0, 1, 1, 1], d0)
pulse.play([1, 0, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0], d1)
pulse.play([1, 0, 1, 0, 0, 0, 1, 0, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0], d2)
pulse.play([1, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0], d3)
pulse.play([1, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 0, 1, 0, 1, 1, 1, 0, 0, 1, 0], d4)
pulse_prog.draw()
```
![../\_images/pulse\_0\_0.png](/images/api/qiskit/0.26/pulse_0_0.png)
In the future the pulse builder will be coupled to the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") with an equivalent circuit builder interface.
| | |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`build`](qiskit.pulse.builder.build "qiskit.pulse.builder.build")(\[backend, schedule, name, …]) | Create a context manager for launching the imperative pulse builder DSL. |
### Channels
Methods to return the correct channels for the respective qubit indices.
```python
from qiskit import pulse
from qiskit.test.mock import FakeArmonk
backend = FakeArmonk()
with pulse.build(backend) as drive_sched:
d0 = pulse.drive_channel(0)
print(d0)
```
```
DriveChannel(0)
```
| | |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [`acquire_channel`](qiskit.pulse.builder.acquire_channel "qiskit.pulse.builder.acquire_channel")(qubit) | Return `AcquireChannel` for `qubit` on the active builder backend. |
| [`control_channels`](qiskit.pulse.builder.control_channels "qiskit.pulse.builder.control_channels")(\*qubits) | Return `AcquireChannel` for `qubit` on the active builder backend. |
| [`drive_channel`](qiskit.pulse.builder.drive_channel "qiskit.pulse.builder.drive_channel")(qubit) | Return `DriveChannel` for `qubit` on the active builder backend. |
| [`measure_channel`](qiskit.pulse.builder.measure_channel "qiskit.pulse.builder.measure_channel")(qubit) | Return `MeasureChannel` for `qubit` on the active builder backend. |
### Instructions
Pulse instructions are available within the builder interface. Heres an example:
```python
from qiskit import pulse
from qiskit.test.mock import FakeArmonk
backend = FakeArmonk()
with pulse.build(backend) as drive_sched:
d0 = pulse.drive_channel(0)
a0 = pulse.acquire_channel(0)
pulse.play(pulse.library.Constant(10, 1.0), d0)
pulse.delay(20, d0)
pulse.shift_phase(3.14/2, d0)
pulse.set_phase(3.14, d0)
pulse.shift_frequency(1e7, d0)
pulse.set_frequency(5e9, d0)
with pulse.build() as temp_sched:
pulse.play(pulse.library.Gaussian(20, 1.0, 3.0), d0)
pulse.play(pulse.library.Gaussian(20, -1.0, 3.0), d0)
pulse.call(temp_sched)
pulse.acquire(30, a0, pulse.MemorySlot(0))
drive_sched.draw()
```
![../\_images/pulse\_2\_0.png](/images/api/qiskit/0.26/pulse_2_0.png)
| | |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| [`acquire`](qiskit.pulse.builder.acquire "qiskit.pulse.builder.acquire")(duration, qubit\_or\_channel, …) | Acquire for a `duration` on a `channel` and store the result in a `register`. |
| [`barrier`](qiskit.pulse.builder.barrier "qiskit.pulse.builder.barrier")(\*channels\_or\_qubits\[, name]) | Barrier directive for a set of channels and qubits. |
| [`call`](qiskit.pulse.builder.call "qiskit.pulse.builder.call")(target\[, name, value\_dict]) | Call the `target` within the currently active builder context with arbitrary parameters which will be assigned to the target program. |
| [`delay`](qiskit.pulse.builder.delay "qiskit.pulse.builder.delay")(duration, channel\[, name]) | Delay on a `channel` for a `duration`. |
| [`play`](qiskit.pulse.builder.play "qiskit.pulse.builder.play")(pulse, channel\[, name]) | Play a `pulse` on a `channel`. |
| [`set_frequency`](qiskit.pulse.builder.set_frequency "qiskit.pulse.builder.set_frequency")(frequency, channel\[, name]) | Set the `frequency` of a pulse `channel`. |
| [`set_phase`](qiskit.pulse.builder.set_phase "qiskit.pulse.builder.set_phase")(phase, channel\[, name]) | Set the `phase` of a pulse `channel`. |
| [`shift_frequency`](qiskit.pulse.builder.shift_frequency "qiskit.pulse.builder.shift_frequency")(frequency, channel\[, name]) | Shift the `frequency` of a pulse `channel`. |
| [`shift_phase`](qiskit.pulse.builder.shift_phase "qiskit.pulse.builder.shift_phase")(phase, channel\[, name]) | Shift the `phase` of a pulse `channel`. |
| [`snapshot`](qiskit.pulse.builder.snapshot "qiskit.pulse.builder.snapshot")(label\[, snapshot\_type]) | Simulator snapshot. |
### Contexts
Builder aware contexts that modify the construction of a pulse program. For example an alignment context like [`align_right()`](qiskit.pulse.builder.align_right "qiskit.pulse.builder.align_right") may be used to align all pulses as late as possible in a pulse program.
```python
from qiskit import pulse
d0 = pulse.DriveChannel(0)
d1 = pulse.DriveChannel(1)
with pulse.build() as pulse_prog:
with pulse.align_right():
# this pulse will start at t=0
pulse.play(pulse.Constant(100, 1.0), d0)
# this pulse will start at t=80
pulse.play(pulse.Constant(20, 1.0), d1)
pulse_prog.draw()
```
![../\_images/pulse\_3\_0.png](/images/api/qiskit/0.26/pulse_3_0.png)
| | |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| [`align_equispaced`](qiskit.pulse.builder.align_equispaced "qiskit.pulse.builder.align_equispaced")(duration) | Equispaced alignment pulse scheduling context. |
| [`align_func`](qiskit.pulse.builder.align_func "qiskit.pulse.builder.align_func")(duration, func) | Callback defined alignment pulse scheduling context. |
| [`align_left`](qiskit.pulse.builder.align_left "qiskit.pulse.builder.align_left")() | Left alignment pulse scheduling context. |
| [`align_right`](qiskit.pulse.builder.align_right "qiskit.pulse.builder.align_right")() | Right alignment pulse scheduling context. |
| [`align_sequential`](qiskit.pulse.builder.align_sequential "qiskit.pulse.builder.align_sequential")() | Sequential alignment pulse scheduling context. |
| [`circuit_scheduler_settings`](qiskit.pulse.builder.circuit_scheduler_settings "qiskit.pulse.builder.circuit_scheduler_settings")(\*\*settings) | Set the currently active circuit scheduler settings for this context. |
| [`frequency_offset`](qiskit.pulse.builder.frequency_offset "qiskit.pulse.builder.frequency_offset")(frequency, \*channels\[, …]) | Shift the frequency of inputs channels on entry into context and undo on exit. |
| [`inline`](qiskit.pulse.builder.inline "qiskit.pulse.builder.inline")() | Inline all instructions within this context into the parent context, inheriting the scheduling policy of the parent context. |
| [`pad`](qiskit.pulse.builder.pad "qiskit.pulse.builder.pad")(\*chs) | Pad all available timeslots with delays upon exiting context. |
| [`phase_offset`](qiskit.pulse.builder.phase_offset "qiskit.pulse.builder.phase_offset")(phase, \*channels) | Shift the phase of input channels on entry into context and undo on exit. |
| [`transpiler_settings`](qiskit.pulse.builder.transpiler_settings "qiskit.pulse.builder.transpiler_settings")(\*\*settings) | Set the currently active transpiler settings for this context. |
### Macros
Macros help you add more complex functionality to your pulse program.
```python
from qiskit import pulse
from qiskit.test.mock import FakeArmonk
backend = FakeArmonk()
with pulse.build(backend) as measure_sched:
mem_slot = pulse.measure(0)
print(mem_slot)
```
```
MemorySlot(0)
```
| | |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`measure`](qiskit.pulse.builder.measure "qiskit.pulse.builder.measure")(qubits\[, registers]) | Measure a qubit within the currently active builder context. |
| [`measure_all`](qiskit.pulse.builder.measure_all "qiskit.pulse.builder.measure_all")() | Measure all qubits within the currently active builder context. |
| [`delay_qubits`](qiskit.pulse.builder.delay_qubits "qiskit.pulse.builder.delay_qubits")(duration, \*qubits) | Insert delays on all of the [`channels.Channel`](qiskit.pulse.channels#channel "qiskit.pulse.channels.Channel")s that correspond to the input `qubits` at the same time. |
### Circuit Gates
To use circuit level gates within your pulse program call a circuit with [`qiskit.pulse.builder.call()`](qiskit.pulse.builder.call "qiskit.pulse.builder.call").
<Admonition title="Warning" type="caution">
These will be removed in future versions with the release of a circuit builder interface in which it will be possible to calibrate a gate in terms of pulses and use that gate in a circuit.
</Admonition>
```python
import math
from qiskit import pulse
from qiskit.test.mock import FakeArmonk
backend = FakeArmonk()
with pulse.build(backend) as u3_sched:
pulse.u3(math.pi, 0, math.pi, 0)
```
| | |
| --------------------------------------------------------------------------------- | --------------------------------------------- |
| [`cx`](qiskit.pulse.builder.cx "qiskit.pulse.builder.cx")(control, target) | Call a `CXGate` on the input physical qubits. |
| [`u1`](qiskit.pulse.builder.u1 "qiskit.pulse.builder.u1")(theta, qubit) | Call a `U1Gate` on the input physical qubit. |
| [`u2`](qiskit.pulse.builder.u2 "qiskit.pulse.builder.u2")(phi, lam, qubit) | Call a `U2Gate` on the input physical qubit. |
| [`u3`](qiskit.pulse.builder.u3 "qiskit.pulse.builder.u3")(theta, phi, lam, qubit) | Call a `U3Gate` on the input physical qubit. |
| [`x`](qiskit.pulse.builder.x "qiskit.pulse.builder.x")(qubit) | Call a `XGate` on the input physical qubit. |
### Utilities
The utility functions can be used to gather attributes about the backend and modify how the program is built.
```python
from qiskit import pulse
from qiskit.test.mock import FakeArmonk
backend = FakeArmonk()
with pulse.build(backend) as u3_sched:
print('Number of qubit in backend: '.format(pulse.num_qubits()))
samples = 160
print('There are {} samples in {} seconds'.format(
samples, pulse.samples_to_seconds(160)))
seconds = 1e-6
print('There are {} seconds in {} samples.'.format(
seconds, pulse.seconds_to_samples(1e-6)))
```
```
Number of qubit in backend:
There are 160 samples in 3.5555555555555554e-08 seconds
There are 1e-06 seconds in 4500 samples.
```
| | |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`active_backend`](qiskit.pulse.builder.active_backend "qiskit.pulse.builder.active_backend")() | Get the backend of the currently active builder context. |
| [`active_transpiler_settings`](qiskit.pulse.builder.active_transpiler_settings "qiskit.pulse.builder.active_transpiler_settings")() | Return the current active builder contexts transpiler settings. |
| [`active_circuit_scheduler_settings`](qiskit.pulse.builder.active_circuit_scheduler_settings "qiskit.pulse.builder.active_circuit_scheduler_settings")() | Return the current active builder contexts circuit scheduler settings. |
| [`num_qubits`](qiskit.pulse.builder.num_qubits "qiskit.pulse.builder.num_qubits")() | Return number of qubits in the currently active backend. |
| [`qubit_channels`](qiskit.pulse.builder.qubit_channels "qiskit.pulse.builder.qubit_channels")(qubit) | Returns the set of channels associated with a qubit. |
| [`samples_to_seconds`](qiskit.pulse.builder.samples_to_seconds "qiskit.pulse.builder.samples_to_seconds")(samples) | Obtain the time in seconds that will elapse for the input number of samples on the active backend. |
| [`seconds_to_samples`](qiskit.pulse.builder.seconds_to_samples "qiskit.pulse.builder.seconds_to_samples")(seconds) | Obtain the number of samples that will elapse in `seconds` on the active backend. |