{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Circuit Execution Quality Metrics\n",
    "\n",
    "This tutorial covers benchmarks for measuring full circuit performance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qcmet import QuantumVolumeFixedQubits\n",
    "from qcmet.devices import IdealSimulator, NoisySimulator\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The circuit execution quality metrics consist of:\n",
    "\n",
    "- Quantum volume (QuantumVolumeFixedQubits)\n",
    "\n",
    "- Mirrored circuits average polarization (MirroredCircuits)\n",
    "\n",
    "- Upper bound on the variation distance (UpperBoundOnVD)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quantum Volume\n",
    "\n",
    "Quantum Volume (QV) is a holistic benchmark that measures the largest random circuit a quantum computer can execute successfully.\n",
    "\n",
    "### How Quantum Volume Works\n",
    "\n",
    "1. Generate random unitary circuits of depth = width = n\n",
    "2. Execute circuits and collect measurement statistics\n",
    "3. Compute Heavy Output Probability (HOP)\n",
    "4. If HOP > 2/3 with high confidence, QV = 2^n\n",
    "\n",
    "QV captures:\n",
    "- Gate fidelity\n",
    "- Measurement fidelity\n",
    "- Circuit connectivity\n",
    "- Crosstalk\n",
    "- Compilation quality"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Generated 20 QV circuits\n",
      "Each circuit has width=3 and depth=3\n"
     ]
    }
   ],
   "source": [
    "# Setup Quantum Volume benchmark\n",
    "qv = QuantumVolumeFixedQubits(\n",
    "    qubits=3,      # Test 3-qubit QV\n",
    "    trials=20,     # Number of random circuits\n",
    "    seed=42,       # For reproducibility\n",
    ")\n",
    "\n",
    "# Generate circuits\n",
    "qv.generate_circuits()\n",
    "print(f\"Generated {len(qv.circuits)} QV circuits\")\n",
    "print(f\"Each circuit has width={qv.num_qubits} and depth={qv.num_qubits}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Example Quantum Volume circuit:\n",
      "           ┌──────┐      ┌──────┐   ┌──────┐ ░ ┌─┐      \n",
      "   q_0: ─X─┤0     ├─X────┤0     ├───┤0     ├─░─┤M├──────\n",
      "         │ │  su4 │ │    │  su4 │   │  su4 │ ░ └╥┘┌─┐   \n",
      "   q_1: ─X─┤1     ├─X──X─┤1     ├─X─┤1     ├─░──╫─┤M├───\n",
      "           └──────┘    │ └──────┘ │ └──────┘ ░  ║ └╥┘┌─┐\n",
      "   q_2: ───────────────X──────────X──────────░──╫──╫─┤M├\n",
      "                                             ░  ║  ║ └╥┘\n",
      "meas: 3/════════════════════════════════════════╩══╩══╩═\n",
      "                                                0  1  2 \n"
     ]
    }
   ],
   "source": [
    "# Look at a QV circuit\n",
    "print(\"Example Quantum Volume circuit:\")\n",
    "print(qv.circuits[-1])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Quantum Volume Results:\n",
      "  mean: 0.844384765625\n",
      "  mean-2sigma: 0.6822742272843888\n",
      "  outcome: Pass\n",
      "  quantum_volume: >= 8\n"
     ]
    }
   ],
   "source": [
    "# Run on ideal simulator\n",
    "device = IdealSimulator()\n",
    "qv.run(device, num_shots=1024)\n",
    "\n",
    "# Analyze\n",
    "results = qv.analyze()\n",
    "print(\"\\nQuantum Volume Results:\")\n",
    "for key, value in results.items():\n",
    "    print(f\"  {key}: {value}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot\n",
    "qv.plot()\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Testing Different Qubit Counts"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Testing QV for 3 qubits...\n",
      "  QV = >= 8\n",
      "  mean HOP = 0.809\n",
      "  mean HOP - 2sigma = 0.698\n",
      "  Passed: Pass\n",
      "\n",
      "Testing QV for 4 qubits...\n",
      "  QV = < 16\n",
      "  mean HOP = 0.743\n",
      "  mean HOP - 2sigma = 0.620\n",
      "  Passed: Fail\n"
     ]
    }
   ],
   "source": [
    "# Test QV for different system sizes\n",
    "device = NoisySimulator(overrotation_amount = 0, detuning_amount = 0, error_1q = 0.00, error_2q = 0.01, t1 = 0, t2 = 0 )\n",
    "qv_results = {}\n",
    "\n",
    "for n_qubits in [3, 4]:\n",
    "    print(f\"\\nTesting QV for {n_qubits} qubits...\")\n",
    "\n",
    "    qv_test = QuantumVolumeFixedQubits(\n",
    "        qubits=n_qubits,\n",
    "        trials=50,\n",
    "        seed=42,\n",
    "    )\n",
    "\n",
    "    qv_test.generate_circuits()\n",
    "    qv_test.run(device, num_shots=1024)\n",
    "    result = qv_test.analyze()\n",
    "    qv_results[n_qubits] = result\n",
    "    print(f\"  QV = {result.get('quantum_volume', 'N/A')}\")\n",
    "    print(f\"  mean HOP = {result.get('mean', 'N/A'):.3f}\")\n",
    "    print(f\"  mean HOP - 2sigma = {result.get('mean-2sigma', 'N/A'):.3f}\")\n",
    "    print(f\"  Passed: {result.get('outcome', 'N/A')}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Interpreting the Results\n",
    "\n",
    "**What QV Tells You:**\n",
    "- QV = $2^{n}$ means the system can handle n-qubit circuits of depth n\n",
    "- Higher QV = better overall quantum computer\n",
    "- QV = 64 means 6 qubits × depth 6\n",
    "\n",
    "**Heavy Output Probability (HOP):**\n",
    "- Must exceed 2/3 (66.7%) to pass with a confidence of 2 sigma\n",
    "- Measures fraction of \"heavy\" outputs (above median probability)\n",
    "- HOP > 2/3 means circuits are executed correctly\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other Benchmarks\n",
    "\n",
    "QCMet furthermore implements mirrored circuits average polarization and the upper bound on the variation distance as circuit execution quality metrics."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "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.12.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}