qiskit-documentation/docs/api/qiskit/qiskit.pulse.Schedule.mdx

---
title: Schedule
description: API reference for qiskit.pulse.Schedule
in_page_toc_min_heading_level: 1
python_api_type: class
python_api_name: qiskit.pulse.Schedule
---

# Schedule

<Class id="qiskit.pulse.Schedule" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L66-L809" signature="qiskit.pulse.Schedule(*schedules, name=None, metadata=None)" modifiers="class">
  Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)")

  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

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

  *   Appending an instruction shifted in time by a given amount

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

  *   Merge two schedules

      ```python
      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`](pulse#qiskit.pulse.PulseError "qiskit.pulse.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`](qiskit.pulse.ScheduleBlock "qiskit.pulse.ScheduleBlock") representation may be used instead.

  **References**

  \[1]: [https://arxiv.org/abs/2004.06755](https://arxiv.org/abs/2004.06755)

  Create an empty schedule.

  **Parameters**

  *   **\*schedules** (*'ScheduleComponent' |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*, 'ScheduleComponent']*) – Child Schedules of this parent Schedule. May either be passed as the list of schedules, or a list of `(start_time, schedule)` pairs.
  *   **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of this schedule. Defaults to an autogenerated string if not provided.
  *   **metadata** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)") *| None*) – Arbitrary key value metadata to associate with the schedule. This gets stored as free-form data in a dict in the [`metadata`](#qiskit.pulse.Schedule.metadata "qiskit.pulse.Schedule.metadata") attribute. It will not be directly used in the schedule.

  **Raises**

  [**TypeError**](https://docs.python.org/3/library/exceptions.html#TypeError "(in Python v3.12)") – if metadata is not a dict.

  ## Attributes

  ### channels

  <Attribute id="qiskit.pulse.Schedule.channels">
    Returns channels that this schedule uses.
  </Attribute>

  ### children

  <Attribute id="qiskit.pulse.Schedule.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.

    **Returns**

    A tuple, where each element is a two-tuple containing the initial scheduled time of each `NamedValue` and the component itself.
  </Attribute>

  ### duration

  <Attribute id="qiskit.pulse.Schedule.duration">
    Duration of this schedule.
  </Attribute>

  ### instances\_counter

  <Attribute id="qiskit.pulse.Schedule.instances_counter" attributeValue="count(0)" />

  ### instructions

  <Attribute id="qiskit.pulse.Schedule.instructions">
    Get the time-ordered instructions from self.
  </Attribute>

  ### metadata

  <Attribute id="qiskit.pulse.Schedule.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.
  </Attribute>

  ### name

  <Attribute id="qiskit.pulse.Schedule.name">
    Name of this Schedule
  </Attribute>

  ### parameters

  <Attribute id="qiskit.pulse.Schedule.parameters">
    Parameters which determine the schedule behavior.
  </Attribute>

  ### prefix

  <Attribute id="qiskit.pulse.Schedule.prefix" attributeValue="'sched'" />

  ### start\_time

  <Attribute id="qiskit.pulse.Schedule.start_time">
    Starting time of this schedule.
  </Attribute>

  ### stop\_time

  <Attribute id="qiskit.pulse.Schedule.stop_time">
    Stopping time of this schedule.
  </Attribute>

  ### timeslots

  <Attribute id="qiskit.pulse.Schedule.timeslots">
    Time keeping attribute.
  </Attribute>

  ## Methods

  ### append

  <Function id="qiskit.pulse.Schedule.append" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L424-L443" signature="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`.

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

    **Parameters**

    *   **schedule** (*ScheduleComponent*) – Schedule to be appended.
    *   **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new `Schedule`. Defaults to name of `self`.
    *   **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Perform operation inplace on this schedule. Otherwise return a new `Schedule`.

    **Return type**

    [Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule")
  </Function>

  ### assign\_parameters

  <Function id="qiskit.pulse.Schedule.assign_parameters" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L715-L738" signature="assign_parameters(value_dict, inplace=True)">
    Assign the parameters in this schedule according to the input.

    **Parameters**

    *   **value\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")  *|*[*ParameterVector*](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector")  *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, ParameterValueType | Sequence\[ParameterValueType]]*) – A mapping from parameters or parameter names (parameter vector
    *   **values** (*or parameter vector name) to either numeric*) –
    *   **expression** (*or another parameter*) –
    *   **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set `True` to override this instance with new parameter.

    **Returns**

    Schedule with updated parameters.

    **Return type**

    [Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule")
  </Function>

  ### ch\_duration

  <Function id="qiskit.pulse.Schedule.ch_duration" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L279-L285" signature="ch_duration(*channels)">
    Return the time of the end of the last instruction over the supplied channels.

    **Parameters**

    **\*channels** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – Channels within `self` to include.

    **Return type**

    [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")
  </Function>

  ### ch\_start\_time

  <Function id="qiskit.pulse.Schedule.ch_start_time" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L287-L298" signature="ch_start_time(*channels)">
    Return the time of the start of the first instruction over the supplied channels.

    **Parameters**

    **\*channels** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – Channels within `self` to include.

    **Return type**

    [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")
  </Function>

  ### ch\_stop\_time

  <Function id="qiskit.pulse.Schedule.ch_stop_time" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L300-L311" signature="ch_stop_time(*channels)">
    Return maximum start time over supplied channels.

    **Parameters**

    **\*channels** ([*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")) – Channels within `self` to include.

    **Return type**

    [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")
  </Function>

  ### draw

  <Function id="qiskit.pulse.Schedule.draw" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L1649-L1722" signature="draw(style=None, backend=None, time_range=None, time_unit='dt', disable_channels=None, show_snapshot=True, show_framechange=True, show_waveform_info=True, plot_barrier=True, plotter='mpl2d', axis=None, show_barrier=True)">
    Plot the schedule.

    **Parameters**

    *   **style** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.12)")*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")*, Any] | None*) – 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** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*] | None*) – Set horizontal axis limit. Tuple `(tmin, tmax)`.

    *   **time\_unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – The unit of specified time range either `dt` or `ns`. The unit of ns is available only when `backend` object is provided.

    *   **disable\_channels** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")*\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – 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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show snapshot instructions.

    *   **show\_framechange** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show frame change instructions. The frame change represents instructions that modulate phase or frequency of pulse channels.

    *   **show\_waveform\_info** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show additional information about waveforms such as their name.

    *   **plot\_barrier** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Show barrier lines.

    *   **plotter** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) –

        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** (*Any | None*) – 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.

    *   **show\_barrier** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – DEPRECATED. Show barrier lines.

    **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.Schedule.exclude" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L482-L514" signature="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
    ```

    **Parameters**

    *   **filter\_funcs** (*Callable*) – A list of Callables which take a (int, Union\[‘Schedule’, Instruction]) tuple and return a bool.
    *   **channels** (*Iterable\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – For example, `[DriveChannel(0), AcquireChannel(0)]`.
    *   **instruction\_types** (*Iterable\[*[*abc.ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)")*] |* [*abc.ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)")) – For example, `[PulseInstruction, AcquireInstruction]`.
    *   **time\_ranges** (*Iterable\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – For example, `[(0, 5), (6, 10)]`.
    *   **intervals** (*Iterable\[Interval] | None*) – For example, `[(0, 5), (6, 10)]`.
    *   **check\_subroutine** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set True to individually filter instructions inside of a subroutine defined by the `Call` instruction.

    **Return type**

    [Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule")
  </Function>

  ### filter

  <Function id="qiskit.pulse.Schedule.filter" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L445-L480" signature="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** (*Iterable\[*[*Channel*](pulse#qiskit.pulse.channels.Channel "qiskit.pulse.channels.Channel")*] | None*) – For example, `[DriveChannel(0), AcquireChannel(0)]`.
    *   **instruction\_types** (*Iterable\[*[*abc.ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)")*] |* [*abc.ABCMeta*](https://docs.python.org/3/library/abc.html#abc.ABCMeta "(in Python v3.12)")) – For example, `[PulseInstruction, AcquireInstruction]`.
    *   **time\_ranges** (*Iterable\[*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.12)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")*]] | None*) – For example, `[(0, 5), (6, 10)]`.
    *   **intervals** (*Iterable\[Interval] | None*) – For example, `[(0, 5), (6, 10)]`.
    *   **check\_subroutine** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Set True to individually filter instructions inside of a subroutine defined by the `Call` instruction.

    **Return type**

    [Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule")
  </Function>

  ### get\_parameters

  <Function id="qiskit.pulse.Schedule.get_parameters" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L740-L752" signature="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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)")) – Name of parameter.

    **Returns**

    Parameter objects that have corresponding name.

    **Return type**

    [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.12)")\[[qiskit.circuit.parameter.Parameter](qiskit.circuit.Parameter "qiskit.circuit.parameter.Parameter")]
  </Function>

  ### initialize\_from

  <Function id="qiskit.pulse.Schedule.initialize_from" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L169-L196" signature="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** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of new schedule. Name of `schedule` is used by default.

    **Returns**

    New schedule object with name and metadata.

    **Raises**

    [**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – When other\_program does not provide necessary information.

    **Return type**

    [Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule")
  </Function>

  ### insert

  <Function id="qiskit.pulse.Schedule.insert" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L375-L393" signature="insert(start_time, schedule, name=None, inplace=False)">
    Return a new schedule with `schedule` inserted into `self` at `start_time`.

    **Parameters**

    *   **start\_time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to insert the schedule.
    *   **schedule** (*ScheduleComponent*) – Schedule to insert.
    *   **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to the name of self.
    *   **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Perform operation inplace on this schedule. Otherwise return a new `Schedule`.

    **Return type**

    [Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule")
  </Function>

  ### is\_parameterized

  <Function id="qiskit.pulse.Schedule.is_parameterized" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L711-L713" signature="is_parameterized()">
    Return True iff the instruction is parameterized.

    **Return type**

    [bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")
  </Function>

  ### replace

  <Function id="qiskit.pulse.Schedule.replace" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L627-L709" signature="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.

    ```python
    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:

    ```python
    .. code-block::
    ```

    > sched = pulse.Schedule()
    >
    > sched += pulse.Schedule(old)
    >
    > sched = sched.flatten()
    >
    > sched = sched.replace(old, new)
    >
    > assert sched == pulse.Schedule(new)

    **Parameters**

    *   **old** ([*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")  *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Instruction to replace.
    *   **new** ([*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")  *|*[*Instruction*](pulse#qiskit.pulse.instructions.Instruction "qiskit.pulse.instructions.instruction.Instruction")) – Instruction to replace with.
    *   **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Replace instruction by mutably modifying this `Schedule`.

    **Returns**

    The modified schedule with `old` replaced by `new`.

    **Raises**

    [**PulseError**](pulse#qiskit.pulse.PulseError "qiskit.pulse.PulseError") – If the `Schedule` after replacements will has a timing overlap.

    **Return type**

    [*Schedule*](#qiskit.pulse.Schedule "qiskit.pulse.schedule.Schedule")
  </Function>

  ### shift

  <Function id="qiskit.pulse.Schedule.shift" github="https://github.com/Qiskit/qiskit/tree/stable/1.1/qiskit/pulse/schedule.py#L327-L338" signature="shift(time, name=None, inplace=False)">
    Return a schedule shifted forward by `time`.

    **Parameters**

    *   **time** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")) – Time to shift by.
    *   **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.12)") *| None*) – Name of the new schedule. Defaults to the name of self.
    *   **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – Perform operation inplace on this schedule. Otherwise return a new `Schedule`.

    **Return type**

    [Schedule](#qiskit.pulse.Schedule "qiskit.pulse.Schedule")
  </Function>
</Class>