Pulse

qiskit.pulse.library.constant(duration, amp, name=None)

Generates constant-sampled Waveform.

For $A=$ amp, samples from the function:

Parameters

• duration (int) – Duration of pulse. Must be greater than zero.
• amp (complex) – Complex pulse amplitude.
• name (str | None) – Name of pulse.

Return type

Waveform

qiskit.pulse.library.zero(duration, name=None)

Generates zero-sampled Waveform.

Samples from the function:

Parameters

• duration (int) – Duration of pulse. Must be greater than zero.
• name (str | None) – Name of pulse.

Return type

Waveform

qiskit.pulse.library.square(duration, amp, freq=None, phase=0, name=None)

Generates square wave Waveform.

For $A=$ amp, $T=$ period, and $\phi=$ phase, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:

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 (float) – Pulse frequency, units of 1./dt. If None defaults to 1./duration.
• phase (float) – Pulse phase.
• name (str | None) – Name of pulse.

Return type

Waveform

qiskit.pulse.library.sawtooth(duration, amp, freq=None, phase=0, name=None)

Generates sawtooth wave Waveform.

For $A=$ amp, $T=$ period, and $\phi=$ phase, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:

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 (float) – Pulse frequency, units of 1./dt. If None defaults to 1./duration.
• phase (float) – Pulse phase.
• name (str | None) – Name of pulse.

Return type

Waveform

Example

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)
plt.show()

qiskit.pulse.library.triangle(duration, amp, freq=None, phase=0, name=None)

Generates triangle wave Waveform.

For $A=$ amp, $T=$ period, and $\phi=$ phase, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:

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 (float) – Pulse frequency, units of 1./dt. If None defaults to 1./duration.
• phase (float) – Pulse phase.
• name (str | None) – Name of pulse.

Return type

Waveform

Example

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)
plt.show()

qiskit.pulse.library.cos(duration, amp, freq=None, phase=0, name=None)

Generates cosine wave Waveform.

For $A=$ amp, $\omega=$ freq, and $\phi=$ phase, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:

Parameters

• duration (int) – Duration of pulse. Must be greater than zero.
• amp (complex) – Pulse amplitude.
• freq (float) – Pulse frequency, units of 1/dt. If None defaults to single cycle.
• phase (float) – Pulse phase.
• name (str | None) – Name of pulse.

Return type

Waveform

qiskit.pulse.library.sin(duration, amp, freq=None, phase=0, name=None)

Generates sine wave Waveform.

For $A=$ amp, $\omega=$ freq, and $\phi=$ phase, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:

Parameters

• duration (int) – Duration of pulse. Must be greater than zero.
• amp (complex) – Pulse amplitude.
• freq (float) – Pulse frequency, units of 1/dt. If None defaults to single cycle.
• phase (float) – Pulse phase.
• name (str | None) – Name of pulse.

Return type

Waveform

qiskit.pulse.library.gaussian(duration, amp, sigma, name=None, zero_ends=True)

Generates unnormalized gaussian Waveform.

For $A=$ amp and $\sigma=$ sigma, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:

with the center $\mu=$ duration/2.

If zero_ends==True, each output sample $y$ is modified according to:

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 (str | None) – Name of pulse.
• zero_ends (bool) – If True, zero ends at x = -1, x = duration + 1, but rescale to preserve amp.

Return type

Waveform

qiskit.pulse.library.gaussian_deriv(duration, amp, sigma, name=None)

Generates unnormalized gaussian derivative Waveform.

For $A=$ amp and $\sigma=$ sigma applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:

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 (str | None) – Name of pulse.

Return type

Waveform

qiskit.pulse.library.sech(duration, amp, sigma, name=None, zero_ends=True)

Generates unnormalized sech Waveform.

For $A=$ amp and $\sigma=$ sigma, applies the midpoint sampling strategy to generate a discrete pulse sampled from the continuous function:

with the center $\mu=$ duration/2.

If zero_ends==True, each output sample $y$ is modified according to:

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

qiskit.pulse.library.sech_deriv(duration, amp, sigma, name=None)

Generates unnormalized sech derivative 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:

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 (str) – Name of pulse.

Return type

Waveform

qiskit.pulse.library.gaussian_square(duration, amp, sigma, risefall=None, width=None, name=None, zero_ends=True)

Generates gaussian square 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:

