[WIP] Add M3 measurement mitigation

.gitignore

@@ -141,13 +141,13 @@ src/qasm-simulator-cpp/test/qubit_vector_tests
 # Cython pass
 qiskit/transpiler/passes/**/cython/**/*.cpp
 qiskit/quantum_info/states/cython/*.cpp
+qiskit/mitigation/mthree/*.cpp
+qiskit/mitigation/mthree/test/*.cpp
+qiskit/result/distributions/*.cpp
 
 docs/stubs/*
 
 # Notebook testing images
-test/ipynb/mpl/*.png
-test/ipynb/mpl/*.zip
-test/ipynb/mpl/result_test.json
 test/ipynb/mpl/circuit/*.png
 test/ipynb/mpl/circuit/*.zip
 test/ipynb/mpl/circuit/result_test.json

docs/apidocs/mitigation.rst

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

docs/apidocs/terra.rst

@@ -35,3 +35,4 @@ Qiskit Terra API Reference
    visualization
    opflow
    algorithms
+   mitigation

pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["Cython>=0.27.1", "setuptools", "wheel"]
+requires = ["Cython>=0.27.1", "numpy>=1.17", "setuptools", "wheel"]
 
 [tool.black]
 line-length = 100

qiskit/mitigation/__init__.py

@@ -0,0 +1,33 @@
+# 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.
+
+"""Error mitigation routines
+
+===========================================
+Error mitigation (:mod:`qiskit.mitigation`)
+===========================================
+
+.. versionadded:: 0.19.0
+
+.. currentmodule:: qiskit.mitigation
+
+Measurement mitigation
+======================
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   M3Mitigation
+
+"""
+
+from .mthree import M3Mitigation

qiskit/mitigation/mthree/__init__.py

@@ -0,0 +1,16 @@
+# 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.
+
+"""Matrix-free measurement mitigation.
+"""
+
+from .mitigation import M3Mitigation

qiskit/mitigation/mthree/compute.pxd

@@ -0,0 +1,30 @@
+# 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.
+
+cdef unsigned int within_distance(unsigned int row,
+                                  unsigned int col,
+                                  const unsigned char * bitstrings,
+                                  unsigned int num_bits,
+                                  unsigned int distance) nogil
+
+cdef double compute_element(unsigned int row,
+                            unsigned int col,
+                            const unsigned char * bitstrings,
+                            const double * cals,
+                            unsigned int num_bits) nogil
+
+cdef void compute_col_norms(double * col_norms,
+                            const unsigned char * bitstrings,
+                            const double * cals,
+                            unsigned int num_bits,
+                            unsigned int num_elems,
+                            unsigned int distance) nogil

qiskit/mitigation/mthree/compute.pyx

@@ -0,0 +1,137 @@
+# 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.
+cimport cython
+from cython.parallel cimport prange
+
+@cython.boundscheck(False)
+@cython.cdivision(True)
+cdef inline unsigned int within_distance(unsigned int row,
+                                         unsigned int col,
+                                         const unsigned char * bitstrings,
+                                         unsigned int num_bits,
+                                         unsigned int distance) nogil:
+    """Computes the Hamming distance between two bitstrings.
+
+    Parameters:
+        row (unsigned int): The row index.
+        col (unsigned int): The col index.
+        bitstrings (unsigned char *): Pointer to array of all bitstrings.
+        num_bits (unsigned int): The number of bits in a bitstring.
+        distance (unsigned int): The distance to calculate out to.
+
+    Returns:
+        unsigned int: Are the bitstrings within given distance.
+    """
+
+    cdef size_t kk
+    cdef unsigned int temp_dist = 0
+    cdef unsigned int row_start = row*num_bits
+    cdef unsigned int col_start = col*num_bits
+
+    for kk in range(num_bits):
+        temp_dist += bitstrings[row_start+kk] != bitstrings[col_start+kk]
+    return temp_dist <= distance
+
+@cython.boundscheck(False)
+@cython.cdivision(True)
+cdef inline double compute_element(unsigned int row,
+                                   unsigned int col,
+                                   const unsigned char * bitstrings,
+                                   const double * cals,
+                                   unsigned int num_bits) nogil:
+    """Computes the matrix element specified by the input
+    bit strings from the supplied tensored cals data.
+
+    Parameters:
+        row_arr (unsigned char *): Basis element giving row index.
+        col_arr (unsigned char *): Basis element giving col index.
+        cals (const double *): Tensored calibration data.
+        num_qubits (unsigned int): Number of qubits in arrays
+
+    Returns:
+        double: Matrix element value.
+    """
+    cdef double res = 1
+    cdef size_t kk
+    cdef unsigned int offset
+    cdef unsigned int row_start = num_bits*row
+    cdef unsigned int col_start = num_bits*col
+
+    for kk in range(num_bits):
+        offset = 2*bitstrings[row_start+kk]+bitstrings[col_start+kk]
+        res *= cals[4*kk+offset]
+    return res
+
+@cython.boundscheck(False)
+@cython.cdivision(True)
+cdef void compute_col_norms(double * col_norms,
+                            const unsigned char * bitstrings,
+                            const double * cals,
+                            unsigned int num_bits,
+                            unsigned int num_elems,
+                            unsigned int distance) nogil:
+    """Compute the matrix column norms for each bitstring.
+
+    Parameters:
+        col_norms (double *): Pointer to double array in which to poulate norms.
+        bitstrings (unsigned char *): Pointer to array of all bitstrings.
+        num_bits (unsigned int): The number of bits in a bitstring.
+        num_elems (unsigned int): The number of bitstring elements.
+        distance (unsigned int): The distance to calculate out to.
+    """
+    cdef size_t col, row
+    cdef double col_norm
+    cdef unsigned int MAX_DIST = 0
+
+    if distance == num_bits:
+        MAX_DIST = 1
+    # Compute the column norm for each element
+    with nogil:
+        for col in prange(num_elems, schedule='static'):
+            col_norm = _inner_col_norm_loop(col,
+                                            bitstrings,
+                                            cals,
+                                            num_bits,
+                                            num_elems,
+                                            distance,
+                                            MAX_DIST)
+            col_norms[col] = col_norm
+
+
+cdef double _inner_col_norm_loop(unsigned int col,
+                                 const unsigned char * bitstrings,
+                                 const double * cals,
+                                 unsigned int num_bits,
+                                 unsigned int num_elems,
+                                 unsigned int distance,
+                                 unsigned int MAX_DIST) nogil:
+    """An inner-loop function for computing col_norms in parallel.
+
+    This is needed to get around an issue with how Cython tries to do
+    OMP reductions.
+
+    Parameters:
+        col (int): The column of interest.
+        col_norms (double *): Pointer to double array in which to poulate norms.
+        bitstrings (unsigned char *): Pointer to array of all bitstrings.
+        num_bits (unsigned int): The number of bits in a bitstring.
+        num_elems (unsigned int): The number of bitstring elements.
+        distance (unsigned int): The distance to calculate out to.
+        MAX_DIST (unsigned int): Are we doing max distance.
+    """
+    cdef size_t row
+    cdef double col_norm = 0
+
+    for row in range(num_elems):
+        if MAX_DIST or within_distance(row, col, bitstrings, num_bits, distance):
+            col_norm += compute_element(row, col, bitstrings, cals, num_bits)
+    return col_norm

qiskit/mitigation/mthree/converters.pxd

@@ -0,0 +1,23 @@
+# 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.
+# cython: c_string_type=unicode, c_string_encoding=UTF-8
+from libcpp.map cimport map
+from libcpp.string cimport string
+
+cdef void counts_to_internal(map[string, double] * counts,
+                             unsigned char * vec,
+                             double * probs,
+                             unsigned int num_bits,
+                             double shots)
+
+cdef void internal_to_probs(map[string, double] * counts,
+                            double * probs)

qiskit/mitigation/mthree/converters.pyx

@@ -0,0 +1,68 @@
+# 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.
+# cython: c_string_type=unicode, c_string_encoding=UTF-8
+cimport cython
+from libcpp.map cimport map
+from libcpp.string cimport string
+from cython.operator cimport dereference, postincrement
+
+@cython.boundscheck(False)
+@cython.cdivision(True)
+cdef void counts_to_internal(map[string, double] * counts_map,
+                             unsigned char * vec,
+                             double * probs,
+                             unsigned int num_bits,
+                             double shots):
+    """Converts a Qiskit counts object (or Python dict) into an array
+    of bitstrings and probabilities.
+
+    Parameters:
+        counts (object): A Qiskit counts object or Python dict.
+        vec (unsigned char *): Pointer to array of bitstrings to populate.
+        probs (double *): Pointer to array of probabilities to populate.
+        num_bits (unsigned int): Number of bits in the bitstrings.
+    """
+    cdef unsigned int idx, letter, start
+    cdef map[string, double].iterator end = counts_map.end()
+    cdef map[string, double].iterator it = counts_map.begin()
+    cdef string temp
+    idx = 0
+    while it != end:
+        start = num_bits*idx
+        probs[idx] = dereference(it).second / shots
+        temp = dereference(it).first
+        for letter in range(num_bits):
+            vec[start+letter] = <unsigned char>temp[letter]-48
+        idx += 1
+        postincrement(it)
+
+
+@cython.boundscheck(False)
+@cython.cdivision(True)
+cdef void internal_to_probs(map[string, double] * counts_map,
+                            double * probs):
+    """Converts internal arrays back into a Python dict.
+
+    Parameters:
+        vec (unsigned char *): Pointer to array of bitstrings.
+        vec (dobule *): Pointer to array of probabilities.
+        num_elems (unsigned int): Number of elements.
+        num_bits (unsigned int): Number of bits in the bitstrings.
+    """
+    cdef size_t idx = 0
+    cdef map[string, double].iterator end = counts_map.end()
+    cdef map[string, double].iterator it = counts_map.begin()
+
+    while it != end:
+        dereference(it).second = probs[idx]
+        idx += 1
+        postincrement(it)