Mitigation experiment

qiskit_experiments/library/__init__.py

@@ -142,6 +142,7 @@ class instance to manage parameters and pulse schedules.
 from .randomized_benchmarking import StandardRB, InterleavedRB
 from .tomography import StateTomography, ProcessTomography
 from .quantum_volume import QuantumVolume
+from .mitigation import ReadoutMitigationExperiment
 
 # Experiment Sub-modules
 from . import calibration

qiskit_experiments/library/mitigation/__init__.py

@@ -0,0 +1,41 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# 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.
+
+"""
+===============================================================================================
+Readout Mitigation Experiments (:mod:`qiskit_experiments.library.mitigation`)
+===============================================================================================
+
+.. currentmodule:: qiskit_experiments.library.mitigation
+
+Experiment
+===========
+.. autosummary::
+    :toctree: ../stubs/
+    :template: autosummary/experiment.rst
+
+    ReadoutMitigationExperiment
+
+
+Analysis
+========
+
+.. autosummary::
+    :toctree: ../stubs/
+    :template: autosummary/analysis.rst
+
+    CorrelatedMitigationAnalysis
+    LocalMitigationAnalysis
+"""
+from .mitigation_experiment import ReadoutMitigationExperiment
+from .mitigation_analysis import CorrelatedMitigationAnalysis
+from .mitigation_analysis import LocalMitigationAnalysis

qiskit_experiments/library/mitigation/mitigation_analysis.py

@@ -0,0 +1,161 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# 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.
+"""
+Measurement calibration analysis classes
+"""
+from typing import List, Tuple
+import numpy as np
+import matplotlib.pyplot as plt
+from qiskit.result import CorrelatedReadoutMitigator
+from qiskit.result import LocalReadoutMitigator
+from qiskit.result import marginal_counts
+from qiskit_experiments.framework import ExperimentData
+from qiskit_experiments.framework.matplotlib import get_non_gui_ax
+from qiskit_experiments.framework import BaseAnalysis, AnalysisResultData, Options
+
+
+class CorrelatedMitigationAnalysis(BaseAnalysis):
+    """
+    Measurement correction analysis for a full calibration
+    """
+
+    def _run_analysis(
+        self, experiment_data: ExperimentData, **options
+    ) -> Tuple[List[AnalysisResultData], List["matplotlib.figure.Figure"]]:
+        data = experiment_data.data()
+        qubits = experiment_data.metadata["physical_qubits"]
+        labels = [datum["metadata"]["label"] for datum in data]
+        matrix = self._generate_matrix(data, labels)
+        result_mitigator = CorrelatedReadoutMitigator(matrix, qubits=qubits)
+        analysis_results = [AnalysisResultData("Correlated Readout Mitigator", result_mitigator)]
+        ax = options.get("ax", None)
+        figures = [self._plot_calibration(matrix, labels, ax)]
+        return analysis_results, figures
+
+    def _generate_matrix(self, data, labels) -> np.array:
+        list_size = len(labels)
+        matrix = np.zeros([list_size, list_size], dtype=float)
+        # matrix[i][j] is the probability of counting i for expected j
+        for datum in data:
+            expected_outcome = datum["metadata"]["label"]
+            j = labels.index(expected_outcome)
+            total_counts = sum(datum["counts"].values())
+            for measured_outcome, count in datum["counts"].items():
+                i = labels.index(measured_outcome)
+                matrix[i][j] = count / total_counts
+        return matrix
+
+    def _plot_calibration(self, matrix, labels, ax=None) -> "matplotlib.figure.Figure":
+        """
+        Plot the calibration matrix (2D color grid plot).
+
+        Args:
+            matrix: calibration matrix to plot
+            ax (matplotlib.axes): settings for the graph
+
+        Returns:
+            The generated plot of the calibration matrix
+
+        Raises:
+            QiskitError: if _cal_matrices was not set.
+
+            ImportError: if matplotlib was not installed.
+
+        """
+
+        if ax is None:
+            ax = get_non_gui_ax()
+        figure = ax.get_figure()
+        ax.matshow(matrix, cmap=plt.cm.binary, clim=[0, 1])
+        ax.set_xlabel("Prepared State")
+        ax.xaxis.set_label_position("top")
+        ax.set_ylabel("Measured State")
+        ax.set_xticks(np.arange(len(labels)))
+        ax.set_yticks(np.arange(len(labels)))
+        ax.set_xticklabels(labels)
+        ax.set_yticklabels(labels)
+        return figure
+
+
+class LocalMitigationAnalysis(BaseAnalysis):
+    """
+    Measurement correction analysis for a full calibration
+    """
+
+    @classmethod
+    def _default_options(cls) -> Options:
+        """Return default analysis options.
+
+        Analysis Options:
+            plot (bool): Set ``True`` to create figure for fit result.
+            ax(AxesSubplot): Optional. A matplotlib axis object to draw.
+        """
+        options = super()._default_options()
+        options.plot = True
+        options.ax = None
+        return options
+
+    def _run_analysis(
+        self, experiment_data: ExperimentData
+    ) -> Tuple[List[AnalysisResultData], List["matplotlib.figure.Figure"]]:
+        data = experiment_data.data()
+        qubits = experiment_data.metadata["physical_qubits"]
+        matrices = self._generate_matrices(data)
+        result_mitigator = LocalReadoutMitigator(matrices, qubits=qubits)
+        analysis_results = [AnalysisResultData("Local Readout Mitigator", result_mitigator)]
+        if self.options.plot:
+            figure = assignment_matrix_visualization(
+                result_mitigator.assignment_matrix(), ax=self.options.ax
+            )
+            figures = [figure]
+        else:
+            figures = None
+        return analysis_results, figures
+
+    def _generate_matrices(self, data) -> List[np.array]:
+        num_qubits = len(data[0]["metadata"]["label"])
+        counts = [None, None]
+        for result in data:
+            for i in range(2):
+                if result["metadata"]["label"] == str(i) * num_qubits:
+                    counts[i] = result["counts"]
+        matrices = []
+        for k in range(num_qubits):
+            matrix = np.zeros([2, 2], dtype=float)
+            marginalized_counts = []
+            for i in range(2):
+                marginalized_counts.append(marginal_counts(counts[i], [k]))
+            # matrix[i][j] is the probability of counting i for expected j
+            for i in range(2):
+                for j in range(2):
+                    matrix[i][j] = marginalized_counts[j][str(i)] / sum(
+                        marginalized_counts[j].values()
+                    )
+            matrices.append(matrix)
+        return matrices
+
+
+def assignment_matrix_visualization(assignment_matrix, ax=None):
+    """Displays a visualization of the assignment matrix compared to the identity"""
+    if ax is None:
+        ax = get_non_gui_ax()
+    figure = ax.get_figure()
+    n = len(assignment_matrix)
+    diff = np.abs(assignment_matrix - np.eye(n))
+    im2 = ax.matshow(diff, cmap=plt.cm.Reds, vmin=0, vmax=0.2)
+    ax.set_yticks(np.arange(n))
+    ax.set_xticks(np.arange(n))
+    ax.set_yticklabels(n * [""])
+    ax.set_xticklabels(n * [""])
+    ax.set_xlabel(r"$|A - I|$", fontsize=16)
+    figure.colorbar(im2, ax=ax)
+    return figure