where $g(x)$ is the Gaussian function sampled from in 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().

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 (float | None) – Number of samples over which pulse rise and fall happen. Width of square portion of pulse will be duration-2*risefall.
• width (float | None) – 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 (str | None) – Name of pulse.
• zero_ends (bool) – If True, zero ends at x = -1, x = duration + 1, but rescale to preserve amp.

Raises

PulseError – If risefall and width arguments are inconsistent or not enough info.

Return type

Waveform

qiskit.pulse.library.drag(duration, amp, sigma, beta, name=None, zero_ends=True)

Generates Y-only correction DRAG 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:

where $g(x)$ is the function sampled in gaussian(), and $h(x)$ is the function sampled in gaussian_deriv().

If zero_ends == True, the samples from $g(x)$ are remapped as in 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).

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 (str | None) – Name of pulse.
• zero_ends (bool) – If True, zero ends at x = -1, x = duration + 1, but rescale to preserve amp.

Return type

Waveform

qiskit.pulse.transforms.add_implicit_acquires(schedule, meas_map)

Return a new schedule with implicit acquires from the measurement mapping replaced by explicit ones.

Parameters

• schedule (Schedule |Instruction) – Schedule to be aligned.
• meas_map (List[List[int]]) – List of lists of qubits that are measured together.

Returns

A Schedule with the additional acquisition instructions.

Return type

Schedule

qiskit.pulse.transforms.align_measures(schedules, inst_map=None, cal_gate='u3', max_calibration_duration=None, align_time=None, align_all=True)

Return new schedules where measurements occur at the same physical time.

This transformation will align the first Acquire on every channel to occur at the same time.

Minimum measurement wait time (to allow for calibration pulses) is enforced and may be set with max_calibration_duration.

By default only instructions containing a AcquireChannel or MeasureChannel will be shifted. If you wish to keep the relative timing of all instructions in the schedule set align_all=True.

This method assumes that MeasureChannel(i) and AcquireChannel(i) correspond to the same qubit and the acquire/play instructions should be shifted together on these channels.

from qiskit import pulse
from qiskit.pulse import transforms
 
d0 = pulse.DriveChannel(0)
m0 = pulse.MeasureChannel(0)
a0 = pulse.AcquireChannel(0)
mem0 = pulse.MemorySlot(0)
 
sched = pulse.Schedule()
sched.append(pulse.Play(pulse.Constant(10, 0.5), d0), inplace=True)
sched.append(pulse.Play(pulse.Constant(10, 1.), m0).shift(sched.duration), inplace=True)
sched.append(pulse.Acquire(20, a0, mem0).shift(sched.duration), inplace=True)
 
sched_shifted = sched << 20
 
aligned_sched, aligned_sched_shifted = transforms.align_measures([sched, sched_shifted])
 
assert aligned_sched == aligned_sched_shifted

If it is desired to only shift acquisition and measurement stimulus instructions set the flag align_all=False:

aligned_sched, aligned_sched_shifted = transforms.align_measures(
    [sched, sched_shifted],
    align_all=False,
)
 
assert aligned_sched != aligned_sched_shifted

Parameters

• schedules (Iterable[Schedule |Instruction]) – Collection of schedules to be aligned together
• inst_map (InstructionScheduleMap | None) – Mapping of circuit operations to pulse schedules
• cal_gate (str) – The name of the gate to inspect for the calibration time
• max_calibration_duration (int | None) – If provided, inst_map and cal_gate will be ignored
• align_time (int | None) – If provided, this will be used as final align time.
• align_all (bool | None) – Shift all instructions in the schedule such that they maintain their relative alignment with the shifted acquisition instruction. If False only the acquisition and measurement pulse instructions will be shifted.

Returns

The input list of schedules transformed to have their measurements aligned.

Raises

PulseError – If the provided alignment time is negative.

Return type

List[Schedule]

qiskit.pulse.transforms.block_to_schedule(block)

Convert ScheduleBlock to Schedule.

Parameters

block (ScheduleBlock) – A ScheduleBlock to convert.

Returns

Scheduled pulse program.

Raises

• UnassignedDurationError – When any instruction duration is not assigned.
• PulseError – When the alignment context duration is shorter than the schedule duration.

Return type

Schedule

qiskit.pulse.transforms.compress_pulses(schedules)

Optimization pass to replace identical pulses.

Parameters

schedules (List[Schedule]) – Schedules to compress.

Returns

Compressed schedules.

