examples/braket_features/IQM_Garnet_Native_Gates.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "79af259d-2ae5-44e2-bcf6-77ecab397592",
   "metadata": {},
   "source": [
    "# IQM Garnet Native Gates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77418bf7-b4d7-4932-9bd6-fdd9434b5a2a",
   "metadata": {},
   "source": [
    "In this notebook, we will explore the functionality of the native gates of IQM Garnet. Programming a quantum circuit directly with native gates grants direct control over quantum operations on the quantum computer. The circuit will run exactly as you compose it. From this notebook, you will learn the mathematical representations of the native gates of IQM Garnet and how to program quantum circuits with these native gates. \n",
    "\n",
    "The native gates of IQM Garnet are the PRx gate and the CZ gate. These gates are physically implemented by applying microwave pulses on the transmon qubits. The PRx gate on its own forms a universal gate set for one-qubit operations. Any one-qubit unitary can be implemented using a few PRx gates. The PRx gate and CZ gate together constitute a universal gate set for quantum computation. Any quantum circuit can be realized using only these native gates."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0030081a-f162-488f-ad91-7e729ae2a4e6",
   "metadata": {},
   "source": [
    "Let's first import the necessary modules and define a constant."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "e38ed090-2cde-4e72-ba24-6d15b69d18c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import sympy as sp\n",
    "from sympy import nsimplify\n",
    "\n",
    "from braket.aws import AwsDevice\n",
    "from braket.circuits import Circuit\n",
    "\n",
    "pi = np.pi"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a5129599-d19a-4798-a2f6-3354d5fad0d3",
   "metadata": {},
   "source": [
    "## Single-qubit native gates\n",
    "\n",
    "### PRx gate\n",
    "\n",
    "The PRx gate, or the Phased Rx gate, is a generalized Rx rotation. With Rx($\\theta$) gate, you can rotate a one-qubit state around the x-axis by $\\theta$. The PRx gate generalizes this. With the PRx gate, you can rotate the one-qubit state around any axis in the x-y plane. The PRx gate has two parameters. The first parameter, $\\theta$, defines the angle of rotation around the axis. The second parameter, $\\phi$, defines the orientation of the axis in the x-y plane. For example, to rotate around the y-axis, we set $\\phi=\\pi/2$. To rotate around the x-axis, we set $\\phi=0$. \n",
    "\n",
    "Mathematically, the PRx gate can be represented as \n",
    "$$\n",
    "PRx(\\theta, \\phi) = Rz(\\phi)Rx(\\theta)Rz(-\\phi)\n",
    "$$\n",
    "You can understand the Rz gates as rotations of the reference frame. The reference frame is rotated by $-\\phi$ before applying the Rx($\\theta$), followed by rotating the reference frame back to the original one."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "27afaaf5-5ee8-43b3-91e0-c0ba3619c24a",
   "metadata": {},
   "outputs": [],
   "source": [
    "def rx_symbolic(x):\n",
    "    return sp.Matrix([[sp.cos(x / 2), -1j * sp.sin(x / 2)], [-1j * sp.sin(x / 2), sp.cos(x / 2)]])\n",
    "\n",
    "\n",
    "def rz_symbolic(x):\n",
    "    return sp.Matrix([[sp.exp(-1j * x / 2), 0], [0, sp.exp(1j * x / 2)]])\n",
    "\n",
    "\n",
    "def prx_symbolic(a1, a2):\n",
    "    return rz_symbolic(a2) * rx_symbolic(a1) * rz_symbolic(-a2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94047493-f3e6-4030-bedc-cd60149f77bd",
   "metadata": {},
   "source": [
    "The matrix representation of the PRx gate is"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "11acbb6c-86cb-46cb-8e83-1eb46d8d8af7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\cos{\\left(\\frac{\\theta}{2} \\right)} & - i e^{- i \\phi} \\sin{\\left(\\frac{\\theta}{2} \\right)}\\\\- i e^{i \\phi} \\sin{\\left(\\frac{\\theta}{2} \\right)} & \\cos{\\left(\\frac{\\theta}{2} \\right)}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[              cos(theta/2), -I*exp(-I*phi)*sin(theta/2)],\n",
       "[-I*exp(I*phi)*sin(theta/2),                cos(theta/2)]])"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "theta, phi = sp.symbols(\"theta phi\")\n",
    "prx_matrix = prx_symbolic(theta, phi)\n",
    "\n",
    "nsimplify(prx_matrix, tolerance=1e-8)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3035568d-b586-48ab-9f13-00884435efe8",
   "metadata": {},
   "source": [
    "Special case when $\\phi=0$: the gate PRx($\\theta$,$0$) is equivalent to Rx($\\theta$). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "db3c3eb5-d5c9-4dcf-acc0-8768910f5be1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\cos{\\left(\\frac{\\theta}{2} \\right)} & - i \\sin{\\left(\\frac{\\theta}{2} \\right)}\\\\- i \\sin{\\left(\\frac{\\theta}{2} \\right)} & \\cos{\\left(\\frac{\\theta}{2} \\right)}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[   cos(theta/2), -I*sin(theta/2)],\n",
       "[-I*sin(theta/2),    cos(theta/2)]])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "theta, phi = sp.symbols(\"theta phi\")\n",
    "rx_matrix = prx_symbolic(theta, 0)\n",
    "\n",
    "nsimplify(rx_matrix.evalf(), tolerance=1e-8)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef9456c3-0002-45b2-9797-1537d50160ef",
   "metadata": {},
   "source": [
    "Special case when $\\phi=\\pi/2$: the gate PRx($\\theta$,$\\pi/2$), is equivalent to Ry($\\theta$). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "226d2840-ed9f-4140-8f06-75e20142e0fa",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\cos{\\left(\\frac{\\theta}{2} \\right)} & - \\sin{\\left(\\frac{\\theta}{2} \\right)}\\\\\\sin{\\left(\\frac{\\theta}{2} \\right)} & \\cos{\\left(\\frac{\\theta}{2} \\right)}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[cos(theta/2), -sin(theta/2)],\n",
       "[sin(theta/2),  cos(theta/2)]])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "theta, phi = sp.symbols(\"theta phi\")\n",
    "ry_matrix = prx_symbolic(theta, pi / 2)\n",
    "\n",
    "nsimplify(ry_matrix.evalf(), tolerance=1e-8)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c1c13b8e-8b7b-477c-b13e-494604e98d83",
   "metadata": {},
   "source": [
    "## Two-qubit entangling gates\n",
    "### CZ gate\n",
    "The two-qubit native gate of IQM Garnet is the CZ gate. It is a symmetric gate that adds a phase to the portion of the two-qubit quantum state where both qubits are in the |1> state. The matrix representation of the CZ gate is \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "e465feab-9c08-4b72-b51d-bf6e984854b8",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}1 & 0 & 0 & 0\\\\0 & 1 & 0 & 0\\\\0 & 0 & 1 & 0\\\\0 & 0 & 0 & -1\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[1, 0, 0,  0],\n",
       "[0, 1, 0,  0],\n",
       "[0, 0, 1,  0],\n",
       "[0, 0, 0, -1]])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cz_symbolic = sp.diag(1, 1, 1, -1)\n",
    "cz_symbolic"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3d27a63b-faf5-4abd-a093-db7fcdcd0a5d",
   "metadata": {},
   "source": [
    "## Submitting verbatim circuits to IQM Garnet\n",
    "\n",
    "Below is an example of executing a circuit on IQM Garnet. When the circuit is submitted to Amazon Braket, it is compiled into an equivalent circuit that only includes native gates, PRx and CZ, before running on the quantum computer.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "c221b054-79c8-4d19-ab33-7a7522925c49",
   "metadata": {},
   "outputs": [],
   "source": [
    "device = AwsDevice(\"arn:aws:braket:eu-north-1::device/qpu/iqm/Garnet\")\n",
    "\n",
    "circuit = Circuit().h(0).cnot(0, 1)\n",
    "\n",
    "task = device.run(circuit, shots=100)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79858d2c-65b0-4fac-8544-f3e9f8209edd",
   "metadata": {},
   "source": [
    "In certain use cases, you may want to program your circuit and skip the compilation step. For example, in compilation research, you could be experimenting with various ways of preparing a quantum state. In algorithm research, you could be experimenting with error mitigation methods that requires applying gates and their inverses together, and you want to prevent a compiler from removing these gate-inverse pairs. In these cases, you can use verbatim compilation by adding your gates into a verbatim box. Gates enclosed by a verbatim box are not modified by the compiler. They will run exactly as you specified in the quantum circuit.\n",
    "\n",
    "Several rules apply for operations inside verbatim boxes:\n",
    "- All qubits must be physical qubits of the device\n",
    "- All two-qubit gates must be applied to physical edges of the device\n",
    "- All gates must be native gates of the device\n",
    "\n",
    "[This notebook](./Verbatim_Compilation.ipynb) shows you how to check the relevant device properties for verbatim compilation. The physical qubits of IQM Garnet are"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "6e76c3cf-9d01-4ed3-b3bd-5693d82782ec",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sorted(device.topology_graph.nodes)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e7cabad-3ea2-4854-a8c5-12a8c0f610ef",
   "metadata": {},
   "source": [
    "The physical edges of IQM Garnet are"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "bd171680-9d5d-440d-a935-a29da157321e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[(1, 2),\n",
       " (1, 4),\n",
       " (2, 5),\n",
       " (3, 4),\n",
       " (3, 8),\n",
       " (4, 5),\n",
       " (4, 9),\n",
       " (5, 6),\n",
       " (6, 7),\n",
       " (8, 9),\n",
       " (10, 5),\n",
       " (10, 9),\n",
       " (10, 11),\n",
       " (10, 15),\n",
       " (11, 6),\n",
       " (11, 12),\n",
       " (11, 16),\n",
       " (12, 7),\n",
       " (12, 17),\n",
       " (13, 8),\n",
       " (13, 14),\n",
       " (14, 9),\n",
       " (14, 15),\n",
       " (14, 18),\n",
       " (15, 16),\n",
       " (15, 19),\n",
       " (16, 17),\n",
       " (16, 20),\n",
       " (18, 19),\n",
       " (19, 20)]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sorted(device.topology_graph.edges)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "208b4cec-9fa1-4518-b614-c63c0037ec90",
   "metadata": {},
   "source": [
    "Based on these device properties, we can create a verbatim circuit:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "f8540d6b-c486-4a43-922d-ba431f9a9f75",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : │        0        │       1        │  2  │       3       │\n",
      "                        ┌──────────────┐                       \n",
      "q1 : ───StartVerbatim───┤ PRx(1.57, 1) ├───●─────EndVerbatim───\n",
      "              ║         └──────────────┘   │          ║        \n",
      "              ║                          ┌─┴─┐        ║        \n",
      "q2 : ─────────╨──────────────────────────┤ Z ├────────╨────────\n",
      "                                         └───┘                 \n",
      "T  : │        0        │       1        │  2  │       3       │\n"
     ]
    }
   ],
   "source": [
    "circuit = Circuit().prx(1, pi / 2, 1).cz(1, 2)\n",
    "circuit = Circuit().add_verbatim_box(circuit)\n",
    "print(circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5dbaeb4-4442-4c7b-a90a-c96d733af22a",
   "metadata": {},
   "source": [
    "## A tip for composing verbatim circuits on IQM device - Rz virtualization\n",
    "\n",
    "Although PRx alone can compose any one-qubit gate, sometime it is more intuitive to write circuits using Rz gates. This section provides a tip that allows you to start writing your circuits with IQM native gates plus Rz gates, and then remove the Rz gates with a process called Rz virtualization. \n",
    "\n",
    "Rz virtualization is based on the following two identities:\n",
    "1. CZ() Rz($\\alpha$) = Rz($\\alpha$) CZ()\n",
    "2. PRx($\\theta$, $\\phi$) Rz($\\alpha$) = Rz($\\alpha$) PRx($\\theta$, $\\phi-\\alpha$)\n",
    "\n",
    "To understand where the second identity comes from, let's substitute PRx on the left-hand side with the identity introduced in the beginning of this notebook, PRx($\\theta$, $\\phi$) = Rz($\\phi$) Rx($\\theta$) Rz($-\\phi$). Following the derivation below, the right-hand side of the identity is obtained:\n",
    "\n",
    "Rz($\\phi$) Rx($\\theta$) Rz($-\\phi$) Rz($\\alpha$)\n",
    "\n",
    "= Rz($\\phi$) Rx($\\theta$) Rz($-\\phi+\\alpha$)\n",
    "\n",
    "= Rz($\\alpha$) Rz($\\phi-\\alpha$) Rx($\\theta$) Rz($-\\phi+\\alpha$)\n",
    "\n",
    "= Rz($\\alpha$) PRx($\\theta$, $\\phi-\\alpha$)\n",
    "\n",
    "When you start with a circuit that has only Rz gates in addition to the IQM native gates, you can use these two identities to move all Rz gates to the very end of the circuit, just before the measurement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "10440181-4ee6-40a6-9b7a-29a1b3bbd3a5",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : │     0      │         1         │  2  │\n",
      "      ┌──────────┐ ┌─────────────────┐       \n",
      "q1 : ─┤ Rz(0.50) ├─┤ PRx(0.50, 1.50) ├───●───\n",
      "      └──────────┘ └─────────────────┘   │   \n",
      "      ┌──────────┐                     ┌─┴─┐ \n",
      "q2 : ─┤ Rz(0.70) ├─────────────────────┤ Z ├─\n",
      "      └──────────┘                     └───┘ \n",
      "T  : │     0      │         1         │  2  │\n"
     ]
    }
   ],
   "source": [
    "circuit_1 = Circuit().rz(1, 0.5).rz(2, 0.7).prx(1, 0.5, 1.5).cz(1, 2)\n",
    "print(circuit_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9cdcb301-a77b-46f9-b214-532766d7f1b6",
   "metadata": {},
   "source": [
    "The circuit above is equivalent to the following circuit with Rz gates moved to the end, up to a global phase."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "6ba84aff-e956-4e5f-a0d2-170d54c8c2b0",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : │         0         │  1  │     2      │\n",
      "      ┌─────────────────┐       ┌──────────┐ \n",
      "q1 : ─┤ PRx(0.50, 1.00) ├───●───┤ Rz(0.50) ├─\n",
      "      └─────────────────┘   │   └──────────┘ \n",
      "                          ┌─┴─┐ ┌──────────┐ \n",
      "q2 : ─────────────────────┤ Z ├─┤ Rz(0.70) ├─\n",
      "                          └───┘ └──────────┘ \n",
      "T  : │         0         │  1  │     2      │\n"
     ]
    }
   ],
   "source": [
    "circuit_2 = Circuit().prx(1, 0.5, 1.5 - 0.5).cz(1, 2).rz(1, 0.5).rz(2, 0.7)\n",
    "print(circuit_2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d51ead23-f5fe-4969-9b9b-f2c88791273d",
   "metadata": {},
   "source": [
    "We can compare the unitaries to make sure the two circuits are indeed equivalent. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "a7f77997-f5af-4698-b274-63eb578c4554",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "u1 = circuit_1.to_unitary()\n",
    "u2 = circuit_2.to_unitary()\n",
    "\n",
    "product = u1 @ np.linalg.inv(u2)\n",
    "np.isclose(np.abs(sum(np.diag(product))), 4.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b3575d3-df0f-40eb-87c6-bc00b2ea5b89",
   "metadata": {},
   "source": [
    "Finally, because an Rz gate at the end of a circuit does not have any direct effect on the measurement in the z-basis, the measurement results will be the same even if we remove all of these Rz gates that are just prior to the measurement. (Note that you can only remove the Rz gates in this way when your desired output is based on measurement counts or probability distribution of measurement outcomes. If your desired output is a state vector, removing the Rz gates would change the output.) Removing the Rz gates produces the following circuit, which consists only of IQM native gates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "0c74fcb8-8ce8-4d54-b000-493926a4f45a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : │         0         │  1  │\n",
      "      ┌─────────────────┐       \n",
      "q1 : ─┤ PRx(0.50, 1.00) ├───●───\n",
      "      └─────────────────┘   │   \n",
      "                          ┌─┴─┐ \n",
      "q2 : ─────────────────────┤ Z ├─\n",
      "                          └───┘ \n",
      "T  : │         0         │  1  │\n"
     ]
    }
   ],
   "source": [
    "circuit_3 = Circuit().prx(1, 0.5, 1.0).cz(1, 2)\n",
    "print(circuit_3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b09d6cf-bec4-4464-ac3a-e6d4d59a0035",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "This notebook introduces the native gate set of IQM Garnet and demonstrates how to write common gates like Rx and Ry gates in terms of the native PRx gate. An example is presented for composing and submitting verbatim circuits to IQM Garnet. Finally, the notebook provides a tip to help you compose verbatim circuits for IQM Garnet more easily by building circuits with Rz gates and then eliminating them from the circuit using Rz virtualization.  "
   ]
  }
 ],
 "metadata": {
  "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}