examples/circuit_stitching/circuit_stitching.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "GTF686-rzJf7"
   },
   "source": [
    "# Circuit Stitching"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "RZkL2zjWt_Fn"
   },
   "source": [
    "Circuit stitching is a technique used to optimize the routing of quantum circuits on physical quantum hardware. In this process, disconnected qubits, which are not physically adjacent, are brought closer together using SWAP gates. However, unlike traditional routing methods, the **qubits are not re-routed back** to their original positions using additional SWAP gates. This decision is made to avoid introducing unnecessary SWAP operations, which can increase the overall complexity and resource usage of the circuit."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "wUozEKEIuCO8"
   },
   "source": [
    "As a result of this process, the allocation of virtual qubits, which represent the logical qubits in the circuit, may change. Virtual qubits are mapped to physical qubits on the quantum hardware, and their allocation determines the routing of the circuit. By knowing the final allocation of qubits after transpilation, we can understand how the circuit has been optimized and how the virtual qubits have been mapped to physical qubits on the quantum device. This information is essential for ensuring the efficient execution of the circuit on the target quantum hardware and to optimize the performance of quantum algorithms."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "Xkd-mXfLzMXg"
   },
   "source": [
    "An example of qubit allocation during transpilation:\n",
    "\n",
    "- `Zero Map` - Ancillas added\n",
    "- `After Layout` - Initial layout applied\n",
    "- `After Routing` - SWAPs applied\n",
    "- `Full Map` - Final qubit allocation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "BtZ6pdz_zbpJ"
   },
   "source": [
    "![image.jpg](Fig1_circuit_stitching.jpg) \n",
    "*Fig.1. Schematic illustration procedure for the circuit stitching*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "6CvKGjfasYAV"
   },
   "source": [
    "## 1. Problem definition\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "QG4RMq92r5_h"
   },
   "source": [
    "Unfortunately, **Qiskit** does not provide such allocation. Instead - the Qiskit transpiled circuit contains `layout` property with data on applied qubit permutations:\n",
    "\n",
    "- `initial_layout` – an initial placement of incoming virtual qubits during Layout stage.\n",
    "\n",
    "- `final_layout` – a placement of outgoing virtual qubits during Routing stage."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "_OlwqURnzZMn"
   },
   "source": [
    "## 2. Solution: Rivet Transpilation\n",
    "\n",
    "**The goal is** to \"stitch\" together transpiled circuits into a chain using `layout` property.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "pyj4U4GHsmV6"
   },
   "source": [
    "### 2.1. Function `transpile`\n",
    "\n",
    "Interface of Rivet `transpile` function matches `qiskit.transpile` - but allows additional parameters like:\n",
    "\n",
    "- pre-defined transpilation stacks\n",
    "- custom PassManager\n",
    "- dynamical decoupling\n",
    "- transpiler options"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from rivet_transpiler import transpile"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To be able visualize the results below the `matplotlib` should be installed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# !pip install matplotlib"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fake backends are simulators with properties of real backends and provides the information such as:\n",
    "\n",
    "- coupling map\n",
    "- basis gates\n",
    "- noise model\n",
    "\n",
    "Fake backends are useful for testing the transpiler and performing noisy simulations of the system.\n",
    "\n",
    "As a minimal example we select 5-qubit fake backend with linear topology:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "import qiskit\n",
    "import qiskit.visualization \n",
    "\n",
    "from qiskit_ibm_runtime.fake_provider import FakeLimaV2\n",
    "\n",
    "backend = FakeLimaV2() \n",
    "\n",
    "# qiskit.visualization.plot_gate_map(backend)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![image.png](Fig2_FakeLima_backend.png) \n",
    "\n",
    "*Fig.2. Schematic representation of FakeLimaV2 backend.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2. Example: transpilation for Litmus Circuit\n",
    "\n",
    "Lets consider how the Rivet transpilation works for a simple example of the `litmus circuit`. **Litmus circuit** is a minimal quantum circuit which consists of:\n",
    "\n",
    "- Parametrized RZ gate on each qubit (each parameter name matches the  index of the virtual qubit - to trace consequent permutations of qubits during layout and routing phases of transpilation).\n",
    "\n",
    "- Circular CNOT gates (necessary to introduce SWAPs during transpilation to not fully connected topology)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "from rivet_transpiler import get_litmus_circuit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">            ┌──────────────┐          ┌───┐ Litmus \n",
       "Litmus_0_0: ┤ Rz(Litmus_0) ├──■───────┤ X ├───░────\n",
       "            ├──────────────┤┌─┴─┐     └─┬─┘   ░    \n",
       "Litmus_0_1: ┤ Rz(Litmus_1) ├┤ X ├──■────┼─────░────\n",
       "            ├──────────────┤└───┘┌─┴─┐  │     ░    \n",
       "Litmus_0_2: ┤ Rz(Litmus_2) ├─────┤ X ├──■─────░────\n",
       "            └──────────────┘     └───┘        ░    </pre>"
      ],
      "text/plain": [
       "            ┌──────────────┐          ┌───┐ Litmus \n",
       "Litmus_0_0: ┤ Rz(Litmus_0) ├──■───────┤ X ├───░────\n",
       "            ├──────────────┤┌─┴─┐     └─┬─┘   ░    \n",
       "Litmus_0_1: ┤ Rz(Litmus_1) ├┤ X ├──■────┼─────░────\n",
       "            ├──────────────┤└───┘┌─┴─┐  │     ░    \n",
       "Litmus_0_2: ┤ Rz(Litmus_2) ├─────┤ X ├──■─────░────\n",
       "            └──────────────┘     └───┘        ░    "
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "QUBITS_COUNT = 3\n",
    "\n",
    "litmus_circuit = get_litmus_circuit(QUBITS_COUNT, \"Litmus\")\n",
    "\n",
    "litmus_circuit.draw()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "id": "s2nchv4lzh2i"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">                ┌──────────────┐          ┌───┐          ┌───┐ Litmus \n",
       "Litmus_0_2 -> 0 ┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────\n",
       "                ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    \n",
       "Litmus_0_0 -> 1 ┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────\n",
       "                ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    \n",
       "Litmus_0_1 -> 2 ┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────\n",
       "                └──────────────┘└───┘                            ░    \n",
       " ancilla_0 -> 3 ──────────────────────────────────────────────────────\n",
       "                                                                      \n",
       " ancilla_1 -> 4 ──────────────────────────────────────────────────────\n",
       "                                                                      </pre>"
      ],
      "text/plain": [
       "                ┌──────────────┐          ┌───┐          ┌───┐ Litmus \n",
       "Litmus_0_2 -> 0 ┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────\n",
       "                ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    \n",
       "Litmus_0_0 -> 1 ┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────\n",
       "                ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    \n",
       "Litmus_0_1 -> 2 ┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────\n",
       "                └──────────────┘└───┘                            ░    \n",
       " ancilla_0 -> 3 ──────────────────────────────────────────────────────\n",
       "                                                                      \n",
       " ancilla_1 -> 4 ──────────────────────────────────────────────────────\n",
       "                                                                      "
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled_circuit = transpile(\n",
    "    litmus_circuit,\n",
    "    backend,\n",
    "    seed_transpiler=1234\n",
    ")\n",
    "\n",
    "transpiled_circuit.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "5WW4-KkNzjzz"
   },
   "source": [
    "\n",
    "### 2.3. Function `get_full_map`\n",
    "\n",
    "Rivet function `get_full_map` follows above permutations to return final allocation of qubits after transpilation. The information about the final allocation of qubits after transpilation  ensures the effective execution of the quantum algorithms on real quantum hardware, namely taking into account the characteristics of the device architecture."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "id": "NaXx3Wo0zh5Y"
   },
   "outputs": [],
   "source": [
    "from rivet_transpiler import get_full_map"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To find the final allocation of qubits after transpilation we work with 3 sets of qubits:\n",
    "- Incoming virtual qubits of the initial circuit\n",
    "- Outgoing virtual qubits of the transpiled circuit\n",
    "- Physical qubits of the selected backend\n",
    "\n",
    "The final qubit allocation after transpilation is defined as:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 2, 1, 3, 4]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_full_map(transpiled_circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "W6pUlY1wznot"
   },
   "source": [
    "### 2.4. Function `transpile_chain`\n",
    "\n",
    "The function consistently transpiles and \"stitches\" a chain of quantum circuits."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "from rivet_transpiler import transpile_chain"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "id": "_Vvb1QbbzrmP"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">                ┌──────────────┐               ┌───┐             ░    ┌──────────────┐┌───┐                            ░    ┌──────────────┐     ┌───┐          ┌───┐     ┌───┐             ░    ┌──────────────┐     ┌───┐          ┌───┐     ┌───┐             ░    ┌──────────────┐     ┌───┐          ┌───┐     ┌───┐             ░    \n",
       "Litmus_0_1 -> 0 ┤ Rz(Litmus_0) ├──■─────────■──┤ X ├──■──────────░────┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────┤ Rz(Litmus_1) ├──■──┤ X ├──■───────┤ X ├──■──┤ X ├──■──────────░────┤ Rz(Litmus_1) ├──■──┤ X ├──■───────┤ X ├──■──┤ X ├──■──────────░────┤ Rz(Litmus_1) ├──■──┤ X ├──■───────┤ X ├──■──┤ X ├──■──────────░────\n",
       "                └──────────────┘  │         │  └─┬─┘  │          ░    └──────────────┘└─┬─┘                 │          ░    └──────────────┘  │  └─┬─┘  │       └─┬─┘  │  └─┬─┘  │          ░    └──────────────┘  │  └─┬─┘  │       └─┬─┘  │  └─┬─┘  │          ░    └──────────────┘  │  └─┬─┘  │       └─┬─┘  │  └─┬─┘  │          ░    \n",
       "                ┌──────────────┐┌─┴─┐     ┌─┴─┐  │  ┌─┴─┐┌───┐ Litmus ┌──────────────┐  │  ┌───┐     ┌───┐┌─┴─┐        ░    ┌──────────────┐┌─┴─┐  │  ┌─┴─┐┌───┐  │  ┌─┴─┐  │  ┌─┴─┐        ░    ┌──────────────┐┌─┴─┐  │  ┌─┴─┐┌───┐  │  ┌─┴─┐  │  ┌─┴─┐        ░    ┌──────────────┐┌─┴─┐  │  ┌─┴─┐┌───┐  │  ┌─┴─┐  │  ┌─┴─┐        ░    \n",
       "Litmus_0_2 -> 1 ┤ Rz(Litmus_1) ├┤ X ├──■──┤ X ├──■──┤ X ├┤ X ├───░────┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────┤ Rz(Litmus_2) ├┤ X ├──■──┤ X ├┤ X ├──■──┤ X ├──■──┤ X ├──■─────░────┤ Rz(Litmus_2) ├┤ X ├──■──┤ X ├┤ X ├──■──┤ X ├──■──┤ X ├──■─────░────┤ Rz(Litmus_2) ├┤ X ├──■──┤ X ├┤ X ├──■──┤ X ├──■──┤ X ├──■─────░────\n",
       "                └──────────────┘└───┘  │  └───┘     └───┘└─┬─┘   ░    └──────────────┘     └─┬─┘  │  └─┬─┘└───┘  │     ░    └──────────────┘└───┘     └───┘└─┬─┘     └───┘     └───┘  │     ░    └──────────────┘└───┘     └───┘└─┬─┘     └───┘     └───┘  │     ░    └──────────────┘└───┘     └───┘└─┬─┘     └───┘     └───┘  │     ░    \n",
       "                ┌──────────────┐     ┌─┴─┐                 │     ░    ┌──────────────┐       │  ┌─┴─┐  │       ┌─┴─┐ Litmus ┌──────────────┐                 │                      ┌─┴─┐ Litmus ┌──────────────┐                 │                      ┌─┴─┐ Litmus ┌──────────────┐                 │                      ┌─┴─┐ Litmus \n",
       "Litmus_0_0 -> 2 ┤ Rz(Litmus_2) ├─────┤ X ├─────────────────■─────░────┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────┤ Rz(Litmus_0) ├─────────────────■──────────────────────┤ X ├───░────┤ Rz(Litmus_0) ├─────────────────■──────────────────────┤ X ├───░────┤ Rz(Litmus_0) ├─────────────────■──────────────────────┤ X ├───░────\n",
       "                └──────────────┘     └───┘                       ░    └──────────────┘          └───┘          └───┘   ░    └──────────────┘                                        └───┘   ░    └──────────────┘                                        └───┘   ░    └──────────────┘                                        └───┘   ░    \n",
       " ancilla_0 -> 3 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                                                                                                                                                                                                                           \n",
       " ancilla_1 -> 4 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                                                                                                                                                                                                                           </pre>"
      ],
      "text/plain": [
       "                ┌──────────────┐               ┌───┐             ░    ┌──────────────┐┌───┐                            ░    ┌──────────────┐     ┌───┐          ┌───┐     ┌───┐             ░    ┌──────────────┐     ┌───┐          ┌───┐     ┌───┐             ░    ┌──────────────┐     ┌───┐          ┌───┐     ┌───┐             ░    \n",
       "Litmus_0_1 -> 0 ┤ Rz(Litmus_0) ├──■─────────■──┤ X ├──■──────────░────┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────┤ Rz(Litmus_1) ├──■──┤ X ├──■───────┤ X ├──■──┤ X ├──■──────────░────┤ Rz(Litmus_1) ├──■──┤ X ├──■───────┤ X ├──■──┤ X ├──■──────────░────┤ Rz(Litmus_1) ├──■──┤ X ├──■───────┤ X ├──■──┤ X ├──■──────────░────\n",
       "                └──────────────┘  │         │  └─┬─┘  │          ░    └──────────────┘└─┬─┘                 │          ░    └──────────────┘  │  └─┬─┘  │       └─┬─┘  │  └─┬─┘  │          ░    └──────────────┘  │  └─┬─┘  │       └─┬─┘  │  └─┬─┘  │          ░    └──────────────┘  │  └─┬─┘  │       └─┬─┘  │  └─┬─┘  │          ░    \n",
       "                ┌──────────────┐┌─┴─┐     ┌─┴─┐  │  ┌─┴─┐┌───┐ Litmus ┌──────────────┐  │  ┌───┐     ┌───┐┌─┴─┐        ░    ┌──────────────┐┌─┴─┐  │  ┌─┴─┐┌───┐  │  ┌─┴─┐  │  ┌─┴─┐        ░    ┌──────────────┐┌─┴─┐  │  ┌─┴─┐┌───┐  │  ┌─┴─┐  │  ┌─┴─┐        ░    ┌──────────────┐┌─┴─┐  │  ┌─┴─┐┌───┐  │  ┌─┴─┐  │  ┌─┴─┐        ░    \n",
       "Litmus_0_2 -> 1 ┤ Rz(Litmus_1) ├┤ X ├──■──┤ X ├──■──┤ X ├┤ X ├───░────┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────┤ Rz(Litmus_2) ├┤ X ├──■──┤ X ├┤ X ├──■──┤ X ├──■──┤ X ├──■─────░────┤ Rz(Litmus_2) ├┤ X ├──■──┤ X ├┤ X ├──■──┤ X ├──■──┤ X ├──■─────░────┤ Rz(Litmus_2) ├┤ X ├──■──┤ X ├┤ X ├──■──┤ X ├──■──┤ X ├──■─────░────\n",
       "                └──────────────┘└───┘  │  └───┘     └───┘└─┬─┘   ░    └──────────────┘     └─┬─┘  │  └─┬─┘└───┘  │     ░    └──────────────┘└───┘     └───┘└─┬─┘     └───┘     └───┘  │     ░    └──────────────┘└───┘     └───┘└─┬─┘     └───┘     └───┘  │     ░    └──────────────┘└───┘     └───┘└─┬─┘     └───┘     └───┘  │     ░    \n",
       "                ┌──────────────┐     ┌─┴─┐                 │     ░    ┌──────────────┐       │  ┌─┴─┐  │       ┌─┴─┐ Litmus ┌──────────────┐                 │                      ┌─┴─┐ Litmus ┌──────────────┐                 │                      ┌─┴─┐ Litmus ┌──────────────┐                 │                      ┌─┴─┐ Litmus \n",
       "Litmus_0_0 -> 2 ┤ Rz(Litmus_2) ├─────┤ X ├─────────────────■─────░────┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────┤ Rz(Litmus_0) ├─────────────────■──────────────────────┤ X ├───░────┤ Rz(Litmus_0) ├─────────────────■──────────────────────┤ X ├───░────┤ Rz(Litmus_0) ├─────────────────■──────────────────────┤ X ├───░────\n",
       "                └──────────────┘     └───┘                       ░    └──────────────┘          └───┘          └───┘   ░    └──────────────┘                                        └───┘   ░    └──────────────┘                                        └───┘   ░    └──────────────┘                                        └───┘   ░    \n",
       " ancilla_0 -> 3 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                                                                                                                                                                                                                           \n",
       " ancilla_1 -> 4 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                                                                                                                                                                                                                           "
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CHAIN = [litmus_circuit] * 5\n",
    "\n",
    "transpiled_chain_circuit = transpile_chain(\n",
    "    CHAIN,\n",
    "    backend,\n",
    "    seed_transpiler=1234,\n",
    "    initial_layout=[0, 1, 2] \n",
    ")\n",
    "\n",
    "transpiled_chain_circuit.draw(fold=-1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check the topology map of the resulting circuit:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "id": "gj2zrLBYzupl"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[2, 0, 1, 3, 4]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_full_map(transpiled_chain_circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "BKPK6552zvJF"
   },
   "source": [
    "### 2.5. Function `transpile_right`\n",
    "Transpiles an additional circuit to the right part of the existing circuit.\n",
    "\n",
    "Let's take a transpiled circuit from the section 2.1. (transpiled litmus circuit):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "id": "a_9d-F-xzvTD"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">                ┌──────────────┐          ┌───┐          ┌───┐ Litmus \n",
       "Litmus_0_2 -> 0 ┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────\n",
       "                ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    \n",
       "Litmus_0_0 -> 1 ┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────\n",
       "                ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    \n",
       "Litmus_0_1 -> 2 ┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────\n",
       "                └──────────────┘└───┘                            ░    \n",
       " ancilla_0 -> 3 ──────────────────────────────────────────────────────\n",
       "                                                                      \n",
       " ancilla_1 -> 4 ──────────────────────────────────────────────────────\n",
       "                                                                      </pre>"
      ],
      "text/plain": [
       "                ┌──────────────┐          ┌───┐          ┌───┐ Litmus \n",
       "Litmus_0_2 -> 0 ┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────\n",
       "                ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    \n",
       "Litmus_0_0 -> 1 ┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────\n",
       "                ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    \n",
       "Litmus_0_1 -> 2 ┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────\n",
       "                └──────────────┘└───┘                            ░    \n",
       " ancilla_0 -> 3 ──────────────────────────────────────────────────────\n",
       "                                                                      \n",
       " ancilla_1 -> 4 ──────────────────────────────────────────────────────\n",
       "                                                                      "
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled_circuit.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below we create circular CNOT gates circuits (necessary to introduce SWAPs during transpilation to not fully connected topology). So we have to import Rivet functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "from rivet_transpiler import get_cnot_circuit, transpile_right"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "id": "GoIU_1W0z4uV"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">          ┌────────────┐      CNOT \n",
       "CNOT_0_0: ┤ Rz(CNOT_0) ├──■────░───\n",
       "          ├────────────┤┌─┴─┐  ░   \n",
       "CNOT_0_1: ┤ Rz(CNOT_1) ├┤ X ├──░───\n",
       "          ├────────────┤└───┘  ░   \n",
       "CNOT_0_2: ┤ Rz(CNOT_2) ├───────░───\n",
       "          └────────────┘       ░   </pre>"
      ],
      "text/plain": [
       "          ┌────────────┐      CNOT \n",
       "CNOT_0_0: ┤ Rz(CNOT_0) ├──■────░───\n",
       "          ├────────────┤┌─┴─┐  ░   \n",
       "CNOT_0_1: ┤ Rz(CNOT_1) ├┤ X ├──░───\n",
       "          ├────────────┤└───┘  ░   \n",
       "CNOT_0_2: ┤ Rz(CNOT_2) ├───────░───\n",
       "          └────────────┘       ░   "
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cnot_circuit = get_cnot_circuit(QUBITS_COUNT, \"CNOT\", [0, 1])\n",
    "cnot_circuit.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The implementation of `transpile_right` function is time-efficient and flexible for circuit stitching.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "id": "8lAJykkWz4wp"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">                ┌──────────────┐          ┌───┐          ┌───┐ Litmus ┌────────────┐                     CNOT \n",
       "Litmus_0_2 -> 0 ┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────┤ Rz(CNOT_0) ├─────────────────■────░───\n",
       "                ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    ├────────────┤┌───┐     ┌───┐┌─┴─┐  ░   \n",
       "Litmus_0_0 -> 1 ┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────┤ Rz(CNOT_2) ├┤ X ├──■──┤ X ├┤ X ├──░───\n",
       "                ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    ├────────────┤└─┬─┘┌─┴─┐└─┬─┘└───┘  ░   \n",
       "Litmus_0_1 -> 2 ┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────┤ Rz(CNOT_1) ├──■──┤ X ├──■─────────░───\n",
       "                └──────────────┘└───┘                            ░    └────────────┘     └───┘            ░   \n",
       " ancilla_0 -> 3 ──────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                              \n",
       " ancilla_1 -> 4 ──────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                              </pre>"
      ],
      "text/plain": [
       "                ┌──────────────┐          ┌───┐          ┌───┐ Litmus ┌────────────┐                     CNOT \n",
       "Litmus_0_2 -> 0 ┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────┤ Rz(CNOT_0) ├─────────────────■────░───\n",
       "                ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    ├────────────┤┌───┐     ┌───┐┌─┴─┐  ░   \n",
       "Litmus_0_0 -> 1 ┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────┤ Rz(CNOT_2) ├┤ X ├──■──┤ X ├┤ X ├──░───\n",
       "                ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    ├────────────┤└─┬─┘┌─┴─┐└─┬─┘└───┘  ░   \n",
       "Litmus_0_1 -> 2 ┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────┤ Rz(CNOT_1) ├──■──┤ X ├──■─────────░───\n",
       "                └──────────────┘└───┘                            ░    └────────────┘     └───┘            ░   \n",
       " ancilla_0 -> 3 ──────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                              \n",
       " ancilla_1 -> 4 ──────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                              "
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled_right_circuit = transpile_right(\n",
    "    central_circuit=transpiled_circuit,\n",
    "    right_circuit=cnot_circuit,\n",
    "    backend=backend,\n",
    "    seed_transpiler=1234\n",
    ")\n",
    "\n",
    "transpiled_right_circuit.draw(fold=-1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "id": "ElYOuzspz4yl"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">                ┌──────────────┐          ┌───┐          ┌───┐ Litmus ┌────────────┐                     CNOT ┌────────────┐      CNOT \n",
       "Litmus_0_2 -> 0 ┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────┤ Rz(CNOT_0) ├─────────────────■────░───┤ Rz(CNOT_0) ├──■────░───\n",
       "                ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    ├────────────┤┌───┐     ┌───┐┌─┴─┐  ░   ├────────────┤┌─┴─┐  ░   \n",
       "Litmus_0_0 -> 1 ┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────┤ Rz(CNOT_2) ├┤ X ├──■──┤ X ├┤ X ├──░───┤ Rz(CNOT_1) ├┤ X ├──░───\n",
       "                ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    ├────────────┤└─┬─┘┌─┴─┐└─┬─┘└───┘  ░   ├────────────┤└───┘  ░   \n",
       "Litmus_0_1 -> 2 ┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────┤ Rz(CNOT_1) ├──■──┤ X ├──■─────────░───┤ Rz(CNOT_2) ├───────░───\n",
       "                └──────────────┘└───┘                            ░    └────────────┘     └───┘            ░   └────────────┘       ░   \n",
       " ancilla_0 -> 3 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                       \n",
       " ancilla_1 -> 4 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                       </pre>"
      ],
      "text/plain": [
       "                ┌──────────────┐          ┌───┐          ┌───┐ Litmus ┌────────────┐                     CNOT ┌────────────┐      CNOT \n",
       "Litmus_0_2 -> 0 ┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────┤ Rz(CNOT_0) ├─────────────────■────░───┤ Rz(CNOT_0) ├──■────░───\n",
       "                ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    ├────────────┤┌───┐     ┌───┐┌─┴─┐  ░   ├────────────┤┌─┴─┐  ░   \n",
       "Litmus_0_0 -> 1 ┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────┤ Rz(CNOT_2) ├┤ X ├──■──┤ X ├┤ X ├──░───┤ Rz(CNOT_1) ├┤ X ├──░───\n",
       "                ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    ├────────────┤└─┬─┘┌─┴─┐└─┬─┘└───┘  ░   ├────────────┤└───┘  ░   \n",
       "Litmus_0_1 -> 2 ┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────┤ Rz(CNOT_1) ├──■──┤ X ├──■─────────░───┤ Rz(CNOT_2) ├───────░───\n",
       "                └──────────────┘└───┘                            ░    └────────────┘     └───┘            ░   └────────────┘       ░   \n",
       " ancilla_0 -> 3 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                       \n",
       " ancilla_1 -> 4 ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                       "
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled_right_circuit = transpile_right(\n",
    "    central_circuit=transpiled_right_circuit,\n",
    "    right_circuit=cnot_circuit,\n",
    "    backend=backend,\n",
    "    seed_transpiler=1234,\n",
    ")\n",
    "\n",
    "transpiled_right_circuit.draw(fold=-1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "BmtIlFYz0AOz"
   },
   "source": [
    "### 2.6. Function `transpile_left`\n",
    "Similarly, as above, the function transpiles additional circuit to the left part of the existing circuit. We have to import Rivet function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "from rivet_transpiler import transpile_left"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "id": "ISMRWYcb0CK4"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">               ┌────────────────┐      ░ ┌──────────────┐          ┌───┐          ┌───┐ Litmus \n",
       " CNOT_0_2 -> 0 ┤ Rz(1.0*CNOT_2) ├──────░─┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────\n",
       "               ├────────────────┤      ░ ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    \n",
       " CNOT_0_0 -> 1 ┤ Rz(1.0*CNOT_0) ├──■───░─┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────\n",
       "               ├────────────────┤┌─┴─┐ ░ ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    \n",
       " CNOT_0_1 -> 2 ┤ Rz(1.0*CNOT_1) ├┤ X ├─░─┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────\n",
       "               └────────────────┘└───┘ ░ └──────────────┘└───┘                            ░    \n",
       "ancilla_0 -> 3 ────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                               \n",
       "ancilla_1 -> 4 ────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                               </pre>"
      ],
      "text/plain": [
       "               ┌────────────────┐      ░ ┌──────────────┐          ┌───┐          ┌───┐ Litmus \n",
       " CNOT_0_2 -> 0 ┤ Rz(1.0*CNOT_2) ├──────░─┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────\n",
       "               ├────────────────┤      ░ ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    \n",
       " CNOT_0_0 -> 1 ┤ Rz(1.0*CNOT_0) ├──■───░─┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────\n",
       "               ├────────────────┤┌─┴─┐ ░ ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    \n",
       " CNOT_0_1 -> 2 ┤ Rz(1.0*CNOT_1) ├┤ X ├─░─┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────\n",
       "               └────────────────┘└───┘ ░ └──────────────┘└───┘                            ░    \n",
       "ancilla_0 -> 3 ────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                               \n",
       "ancilla_1 -> 4 ────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                               "
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled_left_circuit = transpile_left(\n",
    "    central_circuit=transpiled_circuit,\n",
    "    left_circuit=cnot_circuit,\n",
    "    backend=backend,\n",
    "    seed_transpiler=1234\n",
    ")\n",
    "\n",
    "transpiled_left_circuit.draw(fold=-1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "id": "GQVthjsR0CNm"
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"word-wrap: normal;white-space: pre;background: #fff0;line-height: 1.1;font-family: &quot;Courier New&quot;,Courier,monospace\">                ┌──────────────────┐     ┌───┐                     ░ ┌────────────────┐      ░ ┌──────────────┐          ┌───┐          ┌───┐ Litmus \n",
       "Litmus_0_2 -> 0 ┤ Rz(1.0*Litmus_2) ├─────┤ X ├─────────────────■───░─┤ Rz(1.0*CNOT_2) ├──────░─┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────\n",
       "                ├──────────────────┤┌───┐└─┬─┘┌───┐     ┌───┐┌─┴─┐ ░ ├────────────────┤      ░ ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    \n",
       "Litmus_0_1 -> 1 ┤ Rz(1.0*Litmus_1) ├┤ X ├──■──┤ X ├──■──┤ X ├┤ X ├─░─┤ Rz(1.0*CNOT_0) ├──■───░─┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────\n",
       "                ├──────────────────┤└─┬─┘     └─┬─┘┌─┴─┐└─┬─┘└───┘ ░ ├────────────────┤┌─┴─┐ ░ ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    \n",
       "Litmus_0_0 -> 2 ┤ Rz(1.0*Litmus_0) ├──■─────────■──┤ X ├──■────────░─┤ Rz(1.0*CNOT_1) ├┤ X ├─░─┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────\n",
       "                └──────────────────┘               └───┘           ░ └────────────────┘└───┘ ░ └──────────────┘└───┘                            ░    \n",
       " ancilla_0 -> 3 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                                     \n",
       " ancilla_1 -> 4 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                                     </pre>"
      ],
      "text/plain": [
       "                ┌──────────────────┐     ┌───┐                     ░ ┌────────────────┐      ░ ┌──────────────┐          ┌───┐          ┌───┐ Litmus \n",
       "Litmus_0_2 -> 0 ┤ Rz(1.0*Litmus_2) ├─────┤ X ├─────────────────■───░─┤ Rz(1.0*CNOT_2) ├──────░─┤ Rz(Litmus_2) ├───────■──┤ X ├──■───────┤ X ├───░────\n",
       "                ├──────────────────┤┌───┐└─┬─┘┌───┐     ┌───┐┌─┴─┐ ░ ├────────────────┤      ░ ├──────────────┤     ┌─┴─┐└─┬─┘┌─┴─┐┌───┐└─┬─┘   ░    \n",
       "Litmus_0_1 -> 1 ┤ Rz(1.0*Litmus_1) ├┤ X ├──■──┤ X ├──■──┤ X ├┤ X ├─░─┤ Rz(1.0*CNOT_0) ├──■───░─┤ Rz(Litmus_0) ├──■──┤ X ├──■──┤ X ├┤ X ├──■─────░────\n",
       "                ├──────────────────┤└─┬─┘     └─┬─┘┌─┴─┐└─┬─┘└───┘ ░ ├────────────────┤┌─┴─┐ ░ ├──────────────┤┌─┴─┐└───┘     └───┘└─┬─┘        ░    \n",
       "Litmus_0_0 -> 2 ┤ Rz(1.0*Litmus_0) ├──■─────────■──┤ X ├──■────────░─┤ Rz(1.0*CNOT_1) ├┤ X ├─░─┤ Rz(Litmus_1) ├┤ X ├─────────────────■──────────░────\n",
       "                └──────────────────┘               └───┘           ░ └────────────────┘└───┘ ░ └──────────────┘└───┘                            ░    \n",
       " ancilla_0 -> 3 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                                     \n",
       " ancilla_1 -> 4 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────\n",
       "                                                                                                                                                     "
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled_left_circuit = transpile_left(\n",
    "    central_circuit=transpiled_left_circuit,\n",
    "    left_circuit=litmus_circuit,\n",
    "    backend=backend,\n",
    "    seed_transpiler=1234\n",
    ")\n",
    "\n",
    "transpiled_left_circuit.draw(fold=-1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conclusions \n",
    "\n",
    "Circuit stitching implementation in Rivet transpiler gives the user tools for effective workflows. This includes the final allocation of the qubits after transpilation, and the transpilation of the additional circuit to the left/right part of the existing circuit.\n",
    "\n",
    "The interface of Rivet `transpile*` functions matches Qiskit and allows additional parameters and flexibility.\n",
    "\n",
    "With Rivet transpilation, users are able to speed up the circuit design process and calculations."
   ]
  }
 ],
 "metadata": {
  "colab": {
   "provenance": []
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}