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 QuantumCircuits.

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) scheduled in parallel over multiple virtual hardware or simulator resources (see: 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.

Instructions

qiskit.pulse.instructions

The instructions module holds the various Instructions which are supported by Qiskit Pulse. Instructions have operands, which typically include at least one Channel specifying where the instruction will be applied.

Every instruction has a duration, whether explicitly included as an operand or implicitly defined. For instance, a ShiftPhase instruction can be instantiated with operands phase and channel, for some float phase and a Channel channel:

ShiftPhase(phase, channel)

The duration of this instruction is implicitly zero. On the other hand, the Delay instruction takes an explicit duration:

Delay(duration, channel)

An instruction can be added to a Schedule, which is a sequence of scheduled Pulse Instruction s over many channels. Instruction s and Schedule s implement the same interface.

These are all instances of the same base class:

Instruction

Pulse Library

qiskit.pulse.library

This library provides Pulse users with convenient methods to build Pulse waveforms.

A pulse programmer can choose from one of several Pulse Models such as Waveform and SymbolicPulse to create a pulse program. The Waveform model directly stores the waveform data points in each class instance. This model provides the most flexibility to express arbitrary waveforms and allows a rapid prototyping of new control techniques. However, this model is typically memory inefficient and might be hard to scale to large-size quantum processors. Several waveform subclasses are defined by Waveform Pulse Representation, but a user can also directly instantiate the Waveform class with samples argument which is usually a complex numpy array or any kind of array-like data.

In contrast, the SymbolicPulse model only stores the function and its parameters that generate the waveform in a class instance. It thus provides greater memory efficiency at the price of less flexibility in the waveform. This model also defines a small set of pulse subclasses in Parametric Pulse Representation which are commonly used in superconducting quantum processors. An instance of these subclasses can be serialized in the QPY Format while keeping the memory-efficient parametric representation of waveforms. Note that Waveform object can be generated from an instance of a SymbolicPulse which will set values for the parameters and sample the parametric expression to create the Waveform.

Pulse Models

Waveform Pulse Representation

Parametric Pulse Representation

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. Channels include:

• transmit channels, which should subclass PulseChannel
• receive channels, such as AcquireChannel
• non-signal “channels” such as SnapshotChannel, MemorySlot and RegisterChannel.

Novel channel types can often utilize the ControlChannel, but if this is not sufficient, new channel types can be created. Then, they must be supported in the PulseQobj schema and the assembler. Channels are characterized by their type and their index. See each channel type below to learn more.

All channels are children of the same abstract base class:

Channel

And classical IO channels are children of:

ClassicalIOChannel

Schedules

Schedules are Pulse programs. They describe instruction sequences for the control hardware. The Schedule is one of the most fundamental objects to this pulse-level programming module. A Schedule is a representation of a program in Pulse. Each schedule tracks the time of each instruction occuring in parallel over multiple signal channels.

Pulse Transforms

qiskit.pulse.transforms

The pulse transforms provide transformation routines to reallocate and optimize pulse programs for backends.

Alignments

The alignment transforms define alignment policies of instructions in ScheduleBlock. These transformations are called to create Schedules from ScheduleBlocks.

These are all subtypes of the abstract base class AlignmentKind.

AlignmentKind

Canonicalization

The canonicalization transforms convert schedules to a form amenable for execution on OpenPulse backends.

DAG

The DAG transforms create DAG representation of input program. This can be used for optimization of instructions and equality checks.

Composite transform

A sequence of transformations to generate a target code.

Pulse Builder

Use the pulse builder DSL to write pulse programs with an imperative syntax.

The pulse builder provides an imperative API for writing pulse programs with less difficulty than the 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:

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

To begin pulse programming we must first initialize our program builder context with build(), after which we can begin adding program statements. For example, below we write a simple program that play()s a pulse:

from qiskit import execute, pulse
 
d0 = pulse.DriveChannel(0)
 
with pulse.build() as pulse_prog:
    pulse.play(pulse.Constant(100, 1.0), d0)
 
pulse_prog.draw()

The builder initializes a pulse.Schedule, pulse_prog and then begins to construct the program within the context. The output pulse schedule will survive after the context is exited and can be executed like a normal Qiskit schedule using qiskit.execute(pulse_prog, backend).

Pulse programming has a simple imperative style. This leaves the programmer to worry about the raw experimental physics of pulse programming and not constructing cumbersome data structures.

We can optionally pass a Backend to build() to enable enhanced functionality. Below, we prepare a Bell state by automatically compiling the required pulses from their gate-level representations, while simultaneously applying a long decoupling pulse to a neighboring qubit. We terminate the experiment with a measurement to observe the state we prepared. This program which mixes circuits and pulses will be automatically lowered to be run as a pulse program:

import math
 
from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse3Q
 
# TODO: This example should use a real mock backend.
backend = FakeOpenPulse3Q()
 
d2 = pulse.DriveChannel(2)
 
with pulse.build(backend) as bell_prep:
    pulse.u2(0, math.pi, 0)
    pulse.cx(0, 1)
 
with pulse.build(backend) as decoupled_bell_prep_and_measure:
    # We call our bell state preparation schedule constructed above.
    with pulse.align_right():
        pulse.call(bell_prep)
        pulse.play(pulse.Constant(bell_prep.duration, 0.02), d2)
        pulse.barrier(0, 1, 2)
        registers = pulse.measure_all()
 
decoupled_bell_prep_and_measure.draw()

With the pulse builder we are able to blend programming on qubits and channels. While the pulse schedule is based on instructions that operate on channels, the pulse builder automatically handles the mapping from qubits to channels for you.

In the example below we demonstrate some more features of the pulse builder:

import math
 
from qiskit import pulse, QuantumCircuit
from qiskit.pulse import library
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
with pulse.build(backend) as pulse_prog:
    # Create a pulse.
    gaussian_pulse = library.gaussian(10, 1.0, 2)
    # Get the qubit's corresponding drive channel from the backend.
    d0 = pulse.drive_channel(0)
    d1 = pulse.drive_channel(1)
    # Play a pulse at t=0.
    pulse.play(gaussian_pulse, d0)
    # Play another pulse directly after the previous pulse at t=10.
    pulse.play(gaussian_pulse, d0)
    # The default scheduling behavior is to schedule pulses in parallel
    # across channels. For example, the statement below
    # plays the same pulse on a different channel at t=0.
    pulse.play(gaussian_pulse, d1)
 
    # We also provide pulse scheduling alignment contexts.
    # The default alignment context is align_left.
 
    # The sequential context schedules pulse instructions sequentially in time.
    # This context starts at t=10 due to earlier pulses above.
    with pulse.align_sequential():
        pulse.play(gaussian_pulse, d0)
        # Play another pulse after at t=20.
        pulse.play(gaussian_pulse, d1)
 
        # We can also nest contexts as each instruction is
        # contained in its local scheduling context.
        # The output of a child context is a context-schedule
        # with the internal instructions timing fixed relative to
        # one another. This is schedule is then called in the parent context.
 
        # Context starts at t=30.
        with pulse.align_left():
            # Start at t=30.
            pulse.play(gaussian_pulse, d0)
            # Start at t=30.
            pulse.play(gaussian_pulse, d1)
        # Context ends at t=40.
 
        # Alignment context where all pulse instructions are
        # aligned to the right, ie., as late as possible.
        with pulse.align_right():
            # Shift the phase of a pulse channel.
            pulse.shift_phase(math.pi, d1)
            # Starts at t=40.
            pulse.delay(100, d0)
            # Ends at t=140.
 
            # Starts at t=130.
            pulse.play(gaussian_pulse, d1)
            # Ends at t=140.
 
        # Acquire data for a qubit and store in a memory slot.
        pulse.acquire(100, 0, pulse.MemorySlot(0))
 
        # We also support a variety of macros for common operations.
 
        # Measure all qubits.
        pulse.measure_all()
 
        # Delay on some qubits.
        # This requires knowledge of which channels belong to which qubits.
        # delay for 100 cycles on qubits 0 and 1.
        pulse.delay_qubits(100, 0, 1)
 
        # Call a quantum circuit. The pulse builder lazily constructs a quantum
        # circuit which is then transpiled and scheduled before inserting into
        # a pulse schedule.
        # NOTE: Quantum register indices correspond to physical qubit indices.
        qc = QuantumCircuit(2, 2)
        qc.cx(0, 1)
        pulse.call(qc)
        # Calling a small set of standard gates and decomposing to pulses is
        # also supported with more natural syntax.
        pulse.u3(0, math.pi, 0, 0)
        pulse.cx(0, 1)
 
 
        # It is also be possible to call a preexisting schedule
        tmp_sched = pulse.Schedule()
        tmp_sched += pulse.Play(gaussian_pulse, d0)
        pulse.call(tmp_sched)
 
        # We also support:
 
        # frequency instructions
        pulse.set_frequency(5.0e9, d0)
 
        # phase instructions
        pulse.shift_phase(0.1, d0)
 
        # offset contexts
        with pulse.phase_offset(math.pi, d0):
            pulse.play(gaussian_pulse, d0)

The above is just a small taste of what is possible with the builder. See the rest of the module documentation for more information on its capabilities.

Channels

Methods to return the correct channels for the respective qubit indices.

from qiskit import pulse
from qiskit.providers.fake_provider import FakeArmonk
 
backend = FakeArmonk()
 
with pulse.build(backend) as drive_sched:
    d0 = pulse.drive_channel(0)
    print(d0)

DriveChannel(0)

Instructions

Pulse instructions are available within the builder interface. Here’s an example:

from qiskit import pulse
from qiskit.providers.fake_provider 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()

Contexts

Builder aware contexts that modify the construction of a pulse program. For example an alignment context like align_right() may be used to align all pulses as late as possible in a pulse program.

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

Macros

Macros help you add more complex functionality to your pulse program.

from qiskit import pulse
from qiskit.providers.fake_provider import FakeArmonk
 
backend = FakeArmonk()
 
with pulse.build(backend) as measure_sched:
    mem_slot = pulse.measure(0)
    print(mem_slot)

MemorySlot(0)

Circuit Gates

To use circuit level gates within your pulse program call a circuit with call().

import math
 
from qiskit import pulse
from qiskit.providers.fake_provider import FakeArmonk
 
backend = FakeArmonk()
 
with pulse.build(backend) as u3_sched:
    pulse.u3(math.pi, 0, math.pi, 0)

Utilities

The utility functions can be used to gather attributes about the backend and modify how the program is built.

from qiskit import pulse
 
from qiskit.providers.fake_provider import FakeArmonk
 
backend = FakeArmonk()
 
with pulse.build(backend) as u3_sched:
    print('Number of qubits 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 qubits in backend: 1
There are 160 samples in 3.5555555555555554e-08 seconds
There are 1e-06 seconds in 4500 samples.

Configuration

Exceptions

PulseError