Issue 3750 wrap up

qiskit/pulse/__init__.py

@@ -26,30 +26,44 @@
 instructions. Pulse answers that need: it enables the quantum physicist *user* to specify the
 exact time dynamics of an experiment. It is especially powerful for error mitigation techniques.
 
-The input is given as arbitrary, time-ordered signals (see: :ref:`pulse-commands`) scheduled in
+The input is given as arbitrary, time-ordered signals (see: :ref:`pulse-insts`) scheduled in
 parallel over multiple virtual hardware or simulator resources (see: :ref:`pulse-channels`). The
 system also allows the user to recover the time dynamics of the measured output.
 
 This is sufficient to allow the quantum physicist to explore and correct for noise in a quantum
 system.
 
-.. _pulse-commands:
+.. _pulse-insts:
 
-Commands (:mod:`~qiskit.pulse.commands`)
-========================================
+Instructions (:mod:`~qiskit.pulse.instructions`)
+================================================
 
 .. autosummary::
    :toctree: ../stubs/
 
-   SamplePulse
+   ~qiskit.pulse.instructions
+
+   Acquire
    Delay
-   FrameChange
+   Play
+   SetFrequency
+   ShiftPhase
+   Snapshot
+
+Pulse Library (waveforms :mod:`~qiskit.pulse.pulse_lib`)
+========================================================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   ~qiskit.pulse.pulse_lib
+
+   ~qiskit.pulse.pulse_lib.discrete
+   SamplePulse
+   ConstantPulse
+   Drag
    Gaussian
    GaussianSquare
-   Drag
-   ConstantPulse
-   Acquire
-   Snapshot
 
 .. _pulse-channels:
 
@@ -66,6 +80,8 @@
 .. autosummary::
    :toctree: ../stubs/
 
+   ~qiskit.pulse.channels
+
    DriveChannel
    MeasureChannel
    AcquireChannel
@@ -77,21 +93,13 @@
 =========
 
 Schedules are Pulse programs. They describe instruction sequences for the control hardware.
-An :class:`~qiskit.pulse.Instruction` is a :py:class:`~qiskit.pulse.commands.Command` which has
-been assigned to its :class:`~qiskit.pulse.channels.Channel` (s).
 
 .. autosummary::
    :toctree: ../stubs/
 
    Schedule
    Instruction
 
-.. autosummary::
-   :toctree: ../stubs/
-
-   qiskit.pulse.commands
-   qiskit.pulse.channels
-
 Configuration
 =============
 
@@ -112,14 +120,6 @@
    ~reschedule.add_implicit_acquires
    ~reschedule.pad
 
-Pulse Library
-=============
-
-.. autosummary::
-   :toctree: ../stubs/
-
-   ~qiskit.pulse.pulse_lib.discrete
-
 Exceptions
 ==========
 

qiskit/pulse/commands/__init__.py

@@ -14,31 +14,13 @@
 
 # pylint: disable=cyclic-import
 
-"""
-Supported command types in Pulse.
-
-.. autosummary::
-   :toctree: ../stubs/
-
-   Acquire
-   FrameChange
-   SamplePulse
-   Snapshot
-   Delay
-   Gaussian
-   GaussianSquare
-   Drag
-   ConstantPulse
+"""Supported command types in Pulse. This directory is deprecated.
 
-Abstract Classes
-----------------
-.. autosummary::
-   :toctree: ../stubs/
-
-   ParametricPulse
-   Command
-
- """
+AcquireInstruction, FrameChange, FrameChangeInstruction, PersistentValue,
+PersistentValueInstruction, PulseInstruction, DelayInstruction and ParametricInstruction are all
+deprecated. When they are removed, this ``pulse.commands`` import path for the remaining objects
+can also be deprecated.
+"""
 from .acquire import Acquire, AcquireInstruction
 from .frame_change import FrameChange, FrameChangeInstruction
 from .meas_opts import Discriminator, Kernel

