update docs

Qiskit · Jun 15, 2022 · d844253 · d844253
1 parent 15e9f7c
commit d844253
Show file tree

Hide file tree

Showing 5 changed files with 37 additions and 10 deletions.
diff --git a/qiskit/pulse/library/__init__.py b/qiskit/pulse/library/__init__.py
@@ -32,8 +32,16 @@
 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 QPY binary format
+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.
 
 
 .. _pulse_models:
@@ -46,6 +54,7 @@
 
    Waveform
    SymbolicPulse
+   ParametricPulse
 
 
 .. _waveforms:

diff --git a/qiskit/pulse/library/parametric_pulses.py b/qiskit/pulse/library/parametric_pulses.py
@@ -52,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__(
@@ -73,7 +81,7 @@ def __init__(
         super().__init__(duration=duration, name=name, limit_amplitude=limit_amplitude)
 
         warnings.warn(
-            "ParametricPulse and its subclass have been deprecated and will be replaced with "
+            "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,

diff --git a/qiskit/pulse/library/symbolic_pulses.py b/qiskit/pulse/library/symbolic_pulses.py
@@ -211,9 +211,20 @@ class SymbolicPulse(Pulse):
     A symbolic pulse instance can be defined with an envelope and parameter constraints.
     Envelope and parameter constraints should be provided as symbolic expressions.
     Rather than creating a subclass, different pulse shapes can be distinguished by
-    the instance attributes :attr:`SymbolicPulse.envelope` and :attr:`SymbolicPulse.constraints`,
-    together with the ``pulse_type`` argument of the :class:`SymbolicPulse` constructor.
+    the instance attributes :attr:`SymbolicPulse.envelope` and :attr:`SymbolicPulse.pulse_type`.
 
+    The symbolic expressions must be defined either with SymPy_ or Symengine_.
+    Usually Symengine-based expression is much more performant for instantiation
+    of the :class:`SymbolicPulse`, however, it doesn't support every functions available in SymPy.
+    You may need to choose proper library depending on how you define your pulses.
+    Symengine works in the most envelopes and constraints, and thus it is recommended to use
+    this library especially when your program contains a lot of pulses.
+    Also note that Symengine has the limited platform support, in particular, for 32-bit platforms
+    such as ``i686`` and ``arm``, or Ubuntu Server such as ``s390x``. You must confirm Symengine
+    is available in your environment, otherwise it must fall back into SymPy.
+
+    .. _SymPy: https://www.sympy.org/en/index.html
+    .. _Symengine: https://symengine.org
 
     .. _symbolic_pulse_envelope:
 
@@ -344,7 +355,8 @@ def Sawtooth(duration, amp, freq, name):
 
     .. rubric:: Serialization
 
-    The :class:`~SymbolicPulse` subclass is QPY serialized with symbolic expressions.
+    The :class:`~SymbolicPulse` subclass can be serialized along with the
+    symbolic expressions through :mod:`qiskit.qpy`.
     A user can therefore create a custom pulse subclass with a novel envelope and constraints,
     and then one can instantiate the class with certain parameters to run on a backend.
     This pulse instance can be saved in the QPY binary, which can be loaded afterwards

diff --git a/qiskit/qpy/__init__.py b/qiskit/qpy/__init__.py
@@ -64,6 +64,8 @@
 0.29.0. However, loading that QPY file with 0.18.0 is not supported and may not
 work.
 
+.. _qpy_format:
+
 **********
 QPY Format
 **********

diff --git a/releasenotes/notes/add-serializable-parametric-pulse-31490c4d2cc49ec6.yaml b/releasenotes/notes/add-serializable-parametric-pulse-31490c4d2cc49ec6.yaml
@@ -20,7 +20,3 @@ upgrade:
     :class:`~qiskit.pulse.library.Constant`.
     Becasue :class:`~SymbolicPulse` supports full backward compatibility,
     there is no loss of functionality due to the switching of the base class.
-deprecations:
-  - |
-    A pulse base class :class:`~ParametricPulse` has been deprecated and replaced with
-    :class:`~SymbolicPulse`.