Add tags to tutorials (#2467)

* add tags configuration + techniques/interface tags * remove sphinx tags version number * add sphinx-design and sphinx-tags to reqs.txt * pin versions for tags and design * create a separate tags page * tags for difficulty levels * remove tags page from index * add _tags to gitignore * correct typo * delete md files in _tags * update path to _tags * alessandro's comment: update tags page title * nate's suggestion * Update .gitignore
unitaryfund · Aug 30, 2024 · bb44aa4 · bb44aa4
1 parent c94dff7
commit bb44aa4
Show file tree

Hide file tree

Showing 39 changed files with 174 additions and 5 deletions.
diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@
 _build
 __pycache__/
 docs/build/
+docs/source/tags/
 mitiq.egg-info/
 dist/
 build/

diff --git a/docs/CONTRIBUTING_DOCS.md b/docs/CONTRIBUTING_DOCS.md
@@ -212,7 +212,7 @@ To call sphinx directly, `cd` into the `docs` directory and run
 sphinx-build -b html source build
 ```
 
-These commands generate the `docs/build` folder, which is ignore by the `.gitignore` file.
+These commands generate the `docs/build` folder, which is ignored by the `.gitignore` file.
 Once the documentation is generated you can view it by opening it in your browser.
 
 ## Testing the Documentation 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -98,8 +98,42 @@ def setup(app):
     "sphinx_copybutton",
     "nbsphinx",
     "sphinx_gallery.load_style",
+    "sphinx_design",
+    "sphinx_tags",
 ]
 
+# to add tags to the documentation tutorials
+tags_create_tags = True
+tags_output_dir = "tags/"
+tags_overview_title = "All tags"
+tags_create_badges = True
+tags_intro_text = "Tags on this page: "
+tags_page_title = "Tags"
+tags_page_header = "Pages with this tag: "
+tags_index_head = "Tags in the documentation tutorials: "
+tags_extension = ["md"]
+tags_badge_colors = {
+    "zne": "primary",
+    "rem": "primary",
+    "shadows": "primary",
+    "cdr": "primary",
+    "pec": "primary",
+    "ddd": "primary",
+    "calibration": "primary",
+    "cirq": "secondary",
+    "bqskit": "secondary",
+    "braket": "secondary",
+    "pennylane": "secondary",
+    "qiskit": "secondary",
+    "stim": "secondary",
+    "qrack": "secondary",
+    "qibo": "secondary",
+    "ionq": "secondary",
+    "basic": "success",
+    "intermediate": "success",
+    "advanced": "success",
+}
+
 # hide primary sidebar from the following pages
 html_sidebars = {"apidoc": [], "changelog": [], "bibliography": []}
 

diff --git a/docs/source/examples/bqskit.md b/docs/source/examples/bqskit.md
@@ -10,6 +10,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} bqskit, zne, intermediate
+```
+
 # Improving the accuracy of BQSKit compiled circuits with error mitigation
 
 In this tutorial we describe how to use error mitigation capabilities from [Mitiq](https://mitiq.readthedocs.io/en/stable/) together with the compilation capabilities of [BQSKit](https://bqskit.lbl.gov/) {cite}`Patel_2022_ACM`, a compiler for quantum circuits. BQSKit stands for Berkeley Quantum Synthesis Toolkit and it allows one "to compile quantum programs to efficient physical circuits for any QPU".

diff --git a/docs/source/examples/braket_mirror_circuit.md b/docs/source/examples/braket_mirror_circuit.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} braket, zne, basic
+```
+
 # Mitiq with Braket
 
 This notebook shows improved performance on a mirror circuit benchmark with zero-noise extrapolation on Rigetti Aspen-9 via Amazon Braket.

diff --git a/docs/source/examples/calibration-tutorial.md b/docs/source/examples/calibration-tutorial.md
@@ -12,6 +12,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} calibration, zne, qiskit, basic
+```
+
 # Breaking into error mitigation with Mitiq's calibration module
 
 <img src="../_thumbnails/calibration.png" width="400">

diff --git a/docs/source/examples/cdr_qrack.md b/docs/source/examples/cdr_qrack.md
@@ -12,6 +12,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} qiskit, cdr, qrack, cirq, basic
+```
+
 # CDR with Qrack as Near-Clifford Simulator
 
 In this tutorial, [Clifford Data Regression](../guide/cdr.md) (CDR) is used with [Qrack](https://qrack.readthedocs.io/en/latest/) and a Qiskit fake backend.

diff --git a/docs/source/examples/cirq-ibmq-backends.md b/docs/source/examples/cirq-ibmq-backends.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cirq, zne, qiskit, basic
+```
+
 # Error mitigation with Cirq on IBMQ backends
 
 

