qiskit 1.3.0b1__cp39-abi3-macosx_10_9_x86_64.whl

qiskit/pulse/instructions/directives.py

@@ -0,0 +1,146 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Directives are hints to the pulse compiler for how to process its input programs."""
+from __future__ import annotations
+
+from abc import ABC
+
+from qiskit.pulse import channels as chans
+from qiskit.pulse.instructions import instruction
+from qiskit.pulse.exceptions import PulseError
+
+
+class Directive(instruction.Instruction, ABC):
+    """A compiler directive.
+
+    This is a hint to the pulse compiler and is not loaded into hardware.
+    """
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return 0
+
+
+class RelativeBarrier(Directive):
+    """Pulse ``RelativeBarrier`` directive."""
+
+    def __init__(self, *channels: chans.Channel, name: str | None = None):
+        """Create a relative barrier directive.
+
+        The barrier directive blocks instructions within the same schedule
+        as the barrier on channels contained within this barrier from moving
+        through the barrier in time.
+
+        Args:
+            channels: The channel that the barrier applies to.
+            name: Name of the directive for display purposes.
+        """
+        super().__init__(operands=tuple(channels), name=name)
+
+    @property
+    def channels(self) -> tuple[chans.Channel, ...]:
+        """Returns the channels that this schedule uses."""
+        return self.operands
+
+    def __eq__(self, other: object) -> bool:
+        """Verify two barriers are equivalent."""
+        return isinstance(other, type(self)) and set(self.channels) == set(other.channels)
+
+
+class TimeBlockade(Directive):
+    """Pulse ``TimeBlockade`` directive.
+
+    This instruction is intended to be used internally within the pulse builder,
+    to convert :class:`.Schedule` into :class:`.ScheduleBlock`.
+    Because :class:`.ScheduleBlock` cannot take an absolute instruction time interval,
+    this directive helps the block representation to find the starting time of an instruction.
+
+    Example:
+
+        This schedule plays constant pulse at t0 = 120.
+
+        .. code-block:: python
+
+            schedule = Schedule()
+            schedule.insert(120, Play(Constant(10, 0.1), DriveChannel(0)))
+
+        This schedule block is expected to be identical to above at a time of execution.
+
+        .. code-block:: python
+
+            block = ScheduleBlock()
+            block.append(TimeBlockade(120, DriveChannel(0)))
+            block.append(Play(Constant(10, 0.1), DriveChannel(0)))
+
+        Such conversion may be done by
+
+        .. code-block:: python
+
+            from qiskit.pulse.transforms import block_to_schedule, remove_directives
+
+            schedule = remove_directives(block_to_schedule(block))
+
+
+    .. note::
+
+        The TimeBlockade instruction behaves almost identically
+        to :class:`~qiskit.pulse.instructions.Delay` instruction.
+        However, the TimeBlockade is just a compiler directive and must be removed before execution.
+        This may be done by :func:`~qiskit.pulse.transforms.remove_directives` transform.
+        Once these directives are removed, occupied timeslots are released and
+        user can insert another instruction without timing overlap.
+    """
+
+    def __init__(
+        self,
+        duration: int,
+        channel: chans.Channel,
+        name: str | None = None,
+    ):
+        """Create a time blockade directive.
+
+        Args:
+            duration: Length of time of the occupation in terms of dt.
+            channel: The channel that will be the occupied.
+            name: Name of the time blockade for display purposes.
+        """
+        super().__init__(operands=(duration, channel), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``duration`` is not integer value.
+        """
+        if not isinstance(self.duration, int):
+            raise PulseError(
+                "TimeBlockade duration cannot be parameterized. Specify an integer duration value."
+            )
+
+    @property
+    def channel(self) -> chans.Channel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> tuple[chans.Channel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return self.operands[0]

qiskit/pulse/instructions/frequency.py

@@ -0,0 +1,132 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Frequency instructions module. These instructions allow the user to manipulate
+the frequency of a channel.
+"""
+from typing import Optional, Union, Tuple
+
+from qiskit.circuit.parameterexpression import ParameterExpression
+from qiskit.pulse.channels import PulseChannel
+from qiskit.pulse.instructions.instruction import Instruction
+from qiskit.pulse.exceptions import PulseError
+
+
+class SetFrequency(Instruction):
+    r"""Set the channel frequency. This instruction operates on ``PulseChannel`` s.
+    A ``PulseChannel`` creates pulses of the form
+
+    .. math::
+        Re[\exp(i 2\pi f jdt + \phi) d_j].
+
+    Here, :math:`f` is the frequency of the channel. The instruction ``SetFrequency`` allows
+    the user to set the value of :math:`f`. All pulses that are played on a channel
+    after SetFrequency has been called will have the corresponding frequency.
+
+    The duration of SetFrequency is 0.
+    """
+
+    def __init__(
+        self,
+        frequency: Union[float, ParameterExpression],
+        channel: PulseChannel,
+        name: Optional[str] = None,
+    ):
+        """Creates a new set channel frequency instruction.
+
+        Args:
+            frequency: New frequency of the channel in Hz.
+            channel: The channel this instruction operates on.
+            name: Name of this set channel frequency instruction.
+        """
+        super().__init__(operands=(frequency, channel), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``channel`` is not type :class:`PulseChannel`.
+        """
+        if not isinstance(self.channel, PulseChannel):
+            raise PulseError(f"Expected a pulse channel, got {self.channel} instead.")
+
+    @property
+    def frequency(self) -> Union[float, ParameterExpression]:
+        """New frequency."""
+        return self.operands[0]
+
+    @property
+    def channel(self) -> PulseChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> Tuple[PulseChannel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return 0
+
+
+class ShiftFrequency(Instruction):
+    """Shift the channel frequency away from the current frequency."""
+
+    def __init__(
+        self,
+        frequency: Union[float, ParameterExpression],
+        channel: PulseChannel,
+        name: Optional[str] = None,
+    ):
+        """Creates a new shift frequency instruction.
+
+        Args:
+            frequency: Frequency shift of the channel in Hz.
+            channel: The channel this instruction operates on.
+            name: Name of this set channel frequency instruction.
+        """
+        super().__init__(operands=(frequency, channel), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``channel`` is not type :class:`PulseChannel`.
+        """
+        if not isinstance(self.channel, PulseChannel):
+            raise PulseError(f"Expected a pulse channel, got {self.channel} instead.")
+
+    @property
+    def frequency(self) -> Union[float, ParameterExpression]:
+        """Frequency shift from the set frequency."""
+        return self.operands[0]
+
+    @property
+    def channel(self) -> PulseChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> Tuple[PulseChannel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return 0

qiskit/pulse/instructions/instruction.py

@@ -0,0 +1,268 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+``Instruction`` s are single operations within a :py:class:`~qiskit.pulse.Schedule`, and can be
+used the same way as :py:class:`~qiskit.pulse.Schedule` s.
+
+For example::
+
+    duration = 10
+    channel = DriveChannel(0)
+    sched = Schedule()
+    sched += Delay(duration, channel)  # Delay is a specific subclass of Instruction
+"""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from qiskit.circuit import Parameter, ParameterExpression
+from qiskit.pulse.channels import Channel
+from qiskit.pulse.exceptions import PulseError
+
+
+# pylint: disable=bad-docstring-quotes
+
+
+class Instruction(ABC):
+    """The smallest schedulable unit: a single instruction. It has a fixed duration and specified
+    channels.
+    """
+
+    def __init__(
+        self,
+        operands: tuple,
+        name: str | None = None,
+    ):
+        """Instruction initializer.
+
+        Args:
+            operands: The argument list.
+            name: Optional display name for this instruction.
+        """
+        self._operands = operands
+        self._name = name
+        self._validate()
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``channels`` are not all of type :class:`Channel`.
+        """
+        for channel in self.channels:
+            if not isinstance(channel, Channel):
+                raise PulseError(f"Expected a channel, got {channel} instead.")
+
+    @property
+    def name(self) -> str:
+        """Name of this instruction."""
+        return self._name
+
+    @property
+    def id(self) -> int:  # pylint: disable=invalid-name
+        """Unique identifier for this instruction."""
+        return id(self)
+
+    @property
+    def operands(self) -> tuple:
+        """Return instruction operands."""
+        return self._operands
+
+    @property
+    @abstractmethod
+    def channels(self) -> tuple[Channel, ...]:
+        """Returns the channels that this schedule uses."""
+        raise NotImplementedError
+
+    @property
+    def start_time(self) -> int:
+        """Relative begin time of this instruction."""
+        return 0
+
+    @property
+    def stop_time(self) -> int:
+        """Relative end time of this instruction."""
+        return self.duration
+
+    @property
+    def duration(self) -> int | ParameterExpression:
+        """Duration of this instruction."""
+        raise NotImplementedError
+
+    @property
+    def _children(self) -> tuple["Instruction", ...]:
+        """Instruction has no child nodes."""
+        return ()
+
+    @property
+    def instructions(self) -> tuple[tuple[int, "Instruction"], ...]:
+        """Iterable for getting instructions from Schedule tree."""
+        return tuple(self._instructions())
+
+    def ch_duration(self, *channels: Channel) -> int:
+        """Return duration of the supplied channels in this Instruction.
+
+        Args:
+            *channels: Supplied channels
+        """
+        return self.ch_stop_time(*channels)
+
+    def ch_start_time(self, *channels: Channel) -> int:
+        # pylint: disable=unused-argument
+        """Return minimum start time for supplied channels.
+
+        Args:
+            *channels: Supplied channels
+        """
+        return 0
+
+    def ch_stop_time(self, *channels: Channel) -> int:
+        """Return maximum start time for supplied channels.
+
+        Args:
+            *channels: Supplied channels
+        """
+        if any(chan in self.channels for chan in channels):
+            return self.duration
+        return 0
+
+    def _instructions(self, time: int = 0) -> Iterable[tuple[int, "Instruction"]]:
+        """Iterable for flattening Schedule tree.
+
+        Args:
+            time: Shifted time of this node due to parent
+
+        Yields:
+            Tuple[int, Union['Schedule, 'Instruction']]: Tuple of the form
+                (start_time, instruction).
+        """
+        yield (time, self)
+
+    def shift(self, time: int, name: str | None = None):
+        """Return a new schedule shifted forward by `time`.
+
+        Args:
+            time: Time to shift by
+            name: Name of the new schedule. Defaults to name of self
+
+        Returns:
+            Schedule: The shifted schedule.
+        """
+        from qiskit.pulse.schedule import Schedule
+
+        if name is None:
+            name = self.name
+        return Schedule((time, self), name=name)
+
+    def insert(self, start_time: int, schedule, name: str | None = None):
+        """Return a new :class:`~qiskit.pulse.Schedule` with ``schedule`` inserted within
+        ``self`` at ``start_time``.
+
+        Args:
+            start_time: Time to insert the schedule schedule
+            schedule (Union['Schedule', 'Instruction']): Schedule or instruction to insert
+            name: Name of the new schedule. Defaults to name of self
+
+        Returns:
+            Schedule: A new schedule with ``schedule`` inserted with this instruction at t=0.
+        """
+        from qiskit.pulse.schedule import Schedule
+
+        if name is None:
+            name = self.name
+        return Schedule(self, (start_time, schedule), name=name)
+
+    def append(self, schedule, name: str | None = None):
+        """Return a new :class:`~qiskit.pulse.Schedule` with ``schedule`` inserted at the
+        maximum time over all channels shared between ``self`` and ``schedule``.
+
+        Args:
+            schedule (Union['Schedule', 'Instruction']): Schedule or instruction to be appended
+            name: Name of the new schedule. Defaults to name of self
+
+        Returns:
+            Schedule: A new schedule with ``schedule`` a this instruction at t=0.
+        """
+        common_channels = set(self.channels) & set(schedule.channels)
+        time = self.ch_stop_time(*common_channels)
+        return self.insert(time, schedule, name=name)
+
+    @property
+    def parameters(self) -> set:
+        """Parameters which determine the instruction behavior."""
+
+        def _get_parameters_recursive(obj):
+            params = set()
+            if hasattr(obj, "parameters"):
+                for param in obj.parameters:
+                    if isinstance(param, Parameter):
+                        params.add(param)
+                    else:
+                        params |= _get_parameters_recursive(param)
+            return params
+
+        parameters = set()
+        for op in self.operands:
+            parameters |= _get_parameters_recursive(op)
+        return parameters
+
+    def is_parameterized(self) -> bool:
+        """Return True iff the instruction is parameterized."""
+        return any(self.parameters)
+
+    def __eq__(self, other: object) -> bool:
+        """Check if this Instruction is equal to the `other` instruction.
+
+        Equality is determined by the instruction sharing the same operands and channels.
+        """
+        if not isinstance(other, Instruction):
+            return NotImplemented
+        return isinstance(other, type(self)) and self.operands == other.operands
+
+    def __hash__(self) -> int:
+        return hash((type(self), self.operands, self.name))
+
+    def __add__(self, other):
+        """Return a new schedule with `other` inserted within `self` at `start_time`.
+
+        Args:
+            other (Union['Schedule', 'Instruction']): Schedule or instruction to be appended
+
+        Returns:
+            Schedule: A new schedule with ``schedule`` appended after this instruction at t=0.
+        """
+        return self.append(other)
+
+    def __or__(self, other):
+        """Return a new schedule which is the union of `self` and `other`.
+
+        Args:
+            other (Union['Schedule', 'Instruction']): Schedule or instruction to union with
+
+        Returns:
+            Schedule: A new schedule with ``schedule`` inserted with this instruction at t=0
+        """
+        return self.insert(0, other)
+
+    def __lshift__(self, time: int):
+        """Return a new schedule which is shifted forward by `time`.
+
+        Returns:
+            Schedule: The shifted schedule
+        """
+        return self.shift(time)
+
+    def __repr__(self) -> str:
+        operands = ", ".join(str(op) for op in self.operands)
+        name_repr = f", name='{self.name}'" if self.name else ""
+        return f"{self.__class__.__name__}({operands}{name_repr})"

qiskit/pulse/instructions/phase.py

@@ -0,0 +1,149 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""The phase instructions update the modulation phase of pulses played on a channel.
+This includes ``SetPhase`` instructions which lock the modulation to a particular phase
+at that moment, and ``ShiftPhase`` instructions which increase the existing phase by a
+relative amount.
+"""
+from typing import Optional, Union, Tuple
+
+from qiskit.circuit import ParameterExpression
+from qiskit.pulse.channels import PulseChannel
+from qiskit.pulse.instructions.instruction import Instruction
+from qiskit.pulse.exceptions import PulseError
+
+
+class ShiftPhase(Instruction):
+    r"""The shift phase instruction updates the modulation phase of proceeding pulses played on the
+    same :py:class:`~qiskit.pulse.channels.Channel`. It is a relative increase in phase determined
+    by the ``phase`` operand.
+
+    In particular, a PulseChannel creates pulses of the form
+
+    .. math::
+        Re[\exp(i 2\pi f jdt + \phi) d_j].
+
+    The ``ShiftPhase`` instruction causes :math:`\phi` to be increased by the instruction's
+    ``phase`` operand. This will affect all pulses following on the same channel.
+
+    The qubit phase is tracked in software, enabling instantaneous, nearly error-free Z-rotations
+    by using a ShiftPhase to update the frame tracking the qubit state.
+    """
+
+    def __init__(
+        self,
+        phase: Union[complex, ParameterExpression],
+        channel: PulseChannel,
+        name: Optional[str] = None,
+    ):
+        """Instantiate a shift phase instruction, increasing the output signal phase on ``channel``
+        by ``phase`` [radians].
+
+        Args:
+            phase: The rotation angle in radians.
+            channel: The channel this instruction operates on.
+            name: Display name for this instruction.
+        """
+        super().__init__(operands=(phase, channel), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``channel`` is not type :class:`PulseChannel`.
+        """
+        if not isinstance(self.channel, PulseChannel):
+            raise PulseError(f"Expected a pulse channel, got {self.channel} instead.")
+
+    @property
+    def phase(self) -> Union[complex, ParameterExpression]:
+        """Return the rotation angle enacted by this instruction in radians."""
+        return self.operands[0]
+
+    @property
+    def channel(self) -> PulseChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> Tuple[PulseChannel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return 0
+
+
+class SetPhase(Instruction):
+    r"""The set phase instruction sets the phase of the proceeding pulses on that channel
+    to ``phase`` radians.
+
+    In particular, a PulseChannel creates pulses of the form
+
+    .. math::
+
+        Re[\exp(i 2\pi f jdt + \phi) d_j]
+
+    The ``SetPhase`` instruction sets :math:`\phi` to the instruction's ``phase`` operand.
+    """
+
+    def __init__(
+        self,
+        phase: Union[complex, ParameterExpression],
+        channel: PulseChannel,
+        name: Optional[str] = None,
+    ):
+        """Instantiate a set phase instruction, setting the output signal phase on ``channel``
+        to ``phase`` [radians].
+
+        Args:
+            phase: The rotation angle in radians.
+            channel: The channel this instruction operates on.
+            name: Display name for this instruction.
+        """
+        super().__init__(operands=(phase, channel), name=name)
+
+    def _validate(self):
+        """Called after initialization to validate instruction data.
+
+        Raises:
+            PulseError: If the input ``channel`` is not type :class:`PulseChannel`.
+        """
+        if not isinstance(self.channel, PulseChannel):
+            raise PulseError(f"Expected a pulse channel, got {self.channel} instead.")
+
+    @property
+    def phase(self) -> Union[complex, ParameterExpression]:
+        """Return the rotation angle enacted by this instruction in radians."""
+        return self.operands[0]
+
+    @property
+    def channel(self) -> PulseChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> Tuple[PulseChannel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> int:
+        """Duration of this instruction."""
+        return 0