Docathon: Module level docs for Pulse

qiskit/pulse/__init__.py

@@ -13,56 +13,78 @@
 # that they have been altered from the originals.
 
 """
-===============================
-OpenPulse (:mod:`qiskit.pulse`)
-===============================
-
 .. currentmodule:: qiskit.pulse
 
-Channels
-========
+===========================
+Pulse (:mod:`qiskit.pulse`)
+===========================
 
-.. autosummary::
-   :toctree: ../stubs/
+Qiskit-Pulse is a pulse-level quantum programming kit. This lower level of programming offers the
+user more control than programming with :py:class:`~qiskit.circuit.QuantumCircuit` s.
 
-   DriveChannel
-   MeasureChannel
-   AcquireChannel
-   ControlChannel
-   RegisterSlot
-   MemorySlot
+Extracting the greatest performance from quantum hardware requires real-time pulse-level
+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
+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.
 
-Commands
-========
+.. _pulse-commands:
+
+Commands (:mod:`~qiskit.pulse.commands`)
+================================================
 
 .. autosummary::
    :toctree: ../stubs/
 
-   Instruction
-   Acquire
-   AcquireInstruction
-   FrameChange
-   PersistentValue
    SamplePulse
-   Snapshot
-   Kernel
-   Discriminator
    Delay
-   ParametricPulse
-   ParametricInstruction
+   FrameChange
    Gaussian
    GaussianSquare
    Drag
    ConstantPulse
+   Acquire
+   Snapshot
+
+.. _pulse-channels:
+
+Channels (:mod:`~qiskit.pulse.channels`)
+========================================
+
+Pulse is meant to be agnostic to the underlying hardware implementation, while still allowing
+low-level control. Therefore, our signal channels are  *virtual* hardware channels. The backend
+which executes our programs is responsible for mapping these virtual channels to the proper
+physical channel within the quantum control hardware.
+
+Channels are characterized by their type and their index. See each channel type below to learn more.
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   DriveChannel
+   MeasureChannel
+   AcquireChannel
+   ControlChannel
+   RegisterSlot
+   MemorySlot
 
 Schedules
 =========
 
+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
-   ScheduleComponent
+   Instruction
 
 Configuration
 =============
@@ -71,8 +93,18 @@
    :toctree: ../stubs/
 
    InstructionScheduleMap
-   LoConfig
-   LoRange
+
+Rescheduling Utilities
+======================
+
+These utilities return modified :class:`~qiskit.pulse.Schedule` s.
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   ~reschedule.align_measures
+   ~reschedule.add_implicit_acquires
+   ~reschedule.pad
 
 Pulse Library
 =============
@@ -89,6 +121,7 @@
    :toctree: ../stubs/
 
    PulseError
+
 """
 
 from .channels import (DriveChannel, MeasureChannel, AcquireChannel,

qiskit/pulse/channels.py

@@ -15,7 +15,7 @@
 """
 This module defines Pulse Channels. Channels include:
 
-  - transmit channels, which should subclass``PulseChannel``
+  - transmit channels, which should subclass ``PulseChannel``
   - receive channels, such as ``AcquireChannel``
   - non-signal "channels" such as ``SnapshotChannel``, ``MemorySlot`` and ``RegisterChannel``.
 
@@ -31,7 +31,7 @@
 class Channel(metaclass=ABCMeta):
     """Base class of channels. Channels provide a Qiskit-side label for typical quantum control
     hardware signal channels. The final label -> physical channel mapping is the responsibility
-    of the hardware backend. For instance,``DriveChannel(0)`` holds instructions which the backend
+    of the hardware backend. For instance, ``DriveChannel(0)`` holds instructions which the backend
     should map to the signal line driving gate operations on the qubit labeled (indexed) 0.
     """