Migrate measure mitigation from ignis for QuantumInstance

This commit migrates the measurement mitigation code from qiskit-ignis
into qiskit-terra for use with the QuantumInstance class. The
QuantumInstance class's usage of the measurement mitigation from ignis
is the one thing blocking us from deprecating qiskit-ignis completely.
By embedding the code the quantum instance depends on inside
qiskit.utils users of QuantumInstance (and therefore qiskit.algorithms)
can construct and use measurement mitigation in it's current form. The
use of this migrated module is only supported for use with the
QuantumInstance class and is explicitly documented as internal/private
except for how it gets used by the QuantumInstance.

There is ongoing work to create a standardized mitigation API in Qiskit#6485
and Qiskit#6748, this does not preclude that work, but we should adapt this as
part of those efforts to use the standardized interface. Ideally this
would have been made a private interface and not exposed it as user facing
(in deference to the standardization effort), but unfortunately the
QuantumInstance expects classes of these classes as it's public interface
for selecting a mitigation technique which means users need to be able to
use the classes. However, as only the classes are public interfaces we
can adapt this as we come up with a standardized mitigation interface
and rewrite the internals of this and how the QuantumInstance leverages
mitigators to use the new interface.

A good follow-up here would be to adapt the mitigator selection kwarg to
deprecate the use of classes and then we can make things explicitly
private in the migrated code and wait for Qiskit#6495 and Qiskit#6748 to be ready
for our user facing API. I opted to not include that in this PR to
minimize changes to just what we migrated from ignis and update usage of
old ignis classes to rely on the migrated version.

docs/apidocs/terra.rst

@@ -32,6 +32,7 @@ Qiskit Terra API Reference
    transpiler_passes
    transpiler_preset
    utils
+   utils_mitigation
    visualization
    opflow
    algorithms

docs/apidocs/utils_mitigation.rst

@@ -0,0 +1,6 @@
+.. _qiskit-utils-mitigation:
+
+.. automodule:: qiskit.utils.mitigation
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

qiskit/utils/measurement_error_mitigation.py

@@ -14,12 +14,19 @@
 
 import copy
 from typing import List, Optional, Tuple, Dict, Callable
+
 from qiskit import compiler
 from qiskit.providers import BaseBackend
 from qiskit.circuit import QuantumCircuit
 from qiskit.qobj import QasmQobj
 from qiskit.assembler.run_config import RunConfig
-from ..exceptions import QiskitError, MissingOptionalLibraryError
+from qiskit.exceptions import QiskitError, MissingOptionalLibraryError
+from qiskit.utils.mitigation import (
+    complete_meas_cal,
+    tensored_meas_cal,
+    CompleteMeasFitter,
+    TensoredMeasFitter,
+)
 
 # pylint: disable=invalid-name
 
