examples/examples.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "-LuIQvRkv5DN"
   },
   "source": [
    "# Introduction to Rivet Transpiler"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "aC0BK8tYv6GG"
   },
   "source": [
    "**Quantum Transpilation** is the transformation of a given virtual quantum circuit:\n",
    "\n",
    "- to match the topology of a specific device\n",
    "- to optimize the circuit for execution\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "Tf3CiM5nv-Rk"
   },
   "source": [
    "## 1. Transpilation Stages\n",
    "**Pass Manager** is an internal Qiskit object constructed by the `transpile` function \"under the hood\" during transpilation.\n",
    "Pass Manager consists of Passes which analyse or change the transpiled circuit.\n",
    "Calling `pass_manager.run` is equivalent to calling `transpile` and passing a circuit, backend and corresponding transpilation parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "id": "5HAsOYSzwID4"
   },
   "outputs": [],
   "source": [
    "import qiskit\n",
    "\n",
    "pass_manager = qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager(\n",
    "    # backend=backend,\n",
    "    # initial_layout=[1, 0, 2],\n",
    "    optimization_level=3,\n",
    "    seed_transpiler=1234\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "7T1KiSEVv-UZ"
   },
   "source": [
    "Calling `pass_manager.stages` the main transpilation stages can be displayed: ('init', 'layout', 'routing', 'translation', 'optimization', 'scheduling')\n",
    "\n",
    "1) **Init** - Unrolling custom instructions and converting the circuit to all 1 and 2 qubit gates.\n",
    "\n",
    "2) **Layout** - Mapping circuit virtual qubits to backend physical qubits.\n",
    "\n",
    "3) **Routing** - Injecting SWAP gates to comply with the backend’s coupling map.\n",
    "\n",
    "4) **Translation** - Translating to the target backend’s basis gate set.\n",
    "\n",
    "5) **Optimization** - Main optimization loop to increase circuit quality.\n",
    "\n",
    "6) **Scheduling** - Conversion to hardware-specific pulses."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "eFmE1DKZwLGJ"
   },
   "source": [
    "\n",
    "#### **The Rivet Transpiler package** provides a family of functions (transpile and service functions) for the efficient transpilation of quantum circuits.\n",
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "nvMLcxngwNdd"
   },
   "source": [
    "## 2. Rivet Transpiler: Transpile Functions\n",
    "\n",
    "`transpile` - a custom transpilation with possibility of using additional parameters. Interface of the `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\n",
    "\n",
    "Running `transpile` function with `return_metrics=True` additionally returns metrics of the transpilation process in the following form:\n",
    "\n",
    "```\n",
    "{'pass_index': 0,\n",
    " 'pass_name': 'ContainsInstruction',\n",
    " 'pass_type': 'Analysis',\n",
    " 'time': 9.5367431640625e-06,\n",
    " 'depth': 5,\n",
    " 'width': 3,\n",
    " 'ibm_cost': 0.9498972910479807,\n",
    " 'gates_counter': {1: 3, 2: 3}}\n",
    " ...\n",
    "```\n",
    "\n",
    "`transpile_chain` - consistently transpiles and \"stitches\" a chain of quantum circuits.  For more details, check the [Circuit Stitching](circuit_stitching/circuit_stitching.ipynb) notebook.\n",
    "\n",
    "`transpile_right` / `transpile_left`  - transpiles an additional circuit to the right/left part of the existing circuit. Basic transpilation is slow, `transpile_right` / `transpile_left` are much faster. Check the implementation for the case of the [Shadow State Tomography](shadows/shadow_state_tomography.ipynb).\n",
    "\n",
    "`transpile_and_compress` - transpiles and \"topologically compresses\" a circuit considering a coupling map of the selected backend to avoid using unnecessary ancilla qubits. For more details, check the [Qubit-Constrained Transpilation](qubit_constrained_transpilation/qubit_constrained_transpilation.ipynb) notebook.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "z9LS8_03wQhq"
   },
   "source": [
    "# 3. Rivet Transpiler: Service Functions  \n",
    "In the Rivet Transpiler, the following service functions are defined:  \n",
    "\n",
    "`get_full_map` - To get final qubit allocation after transpilation. Check the [Qubit-Constrained Transpilation](qubit_constrained_transpilation/qubit_constrained_transpilation.ipynb) nonebook for more details.\n",
    "\n",
    "`get_circuit_hash` - calculates circuit hash. Check [Hashing](hashing/hashing.ipynb)  nonebook for more details.\n",
    "\n",
    "`get_cnot_circuit` - creates a CNOT test circuit.\n",
    "  \n",
    "`get_litmus_circuit` -creates a \n",
    "**Litmus circuit** which is a minimal quantum circuit which consisting 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).\n",
    "\n",
    "`get_ibm_cost` -  IBM Cost is a product of gate fidelities* (F) and depth penalization** (K): $\n",
    "C=K^d \\prod_{j \\in G}F_j\n",
    "$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* K - circuit depth penalization factor\n",
    "* d - circuit depth\n",
    "* G - gates\n",
    "* F - fidelities\n",
    "\n",
    "IBM Cost can be used as a circuit quality metric (e.g. to compare the cost for the litmus and transpiled circuits) (see e.g. “Demonstration of quantum volume 64 on a superconducting quantum computing system” – IBMQ – P. Jurcevic, A. Javadi-Abhari, L. S. Bishop and others – https://arxiv.org/abs/2008.08571).\n",
    "\n",
    "*the degree of accuracy with which a quantum gate operation is executed on a quantum computing system, measured as the agreement between the physical implementation and the ideal mathematical operation.\n",
    "\n",
    "**technique used in quantum circuit optimization to reduce the depth of a quantum circuit."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "K463n8w1VpsY"
   },
   "source": [
    "## 4. Supported Stacks\n",
    "\n",
    "Make sure you have followed and installed Rivet Transpiler. Check the installation steps from   **Readme.md**.\n",
    "Then import Qiskit and other modules required for the examples and Rivet Transpiler functions execution."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "s1yxZK8_WQ7U"
   },
   "source": [
    "\n",
    "Four pre-defined transpilation stacks have been added:\n",
    "\n",
    "- Qiskit transpilation\n",
    "- Pytket transpilation\n",
    "- BQSKit QSearch synthesis\n",
    "- BQSKit QFactor instantiation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "JNy-siUqWX_E"
   },
   "source": [
    "### Stacks Usage"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "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": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from rivet_transpiler import transpile\n",
    "from rivet_transpiler import get_litmus_circuit\n",
    "\n",
    "from qiskit_ibm_runtime.fake_provider import FakeLimaV2\n",
    "\n",
    "backend = FakeLimaV2()\n",
    "\n",
    "QUBITS_COUNT = 3\n",
    "\n",
    "litmus_circuit = get_litmus_circuit(QUBITS_COUNT, \"Litmus\")\n",
    "\n",
    "litmus_circuit.draw()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "id": "KdwJrqFrWTrU"
   },
   "outputs": [],
   "source": [
    "STACKS = [\"qiskit\",\n",
    "          \"qiskit_qsearch\",\n",
    "          \"qiskit_qfactor_qsearch\",\n",
    "          \"qiskit_pytket\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "RL-JtsJ5Wd6x"
   },
   "source": [
    "#### Qiskit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "id": "QJeXNbuQWeE6"
   },
   "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": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled_circuit = transpile(\n",
    "    litmus_circuit,\n",
    "    backend,\n",
    "    stack=\"qiskit\",\n",
    "    seed_transpiler=1234)\n",
    "\n",
    "transpiled_circuit.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "Ca6C762iWePl"
   },
   "source": [
    "#### Pytket"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "id": "yUjx0ZUTWeZN"
   },
   "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_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": [
       "                ┌──────────────┐          ┌───┐          ┌───┐ ░ \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": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transpiled_circuit = transpile(\n",
    "    litmus_circuit,\n",
    "    backend,\n",
    "    stack=\"qiskit_pytket\",\n",
    "    seed_transpiler=1234)\n",
    "\n",
    "transpiled_circuit.draw()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "bEhwNXsgwjoL"
   },
   "source": [
    "## 5. Transpilation Examples\n",
    "\n",
    "- [Shadow State Tomography](shadows/shadow_state_tomography.ipynb)\n",
    "- [Fourier Adder](fourier_adder/fourier_adder.ipynb)\n",
    "- [Qubit-Constrained Transpilation](qubit_constrained_transpilation/qubit_constrained_transpilation.ipynb)\n",
    "- [Hashing](hashing/hashing.ipynb) \n",
    "- [Circuit Stitching](circuit_stitching/circuit_stitching.ipynb)\n",
    "- [Quantum circuit synthesis](circuit_synthesis/circuit_synthesis.ipynb)\n"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "provenance": []
  },
  "kernelspec": {
   "display_name": "Rivet_Release",
   "language": "python",
   "name": "rivet_release"
  },
  "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.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}