some phrasing in the migration guides (#10083)

* some phrasing in the migration guides * more changes * Update docs/migration_guides/algorithms_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * Update docs/migration_guides/qi_migration.rst Co-authored-by: Abby Mitchell <[email protected]> * rephrase a description for BackendEstimator and BackendSampler * redo intro to qi_migration * readjust opflow * Update docs/migration_guides/algorithms_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * Update docs/migration_guides/qi_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * Update docs/migration_guides/qi_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * algorithm pass * Update docs/migration_guides/qi_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * Update docs/migration_guides/qi_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * Update docs/migration_guides/qi_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * Update docs/migration_guides/qi_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * Update docs/migration_guides/algorithms_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * Update docs/migration_guides/opflow_migration.rst Co-authored-by: Elena Peña Tapia <[email protected]> * services with native primitive implementations * typo --------- Co-authored-by: Elena Peña Tapia <[email protected]> Co-authored-by: Abby Mitchell <[email protected]>
Qiskit · May 30, 2023 · 291824a · 291824a
1 parent 4762e26
commit 291824a
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 32 deletions.
diff --git a/docs/migration_guides/algorithms_migration.rst b/docs/migration_guides/algorithms_migration.rst
@@ -74,15 +74,17 @@ How to choose a primitive configuration for your algorithm
 
 *Back to* `TL;DR`_
 
-The classes in :mod:`qiskit.algorithms` state the base class primitive type (``Sampler``/``Estimator``)
-they require for their initialization. Once the primitive type is known, you can choose between
-four different primitive implementations, depending on how you want to configure your execution:
+The classes in
+:mod:`qiskit.algorithms` are initialized with any implementation of :class:`qiskit.primitive.BaseSampler` or class:`qiskit.primitive.BaseEstimator`.
 
-    a. Using **local** statevector simulators for quick prototyping: **Reference Primitives** in :mod:`qiskit.primitives`
-    b. Using **local** Aer simulators for finer algorithm tuning: **Aer Primitives** in :mod:`qiskit_aer.primitives`
-    c. Accessing backends using the **Qiskit Runtime Service**: **Runtime Primitives** in :mod:`qiskit_ibm_runtime`
-    d. Accessing backends using a **non-Runtime-enabled provider**: **Backend Primitives** in :mod:`qiskit.primitives`
+Once the kind of primitive is known, you can choose between the primitive implementations that better adjust to your case. For example:
 
+    a. For quick prototyping, you can use the **reference implementations of primitives** included in Qiskit: :class:`qiskit.primitives.Sampler` and :class:`qiskit.primitives.Estimator`.
+    b. For finer algorithm tuning, a local simulator such as the **primitive implementation in Aer**: :class:`qiskit_aer.primitives.Sampler` and :class:`qiskit_aer.primitives.Estimator`.
+    c. For executing in quantum hardware you can:
+
+       * access services with native primitive implementations, such as **IBM's Qiskit Runtime service** via :class:`qiskit_ibm_runtime.Sampler` and :class:`qiskit_ibm_runtime.Estimator`
+       * Wrap any backend with **Backend Primitives** (:class:`~qiskit.primitives.BackendSampler` and :class:`~qiskit.primitives.BackendEstimator`). These wrappers implement a primitive interface on top of a backend that only supports ``Backend.run()``.
 
 For more detailed information and examples, particularly on the use of the **Backend Primitives**, please refer to
 the `Quantum Instance migration guide <https://qisk.it/qi_migration>`_.
@@ -133,7 +135,7 @@ In this guide, we will cover 3 different common configurations for algorithms th
 
             from qiskit_aer.primitives import Sampler, Estimator
 
-        - Runtime Primitives with default configuration (see `VQD`_ example):
+        - IBM's Qiskit Runtime Primitives with default configuration (see `VQD`_ example):
 
         .. code-block:: python
 
@@ -249,7 +251,7 @@ The legacy :class:`qiskit.algorithms.minimum_eigen_solvers.VQE` class has now be
 
     .. testcode::
 
-        from qiskit.algorithms.minimum_eigensolvers import VQE # new import!!!
+        from qiskit.algorithms.minimum_eigensolvers import VQE  # new import!!!
         from qiskit.algorithms.optimizers import SPSA
         from qiskit.circuit.library import TwoLocal
         from qiskit.quantum_info import SparsePauliOp

diff --git a/docs/migration_guides/opflow_migration.rst b/docs/migration_guides/opflow_migration.rst
@@ -21,11 +21,8 @@ the :mod:`~qiskit.opflow` module to the :mod:`~qiskit.primitives` and :mod:`~qis
 ..  attention::
 
     Most references to the :class:`qiskit.primitives.Sampler` or :class:`qiskit.primitives.Estimator` in this guide
-    can be replaced with instances of the:
-
-    - Aer primitives (:class:`qiskit_aer.primitives.Sampler`, :class:`qiskit_aer.primitives.Estimator`)
-    - Runtime primitives (:class:`qiskit_ibm_runtime.Sampler`, :class:`qiskit_ibm_runtime.Estimator`)
-    - Terra backend primitives (:class:`qiskit.primitives.BackendSampler`, :class:`qiskit.primitives.BackendEstimator`)
+    can be replaced with instances of any primitive implementation. For example Aer primitives (:class:`qiskit_aer.primitives.Sampler`/:class:`qiskit_aer.primitives.Estimator`) or IBM's Qiskit Runtime primitives (:class:`qiskit_ibm_runtime.Sampler`/:class:`qiskit_ibm_runtime.Estimator`).
+    Specific backends can be wrapped with (:class:`qiskit.primitives.BackendSampler`, :class:`qiskit.primitives.BackendEstimator`) to also present primitive-compatible interfaces.
 
     Certain classes, such as the
     :class:`~qiskit.opflow.expectations.AerPauliExpectation`, can only be replaced by a specific primitive instance

diff --git a/docs/migration_guides/qi_migration.rst b/docs/migration_guides/qi_migration.rst
@@ -50,20 +50,23 @@ Contents
     The Qiskit Primitives are algorithmic abstractions that encapsulate the access to backends or simulators
     for an easy integration into algorithm workflows.
 
-    The current pool of primitives includes **two** different **classes** (:class:`~qiskit.primitives.Sampler` and
-    :class:`~qiskit.primitives.Estimator`) that can be imported from **three** different locations (
-    :mod:`qiskit.primitives`, :mod:`qiskit_aer.primitives` and :mod:`qiskit_ibm_runtime` ). In addition to the
-    reference Sampler and Estimator, :mod:`qiskit.primitives` also contains a
-    :class:`~qiskit.primitives.BackendSampler` and a :class:`~qiskit.primitives.BackendEstimator` class. These are
+    The current pool of primitives includes **two** different types of primitives: Sampler and
+    Estimator.
+
+    Qiskit provides reference implementations in :class:`qiskit.primitives.Sampler` and :class:`qiskit.primitives.Estimator`. Additionally,
+    :class:`qiskit.primitives.BackendSampler` and a :class:`qiskit.primitives.BackendEstimator` are
     wrappers for ``backend.run()`` that follow the primitives interface.
 
-    This guide uses the following naming standard to refer to the primitives:
+    Providers can implement these primitives as subclasses of :class:`~qiskit.primitives.BaseSampler` and :class:`~qiskit.primitives.BaseEstimator` respectively.
+    IBM's Qiskit Runtime (:mod:`qiskit_ibm_runtime`) and Aer (:mod:`qiskit_aer.primitives`) are examples of native implementations of primitives.
+
+    This guide uses the following naming convention:
 
-    - *Primitives* - Any Sampler/Estimator implementation
-    - *Reference Primitives* - The Sampler and Estimator in :mod:`qiskit.primitives` --> ``from qiskit.primitives import Sampler/Estimator``
-    - *Aer Primitives* - The Sampler and Estimator in :mod:`qiskit_aer.primitives` --> ``from qiskit_aer.primitives import Sampler/Estimator``
-    - *Runtime Primitives* - The Sampler and Estimator in :mod:`qiskit_ibm_runtime` --> ``from qiskit_ibm_runtime import Sampler/Estimator``
-    - *Backend Primitives* - The BackendSampler and BackendEstimator in :mod:`qiskit.primitives` --> ``from qiskit import BackendSampler/BackendEstimator``
+    - *Primitives* - Any Sampler/Estimator implementation using base classes :class:`qiskit.primitives.BackendSampler` and a :class:`qiskit.primitives.BackendEstimator`.
+    - *Reference Primitives* -  :class:`qiskit.primitives.Sampler` and :class:`qiskit.primitives.Estimator` are reference implementations that come with Qiskit.
+    - *Aer Primitives* - The `Aer <https://qiskit.org/ecosystem/aer>`_ primitive implementations: class:`qiskit_aer.primitives.Sampler` and :class:`qiskit_aer.primitives.Estimator`.
+    - *Qiskit Runtime Primitives* - IBM's Qiskit Runtime primitive implementations: class:`qiskit_ibm_runtime.Sampler` and :class:`qiskit_ibm_runtime.Estimator`.
+    - *Backend Primitives* - Instances of :class:`qiskit.primitives.BackendSampler` and :class:`qiskit.primitives.BackendEstimator`. These allow any backend to implement primitive interfaces
 
     For guidelines on which primitives to choose for your task, please continue reading.
 
@@ -103,7 +106,7 @@ yourself two questions:
 
     a. Using **local** statevector simulators for quick prototyping: **Reference Primitives**
     b. Using **local** noisy simulations for finer algorithm tuning: **Aer Primitives**
-    c. Accessing **runtime-enabled backends** (or cloud simulators): **Runtime Primitives**
+    c. Accessing **runtime-enabled backends** (or cloud simulators): **Qiskit Runtime Primitives**
     d. Accessing **non runtime-enabled backends** : **Backend Primitives**
 
 Arguably, the ``Sampler`` is the closest primitive to :class:`~qiskit.utils.QuantumInstance`, as they
@@ -136,7 +139,7 @@ primitives **expose a similar setting through their interface**:
    * - QuantumInstance
      - Reference Primitives
      - Aer Primitives
-     - Runtime Primitives
+     - Qiskit Runtime Primitives
      - Backend Primitives
    * - Select ``backend``
      - No
@@ -186,7 +189,7 @@ primitives **expose a similar setting through their interface**:
      - No
 
 
-(*) For more information on error mitigation and setting options on Runtime Primitives, visit
+(*) For more information on error mitigation and setting options on Qiskit Runtime Primitives, visit
 `this link <https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.options.Options.html#qiskit_ibm_runtime.options.Options>`_.
 
 (**) For more information on Runtime sessions, visit `this how-to <https://qiskit.org/documentation/partners/qiskit_ibm_runtime/how_to/run_session.html>`_.
@@ -447,12 +450,12 @@ Code examples
 
     **Using Primitives**
 
-    The Runtime Primitives offer a suite of error mitigation methods that can be easily turned on with the
+    The Qiskit Runtime Primitives offer a suite of error mitigation methods that can be easily turned on with the
     ``resilience_level`` option. These are, however, not configurable. The sampler's ``resilience_level=1``
     is the closest alternative to the Quantum Instance's measurement error mitigation implementation, but this
     is not a 1-1 replacement.
 
-    For more information on the error mitigation options in the Runtime Primitives, you can check out the following
+    For more information on the error mitigation options in the Qiskit Runtime Primitives, you can check out the following
     `link <https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.options.Options.html#qiskit_ibm_runtime.options.Options>`_.
 
     .. code-block:: python
@@ -503,7 +506,7 @@ Code examples
     * You cannot explicitly access their transpilation routine.
     * The mechanism to apply custom transpilation passes to the Aer, Runtime and Backend primitives is to pre-transpile
       locally and set ``skip_transpilation=True`` in the corresponding primitive.
-    * The only primitives that currently accept a custom **bound** transpiler pass manager are the **Backend Primitives**.
+    * The only primitives that currently accept a custom **bound** transpiler pass manager are instances of :class:`~qiskit.primitives.BackendSampler` or :class:`~qiskit.primitives.BackendEstimator`.
       If a ``bound_pass_manager`` is defined, the ``skip_transpilation=True`` option will **not** skip this bound pass.
 
     .. attention::
@@ -518,7 +521,7 @@ Code examples
         so if the circuit ended up on more qubits it did not matter.
 
     Note that the primitives **do** handle parameter bindings, meaning that even if a ``bound_pass_manager`` is defined in a
-    Backend Primitive, you do not have to manually assign parameters as expected in the Quantum Instance workflow.
+    :class:`~qiskit.primitives.BackendSampler` or :class:`~qiskit.primitives.BackendEstimator`, you do not have to manually assign parameters as expected in the Quantum Instance workflow.
 
     The use-case that motivated the addition of the two-stage transpilation to the ``QuantumInstance`` was to allow
     running pulse-efficient transpilation passes with the :class:`~qiskit.opflow.CircuitSampler` class. The following