qiskit 1.0.0b1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

qiskit/pulse/instructions/call.py

@@ -0,0 +1,176 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2020, 2021, 2022.
+#
+# 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.
+
+"""Call instruction that represents calling a schedule as a subroutine."""
+
+from typing import Optional, Union, Dict, Tuple, Set
+
+from qiskit.circuit.parameterexpression import ParameterExpression, ParameterValueType
+from qiskit.pulse.channels import Channel
+from qiskit.pulse.exceptions import PulseError
+from qiskit.pulse.instructions import instruction
+from qiskit.utils.deprecation import deprecate_func
+
+
+class Call(instruction.Instruction):
+    """Pulse ``Call`` instruction.
+
+    The ``Call`` instruction represents the calling of a referenced subroutine (schedule).
+    It enables code reuse both within the pulse representation and hardware (if supported).
+    """
+
+    # Prefix to use for auto naming.
+    prefix = "call"
+
+    @deprecate_func(
+        since="0.25.0",
+        package_name="qiskit-terra",
+        additional_msg="Instead, use the pulse builder function "
+        "qiskit.pulse.builder.call(subroutine) within an active building context.",
+    )
+    def __init__(
+        self,
+        subroutine,
+        value_dict: Optional[Dict[ParameterExpression, ParameterValueType]] = None,
+        name: Optional[str] = None,
+    ):
+        """Define new subroutine.
+
+        .. note:: Inline subroutine is mutable. This requires special care for modification.
+
+        Args:
+            subroutine (Union[Schedule, ScheduleBlock]): A program subroutine to be referred to.
+            value_dict: Mapping of parameter object to assigned value.
+            name: Unique ID of this subroutine. If not provided, this is generated based on
+                the subroutine name.
+
+        Raises:
+            PulseError: If subroutine is not valid data format.
+        """
+        from qiskit.pulse.schedule import Schedule, ScheduleBlock
+
+        if not isinstance(subroutine, (Schedule, ScheduleBlock)):
+            raise PulseError(f"Subroutine type {subroutine.__class__.__name__} cannot be called.")
+
+        value_dict = value_dict or {}
+
+        # initialize parameter template
+        if subroutine.is_parameterized():
+            self._arguments = {par: value_dict.get(par, par) for par in subroutine.parameters}
+            assigned_subroutine = subroutine.assign_parameters(
+                value_dict=self.arguments, inplace=False
+            )
+        else:
+            self._arguments = {}
+            assigned_subroutine = subroutine
+
+        # create cache data of parameter-assigned subroutine
+        self._assigned_cache = (self._get_arg_hash(), assigned_subroutine)
+
+        super().__init__(operands=(subroutine,), name=name or f"{self.prefix}_{subroutine.name}")
+
+    @property
+    def duration(self) -> Union[int, ParameterExpression]:
+        """Duration of this instruction."""
+        return self.subroutine.duration
+
+    @property
+    def channels(self) -> Tuple[Channel]:
+        """Returns the channels that this schedule uses."""
+        return self.assigned_subroutine().channels
+
+    @property
+    def subroutine(self):
+        """Return attached subroutine.
+
+        Returns:
+            program (Union[Schedule, ScheduleBlock]): The program referenced by the call.
+        """
+        return self.operands[0]
+
+    def assigned_subroutine(self):
+        """Returns this subroutine with the parameters assigned.
+
+        .. note:: This function may be often called internally for class equality check
+            despite its overhead of parameter assignment.
+            The subroutine with parameter assigned is cached based on ``.argument`` hash.
+            Once this argument is updated, new assigned instance will be returned.
+            Note that this update is not mutable operation.
+
+        Returns:
+            program (Union[Schedule, ScheduleBlock]): Attached program.
+        """
+        if self._get_arg_hash() != self._assigned_cache[0]:
+            subroutine = self.subroutine.assign_parameters(value_dict=self.arguments, inplace=False)
+            # update cache data
+            self._assigned_cache = (self._get_arg_hash(), subroutine)
+        else:
+            subroutine = self._assigned_cache[1]
+
+        return subroutine
+
+    @property
+    def parameters(self) -> Set:
+        """Unassigned parameters which determine the instruction behavior."""
+        params = set()
+        for value in self._arguments.values():
+            if isinstance(value, ParameterExpression):
+                params |= value.parameters
+        return params
+
+    @property
+    def arguments(self) -> Dict[ParameterExpression, ParameterValueType]:
+        """Parameters dictionary to be assigned to subroutine."""
+        return self._arguments
+
+    @arguments.setter
+    def arguments(self, new_arguments: Dict[ParameterExpression, ParameterValueType]):
+        """Set new arguments.
+
+        Args:
+            new_arguments: Dictionary of new parameter value mapping to update.
+
+        Raises:
+            PulseError: When new arguments doesn't match with existing arguments.
+        """
+        # validation
+        if new_arguments.keys() != self._arguments.keys():
+            new_arg_names = ", ".join(map(repr, new_arguments.keys()))
+            old_arg_names = ", ".join(map(repr, self.arguments.keys()))
+            raise PulseError(
+                "Key mismatch between new arguments and existing arguments. "
+                f"{new_arg_names} != {old_arg_names}"
+            )
+
+        self._arguments = new_arguments
+
+    def _get_arg_hash(self):
+        """A helper function to generate hash of parameters."""
+        return hash(tuple(self.arguments.items()))
+
+    def __eq__(self, other: instruction.Instruction) -> bool:
+        """Check if this instruction is equal to the `other` instruction.
+
+        Instructions are equal if they share the same type, operands, and channels.
+        """
+        # type check
+        if not isinstance(other, self.__class__):
+            return False
+
+        # compare subroutine. assign parameter values before comparison
+        if self.assigned_subroutine() != other.assigned_subroutine():
+            return False
+
+        return True
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.assigned_subroutine()}, name='{self.name}')"