diff --git a/docs/source/examples/combine_ddd_zne.md b/docs/source/examples/combine_ddd_zne.md
@@ -11,6 +11,8 @@ kernelspec:
   language: python
   name: python3
 ---
+```{tags} ddd, zne, cirq, intermediate
+```
 
 # Composing techniques: Digital Dynamical Decoupling and Zero Noise Extrapolation
 

diff --git a/docs/source/examples/combine_rem_zne.md b/docs/source/examples/combine_rem_zne.md
@@ -11,6 +11,8 @@ kernelspec:
   language: python
   name: python3
 ---
+```{tags} rem, zne, cirq, intermediate
+```
 
 # Composing techniques: Readout Error Mitigation and Zero Noise Extrapolation
 

diff --git a/docs/source/examples/ddd_on_ibmq_ghz.md b/docs/source/examples/ddd_on_ibmq_ghz.md
@@ -11,6 +11,8 @@ kernelspec:
   language: python
   name: python3
 ---
+```{tags} ddd, qiskit, basic
+```
 
 # Digital dynamical decoupling (DDD) with Qiskit on GHZ Circuits
 

diff --git a/docs/source/examples/ddd_tutorial.md b/docs/source/examples/ddd_tutorial.md
@@ -10,6 +10,8 @@ kernelspec:
   language: python
   name: python3
 ---
+```{tags} ddd, cirq, basic
+```
 
 # Digital dynamical decoupling (DDD) with Mirror Circuits
 

diff --git a/docs/source/examples/examples.md b/docs/source/examples/examples.md
@@ -1,6 +1,8 @@
 # Examples
 
-Below you can find a gallery of tutorials applying Zero Noise Extrapolation (ZNE), Probabilistic Error Cancellation (PEC), Clifford Data Regression (CDR), and Digital Dynamical Decoupling (DDD) with Mitiq:
+Below you can find a gallery of tutorials applying Zero Noise Extrapolation (ZNE), Probabilistic Error Cancellation (PEC), Clifford Data Regression (CDR), and Digital Dynamical Decoupling (DDD), etc. with Mitiq.
+
+You can also search for an example utilizing a specific QEM technique, frontend, backend or difficulty level by clicking through the tags available [here.](tags.md)
 
 ```{nbgallery}
 ZNE Calibration with Qiskit <calibration-tutorial.md>
@@ -37,4 +39,4 @@ GGI Summer School ZNE Hands-On Tutorial <ggi_summer_school_unsolved.md>
 Composing techniques: REM + ZNE <combine_rem_zne.md>
 Composing techniques: DDD + ZNE <combine_ddd_zne.md>
 The Mitiq paper code <mitiq-paper/mitiq-paper-codeblocks.md>
-```
+```
diff --git a/docs/source/examples/ggi_summer_school_unsolved.md b/docs/source/examples/ggi_summer_school_unsolved.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} qiskit, zne, intermediate
+```
+
 # Hands-on lab on error mitigation with Mitiq.
 
 +++

