Deprecate V1 Primitives and their utils (#12575)

* Deprecate V1 Primitives and their utils * Fix tests * Fix yaml error * Fix build * Fix error after mc * Fix error after mc * Apply comments * Use correct deprecate version for warning message * Update deprecation messages * Add missed `` * update releasenote * Deprecate SamplerResult and EstimatorResult * fix deprecation warning for SamplerResult and EstimatorResult * apply review comments Co-authored-by: Matthew Treinish <[email protected]> Co-authored-by: Elena Peña Tapia <[email protected]> * Applying the agreement of deprecations. - Revert BaseSamplerV1 and BaseEstimatorV1 - Deprecate BaseSampler and BaseEstimator #12497 (comment) * revert SamplerResult, EstimatorResult, and BasePrimitiveResult * fix test_backend_sampler * revert tox.ini * revise deprecation warning for BaseSampler and BaseEstimator * update reno * revert BaseSampler and BaseEstimator --------- Co-authored-by: Takashi Imamichi <[email protected]> Co-authored-by: Takashi Imamichi <[email protected]> Co-authored-by: Matthew Treinish <[email protected]> Co-authored-by: Elena Peña Tapia <[email protected]>
Qiskit · Jul 25, 2024 · 250acc3 · 250acc3
1 parent 6ce5250
commit 250acc3
Show file tree

Hide file tree

Showing 19 changed files with 540 additions and 326 deletions.
diff --git a/qiskit/primitives/backend_estimator.py b/qiskit/primitives/backend_estimator.py
@@ -35,6 +35,7 @@
     Optimize1qGatesDecomposition,
     SetLayout,
 )
+from qiskit.utils.deprecation import deprecate_func
 
 from .base import BaseEstimator, EstimatorResult
 from .primitive_job import PrimitiveJob
@@ -104,6 +105,7 @@ class BackendEstimator(BaseEstimator[PrimitiveJob[EstimatorResult]]):
     precludes doing any provider- or backend-specific optimizations.
     """
 
+    @deprecate_func(since="1.2", additional_msg="Use BackendEstimatorV2 instead.")
     def __init__(
         self,
         backend: BackendV1 | BackendV2,

diff --git a/qiskit/primitives/backend_sampler.py b/qiskit/primitives/backend_sampler.py
@@ -23,6 +23,7 @@
 from qiskit.providers.options import Options
 from qiskit.result import QuasiDistribution, Result
 from qiskit.transpiler.passmanager import PassManager
+from qiskit.utils.deprecation import deprecate_func
 
 from .backend_estimator import _prepare_counts, _run_circuits
 from .base import BaseSampler, SamplerResult
@@ -46,6 +47,7 @@ class BackendSampler(BaseSampler[PrimitiveJob[SamplerResult]]):
     precludes doing any provider- or backend-specific optimizations.
     """
 