Return type

List[Schedule]

qiskit.pulse.transforms.flatten(program)

Flatten (inline) any called nodes into a Schedule tree with no nested children.

Parameters

program (Schedule) – Pulse program to remove nested structure.

Returns

Flatten pulse program.

Raises

PulseError – When invalid data format is given.

Return type

Schedule

qiskit.pulse.transforms.inline_subroutines(program)

Recursively remove call instructions and inline the respective subroutine instructions.

Assigned parameter values, which are stored in the parameter table, are also applied. The subroutine is copied before the parameter assignment to avoid mutation problem.

Parameters

program (Schedule |ScheduleBlock) – A program which may contain the subroutine, i.e. Call instruction.

Returns

A schedule without subroutine.

Raises

PulseError – When input program is not valid data format.

Return type

Schedule | ScheduleBlock

qiskit.pulse.transforms.pad(schedule, channels=None, until=None, inplace=False, pad_with=None)

Pad the input Schedule with Delay``s on all unoccupied timeslots until ``schedule.duration or until if not None.

Parameters

• schedule (Schedule) – Schedule to pad.
• channels (Iterable[Channel] | None) – Channels to pad. Defaults to all channels in schedule if not provided. If the supplied channel is not a member of schedule it will be added.
• until (int | None) – Time to pad until. Defaults to schedule.duration if not provided.
• inplace (bool) – Pad this schedule by mutating rather than returning a new schedule.
• pad_with (Type[Instruction] | None) – Pulse Instruction subclass to be used for padding. Default to Delay instruction.

Returns

The padded schedule.

Raises

PulseError – When non pulse instruction is set to pad_with.

Return type

Schedule

qiskit.pulse.transforms.remove_directives(schedule)

Remove directives.

Parameters

schedule (Schedule) – A schedule to remove compiler directives.

Returns

A schedule without directives.

Return type

Schedule

qiskit.pulse.transforms.remove_trivial_barriers(schedule)

Remove trivial barriers with 0 or 1 channels.

Parameters

schedule (Schedule) – A schedule to remove trivial barriers.

Returns

A schedule without trivial barriers

Return type

schedule

qiskit.pulse.transforms.block_to_dag(block)

Convert schedule block instruction into DAG.

ScheduleBlock can be represented as a DAG as needed. For example, equality of two programs are efficiently checked on DAG representation.

with pulse.build() as sched1:
    with pulse.align_left():
        pulse.play(my_gaussian0, pulse.DriveChannel(0))
        pulse.shift_phase(1.57, pulse.DriveChannel(2))
        pulse.play(my_gaussian1, pulse.DriveChannel(1))
 
with pulse.build() as sched2:
    with pulse.align_left():
        pulse.shift_phase(1.57, pulse.DriveChannel(2))
        pulse.play(my_gaussian1, pulse.DriveChannel(1))
        pulse.play(my_gaussian0, pulse.DriveChannel(0))

Here the sched1 `` and ``sched2 are different implementations of the same program, but it is difficult to confirm on the list representation.

Another example is instruction optimization.

with pulse.build() as sched:
    with pulse.align_left():
        pulse.shift_phase(1.57, pulse.DriveChannel(1))
        pulse.play(my_gaussian0, pulse.DriveChannel(0))
        pulse.shift_phase(-1.57, pulse.DriveChannel(1))

In above program two shift_phase instructions can be cancelled out because they are consecutive on the same drive channel. This can be easily found on the DAG representation.

Parameters

block ("ScheduleBlock") – A schedule block to be converted.

Returns

Instructions in DAG representation.

Raises

PulseError – When the context is invalid subclass.

Return type

PyDAG

qiskit.pulse.transforms.target_qobj_transform(sched, remove_directives=True)

A basic pulse program transformation for OpenPulse API execution.

Parameters

• sched (ScheduleBlock |Schedule |Tuple[int, Instruction] | Instruction |Iterable[Tuple[int, Instruction] | Instruction]) – Input program to transform.
• remove_directives (bool) – Set True to remove compiler directives.

Returns

Transformed program for execution.

Return type

Schedule

qiskit.pulse.builder.build(backend=None, schedule=None, name=None, default_alignment='left', default_transpiler_settings=None, default_circuit_scheduler_settings=None)

Create a context manager for launching the imperative pulse builder DSL.

To enter a building context and starting building a pulse program:

