qiskit-documentation/docs/api/qiskit/0.29/qiskit.pulse.ScheduleBlock.mdx

519 lines
21 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: ScheduleBlock
description: API reference for qiskit.pulse.ScheduleBlock
in_page_toc_min_heading_level: 1
python_api_type: class
python_api_name: qiskit.pulse.ScheduleBlock
---
# ScheduleBlock
<Class id="qiskit.pulse.ScheduleBlock" isDedicatedPage={true} github="https://github.com/qiskit/qiskit/tree/stable/0.18/qiskit/pulse/schedule.py" signature="ScheduleBlock(name=None, metadata=None, alignment_context=None)" modifiers="class">
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 `context_alignment`. 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 index `j` 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`](qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.Instruction") and other `ScheduleBlock` to build an experimental program, but `Schedule` is not supported. This should be added as a [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.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
```python
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 the [`metadata`](#qiskit.pulse.ScheduleBlock.metadata "qiskit.pulse.ScheduleBlock.metadata") 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
<Function id="qiskit.pulse.ScheduleBlock.append" signature="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 new `Schedule`. Defaults to name of `self`.
* **inplace** (`bool`) Perform operation inplace on this schedule. Otherwise return a new `Schedule`.
**Return type**
`ScheduleBlock`
**Returns**
Schedule block with appended schedule.
**Raises**
[**PulseError**](qiskit.pulse.PulseError "qiskit.pulse.PulseError") When invalid schedule type is specified.
</Function>
### assign\_parameters
<Function id="qiskit.pulse.ScheduleBlock.assign_parameters" signature="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`) Set `True` to override this instance with new parameter.
**Return type**
`ScheduleBlock`
**Returns**
Schedule with updated parameters.
</Function>
### ch\_duration
<Function id="qiskit.pulse.ScheduleBlock.ch_duration" signature="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`
</Function>
### ch\_start\_time
<Function id="qiskit.pulse.ScheduleBlock.ch_start_time" signature="ScheduleBlock.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`
</Function>
### ch\_stop\_time
<Function id="qiskit.pulse.ScheduleBlock.ch_stop_time" signature="ScheduleBlock.ch_stop_time(*channels)">
Return maximum start time over supplied channels.
**Parameters**
**\*channels** Channels within `self` to include.
**Return type**
`int`
</Function>
### draw
<Function id="qiskit.pulse.ScheduleBlock.draw" signature="ScheduleBlock.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*](qiskit.providers.BaseBackend "qiskit.providers.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:
```python
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.
</Function>
### exclude
<Function id="qiskit.pulse.ScheduleBlock.exclude" signature="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:
```python
self.filter(args) | self.exclude(args) == self
```
<Admonition title="Note" type="note">
This method is currently not supported. Support will be soon added please create an issue if you believe this must be prioritized.
</Admonition>
**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 the [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction.
**Returns**
`Schedule` consisting of instructions that are not match with filtering condition.
**Raises**
[**PulseError**](qiskit.pulse.PulseError "qiskit.pulse.PulseError") When this method is called. This method will be supported soon.
</Function>
### filter
<Function id="qiskit.pulse.ScheduleBlock.filter" signature="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.
<Admonition title="Note" type="note">
This method is currently not supported. Support will be soon added please create an issue if you believe this must be prioritized.
</Admonition>
**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 the [`Call`](qiskit.pulse.instructions.Call "qiskit.pulse.instructions.Call") instruction.
**Returns**
`Schedule` consisting of instructions that matches with filtering condition.
**Raises**
[**PulseError**](qiskit.pulse.PulseError "qiskit.pulse.PulseError") When this method is called. This method will be supported soon.
</Function>
### get\_parameters
<Function id="qiskit.pulse.ScheduleBlock.get_parameters" signature="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.
</Function>
### initialize\_from
<Function id="qiskit.pulse.ScheduleBlock.initialize_from" signature="ScheduleBlock.initialize_from(other_program, name=None)" modifiers="classmethod">
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 of `block` is used by default.
**Return type**
`ScheduleBlock`
**Returns**
New block object with name and metadata.
**Raises**
[**PulseError**](qiskit.pulse.PulseError "qiskit.pulse.PulseError") When other\_program does not provide necessary information.
</Function>
### insert
<Function id="qiskit.pulse.ScheduleBlock.insert" signature="ScheduleBlock.insert(start_time, block, name=None, inplace=True)">
This method will be removed. Temporarily added for backward compatibility.
<Admonition title="Note" type="note">
This method is not supported and being deprecated.
</Admonition>
**Parameters**
* **start\_time** (`int`) Time to insert the schedule.
* **block** (`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`.
**Raises**
[**PulseError**](qiskit.pulse.PulseError "qiskit.pulse.PulseError") When this method is called. This method is not supported.
</Function>
### is\_parameterized
<Function id="qiskit.pulse.ScheduleBlock.is_parameterized" signature="ScheduleBlock.is_parameterized()">
Return True iff the instruction is parameterized.
**Return type**
`bool`
</Function>
### is\_schedulable
<Function id="qiskit.pulse.ScheduleBlock.is_schedulable" signature="ScheduleBlock.is_schedulable()">
Return `True` if all durations are assigned.
**Return type**
`bool`
</Function>
### replace
<Function id="qiskit.pulse.ScheduleBlock.replace" signature="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 this `ScheduleBlock`.
**Return type**
`ScheduleBlock`
**Returns**
The modified schedule block with `old` replaced by `new`.
</Function>
### shift
<Function id="qiskit.pulse.ScheduleBlock.shift" signature="ScheduleBlock.shift(time, name=None, inplace=True)">
This method will be removed. Temporarily added for backward compatibility.
<Admonition title="Note" type="note">
This method is not supported and being deprecated.
</Admonition>
**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`.
**Raises**
[**PulseError**](qiskit.pulse.PulseError "qiskit.pulse.PulseError") When this method is called. This method is not supported.
</Function>
## Attributes
### alignment\_context
<Attribute id="qiskit.pulse.ScheduleBlock.alignment_context">
Return alignment instance that allocates block component to generate schedule.
</Attribute>
### blocks
<Attribute id="qiskit.pulse.ScheduleBlock.blocks">
Get the time-ordered instructions from self.
**Return type**
`Tuple`\[`Union`\[`ScheduleBlock`, `Instruction`]]
</Attribute>
### channels
<Attribute id="qiskit.pulse.ScheduleBlock.channels">
Returns channels that this schedule clock uses.
**Return type**
`Tuple`\[`Channel`]
</Attribute>
### duration
<Attribute id="qiskit.pulse.ScheduleBlock.duration">
Duration of this schedule block.
**Return type**
`int`
</Attribute>
### instances\_counter
<Attribute id="qiskit.pulse.ScheduleBlock.instances_counter" attributeValue="count(0)" />
### instructions
<Attribute id="qiskit.pulse.ScheduleBlock.instructions">
Get the time-ordered instructions from self.
**Return type**
`Tuple`\[`Tuple`\[`int`, `Instruction`]]
</Attribute>
### metadata
<Attribute id="qiskit.pulse.ScheduleBlock.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`]
</Attribute>
### name
<Attribute id="qiskit.pulse.ScheduleBlock.name">
Name of this Schedule
**Return type**
`str`
</Attribute>
### parameters
<Attribute id="qiskit.pulse.ScheduleBlock.parameters">
Parameters which determine the schedule behavior.
**Return type**
`Set`
</Attribute>
### prefix
<Attribute id="qiskit.pulse.ScheduleBlock.prefix" attributeValue="'block'" />
### start\_time
<Attribute id="qiskit.pulse.ScheduleBlock.start_time">
Starting time of this schedule block.
**Return type**
`int`
</Attribute>
### stop\_time
<Attribute id="qiskit.pulse.ScheduleBlock.stop_time">
Stopping time of this schedule block.
**Return type**
`int`
</Attribute>
### timeslots
<Attribute id="qiskit.pulse.ScheduleBlock.timeslots">
Time keeping attribute.
**Return type**
`Dict`\[`Channel`, `List`\[`Tuple`\[`int`, `int`]]]
</Attribute>
</Class>