qiskit.pulse.Schedule¶

class Schedule(*schedules, name=None, metadata=None)[source]¶

A quantum program schedule with exact time constraints for its instructions, operating over all input signal channels and supporting special syntaxes for building.

Pulse program representation for the original Qiskit Pulse model [1]. Instructions are not allowed to overlap in time on the same channel. This overlap constraint is immediately evaluated when a new instruction is added to the Schedule object.

It is necessary to specify the absolute start time and duration for each instruction so as to deterministically fix its execution time.

The Schedule program supports some syntax sugar for easier programming.

Appending an instruction to the end of a channel

sched = Schedule()
sched += Play(Gaussian(160, 0.1, 40), DriveChannel(0))

Appending an instruction shifted in time by a given amount

sched = Schedule()
sched += Play(Gaussian(160, 0.1, 40), DriveChannel(0)) << 30

Merge two schedules

sched1 = Schedule()
sched1 += Play(Gaussian(160, 0.1, 40), DriveChannel(0))

sched2 = Schedule()
sched2 += Play(Gaussian(160, 0.1, 40), DriveChannel(1))
sched2 = sched1 | sched2

A PulseError is immediately raised when the overlap constraint is violated.

In the schedule representation, we cannot parametrize the duration of instructions. Thus we need to create a new schedule object for each duration. To parametrize an instruction’s duration, the ScheduleBlock representation may be used instead.

References

[1]: https://arxiv.org/abs/2004.06755

Create an empty schedule.

Parameters

*schedules – Child Schedules of this parent Schedule. May either be passed as the list of schedules, or a list of (start_time, schedule) pairs.
name (Optional[str]) – Name of this schedule. Defaults to an autogenerated string if not provided.
metadata (Optional[dict]) – Arbitrary key value metadata to associate with the schedule. This gets stored as free-form data in a dict in the metadata attribute. It will not be directly used in the schedule.

Raises

TypeError – if metadata is not a dict.

__init__(*schedules, name=None, metadata=None)[source]¶

Create an empty schedule.

Parameters

*schedules – Child Schedules of this parent Schedule. May either be passed as the list of schedules, or a list of (start_time, schedule) pairs.
name (Optional[str]) – Name of this schedule. Defaults to an autogenerated string if not provided.
metadata (Optional[dict]) – Arbitrary key value metadata to associate with the schedule. This gets stored as free-form data in a dict in the metadata attribute. It will not be directly used in the schedule.

Raises

TypeError – if metadata is not a dict.

Methods

`__init__`(*schedules[, name, metadata])	Create an empty schedule.
`append`(schedule[, name, inplace])	Return a new schedule with `schedule` inserted at the maximum time over all channels shared between `self` and `schedule`.
`assign_parameters`(value_dict[, inplace])	Assign the parameters in this schedule according to the input.
`ch_duration`(*channels)	Return the time of the end of the last instruction over the supplied channels.
`ch_start_time`(*channels)	Return the time of the start of the first instruction over the supplied channels.
`ch_stop_time`(*channels)	Return maximum start time over supplied channels.
`draw`([dt, style, filename, interp_method, …])	Plot the schedule.
`exclude`(*filter_funcs[, channels, …])	Return a `Schedule` with only the instructions from this Schedule failing at least one of the provided filters. This method is the complement of py:meth:~self.filter, so that::.
`filter`(*filter_funcs[, channels, …])	Return a new `Schedule` with only the instructions from this `Schedule` which pass though the provided filters; i.e. an instruction will be retained iff every function in `filter_funcs` returns `True`, the instruction occurs on a channel type contained in `channels`, the instruction type is contained in `instruction_types`, and the period over which the instruction operates is fully contained in one specified in `time_ranges` or `intervals`.
`flatten`()	Deprecated.
`get_parameters`(parameter_name)	Get parameter object bound to this schedule by string name.
`insert`(start_time, schedule[, name, inplace])	Return a new schedule with `schedule` inserted into `self` at `start_time`.
`is_parameterized`()	Return True iff the instruction is parameterized.
`replace`(old, new[, inplace])	Return a `Schedule` with the `old` instruction replaced with a `new` instruction.
`shift`(time[, name, inplace])	Return a schedule shifted forward by `time`.

Attributes

`channels`	Returns channels that this schedule uses.
`duration`	Duration of this schedule.
`instances_counter`
`instructions`	Get the time-ordered instructions from self.
`metadata`	The user provided metadata associated with the schedule.
`name`	Name of this Schedule
`parameters`	Parameters which determine the schedule behavior.
`prefix`
`start_time`	Starting time of this schedule.
`stop_time`	Stopping time of this schedule.
`timeslots`	Time keeping attribute.

append(schedule, name=None, inplace=False)[source]¶

