ScheduleBlock
class ScheduleBlock(name=None, metadata=None, alignment_context=None)
Bases: object
A ScheduleBlock
is a time-ordered sequence of instructions and transform macro to manage their relative timing. The relative position of the instructions is managed by the alignment_context
. This allows ScheduleBlock
to support instructions with a parametric duration and allows the lazy scheduling of instructions, i.e. allocating the instruction time just before execution.
ScheduleBlock
s should be initialized with one of the following alignment contexts:
AlignLeft
: Align instructions in the as-soon-as-possible manner. Instructions are scheduled at the earliest possible time on the channel.AlignRight
: Align instructions in the as-late-as-possible manner. Instructions are scheduled at the latest possible time on the channel.AlignSequential
: Align instructions sequentially even though they are allocated in different channels.AlignEquispaced
: Align instructions with equal interval within a specified duration. Instructions on different channels are aligned sequentially.AlignFunc
: Align instructions with arbitrary position within the given duration. The position is specified by a callback function taking a pulse indexj
and returning a fractional coordinate in [0, 1].
The ScheduleBlock
defaults to the AlignLeft
alignment. The timing overlap constraint of instructions is not immediately evaluated, and thus we can assign a parameter object to the instruction duration. Instructions are implicitly scheduled at optimum time when the program is executed.
Note that ScheduleBlock
can contain Instruction
and other ScheduleBlock
to build an experimental program, but Schedule
is not supported. This should be added as a Call
instruction. This conversion is automatically performed with the pulse builder.
By using ScheduleBlock
representation we can fully parametrize pulse waveforms. For example, Rabi schedule generator can be defined as
duration = Parameter('rabi_dur')
amp = Parameter('rabi_amp')
block = ScheduleBlock()
rabi_pulse = pulse.Gaussian(duration=duration, amp=amp, sigma=duration/4)
block += Play(rabi_pulse, pulse.DriveChannel(0))
block += Call(measure_schedule)
Note that such waveform cannot be appended to the Schedule
representation.
In the block representation, the interval between two instructions can be managed with the Delay
instruction. Because the schedule block lacks an instruction start time t0
, we cannot insert
or shift
the target instruction. In addition, stored instructions are not interchangable because the schedule block is sensitive to the relative position of instructions. Apart from these differences, the block representation can provide compatible functionality with Schedule
representation.
Create an empty schedule block.
Parameters
- 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. - alignment_context (AlignmentKind) –
AlignmentKind
instance that manages scheduling of instructions in this block.
Raises
TypeError – if metadata is not a dict.
Methods
append
ScheduleBlock.append(block, name=None, inplace=True)
Return a new schedule block with block
appended to the context block. The execution time is automatically assigned when the block is converted into schedule.
Parameters
- block (
Union
[ScheduleBlock
,Instruction
]) – ScheduleBlock 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
Returns
Schedule block with appended schedule.
Raises
PulseError – When invalid schedule type is specified.
assign_parameters
ScheduleBlock.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
ScheduleBlock.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
draw
ScheduleBlock.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
ScheduleBlock.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
This method is currently not supported. Support will be soon added please create an issue if you believe this must be prioritized.
Parameters
- filter_funcs (
List
[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.
Returns
Schedule
consisting of instructions that are not match with filtering condition.
Raises
PulseError – When this method is called. This method will be supported soon.
filter
ScheduleBlock.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 ScheduleBlock
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.
This method is currently not supported. Support will be soon added please create an issue if you believe this must be prioritized.
Parameters
- filter_funcs (
List
[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.
Returns
Schedule
consisting of instructions that matches with filtering condition.
Raises
PulseError – When this method is called. This method will be supported soon.
get_parameters
ScheduleBlock.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 ScheduleBlock.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 ofblock
is used by default.
Return type
Returns
New block object with name and metadata.
Raises
PulseError – When other_program does not provide necessary information.
is_parameterized
ScheduleBlock.is_parameterized()
Return True iff the instruction is parameterized.
Return type
bool
is_schedulable
ScheduleBlock.is_schedulable()
Return True
if all durations are assigned.
Return type
bool
replace
ScheduleBlock.replace(old, new, inplace=True)
Return a ScheduleBlock
with the old
component replaced with a new
component.
Parameters
- old (
Union
[ScheduleBlock
,Instruction
]) – Schedule block component to replace. - new (
Union
[ScheduleBlock
,Instruction
]) – Schedule block component to replace with. - inplace (
bool
) – Replace instruction by mutably modifying thisScheduleBlock
.
Return type
Returns
The modified schedule block with old
replaced by new
.
Attributes
alignment_context
Return alignment instance that allocates block component to generate schedule.
blocks
Get the time-ordered instructions from self.
Return type
Tuple
[Union
[ScheduleBlock
, Instruction
], ...
]
channels
duration
Duration of this schedule block.
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: 'block'