Foward port release note updates for 0.22.0 release

releasenotes/notes/0.22/adapt-vqe-0f71234cb6ec92f8.yaml

@@ -1,11 +1,11 @@
 ---
 features:
   - |
-    Implements the :class:`qiskit.algorithms.minimum_eigensolvers.AdaptVQE`
-    algorithm. This algorithm uses a
-    :class:`qiskit.algorithms.minimum_eigensolvers.VQE` in combination with a
-    pool of operators from which to build out an
+    Added a new algorithm class, :class:`~.AdaptVQE` to :mod:`qiskit.algorithms`
+    This algorithm uses a :class:`qiskit.algorithms.minimum_eigensolvers.VQE`
+    in combination with a pool of operators from which to build out an
     :class:`qiskit.circuit.library.EvolvedOperatorAnsatz` adaptively.
+    For example:
 
     .. code-block:: python
 

releasenotes/notes/0.22/add-backend-custom-passes-cddfd05c8704a4b1.yaml

@@ -11,8 +11,10 @@ features:
     backends to run additional custom transpiler passes when targetting that
     backend by leveraging the transpiler stage
     :mod:`~qiskit.transpiler.preset_passmanagers.plugin` interface.
-    For more details on how to use this see :ref:`custom_transpiler_backend`.
+    For more details on how to use this see: :ref:`custom_transpiler_backend`.
   - |
     Added a new keyword argument, ``ignore_backend_supplied_default_methods``, to the
-    :func:`~.transpile` function can be used to disable a backend's custom
-    default method if the target backend has one set.
+    :func:`~.transpile` function which can be used to disable a backend's
+    custom selection of a default method if the target backend has
+    ``get_scheduling_stage_plugin()`` or ``get_translation_stage_plugin()``
+    defined.

releasenotes/notes/0.22/add-barrier-label-8e677979cb37461e.yaml

@@ -1,18 +1,19 @@
 ---
 features:
   - |
-    Added a ``label`` parameter to the :class:`.Barrier` which now allows
-    a user to enter a label for the ``barrier`` directive and the label
-    will be printed at the top of the ``barrier`` in the `mpl`, `latex`,
-    and `text` circuit drawers. Printing of existing ``snapshot`` labels
-    to the 3 circuit drawers was also added.
+    Added a ``label`` parameter to the :class:`.Barrier` class's constructor
+    and the :meth:`~.QuantumCircuit.barrier` method which allows a user to
+    assign a label to an instance of the :class:`~.Barrier` directive. For
+    visualizations generated with :func:`~.circuit_drawer` or
+    :meth:`.QuantumCircuit.draw` this label will be printed at the top of the
+    ``barrier``.
 
-    .. code-block:: python
+    .. jupyter-execute::
 
-      from qiskit import QuantumCircuit
+        from qiskit import QuantumCircuit
 
-      circuit = QuantumCircuit(2)
-      circuit.h(0)
-      circuit.h(1)
-      circuit.barrier(label="After H")
-      circuit.draw('mpl')
+        circuit = QuantumCircuit(2)
+        circuit.h(0)
+        circuit.h(1)
+        circuit.barrier(label="After H")
+        circuit.draw('mpl')

releasenotes/notes/0.22/add-ccz-cs-and-csdg-gates-4ad05e323f1dec4d.yaml

@@ -1,5 +1,6 @@
 ---
 features:
   - |
-    Add new gates :class:`.CZZGate`, :class:`.CSGate`, and :class:`.CSdgGate`.
-    Added their equivalences into the standard :class:`EquivalenceLibrary`. 
+    Add new gates :class:`.CCZGate`, :class:`.CSGate`, and :class:`.CSdgGate`
+    to the standard gates in the Circuit Library
+    (:mod:`qiskit.circuit.library`).

releasenotes/notes/0.22/add-eigensolvers-with-primitives-8b3a9f55f5fd285f.yaml

@@ -1,22 +1,30 @@
 ---
 features:
   - |
-    Added :class:`qiskit.algorithms.eigensolvers` package to include
-    interfaces for primitive-enabled algorithms.
-    :class:`qiskit.algorithms.eigensolvers.VQD` has been
-    refactored in this implementation to leverage primitives.
-
-    To use the new implementation with a reference primitive, one can do, for example:
+    Added :mod:`qiskit.algorithms.eigensolvers` package to include
+    interfaces for primitive-enabled algorithms. This new module
+    will eventually replace the previous ``qiskit.algorithms.eigen_solvers``.
+    This new module contains an alternative implementation of the
+    :class:`~qiskit.algorithms.eigensolvers.VQD` which instead of taking
+    a backend or :class:`~.QuantumInstance` instead takes an instance of
+    :class:`~.BaseEstimator`, including :class:`~.Estimator`,
+    :class:`~.BackendEstimator`, or any provider implementations such as
+    those as those present in ``qiskit-ibm-runtime`` and ``qiskit-aer``.
+
+    For example, to use the new implementation with an instance of
+    :class:`~.Estimator` class:
 
     .. code-block:: python
 