diff --git a/docs/source/examples/hamiltonians.md b/docs/source/examples/hamiltonians.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cirq, zne, advanced
+```
+
 # Defining Hamiltonians as Linear Combinations of Pauli Strings
 
 This tutorial shows an example of using Hamiltonians defined as {class}`~cirq.PauliSum` objects or similar objects in other

diff --git a/docs/source/examples/ibmq-backends.md b/docs/source/examples/ibmq-backends.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} qiskit, zne, basic
+```
+
 # Error mitigation on IBMQ backends with Qiskit
 
 

diff --git a/docs/source/examples/layerwise-folding.md b/docs/source/examples/layerwise-folding.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} qiskit, zne, intermediate
+```
+
 # ZNE with Qiskit: Layerwise folding
 
 

diff --git a/docs/source/examples/learning-depolarizing-noise.md b/docs/source/examples/learning-depolarizing-noise.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cirq, pec, advanced
+```
+
 # Learning quasiprobability representations with a depolarizing noise model
 
 In this example, we demonstrate the workflow of learning quasiprobability representations of a `CNOT` gate with a depolarizing noise model,

diff --git a/docs/source/examples/maxcut-demo.md b/docs/source/examples/maxcut-demo.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cirq, zne, advanced
+```
+
 # Solving MaxCut with Mitiq-improved QAOA
 
 +++

diff --git a/docs/source/examples/molecular_hydrogen.md b/docs/source/examples/molecular_hydrogen.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cirq, zne, advanced
+```
+
 # Estimating the potential energy surface of molecular Hydrogen with ZNE and OpenFermion
 
 In this example we apply zero-noise extrapolation (ZNE) to the estimation of the potential energy surface of molecular Hydrogen ($\rm H_2$).

diff --git a/docs/source/examples/molecular_hydrogen_pennylane.md b/docs/source/examples/molecular_hydrogen_pennylane.md
@@ -10,6 +10,8 @@ kernelspec:
   language: python
   name: python3
 ---
+```{tags} cirq, pennylane, zne, advanced
+```
 
 # Estimating the potential energy surface of molecular Hydrogen with ZNE and PennyLane + Cirq
 

diff --git a/docs/source/examples/pec_tutorial.md b/docs/source/examples/pec_tutorial.md
@@ -11,6 +11,8 @@ kernelspec:
   name: python3
 ---
 
+```{tags} pec, cirq, qiskit, basic
+```
 # Probabilistic error cancellation (PEC) with Mirror Circuits
 
 This notebook shows probabilistic error cancellation (PEC) *Temme et al. PRL (2017)* {cite}`Temme_2017_PRL`, *Sun et al. PRLAppl (2021)* {cite}`Sun_2021_PRAppl`,  *Zhang et al. NatComm (2020)* {cite}`Zhang_2020_NatComm`, improving performance of a mirror circuit benchmark  on the `braket_dm` noisy simulator.

