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 <mtreinish@kortar.org>
Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com>

* 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 <imamichi@jp.ibm.com>
Co-authored-by: Takashi Imamichi <31178928+t-imamichi@users.noreply.github.com>
Co-authored-by: Matthew Treinish <mtreinish@kortar.org>
Co-authored-by: Elena Peña Tapia <57907331+ElePT@users.noreply.github.com>

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,

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,

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):

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()

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:

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):

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
 

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
 

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:

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:

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.
 

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.
+