Serializable parametric pulse

qiskit/assembler/assemble_circuits.py

@@ -101,7 +101,6 @@ def _assemble_circuit(
 
     # TODO: why do we need n_qubits and memory_slots in both the header and the config
     config = QasmQobjExperimentConfig(n_qubits=num_qubits, memory_slots=memory_slots)
-
     calibrations, pulse_library = _assemble_pulse_gates(circuit, run_config)
     if calibrations:
         config.calibrations = calibrations

qiskit/assembler/assemble_schedules.py

@@ -187,25 +187,30 @@ def _assemble_instructions(
     acquire_instruction_map = defaultdict(list)
     for time, instruction in sched.instructions:
 
-        if isinstance(instruction, instructions.Play) and isinstance(
-            instruction.pulse, library.ParametricPulse
-        ):
-            pulse_shape = ParametricPulseShapes(type(instruction.pulse)).name
-            if pulse_shape not in run_config.parametric_pulses:
+        if isinstance(instruction, instructions.Play):
+            if isinstance(instruction.pulse, (library.ParametricPulse, library.SymbolicPulse)):
+                is_backend_supported = True
+                try:
+                    pulse_shape = ParametricPulseShapes(type(instruction.pulse)).name
+                    if pulse_shape not in run_config.parametric_pulses:
+                        is_backend_supported = False
+                except ValueError:
+                    # Custom pulse class, or bare SymbolicPulse object.
+                    is_backend_supported = False
+
+                if not is_backend_supported:
+                    instruction = instructions.Play(
+                        instruction.pulse.get_waveform(), instruction.channel, name=instruction.name
+                    )
+
+            if isinstance(instruction.pulse, library.Waveform):
+                name = hashlib.sha256(instruction.pulse.samples).hexdigest()
                 instruction = instructions.Play(
-                    instruction.pulse.get_waveform(), instruction.channel, name=instruction.name
+                    library.Waveform(name=name, samples=instruction.pulse.samples),
+                    channel=instruction.channel,
+                    name=name,
                 )
-
-        if isinstance(instruction, instructions.Play) and isinstance(
-            instruction.pulse, library.Waveform
-        ):
-            name = hashlib.sha256(instruction.pulse.samples).hexdigest()
-            instruction = instructions.Play(
-                library.Waveform(name=name, samples=instruction.pulse.samples),
-                channel=instruction.channel,
-                name=name,
-            )
-            user_pulselib[name] = instruction.pulse.samples
+                user_pulselib[name] = instruction.pulse.samples
 
         # ignore explicit delay instrs on acq channels as they are invalid on IBMQ backends;
         # timing of other instrs will still be shifted appropriately

qiskit/pulse/__init__.py

@@ -143,6 +143,7 @@
     Gaussian,
     GaussianSquare,
     ParametricPulse,
+    SymbolicPulse,
     Waveform,
 )
 from qiskit.pulse.library.samplers.decorators import functional_pulse

qiskit/pulse/library/__init__.py

@@ -10,35 +10,107 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-r"""
-=====================================================
-Pulse Library (waveforms :mod:`qiskit.pulse.library`)
-=====================================================
+"""
+===========================================
+Pulse Library (:mod:`qiskit.pulse.library`)
+===========================================
 
 This library provides Pulse users with convenient methods to build Pulse waveforms.
 
-Arbitrary waveforms can be described with :py:class:`~qiskit.pulse.library.Waveform`\ s.
+A pulse programmer can choose from one of several :ref:`pulse_models` such as
+:class:`~Waveform` and :class:`~SymbolicPulse` to create a pulse program.
+The :class:`~Waveform` model directly stores the waveform data points in each class instance.
+This model provides the most flexibility to express arbitrary waveforms and allows
+a rapid prototyping of new control techniques. However, this model is typically memory
+inefficient and might be hard to scale to large-size quantum processors.
+Several waveform subclasses are defined by :ref:`waveforms`,
+but a user can also directly instantiate the :class:`~Waveform` class with ``samples`` argument
+which is usually a complex numpy array or any kind of array-like data.
+
+In contrast, the :class:`~SymbolicPulse` model only stores the function and its parameters
+that generate the waveform in a class instance.
+It thus provides greater memory efficiency at the price of less flexibility in the waveform.
+This model also defines a small set of pulse subclasses in :ref:`symbolic_pulses`
+which are commonly used in superconducting quantum processors.
+An instance of these subclasses can be serialized in the :ref:`qpy_format`
+while keeping the memory-efficient parametric representation of waveforms.
+Note that :class:`~Waveform` object can be generated from an instance of
+a :class:`~SymbolicPulse` which will set values for the parameters and
+sample the parametric expression to create the :class:`~Waveform`.
+
+.. note::
+
+    QPY serialization support for :class:`.SymbolicPulse` is currently not available.
+    This feature will be implemented soon in Qiskit terra version 0.21.
+
 
-The :py:mod:`~qiskit.pulse.library.discrete` module will generate
-:py:class:`~qiskit.pulse.library.Waveform`\ s for common waveform envelopes.
+.. _pulse_models:
 
-The parametric pulses, :py:class:`~qiskit.pulse.library.Gaussian`,
-:py:class:`~qiskit.pulse.library.GaussianSquare`, :py:class:`~qiskit.pulse.library.Drag` and
-:py:class:`~qiskit.pulse.library.Constant` will generate parameterized descriptions of
-those pulses, which can greatly reduce the size of the job sent to the backend.
+Pulse Models
+============
 
 .. autosummary::
    :toctree: ../stubs/
 
-   ~qiskit.pulse.library.discrete
    Waveform
+   SymbolicPulse
+   ParametricPulse
+
+
+.. _waveforms:
+
+Waveform Pulse Representation
+=============================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   constant
+   zero
+   square
+   sawtooth
+   triangle
+   cos
+   sin
+   gaussian
+   gaussian_deriv
+   sech
+   sech_deriv
+   gaussian_square
+   drag
+
+
+.. _symbolic_pulses:
+
+Parametric Pulse Representation
+===============================
+
+.. autosummary::
+   :toctree: ../stubs/
+
    Constant
    Drag
    Gaussian
    GaussianSquare
 
 """
-from .discrete import *
-from .parametric_pulses import ParametricPulse, Gaussian, GaussianSquare, Drag, Constant
+
+from .discrete import (
+    constant,
+    zero,
+    square,
+    sawtooth,
+    triangle,
+    cos,
+    sin,
+    gaussian,
+    gaussian_deriv,
+    sech,
+    sech_deriv,
+    gaussian_square,
+    drag,
+)
+from .parametric_pulses import ParametricPulse
+from .symbolic_pulses import SymbolicPulse, Gaussian, GaussianSquare, Drag, Constant
 from .pulse import Pulse
 from .waveform import Waveform

qiskit/pulse/library/parametric_pulses.py

@@ -36,6 +36,7 @@ class ParametricPulseShapes(Enum):
         ...
         new_supported_pulse_name = library.YourPulseWaveformClass
 """
+import warnings
 from abc import abstractmethod
 from typing import Any, Dict, Optional, Union
 
@@ -51,7 +52,15 @@ class ParametricPulseShapes(Enum):
 
 
 class ParametricPulse(Pulse):
-    """The abstract superclass for parametric pulses."""
+    """The abstract superclass for parametric pulses.
+
+    .. warning::
+
+        This class is superseded by :class:`.SymbolicPulse` and will be deprecated
+        and eventually removed in the future because of the poor flexibility
+        for defining a new waveform type and serializing it through the :mod:`qiskit.qpy` framework.
+
+    """
 
     @abstractmethod
     def __init__(
@@ -70,6 +79,14 @@ def __init__(
                              amplitude is constrained to 1.
         """
         super().__init__(duration=duration, name=name, limit_amplitude=limit_amplitude)
+
+        warnings.warn(
+            "ParametricPulse and its subclass will be deprecated and will be replaced with "
+            "SymbolicPulse and its subclass because of QPY serialization support. "
+            "See qiskit.pulse.library.symbolic_pulses for details.",
+            PendingDeprecationWarning,
+            stacklevel=3,
+        )
         self.validate_parameters()
 
     @abstractmethod
@@ -155,7 +172,7 @@ def get_waveform(self) -> Waveform:
         return gaussian(duration=self.duration, amp=self.amp, sigma=self.sigma, zero_ends=True)
 
     def validate_parameters(self) -> None:
-        if not _is_parameterized(self.amp) and abs(self.amp) > 1.0 and self.limit_amplitude:
+        if not _is_parameterized(self.amp) and abs(self.amp) > 1.0 and self._limit_amplitude:
             raise PulseError(
                 f"The amplitude norm must be <= 1, found: {abs(self.amp)}"
                 + "This can be overruled by setting Pulse.limit_amplitude."
@@ -287,7 +304,7 @@ def get_waveform(self) -> Waveform:
         )
 
     def validate_parameters(self) -> None:
-        if not _is_parameterized(self.amp) and abs(self.amp) > 1.0 and self.limit_amplitude:
+        if not _is_parameterized(self.amp) and abs(self.amp) > 1.0 and self._limit_amplitude:
             raise PulseError(
                 f"The amplitude norm must be <= 1, found: {abs(self.amp)}"
                 + "This can be overruled by setting Pulse.limit_amplitude."
@@ -431,7 +448,7 @@ def get_waveform(self) -> Waveform:
         )
 
     def validate_parameters(self) -> None:
-        if not _is_parameterized(self.amp) and abs(self.amp) > 1.0 and self.limit_amplitude:
+        if not _is_parameterized(self.amp) and abs(self.amp) > 1.0 and self._limit_amplitude:
             raise PulseError(
                 f"The amplitude norm must be <= 1, found: {abs(self.amp)}"
                 + "This can be overruled by setting Pulse.limit_amplitude."
@@ -445,7 +462,7 @@ def validate_parameters(self) -> None:
             not _is_parameterized(self.beta)
             and not _is_parameterized(self.sigma)
             and np.abs(self.beta) > self.sigma
-            and self.limit_amplitude
+            and self._limit_amplitude
         ):
             # If beta <= sigma, then the maximum amplitude is at duration / 2, which is
             # already constrained by self.amp <= 1
@@ -528,7 +545,7 @@ def get_waveform(self) -> Waveform:
         return constant(duration=self.duration, amp=self.amp)
 
     def validate_parameters(self) -> None:
-        if not _is_parameterized(self.amp) and abs(self.amp) > 1.0 and self.limit_amplitude:
+        if not _is_parameterized(self.amp) and abs(self.amp) > 1.0 and self._limit_amplitude:
             raise PulseError(
                 f"The amplitude norm must be <= 1, found: {abs(self.amp)}"
                 + "This can be overruled by setting Pulse.limit_amplitude."

qiskit/pulse/library/pulse.py

@@ -24,6 +24,8 @@ class Pulse(ABC):
     modulation phase and frequency are specified separately from ``Pulse``s.
     """
 
+    __slots__ = ("duration", "name", "_limit_amplitude")
+
     limit_amplitude = True
 
     @abstractmethod
@@ -46,8 +48,7 @@ def __init__(
 
         self.duration = duration
         self.name = name
-        if limit_amplitude is not None:
-            self.limit_amplitude = limit_amplitude
+        self._limit_amplitude = limit_amplitude or self.__class__.limit_amplitude
 
     @property
     def id(self) -> int:  # pylint: disable=invalid-name