qiskit/pulse/instructions/delay.py

@@ -0,0 +1,69 @@
+# 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.
+
+"""An instruction for blocking time on a channel; useful for scheduling alignment."""
+from typing import Optional, Union, Tuple
+
+from qiskit.circuit import ParameterExpression
+from qiskit.pulse.channels import Channel
+from qiskit.pulse.instructions.instruction import Instruction
+
+
+class Delay(Instruction):
+    """A blocking instruction with no other effect. The delay is used for aligning and scheduling
+    other instructions.
+
+    Example:
+
+        To schedule an instruction at time = 10, on a channel assigned to the variable ``channel``,
+        the following could be used::
+
+            sched = Schedule(name="Delay instruction example")
+            sched += Delay(10, channel)
+            sched += Gaussian(duration, amp, sigma, channel)
+
+        The ``channel`` will output no signal from time=0 up until time=10.
+    """
+
+    def __init__(
+        self,
+        duration: Union[int, ParameterExpression],
+        channel: Channel,
+        name: Optional[str] = None,
+    ):
+        """Create a new delay instruction.
+
+        No other instruction may be scheduled within a ``Delay``.
+
+        Args:
+            duration: Length of time of the delay in terms of dt.
+            channel: The channel that will have the delay.
+            name: Name of the delay for display purposes.
+        """
+        super().__init__(operands=(duration, channel), name=name)
+
+    @property
+    def channel(self) -> Channel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self.operands[1]
+
+    @property
+    def channels(self) -> Tuple[Channel]:
+        """Returns the channels that this schedule uses."""
+        return (self.channel,)
+
+    @property
+    def duration(self) -> Union[int, ParameterExpression]:
+        """Duration of this instruction."""
+        return self.operands[0]

qiskit/pulse/instructions/directives.py

@@ -0,0 +1,145 @@
+# 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 abc import ABC
+from typing import Optional, Tuple
+
+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: Optional[str] = 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):
+        """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: Optional[str] = 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