New guides page for circuit cutting addon

docs/guides/_toc.json

@@ -534,7 +534,7 @@
                   "url": "/guides/qiskit-addons-sqd"
                 },
                 {
-                  "title": "Getting started with SQD",
+                  "title": "Get started with SQD",
                   "url": "/guides/qiskit-addons-sqd-get-started"
                 }
               ]
@@ -547,7 +547,7 @@
                   "url": "/guides/qiskit-addons-aqc"
                 },
                 {
-                  "title": "Getting started with AQC-Tensor",
+                  "title": "Get started with AQC-Tensor",
                   "url": "/guides/qiskit-addons-aqc-get-started"
                 }
               ]
@@ -560,7 +560,7 @@
                   "url": "/guides/qiskit-addons-obp"
                 },
                 {
-                  "title": "Getting started with OBP",
+                  "title": "Get started with OBP",
                   "url": "/guides/qiskit-addons-obp-get-started"
                 }
               ]
@@ -577,6 +577,23 @@
                   "url": "/guides/qiskit-addons-mpf-get-started"
                 }
               ]
+            },
+            {
+              "title": "Circuit cutting (CC)",
+              "children": [
+                {
+                  "title": "Circuit cutting overview",
+                  "url": "/guides/qiskit-addons-cutting"
+                },
+                {
+                  "title": "Get started with gate cuts",
+                  "url": "/guides/qiskit-addons-cutting-gates"
+                },
+                {
+                  "title": "Get started with wire cuts",
+                  "url": "/guides/qiskit-addons-cutting-wires"
+                }
+              ]
             }
           ]
         },

docs/guides/optimize-for-hardware.mdx

@@ -63,6 +63,9 @@ can be run on IBM® hardware using IBM Qiskit Runtime.
 
 ### Qiskit addons
 * [Approximate Quantum Compilation with Tensor Networks (AQC-Tensor)](./qiskit-addons-aqc)
-  * [Getting started with AQC-Tensor](./qiskit-addons-aqc-get-started)
+  * [Get started with AQC-Tensor](./qiskit-addons-aqc-get-started)
 * [Operator Backpropagation (OBP)](./qiskit-addons-obp)
-  * [Getting started with OBP](./qiskit-addons-obp-get-started)
+  * [Get started with OBP](./qiskit-addons-obp-get-started)
+* [Circuit cutting](./qiskit-addons-cutting)
+  * [Get started with circuit cutting using gate cuts](./qiskit-addons-cutting-gates)
+  * [Get started with circuit cutting using wire cuts](./qiskit-addons-cutting-wires)

docs/guides/qiskit-addons-cutting.mdx

