qiskit 1.1.2__cp38-abi3-macosx_10_9_universal2.whl → 1.2.0__cp38-abi3-macosx_10_9_universal2.whl

qiskit/primitives/backend_sampler_v2.py

@@ -155,7 +155,7 @@ class BackendSamplerV2(BaseSamplerV2):
             # reconstruct the result of pubs
             for i, pub_result in zip(lst, pub_results):
                 results[i] = pub_result
-        return PrimitiveResult(results)
+        return PrimitiveResult(results, metadata={"version": 2})
 
     def _run_pubs(self, pubs: list[SamplerPub], shots: int) -> list[SamplerPubResult]:
         """Compute results for pubs that all require the same value of ``shots``."""
@@ -183,7 +183,12 @@ class BackendSamplerV2(BaseSamplerV2):
             end = start + bound.size
             results.append(
                 self._postprocess_pub(
-                    result_memory[start:end], shots, bound.shape, meas_info, max_num_bytes
+                    result_memory[start:end],
+                    shots,
+                    bound.shape,
+                    meas_info,
+                    max_num_bytes,
+                    pub.circuit.metadata,
                 )
             )
             start = end
@@ -197,6 +202,7 @@ class BackendSamplerV2(BaseSamplerV2):
         shape: tuple[int, ...],
         meas_info: list[_MeasureInfo],
         max_num_bytes: int,
