diff --git a/qiskit/primitives/backend_estimator.py b/qiskit/primitives/backend_estimator.py index b217ff25665..f6a53c02ea9 100644 --- a/qiskit/primitives/backend_estimator.py +++ b/qiskit/primitives/backend_estimator.py @@ -9,9 +9,8 @@ # Any modifications or derivative works of this code must retain this # copyright notice, and modified files need to carry a notice indicating # that they have been altered from the originals. -""" -Expectation value class -""" + +"""Estimator V1 implementation for an arbitrary Backend object.""" from __future__ import annotations @@ -37,7 +36,7 @@ ) from qiskit.utils.deprecation import deprecate_func -from .base import BaseEstimator, EstimatorResult +from .base import BaseEstimatorV1, EstimatorResult from .primitive_job import PrimitiveJob from .utils import _circuit_key, _observable_key, init_observable @@ -89,23 +88,29 @@ def _prepare_counts(results: list[Result]): return counts -class BackendEstimator(BaseEstimator[PrimitiveJob[EstimatorResult]]): +class BackendEstimator(BaseEstimatorV1[PrimitiveJob[EstimatorResult]]): """Evaluates expectation value using Pauli rotation gates. The :class:`~.BackendEstimator` class is a generic implementation of the - :class:`~.BaseEstimator` interface that is used to wrap a :class:`~.BackendV2` - (or :class:`~.BackendV1`) object in the :class:`~.BaseEstimator` API. It + :class:`~.BaseEstimatorV1` interface that is used to wrap a :class:`~.BackendV2` + (or :class:`~.BackendV1`) object in the :class:`~.BaseEstimatorV1` API. It facilitates using backends that do not provide a native - :class:`~.BaseEstimator` implementation in places that work with - :class:`~.BaseEstimator`. However, - if you're using a provider that has a native implementation of - :class:`~.BaseEstimator`, it is a better choice to leverage that native - implementation as it will likely include additional optimizations and be - a more efficient implementation. The generic nature of this class - precludes doing any provider- or backend-specific optimizations. + :class:`~.BaseEstimatorV1` implementation in places that work with + :class:`~.BaseEstimatorV1`. + However, if you're using a provider that has a native implementation of + :class:`~.BaseEstimatorV1` or :class:`~.BaseEstimatorV2`, it is a better + choice to leverage that native implementation as it will likely include + additional optimizations and be a more efficient implementation. + The generic nature of this class precludes doing any provider- or + backend-specific optimizations. """ - @deprecate_func(since="1.2", additional_msg="Use BackendEstimatorV2 instead.") + @deprecate_func( + since="1.2", + additional_msg="All implementations of the `BaseEstimatorV1` interface " + "have been deprecated in favor of their V2 counterparts. " + "The V2 alternative for the `BackendEstimator` class is `BackendEstimatorV2`.", + ) def __init__( self, backend: BackendV1 | BackendV2, @@ -114,10 +119,10 @@ def __init__( bound_pass_manager: PassManager | None = None, skip_transpilation: bool = False, ): - """Initialize a new BackendEstimator instance + """Initialize a new BackendEstimator (V1) instance Args: - backend: Required: the backend to run the primitive on + backend: (required) the backend to run the primitive on options: Default options. abelian_grouping: Whether the observable should be grouped into commuting diff --git a/qiskit/primitives/backend_sampler.py b/qiskit/primitives/backend_sampler.py index 98592e079cb..213b9701a55 100644 --- a/qiskit/primitives/backend_sampler.py +++ b/qiskit/primitives/backend_sampler.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 implementation for an arbitrary Backend object.""" +"""Sampler V1 implementation for an arbitrary Backend object.""" from __future__ import annotations @@ -26,28 +26,34 @@ from qiskit.utils.deprecation import deprecate_func from .backend_estimator import _prepare_counts, _run_circuits -from .base import BaseSampler, SamplerResult +from .base import BaseSamplerV1, SamplerResult from .primitive_job import PrimitiveJob from .utils import _circuit_key -class BackendSampler(BaseSampler[PrimitiveJob[SamplerResult]]): - """A :class:`~.BaseSampler` implementation that provides an interface for - leveraging the sampler interface from any backend. +class BackendSampler(BaseSamplerV1[PrimitiveJob[SamplerResult]]): + """A :class:`~.BaseSamplerV1` implementation that provides a wrapper for + leveraging the Sampler V1 interface from any backend. This class provides a sampler interface from any backend and doesn't do any measurement mitigation, it just computes the probability distribution from the counts. It facilitates using backends that do not provide a - native :class:`~.BaseSampler` implementation in places that work with - :class:`~.BaseSampler`. + native :class:`~.BaseSamplerV1` implementation in places that work with + :class:`~.BaseSamplerV1`. However, if you're using a provider that has a native implementation of - :class:`~.BaseSampler`, it is a better choice to leverage that native - implementation as it will likely include additional optimizations and be - a more efficient implementation. The generic nature of this class - precludes doing any provider- or backend-specific optimizations. + :class:`~.BaseSamplerV1` or :class:`~.BaseESamplerV2`, it is a better + choice to leverage that native implementation as it will likely include + additional optimizations and be a more efficient implementation. + The generic nature of this class precludes doing any provider- or + backend-specific optimizations. """ - @deprecate_func(since="1.2", additional_msg="Use BackendSamplerV2 instead.") + @deprecate_func( + since="1.2", + additional_msg="All implementations of the `BaseSamplerV1` interface " + "have been deprecated in favor of their V2 counterparts. " + "The V2 alternative for the `BackendSampler` class is `BackendSamplerV2`.", + ) def __init__( self, backend: BackendV1 | BackendV2, @@ -55,10 +61,10 @@ def __init__( bound_pass_manager: PassManager | None = None, skip_transpilation: bool = False, ): - """Initialize a new BackendSampler + """Initialize a new BackendSampler (V1) instance Args: - backend: Required: the backend to run the sampler primitive on + backend: (required) the backend to run the sampler primitive on options: Default options. bound_pass_manager: An optional pass manager to run after parameter binding. diff --git a/qiskit/primitives/base/base_estimator.py b/qiskit/primitives/base/base_estimator.py index 33ec40300b2..d3d364f9951 100644 --- 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. -"""Base Estimator Classes""" +"""Base Estimator V1 and V2 classes""" from __future__ import annotations @@ -110,7 +110,7 @@ def __init__( options: dict | None = None, ): """ - Creating an instance of an Estimator, or using one in a ``with`` context opens a session that + Creating an instance of an Estimator V1, 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: @@ -189,12 +189,19 @@ def _run( class BaseEstimator(BaseEstimatorV1[T]): - """DEPRECATED. Type alias of Estimator V1 base class. + """DEPRECATED. Type alias for Estimator V1 base class. See :class:`.BaseEstimatorV1` for details. """ - @deprecate_func(since="1.2", additional_msg="Use BaseEstimatorV2 instead.") + @deprecate_func( + since="1.2", + additional_msg="The `BaseEstimator` class is a type alias for the `BaseEstimatorV1` " + "interface that has been deprecated in favor of explicitly versioned interface classes. " + "It is recommended to migrate all implementations to use `BaseEstimatorV2`. " + "However, for implementations incompatible with `BaseEstimatorV2`, `BaseEstimator` can " + "be replaced with the explicitly versioned `BaseEstimatorV1` class.", + ) def __init__( self, *, diff --git a/qiskit/primitives/base/base_sampler.py b/qiskit/primitives/base/base_sampler.py index 81a1754ae35..65d87d86b07 100644 --- a/qiskit/primitives/base/base_sampler.py +++ b/qiskit/primitives/base/base_sampler.py @@ -10,7 +10,7 @@ # copyright notice, and modified files need to carry a notice indicating # that they have been altered from the originals. -"""Base Sampler Classes""" +"""Base Sampler V1 and V2 classes""" from __future__ import annotations @@ -152,12 +152,19 @@ def _run( class BaseSampler(BaseSamplerV1[T]): - """DEPRECATED. Type alias of Sampler V1 base class + """DEPRECATED. Type alias for Sampler V1 base class See :class:`.BaseSamplerV1` for details. """ - @deprecate_func(since="1.2", additional_msg="Use BaseSamplerV2 instead.") + @deprecate_func( + since="1.2", + additional_msg="The `BaseSampler` class is a type alias for the `BaseSamplerV1` " + "interface that has been deprecated in favor of explicitly versioned interface classes. " + "It is recommended to migrate all implementations to use `BaseSamplerV2`. " + "However, for implementations incompatible with `BaseSamplerV2`, `BaseSampler` can " + "be replaced with the explicitly versioned `BaseSamplerV1` class.", + ) def __init__( self, *, diff --git a/qiskit/primitives/estimator.py b/qiskit/primitives/estimator.py index 874b631379b..1ca1529852c 100644 --- a/qiskit/primitives/estimator.py +++ b/qiskit/primitives/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. """ -Estimator class +Estimator V1 reference implementation """ from __future__ import annotations @@ -26,7 +26,7 @@ from qiskit.quantum_info.operators.base_operator import BaseOperator from qiskit.utils.deprecation import deprecate_func -from .base import BaseEstimator, EstimatorResult +from .base import BaseEstimatorV1, EstimatorResult from .primitive_job import PrimitiveJob from .utils import ( _circuit_key, @@ -36,9 +36,9 @@ ) -class Estimator(BaseEstimator[PrimitiveJob[EstimatorResult]]): +class Estimator(BaseEstimatorV1[PrimitiveJob[EstimatorResult]]): """ - Reference implementation of :class:`BaseEstimator`. + Reference implementation of :class:`BaseEstimatorV1`. :Run Options: @@ -52,7 +52,12 @@ class Estimator(BaseEstimator[PrimitiveJob[EstimatorResult]]): this option is ignored. """ - @deprecate_func(since="1.2", additional_msg="Use StatevectorEstimator instead.") + @deprecate_func( + since="1.2", + additional_msg="All implementations of the `BaseEstimatorV1` interface " + "have been deprecated in favor of their V2 counterparts. " + "The V2 alternative for the `Estimator` class is `StatevectorEstimator`.", + ) def __init__(self, *, options: dict | None = None): """ Args: diff --git a/qiskit/primitives/primitive_job.py b/qiskit/primitives/primitive_job.py index 5dddda27d98..64ab8d01609 100644 --- a/qiskit/primitives/primitive_job.py +++ b/qiskit/primitives/primitive_job.py @@ -10,7 +10,7 @@ # copyright notice, and modified files need to carry a notice indicating # that they have been altered from the originals. """ -Job implementation for the reference implementations of Primitives. +Job for the reference implementations of Primitives V1 and V2. """ import uuid diff --git a/qiskit/primitives/sampler.py b/qiskit/primitives/sampler.py index da0b4ed4d00..d93db4f0411 100644 --- a/qiskit/primitives/sampler.py +++ b/qiskit/primitives/sampler.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 class +Sampler V1 reference implementation """ from __future__ import annotations @@ -26,7 +26,7 @@ from qiskit.result import QuasiDistribution from qiskit.utils.deprecation import deprecate_func -from .base import BaseSampler, SamplerResult +from .base import BaseSamplerV1, SamplerResult from .primitive_job import PrimitiveJob from .utils import ( _circuit_key, @@ -36,11 +36,11 @@ ) -class Sampler(BaseSampler[PrimitiveJob[SamplerResult]]): +class Sampler(BaseSamplerV1[PrimitiveJob[SamplerResult]]): """ - Sampler class. + Sampler V1 class. - :class:`~Sampler` is a reference implementation of :class:`~BaseSampler`. + :class:`~Sampler` is a reference implementation of :class:`~BaseSamplerV1`. :Run Options: @@ -53,7 +53,12 @@ class Sampler(BaseSampler[PrimitiveJob[SamplerResult]]): option is ignored. """ - @deprecate_func(since="1.2", additional_msg="Use StatevectorSampler instead.") + @deprecate_func( + since="1.2", + additional_msg="All implementations of the `BaseSamplerV1` interface " + "have been deprecated in favor of their V2 counterparts. " + "The V2 alternative for the `Sampler` class is `StatevectorSampler`.", + ) def __init__(self, *, options: dict | None = None): """ Args: diff --git a/qiskit/primitives/statevector_estimator.py b/qiskit/primitives/statevector_estimator.py index a5dc029edf7..722291bcf42 100644 --- a/qiskit/primitives/statevector_estimator.py +++ b/qiskit/primitives/statevector_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. """ -Estimator class +Statevector Estimator V2 class """ from __future__ import annotations diff --git a/qiskit/primitives/statevector_sampler.py b/qiskit/primitives/statevector_sampler.py index 90fe452ad12..7488faa284d 100644 --- a/qiskit/primitives/statevector_sampler.py +++ b/qiskit/primitives/statevector_sampler.py @@ -10,7 +10,7 @@ # copyright notice, and modified files need to carry a notice indicating # that they have been altered from the originals. """ -Statevector Sampler class +Statevector Sampler V2 class """ from __future__ import annotations diff --git a/releasenotes/notes/deprecate-primitives-v1.yaml b/releasenotes/notes/deprecate-primitives-v1.yaml index 9526c12d6ec..3d0335d358c 100644 --- a/releasenotes/notes/deprecate-primitives-v1.yaml +++ b/releasenotes/notes/deprecate-primitives-v1.yaml @@ -1,17 +1,23 @@ --- deprecations_primitives: - | - Primitives V1 is now deprecated and will be removed in no less than 3 months from the release date. + Primitive V1 implementations and V1-exclusive non-versioned type aliases are now + deprecated in favor of their V2 counterparts. The deprecation is extended to the + following classes implementing V1 interfaces: - The following Primitives V1 classes are deprecated: + * :class:`.Estimator`, in favor of the V2 equivalent, :class:`.StatevectorEstimator` + * :class:`.Sampler`, in favor of the V2 equivalent, :class:`.StatevectorSampler` + * :class:`.BackendEstimator`, in favor of the V2 equivalent, :class:`.BackendEstimatorV2` + * :class:`.BackendSampler`, in favor of the V2 equivalent, :class:`.BackendSamplerV2` - * :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, + As well as the following non-versioned type aliases: + + * :class:`.BaseEstimator`, alias for :class:`.BaseEstimatorV1` + * :class:`.BaseSampler`, alias for :class:`.BaseSamplerV1` + This deprecation does NOT affect the explicitly-versioned :class:`BaseEstimatorV1` + and :class:`BaseSamplerV1` abstract + interface definitions or related result and job classes. In addition, the following utility functions are deprecated: