Initial Commit

MANIFEST.in

@@ -0,0 +1 @@
+include _version.py

README.md

@@ -0,0 +1,53 @@
+# qermit
+
+`qermit` is a python module for running error mitigation protocols on quantum processors using [`pytket`](https://github.com/CQCL/pytket), CQC's python module for interfacing with [CQC](https://cambridgequantum.com/) tket, a set of quantum programming tools.
+
+This repo containts API documentation, a user manual for getting started with `qermit` and source code.
+
+## Getting Started
+
+`qermit` is available for ``python3.7`` or higher, on Linux, MacOS and Windows.
+To install, ensure that you have `pip` version 19 or above, and run
+
+``pip install qermit``
+
+**Documentation** can be found at [cqcl.github.io/qermit](https://cqcl.github.io/qermit)
+
+A **User Manual** can be found at TODO fill:
+
+
+## Bugs and feature requests
+
+Please file bugs and feature requests on the Github
+[issue tracker](https://github.com/CQCL/qermit/issues).
+
+
+## Contributing
+
+Pull requests are welcome. To make a PR, first fork the repo, make your proposed
+changes on the `master` branch, and open a PR from your fork. If it passes
+tests and is accepted after review, it will be merged in.
+
+### Code style
+
+#### Formatting
+
+All code should be formatted using
+[black](https://black.readthedocs.io/en/stable/), with default options. 
+
+#### Type annotation
+
+On the CI, [mypy](https://mypy.readthedocs.io/en/stable/) is used as a static
+type checker and all submissions must pass its checks. You should therefore run
+`mypy` locally on any changed files before submitting a PR. 
+
+### Tests
+
+To run the tests:
+
+1. `cd` into the `tests` directory;
+2. ensure you have installed `pytest`;
+3. run `pytest`.
+
+When adding a new feature, please add a test for it. When fixing a bug, please
+add a test that demonstrates the fix.

_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+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/build_docs.sh

@@ -0,0 +1,2 @@
+rm -rf ./_build
+sphinx-build -b html ./ ./_build

docs/clifford_noise_characterisation.rst

@@ -0,0 +1,26 @@
+qermit.clifford_noise_characterisation
+======================================
+
+.. automethod:: qermit.clifford_noise_characterisation.ccl.gen_CDR_MitEx
+
+.. autoclass:: qermit.clifford_noise_characterisation.ccl.LikelihoodFunction
+    :members:
+    :special-members:
+
+.. automethod:: qermit.clifford_noise_characterisation.dfsc.gen_DFSC_MitEx
+
+.. automethod:: qermit.clifford_noise_characterisation.ccl.ccl_state_task_gen
+
+.. automethod:: qermit.clifford_noise_characterisation.ccl.ccl_result_batching_task_gen
+
+.. automethod:: qermit.clifford_noise_characterisation.ccl.ccl_likelihood_filtering_task_gen
+
+.. automethod:: qermit.clifford_noise_characterisation.dfsc.DFSC_circuit_task_gen
+
+.. automethod:: qermit.clifford_noise_characterisation.dfsc.DFSC_collater_task_gen
+
+.. automethod:: qermit.clifford_noise_characterisation.dfsc.DFSC_characterisation_task_gen
+
+.. automethod:: qermit.clifford_noise_characterisation.dfsc.DFSC_correction_task_gen
+
+

docs/conf.py

@@ -0,0 +1,89 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "qermit"
+copyright = "2021, Cambridge Quantum Computing Ltd"
+author = "Cambridge Quantum Computing Ltd"
+
+# The short X.Y version
+version = "0.1"
+# The full version, including alpha/beta/rc tags
+release = "0.1.0"
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ".rst"
+
+# The master toctree document.
+master_doc = "index"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "qermitdoc"

docs/frame_randomisation.rst

@@ -0,0 +1,12 @@
+qermit.frame_randomisation
+==========================
+
+.. automethod:: qermit.frame_randomisation.frame_randomisation.gen_Frame_Randomisation_MitRes
+
+.. autoclass:: qermit.frame_randomisation.frame_randomisation.FrameRandomisation
+    :members:
+    :special-members:
+
+.. automethod:: qermit.frame_randomisation.frame_randomisation.frame_randomisation_circuits_task_gen
+
+.. automethod:: qermit.frame_randomisation.frame_randomisation.frame_randomisation_result_task_gen

docs/index.rst

@@ -0,0 +1,146 @@
+qermit
+======
+
+.. image:: CQCLogo.png
+   :width: 120px
+   :align: right
+
+``qermit`` is a python module for running error mitigation protocols on quantum computers using ``pytket``, 
+CQC's python module for interfacing with `CQC <https://cambridgequantum.com/>`_ tket, a set of quantum programming tools. 
+``qermit`` functions using the ``pytket`` :py:class:`Backend` class, meaning ``qermit`` supports any of the 
+`numerous providers <https://github.com/CQCL/pytket-extensions>`_ ``pytket`` does.
+``qermit`` also provides easy composability of error mitigation methods, meaning 
+it is practically straightforward to run an experiment with multiple forms of error-mitigation 
+where appropriate.
+
+``qermit`` is compatible with ``pytket`` 0.11.0.
+
+To install, run
+
+``pip install qermit``
+
+To use ``qermit``, simply import the appropriate modules into your python code or into an interactive Python notebook.
+
+Error-mitigation methods in ``qermit`` fit in to two distinctions, ``MitRes`` methods 
+that result in a modification of a distribution of counts  retrieved from some 
+quantum computer, and ``MitEx`` methods that result in the modification of the 
+expectation value of some observable.
+
+In their basic capacity, ``MitRes`` and ``MitEx`` objects will run experiments without error mitigation.
+
+::
+
+   from qermit import MitRes, CircuitShots
+   from pytket import Circuit
+   from pytket.extensions.qiskit import AerBackend
+
+   mitres = MitRes(backend = AerBackend())
+   c = Circuit(2,2).H(0).Rz(0.25,0).CX(1,0).measure_all()
+   results = mitres.run([CircuitShots(Circuit = c, Shots = 50)])
+   print(results[0].get_counts())
+
+::
+   
+   Counter({(0, 0): 25, (1, 0): 25})
+
+
+The ``MitRes.run`` method takes a list of ``CircuitShots`` as an argument
+and returns a ``pytket`` ``BackendResult`` object for each list element.
+
+The ``MitRes`` and ``MitEx`` objects hold a graph of ``MitTask`` objects (a ``TaskGraph``). A ``MitTask``
+object is a pure function that computes some basic step in a typical experiment. When the run function
+is called, a topological sort is applied to the graph to order these tasks and then each is run sequentially.
+
+In its default construction, a ``MitRes`` object will simply run each Circuit through the backend it is defined by.
+
+::
+
+   mitres.get_task_graph()
+
+.. image:: mitresgraph.png
+
+Similarly, in its default construction a ``MitEx`` object will simply estimate the expectation of each observable 
+desired without applying any mitigation method.
+
+::
+
+   from qermit import MitEx, AnsatzCircuit, ObservableExperiment, ObservableTracker
+   from pytket.pauli import Pauli, QubitPauliString
+   from pytket.utils import QubitPauliOperator
+
+   mitex = MitEx(backend = AerBackend())
+   qubit_pauli_string = QubitPauliString([Qubit(1), Qubit(2)], [Pauli.Z, Pauli.Z])
+   qubit_pauli_operator = QubitPauliOperator({qubit_pauli_String: 1.0})
+   ansatz_circuit = AnsatzCircuit(
+      Circuit = Circuit(3,3).X(0).X(1), 
+      Shots = 50, 
+      SymbolsDict = SymbolsDict()
+   )
+   experiment = ObservableExperiment(
+      AnsatzCircuit = ansatz_circuit, 
+      ObservableTracker = ObservableTracker(qubit_pauli_operator)
+   )
+   mitex_results = mitex.run([experiment])
+   print(mitex_results)
+
+::
+
+   [{(Zq[1], Zq[2]): -1.00000000000000}]
+
+The ``MitEx.run`` method takes a list of ``ObservableExperiment`` objects as an argument. Each ``ObservableExperiment`` objects
+contains the basic information required to estimate the expectation value of an observable; a state preparation circuit,
+a dictionary between symbols and parameter values (where appropriate), a ``pytket`` ``QubitPauliOperator`` detailing the 
+operator being measured and used for preparing measurement circuits, and the number of shots to run for each measurement circuit.
+
+Each experiment returns a ``QubitPauliOperator`` object containing an expectation value for each internal ``QubitPauliString``. In its default
+version, this is achieved by appending a measurement circuit for each ``QubitPauliString`` to the ansatz circuit and executing through
+the ``pytket`` ``Backend`` the ``MitEx`` object is defined by.
+
+::
+
+   mitex.get_task_graph()
+
+.. image:: mitexgraph.png
+
+.. TODO: add user manual link ....
+
+See the Qermit User Manual page for an extended tutorial on using ``qermit``, including
+pre-defined error mitigation methods and composing error mitigation methods.
+
+``qermit`` currently provides the following error mitigation schemes (under their commonly known names):
+
+* SPAM Correction
+* Frame Randomisation
+* Zero-Noise Extrapolation
+* Probabilistic-Error-Cancellation
+* Clifford Data Regression
+* Depolarisation-Factor-Supression-For-Nearest-Clifford 
+
+.. How to cite
+.. ~~~~~~~~~~~
+.. If you wish to cite qermit in any academic pulibcations, we generally recommend 
+.. citing our paper TODO: add paper link.
+
+User Support
+~~~~~~~~~~~~
+
+If you have problems with the use of qermit or you think you have found a bug, there 
+are several ways to contact us:
+- Write an email to [email protected] and ask for help with your problem.
+- You can write a bug report on the `CQC github <https://github.com/CQCL/qermit/issues>`_ with details of the problem and we will pick that up. You can also have a look on that page so see if your problem has already been reported by someone else.
+
+.. toctree::
+   :caption: API Reference:
+   :maxdepth: 2
+
+   taskgraph.rst
+   mitres.rst
+   mitex.rst
+   utils.rst
+   mittask.rst
+   measurement_reduction.rst
+   spam.rst
+   frame_randomisation.rst
+   clifford_noise_characterisation.rst
+   zero_noise_extrapolation.rst
+   probabilistic_error_cancellation.rst

docs/measurement_reduction.rst

@@ -0,0 +1,8 @@
+qermit.measurement_reduction
+============================
+
+.. currentmodule:: qermit.taskgraph.measurement_reduction.MeasurementReduction
+
+.. automethod:: qermit.taskgraph.measurement_reduction.measurement_reduction_task_gen
+.. automethod:: qermit.taskgraph.measurement_reduction.gen_MeasurementReduction_MitEx
+

docs/mitex.rst

@@ -0,0 +1,21 @@
+qermit.mitex
+================
+
+.. currentmodule:: qermit.taskgraph.mitex.MitEx
+.. autoclass:: qermit.taskgraph.mitex.MitEx
+    :special-members:
+    :members:
+
+.. automethod:: qermit.taskgraph.mitex.gen_compiled_MitRes
+
+.. automethod:: qermit.taskgraph.mitex.get_basic_measurement_circuit
+
+.. automethod:: qermit.taskgraph.mitex.filter_observable_tracker_task_gen
+
+.. automethod:: qermit.taskgraph.mitex.collate_circuit_shots_task_gen
+
+.. automethod:: qermit.taskgraph.mitex.split_results_task_gen
+
+.. automethod:: qermit.taskgraph.mitex.get_expectations_task_gen
+
+