from qiskit import execute, pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
d0 = pulse.DriveChannel(0)
 
with pulse.build() as pulse_prog:
    pulse.play(pulse.Constant(100, 0.5), d0)

While the output program pulse_prog cannot be executed as we are using a mock backend. If a real backend is being used, executing the program is done with:

qiskit.execute(pulse_prog, backend)

Parameters

• backend (Backend) – A Qiskit backend. If not supplied certain builder functionality will be unavailable.
• schedule (ScheduleBlock | None) – A pulse ScheduleBlock in which your pulse program will be built.
• name (str | None) – Name of pulse program to be built.
• default_alignment (str |AlignmentKind | None) – Default scheduling alignment for builder. One of left, right, sequential or an alignment context.
• default_transpiler_settings (Dict[str, Any] | None) – Default settings for the transpiler.
• default_circuit_scheduler_settings (Dict[str, Any] | None) – Default settings for the circuit to pulse scheduler.

Returns

A new builder context which has the active builder initialized.

Return type

ContextManager[ScheduleBlock]

qiskit.pulse.builder.acquire_channel(qubit)

Return AcquireChannel for qubit on the active builder backend.

Examples:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
with pulse.build(backend):
    assert pulse.acquire_channel(0) == pulse.AcquireChannel(0)

Return type

AcquireChannel

qiskit.pulse.builder.control_channels(*qubits)

Return ControlChannel for qubit on the active builder backend.

Return the secondary drive channel for the given qubit – typically utilized for controlling multi-qubit interactions.

Examples:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
with pulse.build(backend):
    assert pulse.control_channels(0, 1) == [pulse.ControlChannel(0)]

Parameters

qubits (Iterable[int]) – Tuple or list of ordered qubits of the form (control_qubit, target_qubit).

Returns

List of control channels associated with the supplied ordered list of qubits.

Return type

List[ControlChannel]

qiskit.pulse.builder.drive_channel(qubit)

Return DriveChannel for qubit on the active builder backend.

Examples:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
with pulse.build(backend):
    assert pulse.drive_channel(0) == pulse.DriveChannel(0)

Return type

DriveChannel

qiskit.pulse.builder.measure_channel(qubit)

Return MeasureChannel for qubit on the active builder backend.

Examples:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
with pulse.build(backend):
    assert pulse.measure_channel(0) == pulse.MeasureChannel(0)

Return type

MeasureChannel

qiskit.pulse.builder.acquire(duration, qubit_or_channel, register, **metadata)

Acquire for a duration on a channel and store the result in a register.

Examples:

from qiskit import pulse
 
acq0 = pulse.AcquireChannel(0)
mem0 = pulse.MemorySlot(0)
 
with pulse.build() as pulse_prog:
    pulse.acquire(100, acq0, mem0)
 
    # measurement metadata
    kernel = pulse.configuration.Kernel('linear_discriminator')
    pulse.acquire(100, acq0, mem0, kernel=kernel)

Parameters

• duration (int) – Duration to acquire data for
• qubit_or_channel (int |AcquireChannel) – Either the qubit to acquire data for or the specific AcquireChannel to acquire on.
• register (StorageLocation) – Location to store measured result.
• metadata (Kernel | Discriminator) – Additional metadata for measurement. See Acquire for more information.

Raises

exceptions.PulseError – If the register type is not supported.

qiskit.pulse.builder.barrier(*channels_or_qubits, name=None)

Barrier directive for a set of channels and qubits.

This directive prevents the compiler from moving instructions across the barrier. Consider the case where we want to enforce that one pulse happens after another on separate channels, this can be done with:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
d0 = pulse.DriveChannel(0)
d1 = pulse.DriveChannel(1)
 
with pulse.build(backend) as barrier_pulse_prog:
    pulse.play(pulse.Constant(10, 1.0), d0)
    pulse.barrier(d0, d1)
    pulse.play(pulse.Constant(10, 1.0), d1)

Of course this could have been accomplished with:

from qiskit.pulse import transforms
 
with pulse.build(backend) as aligned_pulse_prog:
    with pulse.align_sequential():
        pulse.play(pulse.Constant(10, 1.0), d0)
        pulse.play(pulse.Constant(10, 1.0), d1)
 
barrier_pulse_prog = transforms.target_qobj_transform(barrier_pulse_prog)
aligned_pulse_prog = transforms.target_qobj_transform(aligned_pulse_prog)
 
