Initial version

.github/workflows/python-package-conda.yml

@@ -0,0 +1,34 @@
+name: Mthree using Conda
+
+on: [push]
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 5
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.9
+    - name: Add conda to system path
+      run: |
+        # $CONDA is an environment variable pointing to the root of the miniconda directory
+        echo $CONDA/bin >> $GITHUB_PATH
+    - name: Install dependencies
+      run: |
+        conda config --set always_yes yes --set changeps1 no
+        pip install -U -r requirements.txt
+        python setup.py install
+    - name: Lint with pylint and pycodestyle
+      run: |
+        pip install -U -r requirements-dev.txt
+        pylint -rn mthree
+        pycodestyle --max-line-length=100 mthree
+    - name: Test no-Qiskit with pytest
+      run: |
+        conda install pytest
+        pytest -p no:warnings --pyargs mthree/test

.gitignore

@@ -0,0 +1,134 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+.DS_Store
+mthree/version.py
+*.cpp
+
+docs/stubs/*

LICENSE → LICENSE.txt

@@ -1,3 +1,5 @@
+                    Copyright 2017 IBM and its contributors
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -186,7 +188,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2017 IBM and its contributors.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -0,0 +1,98 @@
+# mthree
+
+Matrix-free Measurement Mitigation (M3).
+
+M3 is a measurement mitigation technique that solves for corrected counts using a dimensionality reduction step followed by a simple iterative method that nominally converges in O(1) steps, and can be computed in parallel.  For example, M3 can compute corrections on 30 qubit GHZ problems in under one second on a quad-core machine (depending on the number of unique bitstrings in the output).
+
+## Installation
+
+Currently M3 needs to be installed from source:
+
+```bash
+python setup.py install
+```
+
+To enable openmp one must have an openmp enabled compiler and install with:
+
+```bash
+python setup.py install --with-openmp
+```
+
+Optionally one can also set `-march=native` using:
+
+```bash
+python setup.py install --with-native
+```
+
+The `openmp` and `native` flags can be used simultaneously using a comma.
+
+### OpenMP on OSX
+
+On OSX one must install LLVM using homebrew (You cannot use GCC):
+
+```bash
+brew install llvm
+```
+
+after which the following (or the like) must be executed in the terminal:
+
+```bash
+export PATH="/usr/local/opt/llvm/bin:$PATH"
+```
+
+and
+
+```bash
+export LDFLAGS="-L/usr/local/opt/llvm/lib -Wl,-rpath,/usr/local/opt/llvm/lib"
+export CPPFLAGS="-I/usr/local/opt/llvm/include"
+```
+
+Then installation with openmp can be accomplished using:
+
+```bash
+CC=clang CXX=clang python setup.py install --with-openmp
+```
+
+## Usage
+
+M3 is simple to use:
+
+```python
+import mthree
+# Specify a mitigator object targeting a given backend
+mit = mthree.M3Mitigation(backend)
+
+# Compute the tensored 1Q calibration matrices for the given qubits and given number of shots
+# By default it is over all backend qubits at 8192 shots.
+mit.tensored_cals_from_system(qubits, shots)
+
+# Apply mitigation to a given dict of raw counts over the specified qubits
+m3_quasi = mit.apply_correction(raw_counts, qubits)
+```
+Note that here `qubits` is a list of which qubits are measured to yield the bits in the output.
+For example the list `[4,3,1,2,0]` indicates that a measurement on physical qubit 4 was written to
+classical bit zero in the output bit-strings, physical qubit 3 maps to classical bit 1, etc.
+The fact that the zeroth bit is right-most in the bitstring is handled internally.
+
+The results of M3 mitigation are quasi-probabilities that contain small negative values.
+This is suitable for use in computing corrected expectation values.  However, if one needs
+a true probability distribution then it is possible to convert from quasi-probabilites to
+the closest true probability distribution in L2-norm using:
+
+```python
+closest_probs = m3_quasi.nearest_probability_distribution()
+```
+
+An additional benefit of the way M3 works is that it is possible to compute the effect of mitigation when only
+looking at errors that are up to a given Hamming distance away.  This slightly increases the computational cost, but
+allows for investigating if large weight errors have much impact on the output.  This can be controlled by the `distance` keyword argument in `apply_correction`:
+
+```python
+m3_quasi = mit.apply_correction(raw_counts, qubits, distance=DIST)
+```
+By default, M3 computes errors out to the full distance.
+
+## License
+
+(C) Copyright IBM Quantum 2021.
+This code is for internal IBM Quantum use only.

docs/Makefile

@@ -0,0 +1,28 @@
+# This code is part of Kaleidoscope
+#
+# (C) Copyright IBM 2020.
+#
+# 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.
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/custom.css

@@ -0,0 +1,27 @@
+.toggle .header {
+    display: block;
+    clear: both;
+    background-color: #785EF0;
+    color: #f9f9f9;
+    height: 40px;
+    padding-top: 10px;
+    padding-left: 5px;
+    margin-bottom: 20px;
+}
+
+.toggle .header:before {
+    float: left;
+    content: "▶ ";
+    font-size: 20px;
+
+}
+
+.toggle .header.open:before {
+    float: left;
+    content: "▼ ";
+    font-size: 20px;
+}
+
+.toggle{
+  background: #FBFBFB;
+}