qiskit/pulse/configuration.py

@@ -39,7 +39,8 @@ def __init__(self, name: Optional[str] = None, **params):
     def __repr__(self):
         return "{}({}{})".format(self.__class__.__name__,
                                  "'" + self.name + "', " or "",
-                                 ', '.join("{}={}".format(str(k), str(v)) for k, v in self.params))
+                                 ', '.join("{}={}".format(str(k), str(v))
+                                           for k, v in self.params.items()))
 
 
 class Discriminator:
@@ -60,7 +61,8 @@ def __init__(self, name: Optional[str] = None, **params):
     def __repr__(self):
         return "{}({}{})".format(self.__class__.__name__,
                                  "'" + self.name + "', " or "",
-                                 ', '.join("{}={}".format(str(k), str(v)) for k, v in self.params))
+                                 ', '.join("{}={}".format(str(k), str(v))
+                                           for k, v in self.params.items()))
 
 
 class LoRange:

qiskit/pulse/exceptions.py

@@ -12,9 +12,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""
-Exception for errors raised by pulse module.
-"""
+"""Exception for errors raised by the pulse module."""
 from qiskit.exceptions import QiskitError
 
 

qiskit/pulse/instruction_schedule_map.py

@@ -47,6 +47,8 @@ class InstructionScheduleMap():
     where the first key is the name of a circuit instruction (e.g. ``'u1'``, ``'measure'``), the
     second key is a tuple of qubit indices, and the final value is a Schedule implementing the
     requested instruction.
+
+    These can usually be seen as gate calibrations.
     """
 
     def __init__(self):

qiskit/pulse/instructions/__init__.py

@@ -13,21 +13,42 @@
 # that they have been altered from the originals.
 
 """The ``instruction`` module holds the various ``Instruction`` s which are supported by
-Qiskit Pulse. Instructions accept a list of operands unique to instructions of that type.
-Instructions typically include at least one :py:class:`~qiskit.pulse.channels.Channel` as an
-operand specifying where the instruction will be applied, and every instruction has a duration,
-whether implicitly or explicitly defined.
+Qiskit Pulse. Instructions have operands, which typically include at least one
+:py:class:`~qiskit.pulse.channels.Channel` specifying where the instruction will be applied.
 
+Every instruction has a duration, whether explicitly included as an operand or implicitly defined.
 For instance, a :py:class:`~qiskit.pulse.instructions.ShiftPhase` instruction can be instantiated
 with operands *phase* and *channel*, for some float ``phase`` and a
-:py:class`~qiskit.pulse.channels.Channel` ``channel``::
+:py:class:`~qiskit.pulse.channels.Channel` ``channel``::
 
     ShiftPhase(phase, channel)
 
-The duration of this instruction is implicitly zero.
+The duration of this instruction is implicitly zero. On the other hand, the
+:py:class:`~qiskit.pulse.instructions.Delay` instruction takes an explicit duration::
+
+    Delay(duration, channel)
 
 An instruction can be added to a :py:class:`~qiskit.pulse.Schedule`, which is a
-sequence of scheduled Pulse ``Instruction`` s over many channels.
+sequence of scheduled Pulse ``Instruction`` s over many channels. ``Instruction`` s and
+``Schedule`` s implement the same interface.
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   Acquire
+   Delay
+   Play
+   SetFrequency
+   ShiftPhase
+   Snapshot
+
+Abstract Classes
+----------------
+.. autosummary::
+   :toctree: ../stubs/
+
+   Instruction
+
 """
 from .acquire import Acquire
 from .delay import Delay

qiskit/pulse/instructions/acquire.py

