Deprecate qiskit.result.mitigation (#13351)

* Deprecate qiskit.result.mitigation

* Replace runtime suggestion with mthree

* Add reno

* Update base_readout_mitigator.py to be consistent with other docstrings

---------

Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

Author: ElePT

qiskit/result/mitigation/base_readout_mitigator.py

@@ -21,7 +21,7 @@
 
 
 class BaseReadoutMitigator(ABC):
-    """Base readout error mitigator class."""
+    """This class is DEPRECATED. Base readout error mitigator class."""
 
     @abstractmethod
     def quasi_probabilities(

qiskit/result/mitigation/correlated_readout_mitigator.py

@@ -18,14 +18,15 @@
 import numpy as np
 
 from qiskit.exceptions import QiskitError
+from qiskit.utils.deprecation import deprecate_func
 from ..distributions.quasi import QuasiDistribution
 from ..counts import Counts
 from .base_readout_mitigator import BaseReadoutMitigator
 from .utils import counts_probability_vector, z_diagonal, str2diag
 
 
 class CorrelatedReadoutMitigator(BaseReadoutMitigator):
-    """N-qubit readout error mitigator.
+    """This class is DEPRECATED. N-qubit readout error mitigator.
 
     Mitigates :meth:`expectation_value` and :meth:`quasi_probabilities`.
     The mitigation_matrix should be calibrated using qiskit experiments.
@@ -34,6 +35,13 @@ class CorrelatedReadoutMitigator(BaseReadoutMitigator):
     :math:`2^N x 2^N` so the mitigation complexity is :math:`O(4^N)`.
     """
 
+    @deprecate_func(
+        since="1.3",
+        package_name="Qiskit",
+        removal_timeline="in Qiskit 2.0",
+        additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+        "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+    )
     def __init__(self, assignment_matrix: np.ndarray, qubits: Optional[Iterable[int]] = None):
         """Initialize a CorrelatedReadoutMitigator
 

qiskit/result/mitigation/local_readout_mitigator.py

@@ -19,14 +19,15 @@
 import numpy as np
 
 from qiskit.exceptions import QiskitError
+from qiskit.utils.deprecation import deprecate_func
 from ..distributions.quasi import QuasiDistribution
 from ..counts import Counts
 from .base_readout_mitigator import BaseReadoutMitigator
 from .utils import counts_probability_vector, z_diagonal, str2diag
 
 
 class LocalReadoutMitigator(BaseReadoutMitigator):
-    """1-qubit tensor product readout error mitigator.
+    """This class is DEPRECATED. 1-qubit tensor product readout error mitigator.
 
     Mitigates :meth:`expectation_value` and :meth:`quasi_probabilities`.
     The mitigator should either be calibrated using qiskit experiments,
@@ -37,6 +38,13 @@ class LocalReadoutMitigator(BaseReadoutMitigator):
     so it is more efficient than the :class:`CorrelatedReadoutMitigator` class.
     """
 
+    @deprecate_func(
+        since="1.3",
+        package_name="Qiskit",
+        removal_timeline="in Qiskit 2.0",
+        additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+        "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+    )
     def __init__(
         self,
         assignment_matrices: Optional[List[np.ndarray]] = None,

qiskit/result/mitigation/utils.py

@@ -19,12 +19,20 @@
 import numpy as np
 
 from qiskit.exceptions import QiskitError
+from qiskit.utils.deprecation import deprecate_func
 from ..utils import marginal_counts
 from ..counts import Counts
 
 logger = logging.getLogger(__name__)
 
 
+@deprecate_func(
+    since="1.3",
+    package_name="Qiskit",
+    removal_timeline="in Qiskit 2.0",
+    additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+    "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+)
 def z_diagonal(dim, dtype=float):
     r"""Return the diagonal for the operator :math:`Z^\otimes n`"""
     parity = np.zeros(dim, dtype=dtype)
@@ -33,6 +41,13 @@ def z_diagonal(dim, dtype=float):
     return (-1) ** np.mod(parity, 2)
 
 
+@deprecate_func(
+    since="1.3",
+    package_name="Qiskit",
+    removal_timeline="in Qiskit 2.0",
+    additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+    "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+)
 def expval_with_stddev(coeffs: np.ndarray, probs: np.ndarray, shots: int) -> Tuple[float, float]:
     """Compute expectation value and standard deviation.
     Args:
@@ -60,6 +75,13 @@ def expval_with_stddev(coeffs: np.ndarray, probs: np.ndarray, shots: int) -> Tup
     return [expval, calc_stddev]
 
 
+@deprecate_func(
+    since="1.3",
+    package_name="Qiskit",
+    removal_timeline="in Qiskit 2.0",
+    additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+    "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+)
 def stddev(probs, shots):
     """Calculate stddev dict"""
     ret = {}
@@ -69,6 +91,13 @@ def stddev(probs, shots):
     return ret
 
 
+@deprecate_func(
+    since="1.3",
+    package_name="Qiskit",
+    removal_timeline="in Qiskit 2.0",
+    additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+    "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+)
 def str2diag(string):
     """Transform diagonal from a string to a numpy array"""
     chars = {
@@ -85,6 +114,13 @@ def str2diag(string):
     return ret
 
 
+@deprecate_func(
+    since="1.3",
+    package_name="Qiskit",
+    removal_timeline="in Qiskit 2.0",
+    additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+    "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+)
 def counts_to_vector(counts: Counts, num_qubits: int) -> Tuple[np.ndarray, int]:
     """Transforms Counts to a probability vector"""
     vec = np.zeros(2**num_qubits, dtype=float)
@@ -96,6 +132,13 @@ def counts_to_vector(counts: Counts, num_qubits: int) -> Tuple[np.ndarray, int]:
     return vec, shots
 
 
+@deprecate_func(
+    since="1.3",
+    package_name="Qiskit",
+    removal_timeline="in Qiskit 2.0",
+    additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+    "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+)
 def remap_qubits(
     vec: np.ndarray, num_qubits: int, qubits: Optional[List[int]] = None
 ) -> np.ndarray:
@@ -108,6 +151,13 @@ def remap_qubits(
     return vec
 
 
+@deprecate_func(
+    since="1.3",
+    package_name="Qiskit",
+    removal_timeline="in Qiskit 2.0",
+    additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+    "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+)
 def marganalize_counts(
     counts: Counts,
     qubit_index: Dict[int, int],
@@ -129,6 +179,13 @@ def marganalize_counts(
     return counts
 
 
+@deprecate_func(
+    since="1.3",
+    package_name="Qiskit",
+    removal_timeline="in Qiskit 2.0",
+    additional_msg="The `qiskit.result.mitigation` module is deprecated in favor of "
+    "the https://github.com/Qiskit/qiskit-addon-mthree package.",
+)
 def counts_probability_vector(
     counts: Counts,
     qubit_index: Dict[int, int],

releasenotes/notes/deprecate-mitigation-f5f6ef3233b3d726.yaml

@@ -0,0 +1,7 @@
+---
+deprecations_misc:
+  - |
+    The ``qiskit.result.mitigation`` module has been deprecated and will be removed in the 2.0 release.
+    The deprecation includes the ``LocalReadoutMitigator`` and ``CorrelatedReadoutMitigator`` classes 
+    as well as the associated utils. 
+    Their functionality has been superseded by the mthree package, found in https://github.com/Qiskit/qiskit-addon-mthree.