+        circuit_metadata: dict,
     ) -> SamplerPubResult:
         """Converts the memory data into an array of bit arrays with the shape of the pub."""
         arrays = {
@@ -213,7 +219,10 @@ class BackendSamplerV2(BaseSamplerV2):
         meas = {
             item.creg_name: BitArray(arrays[item.creg_name], item.num_bits) for item in meas_info
         }
-        return SamplerPubResult(DataBin(**meas, shape=shape), metadata={})
+        return SamplerPubResult(
+            DataBin(**meas, shape=shape),
+            metadata={"shots": shots, "circuit_metadata": circuit_metadata},
+        )
 
 
 def _analyze_circuit(circuit: QuantumCircuit) -> tuple[list[_MeasureInfo], int]:

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 V1 and V2 classes"""
 
 from __future__ import annotations
 
@@ -23,6 +23,7 @@ from qiskit.circuit import QuantumCircuit
 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,
@@ -109,7 +110,7 @@ class BaseEstimatorV1(BasePrimitive, Generic[T]):
         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:
@@ -187,7 +188,33 @@ class BaseEstimatorV1(BasePrimitive, Generic[T]):
         raise NotImplementedError("The subclass of BaseEstimator must implement `_run` method.")
 
 
-BaseEstimator = BaseEstimatorV1
+class BaseEstimator(BaseEstimatorV1[T]):
+    """DEPRECATED. Type alias for Estimator V1 base class.
+
+    See :class:`.BaseEstimatorV1` for details.
+    """
+
+    @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,
+        *,
+        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):
@@ -203,7 +230,7 @@ class BaseEstimatorV2(ABC):
 
     @staticmethod
     def _make_data_bin(_: EstimatorPub) -> type[DataBin]:
-        # this method is present for backwards compat. new primitive implementatinos
+        # this method is present for backwards compat. new primitive implementations
         # should avoid it.
         return DataBin
 

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 @@ from qiskit.providers import Options
 
 
 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 @@ ExperimentData = Dict[str, Any]
 
 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

@@ -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
 
@@ -21,6 +21,7 @@ from typing import Generic, TypeVar
 
 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,30 @@ class BaseSamplerV1(BasePrimitive, Generic[T]):
         raise NotImplementedError("The subclass of BaseSampler must implement `_run` method.")
 
 
-BaseSampler = BaseSamplerV1
+class BaseSampler(BaseSamplerV1[T]):
+    """DEPRECATED. Type alias for Sampler V1 base class
+
+    See :class:`.BaseSamplerV1` for details.
+    """
+
+    @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,
+        *,
+        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 @@ if TYPE_CHECKING:
 
 @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 @@ from .base_result import _BasePrimitiveResult
 
 @dataclass(frozen=True)
 class SamplerResult(_BasePrimitiveResult):
-    """Result of Sampler.
+    """Result of Sampler V1.
 
     .. code-block:: python
 

qiskit/primitives/containers/__init__.py

@@ -24,4 +24,3 @@ from .primitive_result import PrimitiveResult
 from .pub_result import PubResult
 from .sampler_pub import SamplerPubLike
 from .sampler_pub_result import SamplerPubResult
-from .shape import Shaped

qiskit/primitives/containers/bindings_array.py

@@ -95,7 +95,7 @@ class BindingsArray(ShapedMixin):
         be inferred from the provided arrays. Ambiguity arises whenever the key of an entry of
         ``data`` contains only one parameter and the corresponding array's shape ends in a one.
         In this case, it can't be decided whether that one is an index over parameters, or whether
-        it should be encorporated in :attr:`~shape`.
+        it should be incorporated in :attr:`~shape`.
 
         Since :class:`~.Parameter` objects are only allowed to represent float values, this
         class casts all given values to float. If an incompatible dtype is given, such as complex
@@ -131,7 +131,7 @@ class BindingsArray(ShapedMixin):
 
     def __getitem__(self, args) -> BindingsArray:
         # because the parameters live on the last axis, we don't need to do anything special to
-        # accomodate them because there will always be an implicit slice(None, None, None)
+        # accommodate them because there will always be an implicit slice(None, None, None)
         # on all unspecified trailing dimensions
         # separately, we choose to not disallow args which touch the last dimension, even though it
         # would not be a particularly friendly way to chop parameters

qiskit/primitives/containers/bit_array.py

@@ -130,11 +130,15 @@ class BitArray(ShapedMixin):
         return f"BitArray({desc})"
 
     def __getitem__(self, indices):
-        """Slices the array along an existing axis of the array."""
-        if isinstance(indices, tuple) and len(indices) >= self.ndim + 2:
-            raise ValueError(
-                "BitArrays cannot be sliced along the bits axis, see slice_bits() instead."
-            )
+        if isinstance(indices, tuple):
+            if len(indices) == self.ndim + 1:
+                raise IndexError(
+                    "BitArray cannot be sliced along the shots axis, use slice_shots() instead."
+                )
+            if len(indices) >= self.ndim + 2:
+                raise IndexError(
+                    "BitArray cannot be sliced along the bits axis, use slice_bits() instead."
+                )
         return BitArray(self._array[indices], self.num_bits)
 
     @property
@@ -208,7 +212,10 @@ class BitArray(ShapedMixin):
         if order == "little":
             # np.unpackbits assumes "big"
             array = array[..., ::-1]
-
+        elif order != "big":
+            raise ValueError(
+                f"unknown value for order: '{order}'. Valid values are 'big' and 'little'."
+            )
         num_bits = array.shape[-1]
         if remainder := (-num_bits) % 8:
             # unpackbits pads with zeros on the wrong side with respect to what we want, so
@@ -428,13 +435,13 @@ class BitArray(ShapedMixin):
             A bit array sliced along the bit axis.
 
         Raises:
-            ValueError: If there are any invalid indices of the bit axis.
+            IndexError: If there are any invalid indices of the bit axis.
         """
         if isinstance(indices, int):
             indices = (indices,)
         for index in indices:
             if index < 0 or index >= self.num_bits:
-                raise ValueError(
+                raise IndexError(
                     f"index {index} is out of bounds for the number of bits {self.num_bits}."
                 )
         # This implementation introduces a temporary 8x memory overhead due to bit
@@ -455,19 +462,110 @@ class BitArray(ShapedMixin):
             A bit array sliced along the shots axis.
 
         Raises:
-            ValueError: If there are any invalid indices of the shots axis.
+            IndexError: If there are any invalid indices of the shots axis.
         """
         if isinstance(indices, int):
             indices = (indices,)
         for index in indices:
             if index < 0 or index >= self.num_shots:
-                raise ValueError(
+                raise IndexError(
                     f"index {index} is out of bounds for the number of shots {self.num_shots}."
                 )
         arr = self._array
         arr = arr[..., indices, :]
         return BitArray(arr, self.num_bits)
 
+    def postselect(
+        self,
+        indices: Sequence[int] | int,
+        selection: Sequence[bool | int] | bool | int,
+    ) -> BitArray:
+        """Post-select this bit array based on sliced equality with a given bitstring.
+
+        .. note::
+            If this bit array contains any shape axes, it is first flattened into a long list of shots
+            before applying post-selection. This is done because :class:`~BitArray` cannot handle
+            ragged numbers of shots across axes.
+
+        Args:
+            indices: A list of the indices of the cbits on which to postselect.
+                If this bit array was produced by a sampler, then an index ``i`` corresponds to the
+                :class:`~.ClassicalRegister` location ``creg[i]`` (as in :meth:`~slice_bits`).
+                Negative indices are allowed.
+
+            selection: A list of binary values (will be cast to ``bool``) of length matching
+                ``indices``, with ``indices[i]`` corresponding to ``selection[i]``. Shots will be
+                discarded unless all cbits specified by ``indices`` have the values given by
+                ``selection``.
+
+        Returns:
+            A new bit array with ``shape=(), num_bits=data.num_bits, num_shots<=data.num_shots``.
+
+        Raises:
+            IndexError: If ``max(indices)`` is greater than or equal to :attr:`num_bits`.
+            IndexError: If ``min(indices)`` is less than negative :attr:`num_bits`.
+            ValueError: If the lengths of ``selection`` and ``indices`` do not match.
+        """
+        if isinstance(indices, int):
+            indices = (indices,)
+        if isinstance(selection, (bool, int)):
+            selection = (selection,)
+        selection = np.asarray(selection, dtype=bool)
+
+        num_indices = len(indices)
+
+        if len(selection) != num_indices:
+            raise ValueError("Lengths of indices and selection do not match.")
+
+        num_bytes = self._array.shape[-1]
+        indices = np.asarray(indices)
+
+        if num_indices > 0:
+            if indices.max() >= self.num_bits:
+                raise IndexError(
+                    f"index {int(indices.max())} out of bounds for the number of bits {self.num_bits}."
+                )
+            if indices.min() < -self.num_bits:
+                raise IndexError(
+                    f"index {int(indices.min())} out of bounds for the number of bits {self.num_bits}."
+                )
+
+        flattened = self.reshape((), self.size * self.num_shots)
+
+        # If no conditions, keep all data, but flatten as promised:
+        if num_indices == 0:
+            return flattened
+
+        # Make negative bit indices positive:
+        indices %= self.num_bits
+
+        # Handle special-case of contradictory conditions:
+        if np.intersect1d(indices[selection], indices[np.logical_not(selection)]).size > 0:
+            return BitArray(np.empty((0, num_bytes), dtype=np.uint8), num_bits=self.num_bits)
+
+        # Recall that creg[0] is the LSb:
+        byte_significance, bit_significance = np.divmod(indices, 8)
+        # least-significant byte is at last position:
+        byte_idx = (num_bytes - 1) - byte_significance
+        # least-significant bit is at position 0:
+        bit_offset = bit_significance.astype(np.uint8)
+
+        # Get bitpacked representation of `indices` (bitmask):
+        bitmask = np.zeros(num_bytes, dtype=np.uint8)
+        np.bitwise_or.at(bitmask, byte_idx, np.uint8(1) << bit_offset)
+
+        # Get bitpacked representation of `selection` (desired bitstring):
+        selection_bytes = np.zeros(num_bytes, dtype=np.uint8)
+        ## This assumes no contradictions present, since those were already checked for:
+        np.bitwise_or.at(
+            selection_bytes, byte_idx, np.asarray(selection, dtype=np.uint8) << bit_offset
+        )
+
+        return BitArray(
+            flattened._array[((flattened._array & bitmask) == selection_bytes).all(axis=-1)],
+            num_bits=self.num_bits,
+        )
+
     def expectation_values(self, observables: ObservablesArrayLike) -> NDArray[np.float64]:
         """Compute the expectation values of the provided observables, broadcasted against
         this bit array.

qiskit/primitives/containers/shape.py

@@ -59,15 +59,15 @@ class ShapedMixin(Shaped):
         return f"{type(self).__name__}(<{self.shape}>)"
 
     @property
-    def shape(self) -> tuple[int, ...]:
+    def shape(self):
         return self._shape
 
     @property
-    def ndim(self) -> int:
+    def ndim(self):
         return len(self._shape)
 
     @property
-    def size(self) -> int:
+    def size(self):
         return int(np.prod(self._shape, dtype=int))
 
 

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
@@ -24,6 +24,7 @@ from qiskit.circuit import QuantumCircuit
 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
@@ -37,7 +38,7 @@ from .utils import (
 
 class Estimator(BaseEstimator[PrimitiveJob[EstimatorResult]]):
     """
-    Reference implementation of :class:`BaseEstimator`.
+    Reference implementation of :class:`BaseEstimator` (V1).
 
     :Run Options:
 
@@ -51,6 +52,12 @@ class Estimator(BaseEstimator[PrimitiveJob[EstimatorResult]]):
           this option is ignored.
     """
 
+    @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:

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

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
@@ -24,6 +24,7 @@ from qiskit.circuit import QuantumCircuit
 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
@@ -37,9 +38,9 @@ from .utils import (
 
 class Sampler(BaseSampler[PrimitiveJob[SamplerResult]]):
     """
-    Sampler class.
+    Sampler V1 class.
 
-    :class:`~Sampler` is a reference implementation of :class:`~BaseSampler`.
+    :class:`~Sampler` is a reference implementation of :class:`~BaseSampler` (V1).
 
     :Run Options:
 
@@ -52,6 +53,12 @@ class Sampler(BaseSampler[PrimitiveJob[SamplerResult]]):
           option is ignored.
     """
 
+    @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:

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
@@ -136,7 +136,7 @@ class StatevectorEstimator(BaseEstimatorV2):
         return job
 
     def _run(self, pubs: list[EstimatorPub]) -> PrimitiveResult[PubResult]:
-        return PrimitiveResult([self._run_pub(pub) for pub in pubs])
+        return PrimitiveResult([self._run_pub(pub) for pub in pubs], metadata={"version": 2})
 
     def _run_pub(self, pub: EstimatorPub) -> PubResult:
         rng = np.random.default_rng(self._seed)
@@ -162,4 +162,6 @@ class StatevectorEstimator(BaseEstimatorV2):
             evs[index] = expectation_value
 
         data = DataBin(evs=evs, stds=stds, shape=evs.shape)
-        return PubResult(data, metadata={"precision": precision})
+        return PubResult(
+            data, metadata={"target_precision": precision, "circuit_metadata": pub.circuit.metadata}
+        )

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
@@ -171,7 +171,7 @@ class StatevectorSampler(BaseSamplerV2):
 
     def _run(self, pubs: Iterable[SamplerPub]) -> PrimitiveResult[SamplerPubResult]:
         results = [self._run_pub(pub) for pub in pubs]
-        return PrimitiveResult(results)
+        return PrimitiveResult(results, metadata={"version": 2})
 
     def _run_pub(self, pub: SamplerPub) -> SamplerPubResult:
         circuit, qargs, meas_info = _preprocess_circuit(pub.circuit)
@@ -197,7 +197,10 @@ class StatevectorSampler(BaseSamplerV2):
         meas = {
             item.creg_name: BitArray(arrays[item.creg_name], item.num_bits) for item in meas_info
         }
-        return SamplerPubResult(DataBin(**meas, shape=pub.shape), metadata={"shots": pub.shots})
+        return SamplerPubResult(
+            DataBin(**meas, shape=pub.shape),
+            metadata={"shots": pub.shots, "circuit_metadata": pub.circuit.metadata},
+        )
 
 
 def _preprocess_circuit(circuit: QuantumCircuit):
@@ -207,7 +210,7 @@ def _preprocess_circuit(circuit: QuantumCircuit):
     qargs_index = {v: k for k, v in enumerate(qargs)}
     circuit = circuit.remove_final_measurements(inplace=False)
     if _has_control_flow(circuit):
-        raise QiskitError("StatevectorSampler cannot handle ControlFlowOp")
+        raise QiskitError("StatevectorSampler cannot handle ControlFlowOp and c_if")
     if _has_measure(circuit):
         raise QiskitError("StatevectorSampler cannot handle mid-circuit measurements")
     # num_qubits is used as sentinel to fill 0 in _samples_to_packed_array
@@ -283,4 +286,7 @@ def _final_measurement_mapping(circuit: QuantumCircuit) -> dict[tuple[ClassicalR
 
 
 def _has_control_flow(circuit: QuantumCircuit) -> bool:
-    return any(isinstance(instruction.operation, ControlFlowOp) for instruction in circuit)
+    return any(
+        isinstance((op := instruction.operation), ControlFlowOp) or op.condition
+        for instruction in circuit
+    )

qiskit/primitives/utils.py

@@ -25,8 +25,14 @@ from qiskit.exceptions import QiskitError
 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.