@@ -137,35 +144,44 @@ def build_measurement_error_mitigation_circuits(
         QiskitError: when the fitter_cls is not recognizable.
         MissingOptionalLibraryError: Qiskit-Ignis not installed
     """
-    try:
-        from qiskit.ignis.mitigation.measurement import (
-            complete_meas_cal,
-            tensored_meas_cal,
-            CompleteMeasFitter,
-            TensoredMeasFitter,
-        )
-    except ImportError as ex:
-        raise MissingOptionalLibraryError(
-            libname="qiskit-ignis",
-            name="build_measurement_error_mitigation_qobj",
-            pip_install="pip install qiskit-ignis",
-        ) from ex
-
     circlabel = "mcal"
 
     if not qubit_list:
         raise QiskitError("The measured qubit list can not be [].")
 
+    run = False
     if fitter_cls == CompleteMeasFitter:
         meas_calibs_circuits, state_labels = complete_meas_cal(
             qubit_list=range(len(qubit_list)), circlabel=circlabel
         )
+        run = True
     elif fitter_cls == TensoredMeasFitter:
         meas_calibs_circuits, state_labels = tensored_meas_cal(
             mit_pattern=mit_pattern, circlabel=circlabel
         )
-    else:
-        raise QiskitError(f"Unknown fitter {fitter_cls}")
+        run = True
+    if not run:
+        try:
+            from qiskit.ignis.mitigation.measurement import (
+                CompleteMeasFitter as CompleteMeasFitter_IG,
+                TensoredMeasFitter as TensoredMeasFitter_IG,
+            )
+        except ImportError as ex:
+            raise MissingOptionalLibraryError(
+                libname="qiskit-ignis",
+                name="build_measurement_error_mitigation_qobj",
+                pip_install="pip install qiskit-ignis",
+            ) from ex
+        if fitter_cls == CompleteMeasFitter_IG:
+            meas_calibs_circuits, state_labels = complete_meas_cal(
+                qubit_list=range(len(qubit_list)), circlabel=circlabel
+            )
+        elif fitter_cls == TensoredMeasFitter_IG:
+            meas_calibs_circuits, state_labels = tensored_meas_cal(
+                mit_pattern=mit_pattern, circlabel=circlabel
+            )
+        else:
+            raise QiskitError(f"Unknown fitter {fitter_cls}")
 
     # the provided `qubit_list` would be used as the initial layout to
     # assure the consistent qubit mapping used in the main circuits.
@@ -209,19 +225,6 @@ def build_measurement_error_mitigation_qobj(
         QiskitError: when the fitter_cls is not recognizable.
         MissingOptionalLibraryError: Qiskit-Ignis not installed
     """
-    try:
-        from qiskit.ignis.mitigation.measurement import (
-            complete_meas_cal,
-            tensored_meas_cal,
-            CompleteMeasFitter,
-            TensoredMeasFitter,
-        )
-    except ImportError as ex:
-        raise MissingOptionalLibraryError(
-            libname="qiskit-ignis",
-            name="build_measurement_error_mitigation_qobj",
-            pip_install="pip install qiskit-ignis",
-        ) from ex
 
     circlabel = "mcal"
 

qiskit/utils/mitigation/__init__.py

@@ -0,0 +1,54 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2019.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# 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.
+
+# This code was originally copied from the qiskit-ignis repsoitory see:
+# https://github.com/Qiskit/qiskit-ignis/blob/b91066c72171bcd55a70e6e8993b813ec763cf41/qiskit/ignis/mitigation/measurement/__init__.py
+# it was migrated as qiskit-ignis is being deprecated
+
+"""
+=============================================================
+Measurement Mitigation Utils (:mod:`qiskit.utils.mitigation`)
+=============================================================
+
+.. currentmodule:: qiskit.utils.mitigation
+
+Measurement correction
+======================
+
+The measurement calibration is used to mitigate measurement errors.
+The main idea is to prepare all :math:`2^n` basis input states and compute
+the probability of measuring counts in the other basis states.
+From these calibrations, it is possible to correct the average results
+of another experiment of interest. These tools are intended for use solely
+with the :class:`~qiskit.utils.QuantumInstance` class as part of
+:mod:`qiskit.algorithms` and :mod:`qiskit.opflow`.
+
+.. warning::
+
+    The user facing API stability of this module is not guaranteed except for
+    their use with the :class:`~qiskit.utils.QuantumInstance` (ie using the
+    :class:`~qiskit.utils.mitigation.CompleteMeasFitter` or
+    :class:`~qiskit.utils.mitigation.TensoredMeasFitter` class as values for the
+    ``meas_error_mitigation_cls``). The rest of this module should be treated as
+    an internal private API that can not be relied upon.
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   CompleteMeasFitter
+   TensoredMeasFitter
+"""
+
+# Measurement correction functions
+from .circuits import complete_meas_cal, tensored_meas_cal
+from .filters import MeasurementFilter, TensoredFilter
+from .fitters import CompleteMeasFitter, TensoredMeasFitter