assert barrier_pulse_prog == aligned_pulse_prog

The barrier allows the pulse compiler to take care of more advanced scheduling alignment operations across channels. For example in the case where we are calling an outside circuit or schedule and want to align a pulse at the end of one call:

import math
 
d0 = pulse.DriveChannel(0)
 
with pulse.build(backend) as pulse_prog:
    with pulse.align_right():
        pulse.x(1)
        # Barrier qubit 1 and d0.
        pulse.barrier(1, d0)
        # Due to barrier this will play before the gate on qubit 1.
        pulse.play(pulse.Constant(10, 1.0), d0)
        # This will end at the same time as the pulse above due to
        # the barrier.
        pulse.x(1)

Parameters

• channels_or_qubits (Channel |int) – Channels or qubits to barrier.
• name (str | None) – Name for the barrier

qiskit.pulse.builder.call(target, name=None, value_dict=None, **kw_params)

Call the subroutine within the currently active builder context with arbitrary parameters which will be assigned to the target program.

Examples

1. Calling a schedule block (recommended)

from qiskit import circuit, pulse
from qiskit.providers.fake_provider import FakeBogotaV2
 
backend = FakeBogotaV2()
 
with pulse.build() as x_sched:
    pulse.play(pulse.Gaussian(160, 0.1, 40), pulse.DriveChannel(0))
 
with pulse.build() as pulse_prog:
    pulse.call(x_sched)
 
print(pulse_prog)

ScheduleBlock(
    ScheduleBlock(
        Play(
            Gaussian(duration=160, amp=(0.1+0j), sigma=40),
            DriveChannel(0)
        ),
        name="block0",
        transform=AlignLeft()
    ),
    name="block1",
    transform=AlignLeft()
)

The actual program is stored in the reference table attached to the schedule.

print(pulse_prog.references)

