Pulse

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[ScheduleComponent]) – 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[qiskit.pulse.schedule.Schedule]) – Schedules to compress.

Returns

Compressed schedules.

Return type

list[qiskit.pulse.schedule.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[chans.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[instructions.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

rx.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')

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 transpile, 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:

backend.run(transpile(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.

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[qiskit.pulse.channels.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 | chans.AcquireChannel) – Either the qubit to acquire data for or the specific AcquireChannel to acquire on.
• register (StorageLocation) – Location to store measured result.
• metadata (Unpack[_MetaDataType]) – 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.call(backend.defaults.instruction_schedule_map.get('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.call(backend.defaults.instruction_schedule_map.get('x', (1,)))

Parameters

• channels_or_qubits (chans.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 GenericBackendV2
 
backend = GenericBackendV2(num_qubits=5, calibrate_instructions=True)
 
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.

Parameters

• target (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[ParameterValueType, ParameterValueType] | 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 (ParameterValueType) – 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 (chans.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 (library.Pulse | np.ndarray) – Pulse to play.
• channel (chans.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 (chans.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 (chans.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 (chans.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 (chans.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

Generator[None, None, None]

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

Generator[None, None, None]

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

Generator[None, None, 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)

Yields

None

Return type

Generator[None, None, None]

qiskit.pulse.builder.align_sequential()

Sequential alignment pulse scheduling context.

Pulse instructions within this context are scheduled sequentially in time such that no two instructions will be played at the same time.

Examples:

from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
d1 = pulse.DriveChannel(1)
 
with pulse.build() as pulse_prog:
    with pulse.align_sequential():
        # this pulse will start at t=0
        pulse.play(pulse.Constant(100, 1.0), d0)
        # this pulse will also start at t=100
        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_start_time(d1)

Yields

None

Return type

Generator[None, None, None]

qiskit.pulse.builder.frequency_offset(frequency, *channels, compensate_phase=False)

Shift the frequency of inputs channels on entry into context and undo on exit.

Examples:

from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
 
with pulse.build(backend) as pulse_prog:
    # shift frequency by 1GHz
    with pulse.frequency_offset(1e9, d0):
        pulse.play(pulse.Constant(10, 1.0), d0)
 
assert len(pulse_prog.instructions) == 3
 
with pulse.build(backend) as pulse_prog:
    # Shift frequency by 1GHz.
    # Undo accumulated phase in the shifted frequency frame
    # when exiting the context.
    with pulse.frequency_offset(1e9, d0, compensate_phase=True):
        pulse.play(pulse.Constant(10, 1.0), d0)
 
assert len(pulse_prog.instructions) == 4

Parameters

• frequency (float) – Amount of frequency offset in Hz.
• channels (PulseChannel) – Channels to offset frequency of.
• compensate_phase (bool) – Compensate for accumulated phase accumulated with respect to the channels’ frame at its initial frequency.

Yields

None

Return type

Generator[None, None, None]

qiskit.pulse.builder.phase_offset(phase, *channels)

Shift the phase of input channels on entry into context and undo on exit.

Examples:

import math
 
from qiskit import pulse
 
d0 = pulse.DriveChannel(0)
 
with pulse.build() as pulse_prog:
    with pulse.phase_offset(math.pi, d0):
        pulse.play(pulse.Constant(10, 1.0), d0)
 
assert len(pulse_prog.instructions) == 3

Parameters

• phase (float) – Amount of phase offset in radians.
• channels (PulseChannel) – Channels to offset phase of.

Yields

None

Return type

Generator[None, None, None]

qiskit.pulse.builder.measure(qubits, registers=None)

Measure a qubit within the currently active builder context.

At the pulse level a measurement is composed of both a stimulus pulse and an acquisition instruction which tells the systems measurement unit to acquire data and process it. We provide this measurement macro to automate the process for you, but if desired full control is still available with acquire() and play().

To use the measurement it is as simple as specifying the qubit you wish to measure:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
qubit = 0
 
with pulse.build(backend) as pulse_prog:
    # Do something to the qubit.
    qubit_drive_chan = pulse.drive_channel(0)
    pulse.play(pulse.Constant(100, 1.0), qubit_drive_chan)
    # Measure the qubit.
    reg = pulse.measure(qubit)

For now it is not possible to do much with the handle to reg but in the future we will support using this handle to a result register to build up ones program. It is also possible to supply this register:

with pulse.build(backend) as pulse_prog:
    pulse.play(pulse.Constant(100, 1.0), qubit_drive_chan)
    # Measure the qubit.
    mem0 = pulse.MemorySlot(0)
    reg = pulse.measure(qubit, mem0)
 
assert reg == mem0

Parameters

• qubits (list[int] | int) – Physical qubit to measure.
• registers (list[StorageLocation] | StorageLocation) – Register to store result in. If not selected the current behavior is to return the MemorySlot with the same index as qubit. This register will be returned.

Returns

The register the qubit measurement result will be stored in.

Return type

list[StorageLocation] | StorageLocation

qiskit.pulse.builder.measure_all()

Measure all qubits within the currently active builder context.

A simple macro function to measure all of the qubits in the device at the same time. This is useful for handling device meas_map and single measurement constraints.

Examples:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
with pulse.build(backend) as pulse_prog:
    # Measure all qubits and return associated registers.
    regs = pulse.measure_all()

Returns

The registers the qubit measurement results will be stored in.

Return type

list[qiskit.pulse.channels.MemorySlot]

qiskit.pulse.builder.delay_qubits(duration, *qubits)

Insert delays on all the channels.Channels that correspond to the input qubits at the same time.

Examples:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse3Q
 
backend = FakeOpenPulse3Q()
 
with pulse.build(backend) as pulse_prog:
    # Delay for 100 cycles on qubits 0, 1 and 2.
    regs = pulse.delay_qubits(100, 0, 1, 2)

Parameters

• duration (int) – Duration to delay for.
• qubits (int) – Physical qubits to delay on. Delays will be inserted based on the channels returned by pulse.qubit_channels().

qiskit.pulse.builder.active_backend()

Get the backend of the currently active builder context.

Returns

The active backend in the currently active

builder context.

Return type

Backend

Raises

exceptions.BackendNotSet – If the builder does not have a backend set.

qiskit.pulse.builder.num_qubits()

Return number of qubits in the currently active backend.

Examples:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
with pulse.build(backend):
    print(pulse.num_qubits())

2

Return type

int

qiskit.pulse.builder.qubit_channels(qubit)

Returns the set of channels associated with a qubit.

Examples:

from qiskit import pulse
from qiskit.providers.fake_provider import FakeOpenPulse2Q
 
backend = FakeOpenPulse2Q()
 
with pulse.build(backend):
    print(pulse.qubit_channels(0))

{MeasureChannel(0), ControlChannel(0), DriveChannel(0), AcquireChannel(0), ControlChannel(1)}

Return type

set[qiskit.pulse.channels.Channel]

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.

Parameters

samples (int | np.ndarray) – Number of samples to convert to time in seconds.

Returns

The time that elapses in samples.

Return type

float | np.ndarray

qiskit.pulse.builder.seconds_to_samples(seconds)

Obtain the number of samples that will elapse in seconds on the active backend.

Rounds down.

Parameters

seconds (float | np.ndarray) – Time in seconds to convert to samples.

Returns

The number of samples for the time to elapse

Return type

int | np.ndarray