-        from qiskit.algorithms.eigensolvers import VQQ
+        from qiskit.algorithms.eigensolvers import VQD
         from qiskit.algorithms.optimizers import SLSQP
         from qiskit.circuit.library import TwoLocal
         from qiskit.primitives import Sampler, Estimator
         from qiskit.algorithms.state_fidelities import ComputeUncompute
+        from qiskit.opflow import PauliSumOp
+        from qiskit.quantum_info import SparsePauliOp
 
-        h2_op = SparsePauliOp(
+        h2_op = PauliSumOp(SparsePauliOp(
             ["II", "IZ", "ZI", "ZZ", "XX"],
             coeffs=[
                 -1.052373245772859,
@@ -25,7 +33,7 @@ features:
                 -0.01128010425623538,
                 0.18093119978423156,
             ],
-        )
+        ))
 
         estimator = Estimator()
         ansatz = TwoLocal(rotation_blocks=["ry", "rz"], entanglement_blocks="cz")
@@ -40,4 +48,3 @@ features:
     ``aux_operators_evaluated`` field on the results. This will consist of a list or dict of
     tuples containing the expectation values for these operators, as we well as the metadata from
     primitive run. ``aux_operator_eigenvalues`` is no longer a valid field.
-

releasenotes/notes/0.22/add-fidelity-interface-primitives-dc543d079ecaa8dd.yaml

@@ -1,11 +1,11 @@
 ---
 features:
   - |
-    Add new algorithms to calculate state fidelities/overlaps
+    Added new algorithms to calculate state fidelities/overlaps
     for pairs of quantum circuits (that can be parametrized). Apart from
-    the base class (:class:`qiskit.algorithms.state_fidelities.BaseStateFidelity`),
-    there is now an implementation of the compute-uncompute method that leverages
-    the sampler primitive (:class:`qiskit.algorithms.state_fidelities.ComputeUncompute`).
+    the base class (:class:`~qiskit.algorithms.state_fidelities.BaseStateFidelity`) which defines the interface,
+    there is an implementation of the compute-uncompute method that leverages
+    instances of the :class:`~.BaseSampler` primitive: :class:`qiskit.algorithms.state_fidelities.ComputeUncompute`.
 
     For example:
 
@@ -14,7 +14,7 @@ features:
       import numpy as np
       from qiskit.primitives import Sampler
       from qiskit.algorithms.state_fidelities import ComputeUncompute
-      from qiskit. import RealAmplitudes
+      from qiskit.circuit.library import RealAmplitudes
 
       sampler = Sampler(...)
       fidelity = ComputeUncompute(sampler)
@@ -24,5 +24,3 @@ features:
 
       job = fidelity.run([circuit], [circuit], [values], [values+shift])
       fidelities = job.result().fidelities
-
-

releasenotes/notes/0.22/add-gradients-with-primitives-561cf9cf75a7ccb8.yaml

@@ -1,16 +1,34 @@
 ---
 features:
   - |
-    New gradient Algorithms using the primitives have been added. They internally
-    use the primitives to calculate the gradients. There are 4 types of
-    gradient classes (Finite Difference, Parameter Shift,
-    Linear Combination of Unitary, and SPSA) for a sampler and estimator.
+    Added a new module :mod:`qiskit.algorithms.gradients` that contains
+    classes which are used to compute gradients using the primitive
+    interfaces defined in :mod:`qiskit.primitives`. There are 4 types of
+    gradient classes: Finite Difference, Parameter Shift, Linear
+    Combination of Unitary, and SPSA with implementations that either use
+    an instance of the :class:`~.BaseEstimator` interface:
+
+      * :class:`~.ParamShiftEstimatorGradient`
+      * :class:`~.LinCombEstimatorGradient`
+      * :class:`~.FiniteDiffEstimatorGradient`
+      * :class:`~.SPSAEstimatorGradient`
+
+    or an instance of the :class:`~.BaseSampler` interface:
+
+      * :class:`~.ParamShiftSamplerGradient`
+      * :class:`~.LinCombSamplerGradient`
+      * :class:`~.FiniteDiffSamplerGradient`
+      * :class:`~.SPSASamplerGradient`
+
+    The estimator-based gradients compute the gradient of expectation 
+    values, while the sampler-based gradients return gradients of the
+    measurement outcomes (also referred to as "probability gradients").
 
     For example:
 
     .. code-block:: python
 