diff --git a/docs/source/examples/pennylane-ibmq-backends.md b/docs/source/examples/pennylane-ibmq-backends.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} qiskit, zne, pennylane, basic
+```
+
 # Error mitigation with Pennylane on IBMQ backends
 
 In this tutorial we will cover how to use Mitiq in conjunction with [PennyLane](https://pennylane.ai/), and further how to run error-mitigated circuits on IBMQ backends.

diff --git a/docs/source/examples/pyquil_demo.ipynb b/docs/source/examples/pyquil_demo.ipynb
diff --git a/docs/source/examples/qibo-noisy-simulation.md b/docs/source/examples/qibo-noisy-simulation.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} qibo, zne, basic
+```
+
 # Error mitigation with Qibo using noisy simulation
 
 In this tutorial we will cover how to use Mitiq to apply [Zero-Noise Extrapolation](../guide/zne.md) (ZNE) to a quantum program written using [Qibo](https://qibo.science/).

diff --git a/docs/source/examples/quantum_simulation_1d_ising.md b/docs/source/examples/quantum_simulation_1d_ising.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cdr, zne, cirq, advanced
+```
+
  # Using ZNE and learning-based methods to mitigate the 1D transverse-longitudinal Ising model
 
 In this tutorial, we employ ZNE, CDR, and VNCDR mitigation techniques to address errors in the simulation of the 1-D Transverse-Longitudinal Ising model using Mitiq. It is important to note that the results presented here are not original, but rather an attempt to reproduce some of the findings outlined in the paper available at {cite}`Sopena_2023_Quantum`.

diff --git a/docs/source/examples/quantum_simulation_scars_ibmq.md b/docs/source/examples/quantum_simulation_scars_ibmq.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} qiskit, zne, advanced
+```
+
 ```{code-cell} ipython3
 import qiskit
 from qiskit import QuantumCircuit

diff --git a/docs/source/examples/rshadows_tutorial.md b/docs/source/examples/rshadows_tutorial.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} shadows, cirq, intermediate
+```
+
 # Robust Shadow Estimation with Mitiq
 
 **Corresponding to:** Min Li ([email protected])

diff --git a/docs/source/examples/scaling.md b/docs/source/examples/scaling.md
@@ -11,6 +11,8 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cirq, zne, basic
+```
 # Noise Scaling Methods
 
 In this tutorial we will compare two noise scaling methods available for use in [Zero-Noise Extrapolation](https://mitiq.readthedocs.io/en/stable/guide/zne.html) (ZNE): identity insertion and unitary folding.

diff --git a/docs/source/examples/shadows_tutorial.md b/docs/source/examples/shadows_tutorial.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cirq, shadows, intermediate
+```
+
 # Classical Shadows Protocol with Cirq
 
 **Corresponding to:** Min Li ([email protected])

diff --git a/docs/source/examples/simple-landscape-braket.md b/docs/source/examples/simple-landscape-braket.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} braket, zne, advanced
+```
+
 # Using ZNE to compute the energy landscape of a variational circuit with Braket
 
 This tutorial shows an example in which the energy landscape for a two-qubit variational circuit is explored with and without error mitigation, using Amazon's [Braket](https://amazon-braket-sdk-python.readthedocs.io/en/latest/) as our frontend.

diff --git a/docs/source/examples/simple-landscape-cirq.md b/docs/source/examples/simple-landscape-cirq.md
@@ -11,6 +11,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} cirq, zne, advanced
+```
+
 # Mitigating the energy landscape of a variational circuit with Mitiq
 
 +++

diff --git a/docs/source/examples/simple-landscape-pennylane.md b/docs/source/examples/simple-landscape-pennylane.md
@@ -12,6 +12,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} pennylane, zne, advanced
+```
+
 # Mitigating the energy landscape of a variational circuit with Mitiq and PennyLane
 
 This tutorial shows an example in which the energy landscape for a two-qubit variational circuit is explored

diff --git a/docs/source/examples/simple-landscape-qiskit.md b/docs/source/examples/simple-landscape-qiskit.md
@@ -12,6 +12,9 @@ kernelspec:
   name: python3
 ---
 
+```{tags} qiskit, zne, advanced
+```
+
 # Using ZNE to compute the energy landscape of a variational circuit with Qiskit
 
 This tutorial shows an example in which the energy landscape for a two-qubit variational circuit is explored with and without error mitigation, using Qiskit as our frontend.

diff --git a/docs/source/examples/tags.md b/docs/source/examples/tags.md
@@ -0,0 +1,22 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.1
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+orphan: true
+---
+
+# Tags
+
+```{toctree}
+---
+maxdepth: 2
+---
+../../tags/tagsindex.md
+```
diff --git a/docs/source/examples/vqe-pyquil-demo.ipynb b/docs/source/examples/vqe-pyquil-demo.ipynb
@@ -33,6 +33,15 @@
     "## Defining the quantum system using pyQuil"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "b3340e15",
+   "metadata": {},
+   "source": [
+    "```{tags} zne, advanced\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,