examples/big_shadows/big_shadow_state_tomography.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3ab8d635-377b-4e63-8309-3027badc7003",
   "metadata": {
    "id": "3ab8d635-377b-4e63-8309-3027badc7003"
   },
   "source": [
    "# Big Shadow State Tomography"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57be7600",
   "metadata": {},
   "source": [
    "Quantum computers can solve some problems exponentially faster than classical ones, but their possibilities are still limited by high levels of noise, so quantum advantage has not been reached yet. To compensate for the noise, quantum error correction techniques can be applied by encoding one logical qubit into many physical qubits. This, in turn, requires the availability of a large number of physical qubits. \n",
    "The quantum software and hardware are evolving at a surprising speed: IBM Quantum surpassed the 100-qubit processor milestone in 2021 and has ambitious plans through 2033 [1]. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2dc14a9",
   "metadata": {},
   "source": [
    "\n",
    "![image.png](Fig1_IBMdevolopment_roadmap.png) \n",
    "\n",
    "*Fig.1. IBM Development Roadmap. Image source [1].*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4c80f7f4",
   "metadata": {},
   "source": [
    "In addition to advancements in software, significant improvements can also be made in quantum algorithms and processes, such as compilation. These enhancements are crucial for optimizing performance and making quantum computing more practical and efficient.\n",
    "\n",
    "Here, we compare the speed of standard Qiskit compilation with the compilation using the Rivet transpiler. As benchmark circuits, we selected the case of shadow state tomography (for more details, please check the notebook [Shadow State Tomography](../shadows/shadow_state_tomography.ipynb)). Except for error correction, estimating compilation for a large number of qubits has multiple purposes, such as scalability, effective resource management, and performance prediction."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "58690a54",
   "metadata": {},
   "source": [
    "## 1. Installation and Imports\n",
    "To run the code below make sure you have followed and installed Rivet transpiler. Check the installation steps from   **Readme.md**."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8197249d",
   "metadata": {},
   "source": [
    "#### 1.1. Import Qiskit and Rivet Transpiler Functions Required to Run the Examples Below"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "97625d2b",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from time import time\n",
    "from tqdm import tqdm\n",
    "\n",
    "import qiskit\n",
    "\n",
    "from qiskit_aer import AerSimulator\n",
    "from qiskit.visualization import plot_gate_map \n",
    " \n",
    "from qiskit_ibm_runtime.fake_provider import FakeKyiv\n",
    "\n",
    "from qiskit.circuit.random import random_circuit\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# plt.style.use(\"dark_background\")\n",
    "\n",
    "%cd -q ../..\n",
    "\n",
    "from rivet_transpiler import transpile_right"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "1ef7c0a7-6b49-4da6-b8e5-082f72cc052b",
   "metadata": {
    "id": "1ef7c0a7-6b49-4da6-b8e5-082f72cc052b"
   },
   "outputs": [],
   "source": [
    "def build_bases_rotation_circuit(bases):\n",
    "\n",
    "    qubits_count = len(bases)\n",
    "\n",
    "    circuit = qiskit.QuantumCircuit(qubits_count)\n",
    "\n",
    "    for qubit, basis in enumerate(bases):\n",
    "\n",
    "        if basis == \"X\":\n",
    "            circuit.h(qubit)\n",
    "\n",
    "        elif basis == \"Y\":\n",
    "            circuit.sdg(qubit)\n",
    "            circuit.h(qubit)\n",
    "\n",
    "        elif basis == \"Z\":\n",
    "            pass\n",
    "\n",
    "    return circuit"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "330031c8-1320-45ff-b0c2-6e1487a214a0",
   "metadata": {},
   "source": [
    "#### 1.2. Import Backend\n",
    "\n",
    "Available backends from IBM Qiskit are listed at [2].  To run this example we select the backend with 127 qubits:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "44d41dd7-1696-47de-bb14-6273701d42bb",
   "metadata": {},
   "outputs": [],
   "source": [
    "FAKE_BACKEND = FakeKyiv()\n",
    "\n",
    "backend = AerSimulator.from_backend(FAKE_BACKEND)\n",
    "\n",
    "# backend.options.noise_model = None\n",
    "\n",
    "# qiskit.visualization.plot_gate_map(FAKE_BACKEND)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41fbdfca",
   "metadata": {},
   "source": [
    "![image.png](Fig2_127qubit_IBMbackend_topology.png) \n",
    "\n",
    "*Fig.2. Schematic representation of FakeKyiv backend (127 qubits).*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1fb3b36",
   "metadata": {},
   "source": [
    "## 2. Experiments and Results\n",
    "\n",
    "The case  of Shadow State Tomography is described in more details in [Shadow State Tomography](../shadows/shadow_state_tomography.ipynb). Here we setup a random test circuits and compare  2 types of transpilation:\n",
    "\n",
    "- **Basic Transpilation:** every “measurement circuit” is composed to “original circuit” – and then composed circuit is transpiled.\n",
    "\n",
    "- **Rivet transpilation** using the function `transpile_right`: we transpile “original circuit” only once – and then use `transpile_right` function of Rivet Transpiler – to transpile only “measurement circuit” part.\n",
    "\n",
    "Since “measurement circuit” is much smaller than “original circuit” – `transpile_right` approach is expected to be much faster."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3dbd0fd-3cb0-40c1-a764-0a843b884e53",
   "metadata": {
    "id": "b3dbd0fd-3cb0-40c1-a764-0a843b884e53",
    "tags": []
   },
   "source": [
    "### 2.1. Set Up a Circuit"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e2d9170",
   "metadata": {},
   "source": [
    "Here we set up a random quantum circuit on 127 qubit device: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "25dcc1bb-aae5-45b5-9826-9049dd4ab96f",
   "metadata": {
    "id": "90eb621b-708b-4b95-8aae-5b505db8da5f"
   },
   "outputs": [],
   "source": [
    "# Parameters\n",
    "\n",
    "QUBITS_COUNT = 127\n",
    "CIRCUIT_DEPTH = 1\n",
    "MAX_GATE_SIZE = 4\n",
    "\n",
    "BASES_COUNT = 1\n",
    "\n",
    "OPTIMIZATION_LEVEL = 3\n",
    "\n",
    "SEED = 1234\n",
    "\n",
    "rng = np.random.default_rng(SEED) \n",
    "\n",
    "qubits = list(range(QUBITS_COUNT))\n",
    "\n",
    "## Random Circuit\n",
    "\n",
    "circuit = random_circuit(\n",
    "    num_qubits=QUBITS_COUNT, \n",
    "    depth=CIRCUIT_DEPTH,\n",
    "    max_operands=MAX_GATE_SIZE, \n",
    "    seed=SEED,\n",
    "    measure=False)\n",
    "\n",
    "# circuit.draw(fold=-1)\n",
    "# circuit.draw(fold=-1, output=\"mpl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f7ecdac-b2f3-4636-8747-1034eed2ee63",
   "metadata": {
    "id": "7f7ecdac-b2f3-4636-8747-1034eed2ee63"
   },
   "source": [
    "### 2.2.  Run Paulis Experiment\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c4cefeb",
   "metadata": {},
   "source": [
    "- Define Bases (here we conside 3 possible types of rotations - over X, Y and Z axis):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "159c1e11-b441-4d7a-93c7-1cfbb37e7ef0",
   "metadata": {
    "id": "159c1e11-b441-4d7a-93c7-1cfbb37e7ef0"
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(1, 127)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "random_bases = rng.choice(['X','Y','Z'], size=(BASES_COUNT, QUBITS_COUNT))\n",
    "\n",
    "bases_list, shots_counts = np.unique(random_bases, axis=0, return_counts=True)\n",
    "\n",
    "bases_list.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d3d9b2d",
   "metadata": {},
   "source": [
    "- Define Rotation Circuits"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "8fb972e6-95f5-4ebd-8415-53b3f89b6150",
   "metadata": {
    "id": "8fb972e6-95f5-4ebd-8415-53b3f89b6150",
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "rotation_circuits = []\n",
    "\n",
    "for bases in bases_list:\n",
    "\n",
    "    rotation_circuit = build_bases_rotation_circuit(bases)\n",
    "\n",
    "    rotation_circuits.append(rotation_circuit)\n",
    "\n",
    "len(rotation_circuits)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6d7c756-bd16-4d1b-a4ea-a9b49b2224f3",
   "metadata": {
    "id": "f6d7c756-bd16-4d1b-a4ea-a9b49b2224f3"
   },
   "source": [
    "### 2.3. Results: Basic Transpilation - Slower Version!\n",
    "\n",
    "Using Qiskit default transpilation we have to execute the FULL circuit for each base, so the total time execution depends on the number of BASES_COUNT.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "e57ce961-e840-491d-8c1c-21310b4bd745",
   "metadata": {
    "id": "e57ce961-e840-491d-8c1c-21310b4bd745",
    "outputId": "bff4c7b5-30aa-4295-f29b-862e674a4380",
    "tags": []
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "100%|███████████████████████████████████████████████████████████████████████| 1/1 [00:12<00:00, 12.49s/ basis]"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "estimated_time: 12.49\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "start_time = time()\n",
    "\n",
    "# Compose and Transpile all Rotation Circuits\n",
    "\n",
    "shadow_circuits = []\n",
    "\n",
    "rotation_tracker = tqdm(rotation_circuits, unit=' basis', ncols=110)\n",
    "\n",
    "for rotation_circuit in rotation_tracker:\n",
    "\n",
    "    measurement_circuit = rotation_circuit.measure_all(inplace=False)\n",
    "\n",
    "    measured_circuit = circuit.compose(measurement_circuit)\n",
    "\n",
    "    # display(measured_circuit.draw(fold=-1))\n",
    "\n",
    "    shadow_circuit = qiskit.transpile(\n",
    "        measured_circuit,\n",
    "        backend,\n",
    "        seed_transpiler=SEED,\n",
    "        optimization_level=OPTIMIZATION_LEVEL)\n",
    "\n",
    "    shadow_circuits.append(shadow_circuit)\n",
    "\n",
    "estimated_time = time() - start_time\n",
    "\n",
    "print(f\"estimated_time: {estimated_time:.02f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a792284-52a1-4d26-aff0-079fa71160a3",
   "metadata": {
    "id": "9a792284-52a1-4d26-aff0-079fa71160a3"
   },
   "source": [
    "### 2.4. Results: Transpile Right - Much Faster!\n",
    "Using the Rivet transpilator function `transpile_right`we execute the FULL circuit only ONCE! Then for each base count we run transpilation only the right part of the circuit which is changed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "83f9d09c-e309-4c73-82b9-5861eec5aa40",
   "metadata": {
    "id": "83f9d09c-e309-4c73-82b9-5861eec5aa40",
    "outputId": "3a350493-23b1-4489-f5f9-7497f56e8a20"
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "100%|███████████████████████████████████████████████████████████████████████| 1/1 [00:00<00:00, 11.94 basis/s]"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "estimated_time: 11.64\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "start_time = time()\n",
    "\n",
    "# Transpile Central Part\n",
    "\n",
    "transpiled_central_circuit = qiskit.transpile(\n",
    "    circuit,\n",
    "    backend,\n",
    "    seed_transpiler=SEED,\n",
    "    optimization_level=OPTIMIZATION_LEVEL)\n",
    "\n",
    "\n",
    "# Transpile Right all Rotation Circuits\n",
    "\n",
    "shadow_circuits = []\n",
    "\n",
    "rotation_tracker = tqdm(rotation_circuits, unit=' basis', ncols=110)\n",
    "\n",
    "for rotation_circuit in rotation_tracker:\n",
    "\n",
    "    measurement_circuit = rotation_circuit.measure_all(inplace=False)\n",
    "\n",
    "    shadow_circuit = transpile_right(\n",
    "        transpiled_central_circuit,\n",
    "        measurement_circuit,\n",
    "        backend=backend,\n",
    "        seed_transpiler=SEED,\n",
    "        optimization_level=OPTIMIZATION_LEVEL)\n",
    "\n",
    "    shadow_circuits.append(shadow_circuit)\n",
    "\n",
    "\n",
    "estimated_time = time() - start_time\n",
    "\n",
    "print(f\"estimated_time: {estimated_time:.02f}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92cf5ba6-99a4-4527-9c39-22dd25eed0ef",
   "metadata": {},
   "source": [
    "### 2.5. Compare Transpilation Times\n",
    "\n",
    "Above we have measured times for basic transpilation and transpilation with a `transpile_right`.\n",
    "\n",
    "Now we can extrapolate times for each transpilation type for a range of bases counts:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "36b28595-d03d-462a-a164-d89534ab0f4c",
   "metadata": {},
   "outputs": [],
   "source": [
    "bases_counts = list(range(1, 1000))\n",
    "\n",
    "basic_transpile_time = 20\n",
    "transpile_central_time = 18\n",
    "transpile_right_time = 0.2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "c9e6f27e-08aa-4890-a7d0-3d7610b9687a",
   "metadata": {},
   "outputs": [],
   "source": [
    "basic_transpile_totals = []\n",
    "transpile_right_totals = []\n",
    "\n",
    "for bases_count in bases_counts:\n",
    "\n",
    "    basic_transpile_total = bases_count * basic_transpile_time\n",
    "\n",
    "    transpile_right_total = transpile_central_time + bases_count * transpile_right_time\n",
    "    \n",
    "    basic_transpile_totals.append(basic_transpile_total)\n",
    "    transpile_right_totals.append(transpile_right_total)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "139ca91e-06e3-4774-9fb7-53d36d48a52a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot Transpilation times\n",
    "\n",
    "plt.title(\"Transpilation time comparison\")\n",
    "plt.xlabel(\"Bases count\")\n",
    "plt.ylabel(\"Total transpilation time, seconds\")\n",
    "\n",
    "plt.plot(bases_counts, basic_transpile_totals, label=\"Basic Transpilation\")\n",
    "plt.plot(bases_counts, transpile_right_totals, label=\"Transpile Right\")\n",
    "\n",
    "plt.gca().set_yscale('log')\n",
    "\n",
    "plt.legend()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6df2134e",
   "metadata": {},
   "source": [
    "## Conclusions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f666c277",
   "metadata": {},
   "source": [
    "We have compared 2 types of transpilation for shadow state tomography on 127-qubit backend: \n",
    "- **Basic Transpilation:** every “measurement circuit” is composed to “original circuit” – and then composed circuit is transpiled.\n",
    "- **Rivet transpilation** using the function `transpile_right`: we transpile “original circuit” only once – and then use `transpile_right` function of Rivet Transpiler – to transpile only “measurement circuit” part.\n",
    "\n",
    "Through this experiment we have demonstrated a HUGE time advantage of Rivet transpilation for 127-qubit complicated circuit of specific type."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9f68607",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "[1] IBM Quantum Development & Innovation Roadmap: https://www.ibm.com/quantum/assets/IBM_Quantum_Development_&_Innovation_Roadmap.pdf\n",
    "\n",
    "[2] Qiskit fake backends: https://docs.quantum.ibm.com/api/qiskit/0.37/providers_fake_provider"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "provenance": []
  },
  "kernelspec": {
   "display_name": "Qiskit_1.0",
   "language": "python",
   "name": "qiskit_1.0"
  },
  "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": 5
}