qiskit_experiments/library/mitigation/mitigation_experiment.py

@@ -0,0 +1,114 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# 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.
+"""
+Measurement calibration experiment classes.
+"""
+from typing import Iterable, List
+
+from qiskit import QuantumCircuit
+from qiskit.exceptions import QiskitError
+from qiskit_experiments.framework import BaseExperiment
+from .mitigation_analysis import CorrelatedMitigationAnalysis, LocalMitigationAnalysis
+
+
+class ReadoutMitigationExperiment(BaseExperiment):
+    """Class for readout mitigation experiments"""
+
+    METHOD_LOCAL = "local"
+    METHOD_CORRELATED = "correlated"
+    ALL_METHODS = [METHOD_LOCAL, METHOD_CORRELATED]
+
+    def __init__(self, qubits: Iterable[int], method=METHOD_LOCAL):
+        """Initialize a mitigation experiment.
+
+        Args:
+            qubits: The qubits being mitigated
+            method: A string denoting mitigation method
+
+        Raises:
+            QiskitError: if the given mitigation method is not recoginzed
+
+        Additional info:
+            The currently supported mitigation methods are:
+            * "local": each qubit is mitigated by itself; this is the default method,
+            and assumes readout errors are independent for each qubits
+            * "correlated": All the qubits are mitigated together; this results in an exponentially
+            large mitigation matrix and so is useable only for a small number of qubits,
+            but might be more accurate than local mitigation.
+        """
+        super().__init__(qubits)
+        if method not in self.ALL_METHODS:
+            raise QiskitError("Method {} not recognized".format(method))
+        if method == self.METHOD_LOCAL:
+            self.helper = LocalMitigationHelper(self.num_qubits)
+        if method == self.METHOD_CORRELATED:
+            self.helper = CorrelatedMitigationHelper(self.num_qubits)
+
+        self.analysis = self.helper.analysis()
+
+    def circuits(self) -> List[QuantumCircuit]:
+        """Returns the experiment's circuits"""
+        return [self._calibration_circuit(self.num_qubits, label) for label in self.helper.labels()]
+
+    @staticmethod
+    def _calibration_circuit(num_qubits: int, label: str) -> QuantumCircuit:
+        """Return a calibration circuit.
+
+        This is an N-qubit circuit where N is the length of the label.
+        The circuit consists of X-gates on qubits with label bits equal to 1,
+        and measurements of all qubits.
+        """
+        circ = QuantumCircuit(num_qubits, name="meas_mit_cal_" + label)
+        for i, val in enumerate(reversed(label)):
+            if val == "1":
+                circ.x(i)
+        circ.measure_all()
+        circ.metadata = {"label": label}
+        return circ
+
+
+class CorrelatedMitigationHelper:
+    """Helper class for correlated mitigation experiment data"""
+
+    def __init__(self, num_qubits: int):
+        """Creates the helper class
+        Args:
+            num_qubits: The number of qubits being mitigated
+        """
+        self.num_qubits = num_qubits
+
+    def analysis(self):
+        """Returns the analysis class for the mitigation"""
+        return CorrelatedMitigationAnalysis()
+
+    def labels(self) -> List[str]:
+        """Returns the labels dictating the generation of the mitigation circuits"""
+        return [bin(j)[2:].zfill(self.num_qubits) for j in range(2 ** self.num_qubits)]
+
+
+class LocalMitigationHelper:
+    """Helper class for local mitigation experiment data"""
+
+    def __init__(self, num_qubits: int):
+        """Creates the helper class
+        Args:
+            num_qubits: The number of qubits being mitigated
+        """
+        self.num_qubits = num_qubits
+
+    def analysis(self):
+        """Returns the analysis class for the mitigation"""
+        return LocalMitigationAnalysis()
+
+    def labels(self) -> List[str]:
+        """Returns the labels dictating the generation of the mitigation circuits"""
+        return ["0" * self.num_qubits, "1" * self.num_qubits]

releasenotes/notes/readout-mitigation-experiment-4ea5392ee955a54c.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Added a new experiment (`qiskit_experiments.library import ReadoutMitigationExperiment`)
+    for calibrating readout mitigators.