+    @deprecate_func(since="1.2", additional_msg="Use BackendSamplerV2 instead.")
     def __init__(
         self,
         backend: BackendV1 | BackendV2,

diff --git a/qiskit/primitives/base/base_estimator.py b/qiskit/primitives/base/base_estimator.py
@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-r"""Base Estimator Classes"""
+"""Base Estimator Classes"""
 
 from __future__ import annotations
 
@@ -23,6 +23,7 @@
 from qiskit.providers import JobV1 as Job
 from qiskit.quantum_info.operators import SparsePauliOp
 from qiskit.quantum_info.operators.base_operator import BaseOperator
+from qiskit.utils.deprecation import deprecate_func
 
 from ..containers import (
     DataBin,
@@ -187,7 +188,26 @@ def _run(
         raise NotImplementedError("The subclass of BaseEstimator must implement `_run` method.")
 
 
-BaseEstimator = BaseEstimatorV1
+class BaseEstimator(BaseEstimatorV1[T]):
+    """DEPRECATED. Type alias of Estimator V1 base class.
+
+    See :class:`.BaseEstimatorV1` for details.
+    """
+
+    @deprecate_func(since="1.2", additional_msg="Use BaseEstimatorV2 instead.")
+    def __init__(
+        self,
+        *,
+        options: dict | None = None,
+    ):
+        """
+        Creating an instance of an Estimator, or using one in a ``with`` context opens a session that
+        holds resources until the instance is ``close()`` ed or the context is exited.
+
+        Args:
+            options: Default options.
+        """
+        super().__init__(options=options)
 
 
 class BaseEstimatorV2(ABC):

diff --git a/qiskit/primitives/base/base_primitive.py b/qiskit/primitives/base/base_primitive.py
@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-"""Primitive abstract base class."""
+"""Primitive V1 abstract base class."""
 
 from __future__ import annotations
 
@@ -20,7 +20,7 @@
 
 
 class BasePrimitive(ABC):
-    """Primitive abstract base class."""
+    """Primitive V1 abstract base class."""
 
     def __init__(self, options: dict | None = None):
         self._run_options = Options()

diff --git a/qiskit/primitives/base/base_result.py b/qiskit/primitives/base/base_result.py
@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-Primitive result abstract base class
+Primitive V1 result abstract base class
 """
 
 from __future__ import annotations
@@ -27,7 +27,7 @@
 
 class _BasePrimitiveResult(ABC):
     """
-    Base class for deprecated Primitive result methods.
+    Base class for deprecated Primitive V1 result methods.
     """
 
     def __post_init__(self) -> None:

diff --git a/qiskit/primitives/base/base_sampler.py b/qiskit/primitives/base/base_sampler.py
@@ -21,6 +21,7 @@
 
 from qiskit.circuit import QuantumCircuit
 from qiskit.providers import JobV1 as Job
+from qiskit.utils.deprecation import deprecate_func
 
 from ..containers.primitive_result import PrimitiveResult
 from ..containers.sampler_pub import SamplerPubLike
@@ -150,7 +151,23 @@ def _run(
         raise NotImplementedError("The subclass of BaseSampler must implement `_run` method.")
 
 
-BaseSampler = BaseSamplerV1
+class BaseSampler(BaseSamplerV1[T]):
+    """DEPRECATED. Type alias of Sampler V1 base class
+
+    See :class:`.BaseSamplerV1` for details.
+    """
+
+    @deprecate_func(since="1.2", additional_msg="Use BaseSamplerV2 instead.")
+    def __init__(
+        self,
+        *,
+        options: dict | None = None,
+    ):
+        """
+        Args:
+            options: Default options.
+        """
+        super().__init__(options=options)
 
 
 class BaseSamplerV2(ABC):

diff --git a/qiskit/primitives/base/estimator_result.py b/qiskit/primitives/base/estimator_result.py
@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-Estimator result class
+Estimator V1 result class
 """
 
 from __future__ import annotations
@@ -26,7 +26,7 @@
 
 @dataclass(frozen=True)
 class EstimatorResult(_BasePrimitiveResult):
-    """Result of Estimator.
+    """Result of Estimator V1.
 
     .. code-block:: python
 

diff --git a/qiskit/primitives/base/sampler_result.py b/qiskit/primitives/base/sampler_result.py
@@ -10,7 +10,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 """
-Sampler result class
+Sampler V1 result class
 """
 
 from __future__ import annotations
@@ -25,7 +25,7 @@
 
 @dataclass(frozen=True)
 class SamplerResult(_BasePrimitiveResult):
-    """Result of Sampler.
+    """Result of Sampler V1.
 
     .. code-block:: python
 

diff --git a/qiskit/primitives/estimator.py b/qiskit/primitives/estimator.py
@@ -24,6 +24,7 @@
 from qiskit.exceptions import QiskitError
 from qiskit.quantum_info import Statevector
 from qiskit.quantum_info.operators.base_operator import BaseOperator
+from qiskit.utils.deprecation import deprecate_func
 
 from .base import BaseEstimator, EstimatorResult
 from .primitive_job import PrimitiveJob
@@ -51,6 +52,7 @@ class Estimator(BaseEstimator[PrimitiveJob[EstimatorResult]]):
           this option is ignored.
     """
 
+    @deprecate_func(since="1.2", additional_msg="Use StatevectorEstimator instead.")
     def __init__(self, *, options: dict | None = None):
         """
         Args:

diff --git a/qiskit/primitives/sampler.py b/qiskit/primitives/sampler.py
@@ -24,6 +24,7 @@
 from qiskit.exceptions import QiskitError
 from qiskit.quantum_info import Statevector
 from qiskit.result import QuasiDistribution
+from qiskit.utils.deprecation import deprecate_func
 
 from .base import BaseSampler, SamplerResult
 from .primitive_job import PrimitiveJob
@@ -52,6 +53,7 @@ class Sampler(BaseSampler[PrimitiveJob[SamplerResult]]):
           option is ignored.
     """
 
+    @deprecate_func(since="1.2", additional_msg="Use StatevectorSampler instead.")
     def __init__(self, *, options: dict | None = None):
         """
         Args:

diff --git a/qiskit/primitives/utils.py b/qiskit/primitives/utils.py
@@ -25,8 +25,14 @@
 from qiskit.quantum_info import PauliList, SparsePauliOp, Statevector
 from qiskit.quantum_info.operators.base_operator import BaseOperator
 from qiskit.quantum_info.operators.symplectic.base_pauli import BasePauli
+from qiskit.utils.deprecation import deprecate_func
 
 
+@deprecate_func(
+    since="1.2",
+    additional_msg="To initialize a circuit from a ``Statevector`` instance, "
+    + "use ``QuantumCircuit.initialize`` instead.",
+)
 def init_circuit(state: QuantumCircuit | Statevector) -> QuantumCircuit:
     """Initialize state by converting the input to a quantum circuit.
 
@@ -45,6 +51,10 @@ def init_circuit(state: QuantumCircuit | Statevector) -> QuantumCircuit:
     return qc
 
 
+@deprecate_func(
+    since="1.2",
+    additional_msg="Use the constructor of ``SparsePauliOp`` instead.",
+)
 def init_observable(observable: BaseOperator | str) -> SparsePauliOp:
     """Initialize observable by converting the input to a :class:`~qiskit.quantum_info.SparsePauliOp`.
 
@@ -68,6 +78,12 @@ def init_observable(observable: BaseOperator | str) -> SparsePauliOp:
         return SparsePauliOp(observable)
 
 
+@deprecate_func(
+    since="1.2",
+    additional_msg="Use ``QuantumCircuit.layout`` and ``SparsePauliOp.apply_layout`` "
+    + "to adjust an operator for a layout. Otherwise, use ``mthree.utils.final_measurement_mapping``. "
+    + "See https://qiskit-extensions.github.io/mthree/apidocs/utils.html for details.",
+)
 def final_measurement_mapping(circuit: QuantumCircuit) -> dict[int, int]:
     """Return the final measurement mapping for the circuit.
 

diff --git a/releasenotes/notes/deprecate-primitives-v1.yaml b/releasenotes/notes/deprecate-primitives-v1.yaml
@@ -0,0 +1,26 @@
+---
+deprecations_primitives:
+  - |
+    Primitives V1 is now deprecated and will be removed in no less than 3 months from the release date.
+
+    The following Primitives V1 classes are deprecated:
+
+    * :class:`.BaseEstimator`, use :class:`.BaseEstimatorV2` instead,
+    * :class:`.BaseSampler`, use :class:`.BaseSamplerV2` instead,
+    * :class:`.Estimator`, use :class:`.StatevectorEstimator` instead,
+    * :class:`.Sampler`, use :class:`.StatevectorSampler` instead,
+    * :class:`.BackendEstimator`, use :class:`.BackendEstimatorV2` instead,
+    * :class:`.BackendSampler`, use :class:`.BackendSamplerV2` instead,
+
+
+    In addition, the following utility functions are deprecated:
+
+    * :func:`.init_circuit`, to initialize a circuit from a :class:`.Statevector`,
+      use :meth:`.QuantumCircuit.initialize` instead,
+    * :func:`.init_observable`, use the constructor of :class:`.SparsePauliOp` instead,
+    * :func:`.final_measurement_mapping`, use :meth:`.QuantumCircuit.layout` and
+      :meth:`.SparsePauliOp.apply_layout` to adjust an operator for a layout.
+      Otherwise, use ``mthree.utils.final_measurement_mapping``.
+      See `Mthree Utility functions <https://qiskit-extensions.github.io/mthree/apidocs/utils.html>`__
+      for details.
+