-      estimator = Estimator(...)
-      gradient = ParamShiftEstimatorGradient(estimator)
-      job = gradient.run(circuits, observables, parameters)
-      gradients = job.result().gradients
+        estimator = Estimator(...)
+        gradient = ParamShiftEstimatorGradient(estimator)
+        job = gradient.run(circuits, observables, parameters)
+        gradients = job.result().gradients

releasenotes/notes/0.22/add-grover-primitives-10f81efdba93703d.yaml

@@ -1,27 +1,24 @@
 ---
 features:
   - |
-    :class:`~.Grover` supports the primitives and can use :class:`~.BaseSampler` to
-    calculate the results. Accordingly, ``quantum instance`` in :class:`~.Grover`
-    is pending deprecation and will be deprecated in a future release.
+    The :class:`~.Grover` class has a new keyword argument, ``sampler`` which is
+    used to run the algorithm using an instance of the :class:`~.BaseSampler`
+    interface to calculate the results. This new argument supersedes the
+    the ``quantum_instance`` argument and accordingly, ``quantum_instance``
+    is pending deprecation and will be deprecated and subsequently removed in
+    future releases.
 
     Example:
 
     .. code-block:: python
 
-      from qiskit import QuantumCircuit
-      from qiskit.primitives import Sampler
-      from qiskit.algorithms import Grover, AmplificationProblem
+        from qiskit import QuantumCircuit
+        from qiskit.primitives import Sampler
+        from qiskit.algorithms import Grover, AmplificationProblem
 
-      sampler = Sampler()
-      oracle = QuantumCircuit(2)
-      oracle.cz(0, 1)
-      problem = AmplificationProblem(oracle, is_good_state=["11"])
-      grover = Grover(sampler=sampler)
-      result = grover.amplify(problem)
-
-deprecations:
-   - |
-     Using a :class:`~.QuantumInstance` in :class:`~.Grover` is
-     pending deprecation and will be deprecated in a future release. Instead, use
-     a :class:`.BaseSampler` to calculate the results, see also the features of this release.
+        sampler = Sampler()
+        oracle = QuantumCircuit(2)
+        oracle.cz(0, 1)
+        problem = AmplificationProblem(oracle, is_good_state=["11"])
+        grover = Grover(sampler=sampler)
+        result = grover.amplify(problem)

releasenotes/notes/0.22/add-pulse-drawer-option-936b6d943de9a270.yaml

@@ -1,18 +1,20 @@
 ---
 features:
   - |
-    New pulse drawer option "formatter.control.fill_waveform" has been added to
-    the style sheets. This option removes the face color of pulses in the drawer.
+    A new option, ``"formatter.control.fill_waveform"`` has been added to
+    the pulse drawer (:func:`.pulse_v2.draw` and :meth:`.Schedule.draw`)
+    style sheets. This option can be used to remove the face color of pulses
+    in the output visualization which allows for drawing pulses only with
+    lines.
+
     For example:
 
     .. code-block:: python
 
-      from qiskit.visualization.pulse_v2 import IQXStandard
-
-      my_style = IQXStandard(
-          **{"formatter.control.fill_waveform": False, "formatter.line_width.fill_waveform": 2}
-      )
+        from qiskit.visualization.pulse_v2 import IQXStandard
 
-      my_sched.draw(style=my_style)
+        my_style = IQXStandard(
+            **{"formatter.control.fill_waveform": False, "formatter.line_width.fill_waveform": 2}
+        )
 
-    This code allows a user to draw pulses only with lines.
+        my_sched.draw(style=my_style)

releasenotes/notes/0.22/add-reset-simplification-pass-82377d80dd0081fd.yaml

@@ -1,10 +1,25 @@
 ---
 features:
   - |
-    Added a new transpiler pass, :class:`~ResetAfterMeasureSimplification`,
+    Added a new transpiler pass, :class:`~.ResetAfterMeasureSimplification`,
     which is used to replace a :class:`~.Reset` operation after a
     :class:`~.Measure` with a conditional :class:`~.XGate`. This pass can
     be used on backends where a :class:`~.Reset` operation is performed by
     doing a measurement and then a conditional X gate so that this will
     remove the duplicate implicit :class:`~.Measure` from the :class:`~.Reset`