ReferenceManager:
  - ('block0', '634b3b50bd684e26a673af1fbd2d6c81'): ScheduleBlock(Play(Gaussian(...

In addition, you can call a parameterized target program with parameter assignment.

amp = circuit.Parameter("amp")
 
with pulse.build() as subroutine:
    pulse.play(pulse.Gaussian(160, amp, 40), pulse.DriveChannel(0))
 
with pulse.build() as pulse_prog:
    pulse.call(subroutine, amp=0.1)
    pulse.call(subroutine, amp=0.3)
 
print(pulse_prog)

ScheduleBlock(
    ScheduleBlock(
        Play(
            Gaussian(duration=160, amp=(0.1+0j), sigma=40),
            DriveChannel(0)
        ),
        name="block2",
        transform=AlignLeft()
    ),
    ScheduleBlock(
        Play(
            Gaussian(duration=160, amp=(0.3+0j), sigma=40),
            DriveChannel(0)
        ),
        name="block2",
        transform=AlignLeft()
    ),
    name="block3",
    transform=AlignLeft()
)

If there is a name collision between parameters, you can distinguish them by specifying each parameter object in a python dictionary. For example,

amp1 = circuit.Parameter('amp')
amp2 = circuit.Parameter('amp')
 
with pulse.build() as subroutine:
    pulse.play(pulse.Gaussian(160, amp1, 40), pulse.DriveChannel(0))
    pulse.play(pulse.Gaussian(160, amp2, 40), pulse.DriveChannel(1))
 
with pulse.build() as pulse_prog:
    pulse.call(subroutine, value_dict={amp1: 0.1, amp2: 0.3})
 
print(pulse_prog)

ScheduleBlock(
    ScheduleBlock(
        Play(Gaussian(duration=160, amp=(0.1+0j), sigma=40), DriveChannel(0)),
        Play(Gaussian(duration=160, amp=(0.3+0j), sigma=40), DriveChannel(1)),
        name="block4",
        transform=AlignLeft()
    ),
    name="block5",
    transform=AlignLeft()
)

2. Calling a schedule

x_sched = backend.instruction_schedule_map.get("x", (0,))
 
with pulse.build(backend) as pulse_prog:
    pulse.call(x_sched)
 
print(pulse_prog)

ScheduleBlock(
    Call(
        Schedule(
            (
                0,
                Play(
                    Drag(
                        duration=160,
                        amp=(0.18989731546729305+0j),
                        sigma=40,
                        beta=-1.201258305015517,
                        name='drag_86a8'
                    ),
                    DriveChannel(0),
                    name='drag_86a8'
                )
            ),
            name="x"
        ),
        name='x'
    ),
    name="block6",
    transform=AlignLeft()
)

Currently, the backend calibrated gates are provided in the form of Schedule. The parameter assignment mechanism is available also for schedules. However, the called schedule is not treated as a reference.

3. Calling a quantum circuit

backend = FakeBogotaV2()
 
qc = circuit.QuantumCircuit(1)
qc.x(0)
 
with pulse.build(backend) as pulse_prog:
    pulse.call(qc)
 
print(pulse_prog)

ScheduleBlock(
    Call(
        Schedule(
            (
                0,
                Play(
                    Drag(
                        duration=160,
                        amp=(0.18989731546729305+0j),
                        sigma=40,
                        beta=-1.201258305015517,
                        name='drag_86a8'
                    ),
                    DriveChannel(0),
                    name='drag_86a8'
                )
            ),
            name="circuit-87"
        ),
        name='circuit-87'
    ),
    name="block7",
    transform=AlignLeft()
)

Parameters

• target (QuantumCircuit |Schedule |ScheduleBlock | None) – Target circuit or pulse schedule to call.
• name (str | None) – Optional. A unique name of subroutine if defined. When the name is explicitly provided, one cannot call different schedule blocks with the same name.
• value_dict (Dict[ParameterExpression |float, ParameterExpression |float] | None) – Optional. Parameters assigned to the target program. If this dictionary is provided, the target program is copied and then stored in the main built schedule and its parameters are assigned to the given values. This dictionary is keyed on Parameter objects, allowing parameter name collision to be avoided.
• kw_params (ParameterExpression |float) – Alternative way to provide parameters. Since this is keyed on the string parameter name, the parameters having the same name are all updated together. If you want to avoid name collision, use value_dict with Parameter objects instead.

qiskit.pulse.builder.delay(duration, channel, name=None)

Delay on a channel for a duration.

Examples:

from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
 
with pulse.build() as pulse_prog:
    pulse.delay(10, d0)

Parameters

• duration (int) – Number of cycles to delay for on channel.
• channel (Channel) – Channel to delay on.
• name (str | None) – Name of the instruction.

qiskit.pulse.builder.play(pulse, channel, name=None)

Play a pulse on a channel.

Examples:

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

Parameters

• pulse (Pulse | ndarray) – Pulse to play.
• channel (PulseChannel) – Channel to play pulse on.
• name (str | None) – Name of the pulse.

qiskit.pulse.builder.reference(name, *extra_keys)

Refer to undefined subroutine by string keys.

A Reference instruction is implicitly created and a schedule can be separately registered to the reference at a later stage.

from qiskit import pulse
 
with pulse.build() as main_prog:
    pulse.reference("x_gate", "q0")
 
with pulse.build() as subroutine:
    pulse.play(pulse.Gaussian(160, 0.1, 40), pulse.DriveChannel(0))
 
main_prog.assign_references(subroutine_dict={("x_gate", "q0"): subroutine})

Parameters

• name (str) – Name of subroutine.
• extra_keys (str) – Helper keys to uniquely specify the subroutine.

qiskit.pulse.builder.set_frequency(frequency, channel, name=None)

Set the frequency of a pulse channel.

Examples:

from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
 
with pulse.build() as pulse_prog:
    pulse.set_frequency(1e9, d0)

Parameters

• frequency (float) – Frequency in Hz to set channel to.
• channel (PulseChannel) – Channel to set frequency of.
• name (str | None) – Name of the instruction.

qiskit.pulse.builder.set_phase(phase, channel, name=None)

Set the phase of a pulse channel.

Examples:

import math
 
from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
 
with pulse.build() as pulse_prog:
    pulse.set_phase(math.pi, d0)

Parameters

• phase (float) – Phase in radians to set channel carrier signal to.
• channel (PulseChannel) – Channel to set phase of.
• name (str | None) – Name of the instruction.

qiskit.pulse.builder.shift_frequency(frequency, channel, name=None)

Shift the frequency of a pulse channel.

Examples:

from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
 
with pulse.build() as pulse_prog:
    pulse.shift_frequency(1e9, d0)

Parameters

• frequency (float) – Frequency in Hz to shift channel frequency by.
• channel (PulseChannel) – Channel to shift frequency of.
• name (str | None) – Name of the instruction.

qiskit.pulse.builder.shift_phase(phase, channel, name=None)

Shift the phase of a pulse channel.

Examples:

import math
 
from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
 
with pulse.build() as pulse_prog:
    pulse.shift_phase(math.pi, d0)

Parameters

• phase (float) – Phase in radians to shift channel carrier signal by.
• channel (PulseChannel) – Channel to shift phase of.
• name (str | None) – Name of the instruction.

qiskit.pulse.builder.snapshot(label, snapshot_type='statevector')

Simulator snapshot.

Examples:

from qiskit import pulse
 
with pulse.build() as pulse_prog:
    pulse.snapshot('first', 'statevector')

Parameters

• label (str) – Label for snapshot.
• snapshot_type (str) – Type of snapshot.

qiskit.pulse.builder.align_equispaced(duration)

Equispaced alignment pulse scheduling context.

Pulse instructions within this context are scheduled with the same interval spacing such that the total length of the context block is duration. If the total free duration cannot be evenly divided by the number of instructions within the context, the modulo is split and then prepended and appended to the returned schedule. Delay instructions are automatically inserted in between pulses.

This context is convenient to write a schedule for periodical dynamic decoupling or the Hahn echo sequence.

Examples:

from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
x90 = pulse.Gaussian(10, 0.1, 3)
x180 = pulse.Gaussian(10, 0.2, 3)
 
with pulse.build() as hahn_echo:
    with pulse.align_equispaced(duration=100):
        pulse.play(x90, d0)
        pulse.play(x180, d0)
        pulse.play(x90, d0)
 
hahn_echo.draw()

Parameters

duration (int |ParameterExpression) – Duration of this context. This should be larger than the schedule duration.

Yields

None

Return type

AlignmentKind

Notes

The scheduling is performed for sub-schedules within the context rather than channel-wise. If you want to apply the equispaced context for each channel, you should use the context independently for channels.

qiskit.pulse.builder.align_func(duration, func)

Callback defined alignment pulse scheduling context.

Pulse instructions within this context are scheduled at the location specified by arbitrary callback function position that takes integer index and returns the associated fractional location within [0, 1]. Delay instruction is automatically inserted in between pulses.

This context may be convenient to write a schedule of arbitrary dynamical decoupling sequences such as Uhrig dynamical decoupling.

Examples:

import numpy as np
from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
x90 = pulse.Gaussian(10, 0.1, 3)
x180 = pulse.Gaussian(10, 0.2, 3)
 
def udd10_pos(j):
    return np.sin(np.pi*j/(2*10 + 2))**2
 
with pulse.build() as udd_sched:
    pulse.play(x90, d0)
    with pulse.align_func(duration=300, func=udd10_pos):
        for _ in range(10):
            pulse.play(x180, d0)
    pulse.play(x90, d0)
 
udd_sched.draw()

Parameters

• duration (int |ParameterExpression) – Duration of context. This should be larger than the schedule duration.
• func (Callable[[int], float]) – A function that takes an index of sub-schedule and returns the fractional coordinate of of that sub-schedule. The returned value should be defined within [0, 1]. The pulse index starts from 1.

Yields

None

Return type

AlignmentKind

Notes

The scheduling is performed for sub-schedules within the context rather than channel-wise. If you want to apply the numerical context for each channel, you need to apply the context independently to channels.

qiskit.pulse.builder.align_left()

Left alignment pulse scheduling context.

Pulse instructions within this context are scheduled as early as possible by shifting them left to the earliest available time.

Examples:

from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
d1 = pulse.DriveChannel(1)
 
with pulse.build() as pulse_prog:
    with pulse.align_left():
        # this pulse will start at t=0
        pulse.play(pulse.Constant(100, 1.0), d0)
        # this pulse will start at t=0
        pulse.play(pulse.Constant(20, 1.0), d1)
pulse_prog = pulse.transforms.block_to_schedule(pulse_prog)
 
assert pulse_prog.ch_start_time(d0) == pulse_prog.ch_start_time(d1)

Yields

None

Return type

ContextManager[None]

qiskit.pulse.builder.align_right()

Right alignment pulse scheduling context.

Pulse instructions within this context are scheduled as late as possible by shifting them right to the latest available time.

Examples:

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 = pulse.transforms.block_to_schedule(pulse_prog)
 
assert pulse_prog.ch_stop_time(d0) == pulse_prog.ch_stop_time(d1)