Return a new schedule with schedule inserted at the maximum time over all channels shared between self and schedule.

\[t = \textrm{max}(\texttt{x.stop_time} |\texttt{x} \in \texttt{self.channels} \cap \texttt{schedule.channels})\]

Parameters

schedule (Union[Schedule, Instruction]) – Schedule to be appended.
name (Optional[str]) – Name of the new Schedule. Defaults to name of self.
inplace (bool) – Perform operation inplace on this schedule. Otherwise return a new Schedule.

Return type

Schedule

assign_parameters(value_dict, inplace=True)[source]¶

Assign the parameters in this schedule according to the input.

Parameters

value_dict (Dict[ParameterExpression, Union[ParameterExpression, float, int]]) – A mapping from Parameters to either numeric values or another Parameter expression.
inplace (bool) – Set True to override this instance with new parameter.

Return type

Schedule

Returns

Schedule with updated parameters.

ch_duration(*channels)[source]¶

Return the time of the end of the last instruction over the supplied channels.

Parameters: *channels – Channels within self to include.
Return type: int

ch_start_time(*channels)[source]¶

Return the time of the start of the first instruction over the supplied channels.

Parameters: *channels – Channels within self to include.
Return type: int

ch_stop_time(*channels)[source]¶

Return maximum start time over supplied channels.

Parameters: *channels – Channels within self to include.
Return type: int

property channels¶

Returns channels that this schedule uses.

Return type: Tuple[Channel]

draw(dt=None, style=None, filename=None, interp_method=None, scale=None, channel_scales=None, plot_all=None, plot_range=None, interactive=None, table=None, label=None, framechange=None, channels=None, show_framechange_channels=None, draw_title=None, backend=None, time_range=None, time_unit='dt', disable_channels=None, show_snapshot=True, show_framechange=True, show_waveform_info=True, show_barrier=True, plotter='mpl2d', axis=None)¶

Plot the schedule.

Parameters

style (Optional[Dict[str, Any]]) – Stylesheet options. This can be dictionary or preset stylesheet classes. See IQXStandard, IQXSimple, and IQXDebugging for details of preset stylesheets.
backend (Optional[BaseBackend]) – Backend object to play the input pulse program. If provided, the plotter may use to make the visualization hardware aware.
time_range (Optional[Tuple[int, int]]) – Set horizontal axis limit. Tuple (tmin, tmax).
time_unit (str) – The unit of specified time range either dt or ns. The unit of ns is available only when backend object is provided.
disable_channels (Optional[List[Channel]]) – A control property to show specific pulse channel. Pulse channel instances provided as a list are not shown in the output image.
show_snapshot (bool) – Show snapshot instructions.
show_framechange (bool) – Show frame change instructions. The frame change represents instructions that modulate phase or frequency of pulse channels.
show_waveform_info (bool) – Show additional information about waveforms such as their name.
show_barrier (bool) – Show barrier lines.

plotter (str) –

Name of plotter API to generate an output image. One of following APIs should be specified:

mpl2d: Matplotlib API for 2D image generation.
    Matplotlib API to generate 2D image. Charts are placed along y axis with
    vertical offset. This API takes matplotlib.axes.Axes as ``axis`` input.

axis and style kwargs may depend on the plotter.

