Command/Inst refactor: Delay

qiskit/assembler/assemble_schedules.py

@@ -17,7 +17,7 @@
 from collections import defaultdict
 
 from qiskit.exceptions import QiskitError
-from qiskit.pulse import Schedule
+from qiskit.pulse import Schedule, Delay
 from qiskit.pulse.commands import (Command, PulseInstruction, Acquire, AcquireInstruction,
                                    DelayInstruction, SamplePulse, ParametricInstruction)
 from qiskit.qobj import (PulseQobj, QobjHeader, QobjExperimentHeader,
@@ -193,7 +193,7 @@ def _assemble_instructions(
             acquire_instruction_map[(time, instruction.command)].append(instruction)
             continue
 
-        if isinstance(instruction, DelayInstruction):
+        if isinstance(instruction, (DelayInstruction, Delay)):
             # delay instructions are ignored as timing is explicit within qobj
             continue
 

qiskit/pulse/__init__.py

@@ -135,12 +135,12 @@
 from .cmd_def import CmdDef
 from .commands import (Acquire, AcquireInstruction, FrameChange,
                        PersistentValue, SamplePulse, Snapshot, Kernel,
-                       Discriminator, Delay, ParametricPulse,
+                       Discriminator, ParametricPulse,
                        ParametricInstruction, Gaussian,
                        GaussianSquare, Drag, ConstantPulse, functional_pulse)
 from .configuration import LoConfig, LoRange
 from .exceptions import PulseError
 from .instruction_schedule_map import InstructionScheduleMap
-from .instructions import Instruction
+from .instructions import Instruction, Delay
 from .interfaces import ScheduleComponent
 from .schedule import Schedule

qiskit/pulse/commands/delay.py

@@ -12,65 +12,15 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-Delay instruction.
-"""
-from typing import Optional
+"""Delay instruction. Deprecated path."""
+import warnings
 
-from qiskit.pulse.channels import Channel
+from ..instructions import Delay
 from ..instructions import Instruction
-from .command import Command
-
-
-class Delay(Command):
-    """Delay command."""
-
-    prefix = 'delay'
-
-    def __init__(self, duration: int, name: Optional[str] = None):
-        """Create a new delay command.
-
-        No other command may be scheduled within a delay command.
-
-        Delays that exist as the last instruction on a channel will be removed.
-
-        Note: Delays are not explicitly sent to backends with the current Qobj
-        transport layer. They are only used to enforce the correct offset in time
-        for instructions that will be submitted directly to the backend.
-
-        Args:
-            duration: Length of time of the delay in terms of dt.
-            name: Name of delay command for display purposes.
-        """
-        super().__init__(duration=duration)
-        self._name = Delay.create_name(name)
-
-    # pylint: disable=arguments-differ
-    def to_instruction(self, channel: Channel, name: str = None) -> 'DelayInstruction':
-        """Create a delay instruction on the given channel.
-
-        Args:
-            channel: Channel for delay instruction to be created.
-            name: Name of delay instruction for display purposes.
-
-        Returns:
-            DelayInstruction
-        """
-        return DelayInstruction(self, channel, name=name)
-    # pylint: enable=arguments-differ
 
 
 class DelayInstruction(Instruction):
-    """Instruction to add a blocking delay on a `Channel`.
-
-    No other may be scheduled within a delay command.
-
-    Delays that exist as the last instruction on a channel will be removed.
-
-    Note: Delay's are not explicitly sent to backends with the current Qobj
-    transport layer. They are only used to enforce the correct offset in time
-    for instructions that will be submitted directly to the backend.
-    """
+    """Deprecated."""
 
     def __init__(self, command: Delay, channel: Delay, name: str = None):
         """Create a delay instruction from a delay command.
@@ -80,4 +30,8 @@ def __init__(self, command: Delay, channel: Delay, name: str = None):
             channel: Channel for delay instruction to be created.
             name: Name of delay instruction for display purposes.
         """
+        warnings.warn("The DelayInstruction is deprecated. Use Delay, instead, with channels. "
+                      "For example: DelayInstruction(Delay(5), DriveChannel(0)) -> "
+                      "Delay(5, DriveChannel(0)).",
+                      DeprecationWarning)
         super().__init__(command, channel, name=name)

qiskit/pulse/instructions/__init__.py

@@ -21,4 +21,5 @@
 An instruction can be added to a :py:class:`~qiskit.pulse.Schedule`, which is a
 sequence of scheduled Pulse ``Instruction`` s over many channels.
 """
+from .delay import Delay
 from .instruction import Instruction

qiskit/pulse/instructions/delay.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+
+# 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."""
+import warnings
+
+from typing import List, Optional, Union
+
+from qiskit.pulse.channels import PulseChannel
+from qiskit.pulse.exceptions import PulseError
+from .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: int,
+                 channel: Optional[PulseChannel] = None,
+                 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.
+        """
+        if channel is None:
+            warnings.warn("Usage of Delay without specifying a channel is deprecated. For "
+                          "example, Delay(5)(DriveChannel(0)) should be replaced by "
+                          "Delay(5, DriveChannel(0)).", DeprecationWarning)
+        self._channel = channel
+        super().__init__(duration, channel, name=name)
+
+    @property
+    def operands(self) -> List[Union[int, PulseChannel]]:
+        """Return a list of instruction operands."""
+        return [self.duration, self.channel]
+
+    @property
+    def channel(self) -> PulseChannel:
+        """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
+        scheduled on.
+        """
+        return self._channel
+
+    def __call__(self, channel: PulseChannel) -> 'Delay':
+        """Return new ``Delay`` that is fully instantiated with both ``duration`` and a ``channel``.
+
+        Args:
+            channel: The channel that will have the delay.
+
+        Return:
+            Complete and ready to schedule ``Delay``.
+
+        Raises:
+            PulseError: If ``channel`` has already been set.
+        """
+        warnings.warn("Calling Delay with a channel is deprecated. Instantiate the delay with "
+                      "a channel instead.", DeprecationWarning)
+        if self._channel is not None:
+            raise PulseError("The channel has already been assigned as {}.".format(self.channel))
+        return Delay(self.duration, channel)
+
+    def __repr__(self):
+        return "{}({}, {})".format(self.__class__.__name__,
+                                   self.duration,
+                                   self.channel)

qiskit/pulse/instructions/instruction.py

@@ -55,19 +55,22 @@ def __init__(self, duration: Union['commands.Command', int],
             *channels: List of pulse channels that this instruction operates on.
             name: Display name for this instruction.
         """
-        self._name = name
-
         self._command = None
         if not isinstance(duration, int):
             # TODO: Add deprecation warning once all instructions are migrated
             self._command = duration
             if name is None:
-                self._name = self.command.name
+                name = self.command.name
             duration = self.command.duration
+        self._duration = duration
 
         self._timeslots = TimeslotCollection(*(Timeslot(Interval(0, duration), channel)
                                                for channel in channels if channel is not None))
 
+        if name is None:
+            name = "{}{}".format(self.__class__.__name__.lower(), str(hex(self.__hash__()))[3:8])
+        self._name = name
+
     @property
     def name(self) -> str:
         """Name of this instruction."""
@@ -101,7 +104,7 @@ def stop_time(self) -> int:
     @property
     def duration(self) -> int:
         """Duration of this instruction."""
-        return self.timeslots.duration
+        return self._duration
 
     @property
     def _children(self) -> Tuple[ScheduleComponent]:
@@ -270,8 +273,8 @@ def __eq__(self, other: 'Instruction'):
     def __hash__(self):
         if self.command:
             # Backwards compatibility for Instructions with Commands
-            return hash((hash(tuple(self.command)), self.channels.__hash__()))
-        return hash((hash(tuple(self.duration)), self.channels.__hash__()))
+            return hash(((tuple(self.command)), self.channels.__hash__()))
+        return hash((self.duration, self.channels.__hash__()))
 
     def __add__(self, other: ScheduleComponent) -> Schedule:
         """Return a new schedule with `other` inserted within `self` at `start_time`."""

releasenotes/notes/unify-instructions-and-commands-aaa6d8724b8a29d3.yaml

@@ -22,3 +22,18 @@ features:
 
         sched += Delay(5, DriveChannel(0))
         sched += ShiftPhase(np.pi, DriveChannel(0))
+upgrade:
+  - |
+    ``DelayInstruction`` has been deprecated and replaced by
+    :py:class:`~qiskit.pulse.instruction.Delay`. The migration pattern is::
+
+        Delay(<duration>)(<channel>) -> Delay(<duration>, <channel>)
+        DelayInstruction(Delay(<duration>), <channel>)
+            -> Delay(<duration>, <channel>)
+
+    Until the deprecation period is over, the previous ``Delay`` syntax of
+    calling a command on a channel will also be supported::
+
+        Delay(<phase>)(<channel>)
+
+    The new ``Delay`` instruction does not support a ``command`` attribute.

test/python/pulse/test_instructions.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+
+# 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.
+
+# pylint: disable=invalid-name,unexpected-keyword-arg
+
+"""Unit tests for pulse instructions."""
+
+from qiskit.pulse import Delay, DriveChannel
+from qiskit.test import QiskitTestCase
+
+
+class TestDelayCommand(QiskitTestCase):
+    """Delay tests."""
+
+    def test_delay(self):
+        """Test delay."""
+        delay = Delay(10, DriveChannel(0), name='test_name')
+
+        self.assertEqual(delay.name, "test_name")
+        self.assertEqual(delay.duration, 10)
+        self.assertEqual(delay.operands, [10, DriveChannel(0)])