@@ -0,0 +1,153 @@
+---
+title: Circuit cutting
+description: Overview of the addon for circuit cutting to build utility-scale workloads
+---
+
+# Circuit cutting
+
+Circuit cutting is a technique to increase the size of circuits that can run on quantum hardware, at the cost of an additional sampling overhead. This addon implements this technique, in which a handful of gates, wires, or both are cut, resulting in smaller circuits that are better suited for execution on hardware. These smaller circuits are then executed, and the results of the original circuit are reconstructed through classical post-processing. However, the trade-off is that the overall number of shots must increase by a factor that is dependent on the number and type of cuts made (known as the sampling overhead). Circuit cutting can also be used to engineer gates between distant qubits which would otherwise require a large swap overhead.
+
+### Important terms
+
+- **subcircuits**: The set of circuits resulting from cutting gates in a `QuantumCircuit` and then separating the disconnected qubit subsets into smaller circuits. These circuits contain [`SingleQubitQPDGate`s](/api/qiskit-addon-cutting/qpd-single-qubit-qpd-gate) and are used to instantiate each subexperiment.
+
+- **subexperiment**: A term used to describe the unique circuit samples associated with a subcircuit, which are sent to a QPU for execution.
+
+## Install the circuit cutting package
+
+There are three ways to install the circuit cutting package: PyPI, building from source, and running within a containerized environment. It is recommended to install these packages in a [virtual environment](https://docs.python.org/3.10/tutorial/venv.html) to ensure separation between package dependencies.
+
+### Install from PyPI
+
+The most straightforward way to install the `qiskit-addon-cutting` package is with PyPI:
+```bash
+pip install qiskit-addon-cutting
+```
+
+### Install from source
+
+<details>
+<summary>
+Click here to read how to install this package manually.
+</summary>
+
+To contribute to this package or to install it manually, first clone the repository:
+
+```bash
+git clone git@github.com:Qiskit/qiskit-addon-cutting.git
+```
+and install the package with `pip`. To run the tutorials found in the package repository, install the notebook dependencies as well. Install the `dev` dependencies if you plan on developing in the repository.
+```bash
+pip install tox notebook -e '.[notebook-dependencies,dev]'
+```
+
+</details>
+
+### Use within Docker
+
+The dockerfile included in the addon repository can be used to build a Docker image. There is also a `compose.yaml` file that allows you to use the Docker image with the following commands.
+
+<details>
+<summary>
+Click here to read how to use this package within Docker.
+</summary>
+
+```bash
+git clone git@github.com:Qiskit/qiskit-addon-cutting.git
+cd qiskit-addon-cutting
+docker compose build
+docker compose up
+```
+<Admonition type="note" title="Note">
+    If you are using `podman` and `podman-compose` instead of `docker`, the commands are:
+    ```bash
+    podman machine start
+    podman-compose --podman-pull-args short-name-mode="permissive" build
+    podman-compose up
+    ```
+</Admonition>
+
+Once the container is running, you should see a message similar to:
+```
+notebook_1  |     To access the server, open this file in a browser:
+notebook_1  |         file:///home/$USERNAME/.local/share/jupyter/runtime/jpserver-7-open.html
+notebook_1  |     Or copy and paste one of these URLs:
+notebook_1  |         http://e4a04564eb39:8888/lab?token=00ed70b5342f79f0a970ee9821c271eeffaf760a7dcd36ec
+notebook_1  |      or http://127.0.0.1:8888/lab?token=00ed70b5342f79f0a970ee9821c271eeffaf760a7dcd36ec
+```
+
+The *last* URL in this message will give you access to the Jupyter notebook interface. 
+
+Additionally, the home directory includes a subdirectory named persistent-volume. All work you would like to save should be placed in this directory, as it is the only one that will be saved across different container runs.
+
+
+</details>
+
+## Theoretical background
+
+In the circuit cutting process, there are two types of cuts: a **gate** or "space-like" cut, where a cut goes through a gate operating on two (or more) qubits, and a **wire** or "time-like" cut, which cuts directly through a qubit wire (essentially a single-qubit identity gate that has been cut into two pieces).
+
+![Diagram of circuit cutting by taking one larger circuit and cutting it into two smaller ones](/images/guides/qiskit-addons/circuit-cutting-diagram.avif)
+
+There are also three scenarios to consider when preparing a circuit cutting workflow; which center around the availability of classical communication between the circuit executions. The first is where only local operations (LO) are available while the other two introduce classical communication between executions known as local operations and classical communication (LOCC). The LOCC scenarios are then grouped into either near-time, one-directional communication between circuit executions or real-time, bi-directional communication (which you might see in a multi-QPU environment).
+
+While circuit cutting can be used to execute quantum circuits larger than what is possible on currently available hardware, it does come at a cost. Because the technique can be framed as a quasiprobability decomposition (QPD) problem, there is an exponential sampling overhead required in order to reconstruct the results. This overhead is the factor by which the overall number of shots must increase in order for the quasiprobability decomposition to result in the same amount of error, $\epsilon$, as you would get by executing the original circuit. Each cut gate contributes to this overhead and the amount of overhead added is dependent on the type of gate that was cut (more details on the overhead sampling can be found in final appendix of [[1]](#references)).
+
+For example, a single cut CNOT gate incurs a sampling overhead of 9 [[2,6]](#references) and a circuit with $n$ wire cuts incurs a sampling overhead of $\mathcal{O}(16^n)$ when classical communication is not available (the LO scenario). This is reduced to $\mathcal{O}(4^n)$ when classical communication becomes available (LOCC scenario) [[4]](#references). However, wire cutting with classical communication (LOCC) is not yet supported by this package.
+
+Formally, the QPD problem of circuit cutting can be expressed as follows:
+
+$$ \mathcal{U} = \sum_i a_i \mathcal{F}_i,$$
+
+where $\mathcal{U}$ is the quantum channel implementing the desired operation, and each $a_i$ is a real coefficient corresponding to a channel, $\mathcal{F}_i$, that is executable on hardware.
+
+The results equivalent to the desired channel $\mathcal{U}$ are obtained by first generating the coefficients, $a_i$, then executing subexperiments to obtain the outcomes of the different channels $\mathcal{F}_i$ in order to reconstruct the expectation values corresponding to $\mathcal{U}$.
+
+### A short example: cutting a RZZGate
+
+As a basic explicit example, let's consider the decomposition of a cut RZZGate (all the details can be found in [[2]](#references)). A quantum circuit which contains an RZZGate can be simulated by performing six subexperiments where the RZZGate has been replaced with only single-qubit operations (these are the $\mathcal{F}_i$'s from the equation above). The results of this circuit are reconstructed by combining the results of each subexperiment alongside a set of coefficients (the $a_i$'s from the equation above) which can be either positive or negative.
+
+For some chosen $\theta$ parameter for the RZZGate, the six subexperiments are as follows:
+1. With coefficient $a_1 = \cos^2(\theta/2)$, do nothing ($I\otimes I$)
+1. With coefficient $a_2 = \sin^2(\theta/2)$, perform a ZGate on each qubit ($Z\otimes Z$)
+1. With coefficient $a_3 = -\sin(\theta)/2$, perform a projective measurement in the $Z$ basis on the first qubit and an $S$ on the second ($M_z\otimes S^\dagger$). If the result of the measurement is $1$, flip the sign of that outcome's contribution during reconstruction.
+1. With coefficient $a_4 = \sin(\theta)/2$, perform a projective measurement in the $Z$ basis on the first qubit and an $S^\dagger$ on the second ($M_z\otimes S^\dagger$). If the result of the measurement is 1, flip the sign of that outcome's contribution during reconstruction.
+1. Same as 3. ($a_5=a_3$), but swap the qubits (perform $S\otimes M_z$ instead).
+1. Same as 4. ($a_6=a_4$), but swap the qubits (perform $S^\dagger\otimes M_z$ instead).
+
+### Sampling overhead reference table
+
+The below table provides the sampling overhead factor for a variety of two-qubit instructions, provided that only a single instruction is cut.
+| Instructions | KAK decomposition angles | Sampling overhead factor |
+| --- | --- | --- |
+| CSGate, CSdgGate, CSXGate | $\left(\pi/8, 0, 0\right)$ | $3+2\sqrt(2) \approx 2.828$ |
+| CXGate, CYGate, CZGate, GHGate, ECRGate | $\left(\pi/4, 0, 0\right)$ | $3^2=9$ |
+| iSwapGate, DCXGate | $\left(\pi/4, \pi/4, 0\right)$ | $7^2 = 49$ |
+| SwapGate | $\left(\pi/4, \pi/4, \pi/4\right)$ | $7^2 = 49$ |
+| RXXGate, RYYGate, RZZGate, RZXGate | $\left(\lvert\theta/2\rvert, 0, 0, \right)$ | $\left(1 + 2\lvert\sin(\theta)\rvert\right)^2$ |
+| CRXGate, CRYGate, CRZGate, CPhaseGate | $\left(\lvert\theta/4\rvert, 0, 0\right)$ |  $\left(1 + 2\lvert\sin(\theta/2)\rvert\right)^2$ |
+| XXPlusYYGate, XXMinusYYGate | $\left(\vert\theta/4\rvert, \lvert\theta/4\rvert, 0\right)$ | $\left(1 + 4\lvert\sin(\theta/2)\rvert + 2\sin^2(\theta/2)\right)^2$ (independent of $\beta$) |
+| Move (cut wire in the LO scenario) | N/A | $4^2 = 16$ |
+
+## Next steps
+
+<Admonition type="tip" title="Recommendations"> 
+    - Read through the page on [getting started with circuit cutting using wire cuts](/guides/qiskit-addons-cutting-wires)
+</Admonition>
+
+
+## References
+
+[1] Christophe Piveteau, David Sutter, Circuit knitting with classical communication, https://arxiv.org/abs/2205.00016
+
+[2] Kosuke Mitarai, Keisuke Fujii, Constructing a virtual two-qubit gate by sampling single-qubit operations, https://arxiv.org/abs/1909.07534
+
+[3] Kosuke Mitarai, Keisuke Fujii, Overhead for simulating a non-local channel with local channels by quasiprobability sampling, https://arxiv.org/abs/2006.11174
+
+[4] Lukas Brenner, Christophe Piveteau, David Sutter, Optimal wire cutting with classical communication, https://arxiv.org/abs/2302.03366
+
+[5] K. Temme, S. Bravyi, and J. M. Gambetta, Error mitigation for short-depth quantum circuits, https://arxiv.org/abs/1612.02058
+
+[6] Lukas Schmitt, Christophe Piveteau, David Sutter, Cutting circuits with multiple two-qubit unitaries, https://arxiv.org/abs/2312.11638
+
+[7] Jun Zhang, Jiri Vala, K. Birgitta Whaley, Shankar Sastry, A geometric theory of non-local two-qubit operations, https://arxiv.org/abs/quant-ph/0209120

qiskit_bot.yaml

@@ -409,3 +409,9 @@ notifications:
     - "@kaelynj"
   "docs/guides/qiskit-addons-mpf-get-started":
     - "@kaelynj"
+  "docs/guides/qiskit-addons-cutting":
+    - "@kaelynj"
+  "docs/guides/qiskit-addons-cutting-wires":
+    - "@kaelynj"
+  "docs/guides/qiskit-addons-cutting-gates":
+    - "@kaelynj"

scripts/config/cspell/dictionaries/people.txt

@@ -6,6 +6,7 @@ Almaden
 Alon
 Ambainis
 Bajpe
+Birgitta
 Boeblingen
 Bravyi
 Bremner
@@ -25,6 +26,7 @@ Easwar
 Eisert
 Fock
 Frobenius
+Fujii
 Golecha
 Gosset
 Gottesman
@@ -41,7 +43,9 @@ Ising
 Iten
 Itoko
 Javadi
+Jiri
 Jurcevic
+Keisuke
 Ketan
 Kitaev
 Koenig
@@ -52,10 +56,12 @@ Kutin
 Lauer
 Lindblad
 Luca
+Lukas
 Margolus
 Martonosi
 Maslov
 Merkel
+Mitarai
 Mølmer
 Mosca
 Moscas
@@ -70,6 +76,7 @@ Ochsner
 Ourense
 Paik
 Paulis
+Piveteau
 Poppler
 Prakash
 Raban
@@ -80,6 +87,7 @@ Robledo
 Roetteler
 Ruchir
 Rueschlikon
+Sastry
 Shaohan
 Shaydulin
 Shende
@@ -92,8 +100,10 @@ Sørensen
 Sutter
 Svore
 Tapp
+Temme
 Toffoli
 Uhrig
+Vala
 Vazirani
 Vedral
 Vishal
@@ -104,5 +114,6 @@ Weyl
 Woerner
 Wörner
 Yufei
+Zhang
 Zhuk
 Zoufal

scripts/config/cspell/dictionaries/qiskit.txt

@@ -1,3 +1,4 @@
+AABB
 ALAP
 ASPLOS
 Abelian
@@ -130,6 +131,7 @@ ipywidgets
 iqft
 iswap
 ISYM
+jpserver
 kwarg
 kwargs
 kwparams

scripts/config/notebook-testing.toml

@@ -46,6 +46,8 @@ notebooks = [
     "docs/guides/transpiler-stages.ipynb",
     "docs/guides/visualize-circuits.ipynb",
     "docs/guides/visualize-results.ipynb",
+    "docs/guides/qiskit-addons-cutting-wires.ipynb",
+    "docs/guides/qiskit-addons-cutting-gates.ipynb"
 ]
 
 # Mock the following notebooks using a 6-qubit local simulator