Schedule
class Schedule(*schedules, name=None, metadata=None)
Bases: object
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 themetadata
attribute. It will not be directly used in the schedule.
Raises
TypeError – if metadata is not a dict.
Methods
append
Schedule.append(schedule, name=None, inplace=False)
Return a new schedule with schedule
inserted at the maximum time over all channels shared between self
and schedule
.
Parameters
- schedule (
Union
[Schedule
,Instruction
]) – Schedule to be appended. - name (
Optional
[str
]) – Name of the newSchedule
. Defaults to name ofself
. - inplace (
bool
) – Perform operation inplace on this schedule. Otherwise return a newSchedule
.
Return type
assign_parameters
Schedule.assign_parameters(value_dict, inplace=True)
Assign the parameters in this schedule according to the input.
Parameters
- value_dict (
Dict
[ParameterExpression
,Union
[ParameterExpression
,float
]]) – A mapping from Parameters to either numeric values or another Parameter expression. - inplace (
bool
) – SetTrue
to override this instance with new parameter.
Return type
Returns
Schedule with updated parameters.
ch_duration
Schedule.ch_duration(*channels)
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
Schedule.ch_start_time(*channels)
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
Schedule.ch_stop_time(*channels)
Return maximum start time over supplied channels.
Parameters
*channels – Channels within self
to include.
Return type
int
draw
Schedule.draw(style=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. SeeIQXStandard
,IQXSimple
, andIQXDebugging
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
andstyle
kwargs may depend on the plotter. -
axis (
Optional
[Any
]) – Arbitrary object passed to the plotter. If this object is provided, the plotters use a givenaxis
instead of internally initializing a figure object. This object format depends on the plotter. See plotter argument for details.
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.
exclude
Schedule.exclude(*filter_funcs, channels=None, instruction_types=None, time_ranges=None, intervals=None, check_subroutine=True)
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 theCall
instruction.
Return type
filter
Schedule.filter(*filter_funcs, channels=None, instruction_types=None, time_ranges=None, intervals=None, check_subroutine=True)
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 theCall
instruction.
Return type
get_parameters
Schedule.get_parameters(parameter_name)
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.
initialize_from
classmethod Schedule.initialize_from(other_program, name=None)
Create new schedule object with metadata of another schedule object.
Parameters
- other_program (
Any
) – Qiskit program that provides metadata to new object. - name (
Optional
[str
]) – Name of new schedule. Name ofschedule
is used by default.
Return type
Returns
New schedule object with name and metadata.
Raises
PulseError – When other_program does not provide necessary information.
insert
Schedule.insert(start_time, schedule, name=None, inplace=False)
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 newSchedule
.
Return type
is_parameterized
Schedule.is_parameterized()
Return True iff the instruction is parameterized.
Return type
bool
replace
Schedule.replace(old, new, inplace=False)
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 thisSchedule
.
Return type
Returns
The modified schedule with old
replaced by new
.
Raises
PulseError – If the Schedule
after replacements will has a timing overlap.
shift
Schedule.shift(time, name=None, inplace=False)
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 newSchedule
.
Return type
Attributes
channels
children
Return the child schedule components of this Schedule
in the order they were added to the schedule.
Notes
Nested schedules are returned as-is. If you want to collect only instructions, use py:meth:~Schedule.instructions instead.
Return type
Tuple
[Tuple
[int
, Union
[Schedule
, Instruction
]], ...
]
Returns
A tuple, where each element is a two-tuple containing the initial scheduled time of each NamedValue
and the component itself.
duration
Duration of this schedule.
Return type
int
instances_counter
Default value: count(0)
instructions
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
]
name
Name of this Schedule
Return type
str
parameters
Parameters which determine the schedule behavior.
Return type
Set
prefix
Default value: 'sched'
start_time
Starting time of this schedule.
Return type
int
stop_time
Stopping time of this schedule.
Return type
int