@@ -17,7 +17,7 @@
 """
 import warnings
 
-from typing import List, Optional, Union
+from typing import List, Optional, Tuple, Union
 
 from ..channels import MemorySlot, RegisterSlot, AcquireChannel
 from ..configuration import Kernel, Discriminator
@@ -107,29 +107,26 @@ def __init__(self,
         else:
             reg_slot = []
 
-        if name is None and channels is None:
-            name = 'acq{:10x}'.format(hash((duration, kernel, discriminator)))
-        elif name is None:
-            name = 'acq{:10x}'.format(hash((duration, tuple(channels), tuple(mem_slot),
-                                            tuple(reg_slot), kernel, discriminator)))
-
-        if channels is not None:
-            super().__init__(duration, *channels, *mem_slot, *reg_slot, name=name)
-        else:
-            super().__init__(duration, name=name)
-
         self._acquires = channels
         self._channel = channels[0] if channels else None
         self._mem_slots = mem_slot
         self._reg_slots = reg_slot
         self._kernel = kernel
         self._discriminator = discriminator
 
+        if channels is not None:
+            super().__init__(duration, *channels, *mem_slot, *reg_slot, name=name)
+        else:
+            warnings.warn("Usage of Acquire without specifying a channel is deprecated. For "
+                          "example, Acquire(1200)(AcquireChannel(0)) should be replaced by "
+                          "Acquire(1200, AcquireChannel(0)).", DeprecationWarning)
+            super().__init__(duration, name=name)
+
     @property
-    def operands(self) -> List:
-        """Return a list of instruction operands."""
-        return [self.duration, self.channel,
-                self.mem_slot, self.reg_slot]
+    def operands(self) -> Tuple[int, AcquireChannel, MemorySlot, RegisterSlot]:
+        """Return instruction operands."""
+        return (self.duration, self.channel,
+                self.mem_slot, self.reg_slot)
 
     @property
     def channel(self) -> AcquireChannel:
@@ -182,7 +179,7 @@ def reg_slots(self) -> List[RegisterSlot]:
         """RegisterSlots."""
         return self._reg_slots
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "{}({}{}{}{}{}{})".format(
             self.__class__.__name__,
             self.duration,
@@ -192,9 +189,6 @@ def __repr__(self):
             ', ' + str(self.kernel) if self.kernel else '',
             ', ' + str(self.discriminator) if self.discriminator else '')
 
-    def __eq__(self, other):
-        return isinstance(other, type(self)) and self.operands == other.operands
-
     def __call__(self,
                  channel: Optional[Union[AcquireChannel, List[AcquireChannel]]] = None,
                  mem_slot: Optional[Union[MemorySlot, List[MemorySlot]]] = None,

qiskit/pulse/instructions/delay.py

@@ -15,10 +15,10 @@
 """An instruction for blocking time on a channel; useful for scheduling alignment."""
 import warnings
 
-from typing import List, Optional, Union
+from typing import Optional, Tuple
 
-from qiskit.pulse.channels import PulseChannel
-from qiskit.pulse.exceptions import PulseError
+from ..channels import Channel
+from ..exceptions import PulseError
 from .instruction import Instruction
 
 
@@ -39,7 +39,7 @@ class Delay(Instruction):
     """
 
     def __init__(self, duration: int,
-                 channel: Optional[PulseChannel] = None,
+                 channel: Optional[Channel] = None,
                  name: Optional[str] = None):
         """Create a new delay instruction.
 
@@ -58,18 +58,18 @@ def __init__(self, duration: int,
         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]
+    def operands(self) -> Tuple[int, Channel]:
+        """Return instruction operands."""
+        return (self.duration, self.channel)
 
     @property
-    def channel(self) -> PulseChannel:
+    def channel(self) -> Channel:
         """Return the :py:class:`~qiskit.pulse.channels.Channel` that this instruction is
         scheduled on.
         """
         return self._channel
 
-    def __call__(self, channel: PulseChannel) -> 'Delay':
+    def __call__(self, channel: Channel) -> 'Delay':
         """Return new ``Delay`` that is fully instantiated with both ``duration`` and a ``channel``.
 
         Args:
@@ -86,8 +86,3 @@ def __call__(self, channel: PulseChannel) -> 'Delay':
         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)