axis (Optional[Any]) – Arbitrary object passed to the plotter. If this object is provided, the plotters use a given axis instead of internally initializing a figure object. This object format depends on the plotter. See plotter argument for details.
dt (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
filename (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer. To save output image, you can call .savefig method with returned Matplotlib Figure object.
interp_method (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
scale (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
channel_scales (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
plot_all (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
plot_range (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
interactive (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
table (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
label (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
framechange (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
channels (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
show_framechange_channels (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.
draw_title (Optional[Any]) – Deprecated. This argument is used by the legacy pulse drawer.

Returns

Visualization output data. The returned data type depends on the plotter. If matplotlib family is specified, this will be a matplotlib.pyplot.Figure data.

property duration¶

Duration of this schedule.

Return type: int

exclude(*filter_funcs, channels=None, instruction_types=None, time_ranges=None, intervals=None, check_subroutine=True)[source]¶

Return a Schedule with only the instructions from this Schedule failing at least one of the provided filters. This method is the complement of py:meth:~self.filter, so that:

self.filter(args) | self.exclude(args) == self

Parameters

filter_funcs (Callable) – A list of Callables which take a (int, Union[‘Schedule’, Instruction]) tuple and return a bool.
channels (Optional[Iterable[Channel]]) – For example, [DriveChannel(0), AcquireChannel(0)].
instruction_types (Union[Iterable[ABCMeta], ABCMeta, None]) – For example, [PulseInstruction, AcquireInstruction].
time_ranges (Optional[Iterable[Tuple[int, int]]]) – For example, [(0, 5), (6, 10)].
intervals (Optional[Iterable[Tuple[int, int]]]) – For example, [(0, 5), (6, 10)].
check_subroutine (bool) – Set True to individually filter instructions inside of a subroutine defined by the Call instruction.

Return type

Schedule

filter(*filter_funcs, channels=None, instruction_types=None, time_ranges=None, intervals=None, check_subroutine=True)[source]¶

Return a new Schedule with only the instructions from this Schedule which pass though the provided filters; i.e. an instruction will be retained iff every function in filter_funcs returns True, the instruction occurs on a channel type contained in channels, the instruction type is contained in instruction_types, and the period over which the instruction operates is fully contained in one specified in time_ranges or intervals.

If no arguments are provided, self is returned.

Parameters

filter_funcs (Callable) – A list of Callables which take a (int, Union[‘Schedule’, Instruction]) tuple and return a bool.
channels (Optional[Iterable[Channel]]) – For example, [DriveChannel(0), AcquireChannel(0)].
instruction_types (Union[Iterable[ABCMeta], ABCMeta, None]) – For example, [PulseInstruction, AcquireInstruction].
time_ranges (Optional[Iterable[Tuple[int, int]]]) – For example, [(0, 5), (6, 10)].
intervals (Optional[Iterable[Tuple[int, int]]]) – For example, [(0, 5), (6, 10)].
check_subroutine (bool) – Set True to individually filter instructions inside of a subroutine defined by the Call instruction.

Return type

Schedule

flatten()[source]¶

Deprecated.

Return type: Schedule

get_parameters(parameter_name)[source]¶

Get parameter object bound to this schedule by string name.

Because different Parameter objects can have the same name, this method returns a list of Parameter s for the provided name.

Parameters: parameter_name (str) – Name of parameter.
Return type: List[Parameter]
Returns: Parameter objects that have corresponding name.

insert(start_time, schedule, name=None, inplace=False)[source]¶

Return a new schedule with schedule inserted into self at start_time.

Parameters

start_time (int) – Time to insert the schedule.
schedule (Union[Schedule, Instruction]) – Schedule to insert.
name (Optional[str]) – Name of the new schedule. Defaults to the name of self.
inplace (bool) – Perform operation inplace on this schedule. Otherwise return a new Schedule.

Return type

Schedule

property instructions¶

Get the time-ordered instructions from self.

Return type: Tuple[Tuple[int, Instruction]]

is_parameterized()[source]¶

Return True iff the instruction is parameterized.

Return type: bool

property metadata¶

The user provided metadata associated with the schedule.

User provided dict of metadata for the schedule. The metadata contents do not affect the semantics of the program but are used to influence the execution of the schedule. It is expected to be passed between all transforms of the schedule and that providers will associate any schedule metadata with the results it returns from the execution of that schedule.

Return type: Dict[str, Any]

property name¶

Name of this Schedule

Return type: str

property parameters¶

Parameters which determine the schedule behavior.

Return type: Set

replace(old, new, inplace=False)[source]¶

Return a Schedule with the old instruction replaced with a new instruction.

The replacement matching is based on an instruction equality check.

from qiskit import pulse

d0 = pulse.DriveChannel(0)

sched = pulse.Schedule()

old = pulse.Play(pulse.Constant(100, 1.0), d0)
new = pulse.Play(pulse.Constant(100, 0.1), d0)

sched += old

sched = sched.replace(old, new)

assert sched == pulse.Schedule(new)

Only matches at the top-level of the schedule tree. If you wish to perform this replacement over all instructions in the schedule tree. Flatten the schedule prior to running:

.. jupyter-execute::

sched = pulse.Schedule()

sched += pulse.Schedule(old)

sched = sched.flatten()

sched = sched.replace(old, new)

assert sched == pulse.Schedule(new)

Parameters

old (Union[Schedule, Instruction]) – Instruction to replace.
new (Union[Schedule, Instruction]) – Instruction to replace with.
inplace (bool) – Replace instruction by mutably modifying this Schedule.

Return type

Schedule

Returns

The modified schedule with old replaced by new.

Raises

PulseError – If the Schedule after replacements will has a timing overlap.

shift(time, name=None, inplace=False)[source]¶

Return a schedule shifted forward by time.

Parameters

time (int) – Time to shift by.
name (Optional[str]) – Name of the new schedule. Defaults to the name of self.
inplace (bool) – Perform operation inplace on this schedule. Otherwise return a new Schedule.

Return type

Schedule

property start_time¶

Starting time of this schedule.

Return type: int

property stop_time¶

Stopping time of this schedule.

Return type: int

property timeslots¶

Time keeping attribute.

Return type: Dict[Channel, List[Tuple[int, int]]]