-    operation.
+    operation. For example:
+
+    .. jupyter-execute::
+
+        from qiskit import QuantumCircuit
+        from qiskit.transpiler.passes import ResetAfterMeasureSimplification
+
+        qc = QuantumCircuit(1)
+        qc.measure_all()
+        qc.reset(0)
+        qc.draw('mpl')
+
+    .. jupyter-execute::
+
+        result = ResetAfterMeasureSimplification()(qc)
+        result.draw('mpl')

releasenotes/notes/0.22/add-reverse-linear-entanglement-nlocal-38581e4ffb7a7c68.yaml

@@ -1,9 +1,17 @@
 ---
 features:
   - |
-    Add a new entanglement method `entanglement="reverse_linear"` to :class:`~.NLocal` circuits.
-    In the case of :class:`~.TwoLocal` circuits, if `entanglement_blocks="cx"` then
-    `entanglement="reverse_linear"` actually provides the same n-qubit circuit as
-    `entanglement="full"` but with only n-1 CX gates, instead of n(n-1)/2.
-    For :class:`~.RealAmplitudes` and :class:`~.EfficientSU2` circuits, the default value
-    has therefore been changed from `entanglement="full"` to `entanglement="reverse_linear"`.
+    Added a new supported value, ``"reverse_linear"`` for the ``entanglement`` keyword argument
+    to the constructor for the :class:`~.NLocal` circuit class. For :class:`~.TwoLocal` circuits
+    (which are subclassess of :class:`~.NLocal`), if ``entanglement_blocks="cx"`` then
+    using ``entanglement="reverse_linear"`` provides an equivalent  n-qubit circuit as
+    ``entanglement="full"`` but with only :math:`n-1` :class:`~.CXGate` gates, instead of
+    :math:`\frac{n(n-1)}{2}`.
+upgrade:
+  - |
+    The default value for the ``entanglement`` keyword argument on the constructor for the
+    :class:`~.RealAmplitudes` and :class:`~.EfficientSU2` classes has changed from ``"full"`` to
+    ``"reverse_linear"``. This change was made because the output circuit is equivalent but
+    uses only :math:`n-1` instead of :math:`\frac{n(n-1)}{2}` :class:`~.CXGate` gates. If you
+    desire the previous default you can explicity set ``entanglement="full"`` when calling either
+    constructor.

releasenotes/notes/0.22/add-sampler-error-check-38426fb186db44d4.yaml

@@ -1,6 +1,5 @@
 ---
 upgrade:
   - |
-    Added a validation check to :meth:`~qiskit.primitives.BaseSampler.run`.
+    Added a validation check to :meth:`.BaseSampler.run`.
     It raises an error if there is no classical bit.
-

releasenotes/notes/0.22/add-schedule-block-reference-mechanism-8a7811e17b4fead3.yaml

@@ -30,9 +30,8 @@ features:
     the :attr:`~qiskit.pulse.schedule.ScheduleBlock.references` property.
 
     In addition, every reference is managed with a scope to ease parameter management.
-    :meth:`~qiskit.pulse.schedule.ScheduleBlock.scoped_parameters` and
-    :meth:`~qiskit.pulse.schedule.ScheduleBlock.search_parameters` have been added to
-    the schedule block. See API documentation for more details.
+    :meth:`~.scoped_parameters` and :meth:`~.search_parameters` have been added to
+    :class:`~.ScheduleBlock`. See API documentation for more details.
 upgrade:
   - |
     Behavior of the :func:`~qiskit.pulse.builder.call` pulse builder function has been upgraded.

releasenotes/notes/0.22/add-sparsepauliop-methods-00a7e6cc7055e1d0.yaml

@@ -0,0 +1,16 @@
+features:
+  - |
+    Added a new method :meth:`.SparsePauliOp.argsort`, which
+    returns the composition of permutations in the order of sorting
+    by coefficient and sorting by Pauli. By using the ``weight``
+    keyword argument for the method the output can additionally be sorted
+    by the number of non-identity terms in the Pauli, where the set of
+    all Paulis of a given weight are still ordered lexicographically.
+  - |
+    Added a new method :meth:`.SparsePauliOp.sort`, which will first
+    sort the coefficients using numpy's ``argsort()`` and then sort
+    by Pauli, where the Pauli sort takes precedence. If the Pauli sort
+    is the same, it will then be sorted by coefficient. By using the
+    ``weight`` keyword argument the output can additionally  be sorted
+    by the number of non-identity terms in the Pauli, where the set of
+    all Paulis of a given weight are still ordered lexicographically.