examples/braket_features/IonQ_Native_Gates.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "87c15796-c783-4b91-bc28-4389df9f8308",
   "metadata": {},
   "source": [
    "# IonQ Native Gates\n",
    "\n",
    "In this notebook, we will dive into the details of IonQ's native gates and their functionalities, enabling us to realize direct control over the quantum operations on the computer without compiler optimizations or error mitigation. We will discuss the native gates available on IonQ, their mathematical representations, and how they can be used for applications such as the quantum Fourier transform (QFT). \n",
    "\n",
    "IonQ's native gateset includes the GPi, GPi2, and arbitrary angle MS gate. These gates are physically implemented on IonQ hardware by utilizing resonant lasers to address ions through stimulated Raman transitions. The three gates provide a universal gate set for quantum computation. This means any quantum circuit can be realized with only these elementary operations. \n",
    "\n",
    "## Table of Contents\n",
    "- Single-qubit gates\n",
    "    - GPi gate: $X, Y$ gates\n",
    "    - GPi2 gate: $R_X(\\pi/2), R_Y(\\pi/2)$ gates\n",
    "    - General gate decompositions\n",
    "    - Common single-qubit gates: $H$, $S$, $T$.\n",
    "    - Writing native IonQ circuits in Braket \n",
    "- Two-qubit gates: Arbitrary angle Mølmer-Sørenson gate\n",
    "  - Mapping CNot into $XX$\n",
    "  - Mapping controlled roots of Pauli gates into $XX$ gates\n",
    "- Quantum Fourier transform with native gates"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "266ddd70-259f-4b7b-8e6e-8d82165e3b4d",
   "metadata": {},
   "source": [
    "## Single-qubit native gates\n",
    "\n",
    "### GPi gate\n",
    "\n",
    "The GPi gate is a fundamental single-qubit gate used in IonQ's trapped-ion quantum computing systems. It performs a rotation of $\\pi$ radians (180 degrees) on the Bloch sphere. What makes the GPi gate unique is its ability to rotate along any axis in the $xy$-plane of the Bloch sphere by adjusting the parameter $\\phi$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "0b7acc99-81bc-4bde-a1f1-6b84db2f3297",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The GPi gate is defined as:\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}0 & e^{- i \\phi}\\\\e^{i \\phi} & 0\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[         0, exp(-I*phi)],\n",
       "[exp(I*phi),           0]])"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sympy import I, Matrix, exp, pi, sqrt, symbols\n",
    "\n",
    "phi = symbols(\"phi\")\n",
    "\n",
    "gpi = Matrix([[0, exp(-I * phi)], [exp(I * phi), 0]])\n",
    "GPi = lambda x: gpi.subs({\"phi\": x})\n",
    "\n",
    "print(\"The GPi gate is defined as:\")\n",
    "GPi(phi)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1bac70d5-2b3b-4389-bbf7-bc76af636c54",
   "metadata": {},
   "source": [
    "For $\\phi=0$, the GPi gate is equivalent to the Pauli $X$-gate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "55f428f4-eb04-4741-ad21-beedc5a66246",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}0 & 1\\\\1 & 0\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[0, 1],\n",
       "[1, 0]])"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = GPi(0)\n",
    "x"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a80de21-9990-4c48-99d0-4df20b6c32d0",
   "metadata": {},
   "source": [
    "For $\\phi=\\pi/2$, the GPi gate is the Pauli $Y$ gate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "977bb508-9501-4c85-9bab-e99c18400280",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}0 & - i\\\\i & 0\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[0, -I],\n",
       "[I,  0]])"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "y = GPi(pi / 2)\n",
    "y"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68962f54-3355-470a-b03e-c17e67c6a9d9",
   "metadata": {},
   "source": [
    "In summary, the GPi gate offers the capability to provide Pauli $X$ and $Y$ rotations, as well as rotations about any azimuthal angle on the Bloch sphere."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c4a618a-bd91-4eda-bd6b-d5b0390f65f8",
   "metadata": {},
   "source": [
    "### GPi2 gate\n",
    "\n",
    "The GPi2 gate performs a rotation of $\\pi/2$ radians (90 degrees) on the Bloch sphere. Similar to the GPi gate, the GPi2 gate provides flexibility by allowing rotations along any longitudinal axis of the Bloch sphere. It can be considered as an $R_X(\\pi/2)$ or $R_Y(\\pi/2)$ gate, depending on the parameter $\\phi$. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "6329227f-0b15-42a0-baec-4c4ad78a753d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The GPi2 gate is defined as:\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\frac{\\sqrt{2}}{2} & - \\frac{\\sqrt{2} i e^{- i \\phi}}{2}\\\\- \\frac{\\sqrt{2} i e^{i \\phi}}{2} & \\frac{\\sqrt{2}}{2}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[              sqrt(2)/2, -sqrt(2)*I*exp(-I*phi)/2],\n",
       "[-sqrt(2)*I*exp(I*phi)/2,                sqrt(2)/2]])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gpi2 = 1 / sqrt(2) * Matrix([[1, -I * exp(-I * phi)], [-I * exp(I * phi), 1]])\n",
    "GPi2 = lambda x: gpi2.subs({\"phi\": x})\n",
    "\n",
    "print(\"The GPi2 gate is defined as:\")\n",
    "GPi2(phi)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c5447b0-156f-404c-8f5a-8ba55d75ceae",
   "metadata": {},
   "source": [
    "The $R_X(\\pi/2)$ rotation gate is realized by setting $\\phi=0$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "123874b3-5f46-4a7c-a6a6-52efdea8dd75",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\frac{\\sqrt{2}}{2} & - \\frac{\\sqrt{2} i}{2}\\\\- \\frac{\\sqrt{2} i}{2} & \\frac{\\sqrt{2}}{2}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[   sqrt(2)/2, -sqrt(2)*I/2],\n",
       "[-sqrt(2)*I/2,    sqrt(2)/2]])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "rx_pi2 = GPi2(0)\n",
    "rx_pi2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1524415-9607-4c83-ab52-f9781f88d4ca",
   "metadata": {},
   "source": [
    "So the GPI2 can realize the square root of the $X$ gate, $\\text{GPi}(0) = R_X(\\pi/2)=e^{-i \\pi/4}\\sqrt{X}=e^{-i \\pi/4}V$ up to a phase. In Braket, this is the $V$ gate. \n",
    "\n",
    "\n",
    "Likewise, the The $R_Y(\\pi/2)$ rotation gate is realized by setting $\\phi=\\pi/2$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "ea8e92ac-baa5-4c17-aed3-a31558681a6d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\frac{\\sqrt{2}}{2} & - \\frac{\\sqrt{2}}{2}\\\\\\frac{\\sqrt{2}}{2} & \\frac{\\sqrt{2}}{2}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[sqrt(2)/2, -sqrt(2)/2],\n",
       "[sqrt(2)/2,  sqrt(2)/2]])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ry_pi2 = GPi2(pi / 2)\n",
    "ry_pi2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "102b5cf2-0b3c-4067-9d6f-aa807027a141",
   "metadata": {},
   "source": [
    "In summary, the GPi2 provides a way to use a $V$ gate on IonQ as well as $R_Y(\\pi/2)$ rotations."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "121e70a0-baa7-429f-909d-0742287d4a51",
   "metadata": {},
   "source": [
    "### General single-qubit decompositions\n",
    "\n",
    "Any single-qubit gate can be decomposed into a sequence of rotations. Each rotation is parameterized by one of the Euler angles. The $\\alpha$ angle corresponds to the rotation around the $Z$ axis, the $\\beta$ angle corresponds to the rotation around the $X$ axis, and the $\\gamma$ angle corresponds to the rotation around the $Z$ axis again. This is known as the ZXZ decomposition. Any single-qubit gate can be expressed in the ZXZ decomposition.\n",
    "\n",
    "$$\\begin{equation}\n",
    "R(\\alpha,\\beta,\\gamma) = \\operatorname{Rz}(\\alpha) \\operatorname{Rx}(\\beta) \\operatorname{Rz}(\\gamma) \n",
    "\\end{equation}$$\n",
    "\n",
    "Instead of ZXZ, the IonQ native gates provide a basis set for a similar decomposition. The mapping from the typical ZXZ to native gates is:\n",
    "$$\\begin{equation}\n",
    "R(\\alpha,\\beta,\\gamma) = -i \\,\n",
    "\\text{GPi2}\\left(\\alpha-\\frac{\\pi}{2}\\right) \\,\\text{GPi}\\left(\\frac{\\alpha-\\gamma-\\beta-\\pi}{2}\\right) \\,\\text{GPi2}\\left(\\frac{3\\pi}{2}-\\gamma\\right)\n",
    "\\end{equation}$$\n",
    "\n",
    "Below, we demonstrate this proof using Sympy. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "8742ac2d-e0e4-40ff-9066-1c66c5c82759",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}e^{- \\frac{i \\left(\\alpha + \\gamma\\right)}{2}} \\cos{\\left(\\frac{\\beta}{2} \\right)} & - i e^{- \\frac{i \\left(\\alpha - \\gamma\\right)}{2}} \\sin{\\left(\\frac{\\beta}{2} \\right)}\\\\- i e^{\\frac{i \\left(\\alpha - \\gamma\\right)}{2}} \\sin{\\left(\\frac{\\beta}{2} \\right)} & e^{\\frac{i \\left(\\alpha + \\gamma\\right)}{2}} \\cos{\\left(\\frac{\\beta}{2} \\right)}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[  exp(-I*(alpha + gamma)/2)*cos(beta/2), -I*exp(-I*(alpha - gamma)/2)*sin(beta/2)],\n",
       "[-I*exp(I*(alpha - gamma)/2)*sin(beta/2),     exp(I*(alpha + gamma)/2)*cos(beta/2)]])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sympy import I, Matrix, cos, exp, expand, pi, simplify, sin, symbols, trigsimp\n",
    "\n",
    "alpha, beta, gamma = symbols(\"alpha, beta, gamma\")\n",
    "\n",
    "RX = lambda alpha: Matrix(\n",
    "    [[cos(alpha / 2), -I * sin(alpha / 2)], [-I * sin(alpha / 2), cos(alpha / 2)]]\n",
    ")\n",
    "RZ = lambda beta: Matrix([[exp(-I * beta / 2), 0], [0, exp(I * beta / 2)]])\n",
    "\n",
    "zxz = simplify(RZ(alpha) * RX(beta) * RZ(gamma), full=True)\n",
    "zxz"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "ef081a15-cee2-4fa8-abb6-c2ca8691f550",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}e^{- \\frac{i \\left(\\alpha + \\gamma\\right)}{2}} \\cos{\\left(\\frac{\\beta}{2} \\right)} & - i e^{- \\frac{i \\left(\\alpha - \\gamma\\right)}{2}} \\sin{\\left(\\frac{\\beta}{2} \\right)}\\\\- i e^{\\frac{i \\left(\\alpha - \\gamma\\right)}{2}} \\sin{\\left(\\frac{\\beta}{2} \\right)} & e^{\\frac{i \\left(\\alpha + \\gamma\\right)}{2}} \\cos{\\left(\\frac{\\beta}{2} \\right)}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[  exp(-I*(alpha + gamma)/2)*cos(beta/2), -I*exp(-I*(alpha - gamma)/2)*sin(beta/2)],\n",
       "[-I*exp(I*(alpha - gamma)/2)*sin(beta/2),     exp(I*(alpha + gamma)/2)*cos(beta/2)]])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# with some help, sympy can simplify this expression\n",
    "general_rotation = (\n",
    "    GPi2(alpha - pi / 2)\n",
    "    * GPi((alpha - beta - gamma + pi) / 2)\n",
    "    * GPi2(3 * pi / 2 - gamma)\n",
    ")\n",
    "general_rotation = simplify(\n",
    "    exp(-I * alpha / 2) * exp(I * gamma / 2) * general_rotation\n",
    ")  # bottom sin\n",
    "general_rotation = simplify(exp(I * alpha) * general_rotation)  # top cos\n",
    "general_rotation = simplify(exp(-I * gamma) * general_rotation)  # top sin\n",
    "general_rotation = simplify(exp(-I * alpha) * general_rotation)  # bottom cos\n",
    "general_rotation = simplify(\n",
    "    -I * exp(I * (alpha + gamma) / 2) * general_rotation\n",
    ")  # undo the phase factors\n",
    "general_rotation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9866710e-a1e7-4bc1-91bc-81c4e19e1bfe",
   "metadata": {},
   "source": [
    "Therefore, the combination of GPi and GPi2 gates gives the same effect as ZXZ up to a phase factor of $-i$. This decomposition allows any arbitrary single-qubit gate to run as a combination of native gates on IonQ. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d631f27a-a852-4d59-8157-baf60acbbb12",
   "metadata": {},
   "source": [
    "### Common single-qubit gates\n",
    "\n",
    "For example, the Hadamard gate is usually decomposed as $H=X \\sqrt{Y}$. This can be implemented as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "a58b9da6-8cf4-4c9b-b33e-c23f67ef022e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\frac{\\sqrt{2}}{2} & \\frac{\\sqrt{2}}{2}\\\\\\frac{\\sqrt{2}}{2} & - \\frac{\\sqrt{2}}{2}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "Matrix([\n",
       "[sqrt(2)/2,  sqrt(2)/2],\n",
       "[sqrt(2)/2, -sqrt(2)/2]])"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# H = X * sqrt(Y)\n",
    "hadamard = GPi(0) * GPi2(pi / 2)\n",
    "hadamard"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5ee352c-ed5f-479c-8600-ff72ea64d832",
   "metadata": {},
   "source": [
    "We can use the general single-qubit rotation decomposition to construct more complex gates such as $R_X, R_Y, R_Z, S, T$. Below we list these gates and their decompositions. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "83cf6b31-1817-48cb-a220-8967f78ef0ff",
   "metadata": {},
   "outputs": [],
   "source": [
    "theta = symbols(\"theta\")\n",
    "\n",
    "ID = GPi(0) * GPi(0)\n",
    "X = GPi(0)\n",
    "Y = GPi(pi / 2)\n",
    "Z = 1j * GPi(pi / 2) * GPi(pi)\n",
    "\n",
    "RX = I * GPi2(pi / 2) * GPi(theta / 2 + pi / 2) * GPi2(pi / 2)\n",
    "RY = I * GPi2(pi) * GPi(theta / 2 + pi) * GPi2(pi)\n",
    "RZ = GPi(theta / 2) * GPi(0)\n",
    "\n",
    "H = GPi(0) * GPi2(pi / 2)\n",
    "T = -I * exp(I * pi / 8) * GPi2(-3 * pi / 8) * GPi(pi / 2) * GPi2(11 * pi / 8)\n",
    "S = -I * exp(I * pi / 4) * GPi2(-pi / 4) * GPi(pi / 2) * GPi2(5 * pi / 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d93e7df9-6efb-4c98-9246-25645352f069",
   "metadata": {},
   "source": [
    "### Native gate circuits on Braket \n",
    "\n",
    "In this section we show how to write IonQ native gate circuits in the Amazon Braket SDK. \n",
    "\n",
    "Writing native gate circuits in Braket can be supported by creating a subclass of the Circuit class and adding native gate decompositions. In this example, we name the class `IonQNativeCircuit` and the gates will be decomposed using the formulas from the previous sections. \n",
    "\n",
    "Below, we provide a code snippet that creates the native circuit class with the gate definitions from the previous section. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "da3aff80-9737-4c91-9af5-d558e8684c52",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from braket.circuits import Circuit, Gate\n",
    "\n",
    "\n",
    "class IonQNativeCircuit(Circuit):\n",
    "    pi = np.pi\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        if not self.result_types:\n",
    "            return f\"IonQNativeCircuit('instructions': {self.instructions})\"\n",
    "        else:\n",
    "            return (\n",
    "                f\"IonQNativeCircuit('instructions': {self.instructions}\"\n",
    "                + f\", 'result_types': {self.result_types})\"\n",
    "            )\n",
    "\n",
    "    def add_instruction(self, instruction, target=None, target_mapping=None):\n",
    "        # Validate that only native gates are added to the circuit\n",
    "\n",
    "        # qubit validation\n",
    "        max_num_qubits = 25  # maximum number of qubits on Aria\n",
    "        qubits = list(instruction.target)\n",
    "        for qubit in qubits:\n",
    "            if not (0 <= qubit < max_num_qubits):\n",
    "                raise ValueError(\n",
    "                    f\"Qubit {qubit} is not in the valid range [0, {max_num_qubits}].\"\n",
    "                )\n",
    "\n",
    "        # gate validation\n",
    "        valid_gate_names = {Gate.GPi, Gate.GPi2, Gate.MS}\n",
    "        gate_name = instruction.operator\n",
    "        if not any(isinstance(gate_name, gate_cls) for gate_cls in valid_gate_names):\n",
    "            raise ValueError(f\"Gate {gate_name} is not in the valid gates.\")\n",
    "\n",
    "        return super().add_instruction(instruction, target, target_mapping)\n",
    "\n",
    "    # universal single-qubit rotation decomposition\n",
    "    def unitary(self, qubit, a, b, c):\n",
    "        return self.gpi2(qubit, a).gpi(qubit, b).gpi2(qubit, c)\n",
    "\n",
    "    def x(self, qubit):\n",
    "        return self.gpi(qubit, 0)\n",
    "\n",
    "    def y(self, qubit):\n",
    "        return self.gpi(qubit, pi / 2)\n",
    "\n",
    "    def z(self, qubit):\n",
    "        return self.gpi(qubit, pi).gpi(qubit, pi / 2)\n",
    "\n",
    "    def h(self, qubit):\n",
    "        return self.gpi2(qubit, pi / 2).gpi(qubit, 0)\n",
    "\n",
    "    def t(self, qubit):\n",
    "        return self.unitary(qubit, 11 * pi / 8, pi / 2, -3 * pi / 8)\n",
    "\n",
    "    def s(self, qubit):\n",
    "        return self.unitary(qubit, 5 * pi / 4, pi / 2, -pi / 4)\n",
    "\n",
    "    def rx(self, qubit, theta):\n",
    "        return self.unitary(qubit, pi / 2, theta / 2 + pi / 2, pi / 2)\n",
    "\n",
    "    def ry(self, qubit, theta):\n",
    "        return self.unitary(qubit, pi, theta / 2 + pi, pi)\n",
    "\n",
    "    def rz(self, qubit, theta):\n",
    "        return self.gpi(qubit, 0).gpi(qubit, theta / 2)\n",
    "\n",
    "    # add friendly printing\n",
    "    def to_unitary(self):\n",
    "        return np.round(super().to_unitary(), 5)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "731ad065",
   "metadata": {},
   "source": [
    "Below we create a `IonQNativeCircuit` with a single Hadamard gate. Notice how the effect of the `h` gate is to add `gpi(pi/2)*gpi(0)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "83e7cf40-5562-423f-b1fb-b034335828cc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : |    0     |  1   |\n",
      "                        \n",
      "q0 : -GPi2(pi/2)-GPi(0)-\n",
      "\n",
      "T  : |    0     |  1   |\n"
     ]
    }
   ],
   "source": [
    "circ = IonQNativeCircuit().h(0)\n",
    "\n",
    "print(circ)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3c65be89-0c67-4843-86c7-f197b53c599f",
   "metadata": {},
   "source": [
    "Alternatively, instead of writing the gate decompositions as class methods, they can be append to the `IonQNativeCircuit` class with with the `register_subrountine` method. For example, in the class definition above we did not define the identity gate. We can register it to the class as follows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "3bf21115-fd78-4d6b-8762-479fe0a81caa",
   "metadata": {},
   "outputs": [],
   "source": [
    "def i(qubit):\n",
    "    return IonQNativeCircuit().gpi(qubit, 0).gpi(qubit, 0)\n",
    "\n",
    "\n",
    "IonQNativeCircuit.register_subroutine(i)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "b0158654-cd3c-4ab8-b84a-bc2fc54fdd7c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : |  0   |  1   |\n",
      "                    \n",
      "q0 : -GPi(0)-GPi(0)-\n",
      "\n",
      "T  : |  0   |  1   |\n"
     ]
    }
   ],
   "source": [
    "circ = IonQNativeCircuit().i(0)\n",
    "\n",
    "print(circ)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6ba2b5a-5431-4467-aeaf-1b46aa7a7937",
   "metadata": {},
   "source": [
    "Now we can create native circuits with the usual Braket syntax. However, all gate will be converted into the native gate set. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "0c046301-ecea-4efc-903a-3a24cb4dc9a2",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : |    0     |    1     |  2   |  3   |\n",
      "                                          \n",
      "q0 : -GPi(0)-----GPi2(pi/2)-GPi(0)--------\n",
      "                                          \n",
      "q1 : -GPi2(pi/2)-GPi(0)-----GPi(0)-GPi(0)-\n",
      "                                          \n",
      "q2 : -GPi(pi/2)---------------------------\n",
      "\n",
      "T  : |    0     |    1     |  2   |  3   |\n"
     ]
    }
   ],
   "source": [
    "print(IonQNativeCircuit().x(0).h(1).y(2).h(0).i(1))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef720b17-a40e-45cd-b9d9-9f0c5c501e29",
   "metadata": {},
   "source": [
    "Notice how each gate is expanded into the native gate set. \n",
    "\n",
    "Next, we double check that the unitaries are the same for both circuits. Below is a function to test if the unitaries are equal up to a phase. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "633ba61c-942c-4d5d-b2a3-067a65cf8dc1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def eq_up_to_phase(U1, U2, atol: float = 1e-5, rtol: float = 1e-5):\n",
    "    i, j = np.unravel_index(np.argmax(abs(U1), axis=None), U1.shape)\n",
    "    phase = U2[i, j] / U1[i, j]\n",
    "    eq = np.allclose(U1 * phase, U2, atol=atol, rtol=rtol)\n",
    "    return eq\n",
    "\n",
    "\n",
    "unitary = Circuit().h(0).rz(0, 0.4).rx(1, 0.5).to_unitary()\n",
    "unitary_native = IonQNativeCircuit().h(0).rz(0, 0.4).rx(1, 0.5).to_unitary()\n",
    "\n",
    "eq_up_to_phase(unitary, unitary_native)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07a57e3b-b58f-4d88-a83f-a2a01b7f7dea",
   "metadata": {},
   "source": [
    "In summary, this section provided details about the native gate set on IonQ. \n",
    "It gave an overview of how to construct common single-qubit gates using the GPi and GPi2 gates. \n",
    "Lastly, the code snippet demonstrates how Braket SDK can construct native gate circuits. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ecd4f0c-6db8-49e5-9d52-28014b1d7cae",
   "metadata": {},
   "source": [
    "## Two-qubit entangling gates\n",
    "\n",
    "### Arbitrary angle Mølmer-Sørenson gate \n",
    "\n",
    "The native two-qubit entangling gate on IonQ is the arbitrary angle Mølmer-Sørenson (MS) gate. It realizes an XX gate, this is a simultaneous, entangling $\\pi/2$ rotation on both qubits, however with other angles, both XY and YY are possible. \n",
    "\n",
    "The arbitrary angle MS gate is defined as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "3203623c-dfee-4dec-abfa-14ca61988952",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The arbitrary angle MS gate is defined as:\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\cos{\\left(\\frac{\\theta}{2} \\right)} & 0 & 0 & - i e^{- i \\left(\\phi_{0} + \\phi_{1}\\right)} \\sin{\\left(\\frac{\\theta}{2} \\right)}\\\\0 & \\cos{\\left(\\frac{\\theta}{2} \\right)} & - i e^{- i \\left(\\phi_{0} - \\phi_{1}\\right)} \\sin{\\left(\\frac{\\theta}{2} \\right)} & 0\\\\0 & - i e^{i \\left(\\phi_{0} - \\phi_{1}\\right)} \\sin{\\left(\\frac{\\theta}{2} \\right)} & \\cos{\\left(\\frac{\\theta}{2} \\right)} & 0\\\\- i e^{i \\left(\\phi_{0} + \\phi_{1}\\right)} \\sin{\\left(\\frac{\\theta}{2} \\right)} & 0 & 0 & \\cos{\\left(\\frac{\\theta}{2} \\right)}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[              /theta\\                                                                                      -I*(phi_0 + phi_1)    /theta\\]\n",
       "[           cos|-----|                            0                                  0                  -I*e                  *sin|-----|]\n",
       "[              \\  2  /                                                                                                            \\  2  /]\n",
       "[                                                                                                                                        ]\n",
       "[                                                /theta\\                 -I*(phi_0 - phi_1)    /theta\\                                   ]\n",
       "[               0                             cos|-----|             -I*e                  *sin|-----|                  0                ]\n",
       "[                                                \\  2  /                                       \\  2  /                                   ]\n",
       "[                                                                                                                                        ]\n",
       "[                                      I*(phi_0 - phi_1)    /theta\\                /theta\\                                               ]\n",
       "[               0                  -I*e                 *sin|-----|             cos|-----|                              0                ]\n",
       "[                                                           \\  2  /                \\  2  /                                               ]\n",
       "[                                                                                                                                        ]\n",
       "[    I*(phi_0 + phi_1)    /theta\\                                                                                     /theta\\            ]\n",
       "[-I*e                 *sin|-----|                 0                                  0                             cos|-----|            ]\n",
       "[                         \\  2  /                                                                                     \\  2  /            ]"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from sympy import I, Matrix, cos, exp, pi, sin, symbols\n",
    "from sympy.interactive.printing import init_printing\n",
    "from sympy.matrices import Matrix\n",
    "\n",
    "init_printing(use_unicode=False, wrap_line=False)\n",
    "\n",
    "theta, phi_0, phi_1 = symbols(\"theta phi_0 phi_1\")\n",
    "\n",
    "aams_matrix = Matrix(\n",
    "    [\n",
    "        [cos(theta / 2), 0, 0, -I * exp(-I * (phi_0 + phi_1)) * sin(theta / 2)],\n",
    "        [0, cos(theta / 2), -I * exp(-I * (phi_0 - phi_1)) * sin(theta / 2), 0],\n",
    "        [0, -I * exp(I * (phi_0 - phi_1)) * sin(theta / 2), cos(theta / 2), 0],\n",
    "        [-I * exp(I * (phi_0 + phi_1)) * sin(theta / 2), 0, 0, cos(theta / 2)],\n",
    "    ]\n",
    ")\n",
    "print(\"The arbitrary angle MS gate is defined as:\")\n",
    "aams_matrix"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9af6fe3-166e-46e4-a5ee-efe80306e082",
   "metadata": {},
   "source": [
    "If optional third angle $\\theta$ is not provided, then the default value is $\\theta=\\pi/2$ which is the fully entangling MS gate:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "a8e4c7c2-6678-45d3-b50c-5e624cff0006",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The default MS gate is defined as:\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\frac{\\sqrt{2}}{2} & 0 & 0 & - \\frac{\\sqrt{2} i e^{- i \\left(\\phi_{0} + \\phi_{1}\\right)}}{2}\\\\0 & \\frac{\\sqrt{2}}{2} & - \\frac{\\sqrt{2} i e^{- i \\left(\\phi_{0} - \\phi_{1}\\right)}}{2} & 0\\\\0 & - \\frac{\\sqrt{2} i e^{i \\left(\\phi_{0} - \\phi_{1}\\right)}}{2} & \\frac{\\sqrt{2}}{2} & 0\\\\- \\frac{\\sqrt{2} i e^{i \\left(\\phi_{0} + \\phi_{1}\\right)}}{2} & 0 & 0 & \\frac{\\sqrt{2}}{2}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[             ___                                                                              ___    -I*(phi_0 + phi_1) ]\n",
       "[           \\/ 2                                                                            -\\/ 2 *I*e                   ]\n",
       "[           -----                           0                              0                -----------------------------]\n",
       "[             2                                                                                           2              ]\n",
       "[                                                                                                                        ]\n",
       "[                                           ___                 ___    -I*(phi_0 - phi_1)                                ]\n",
       "[                                         \\/ 2               -\\/ 2 *I*e                                                  ]\n",
       "[             0                           -----              -----------------------------                0              ]\n",
       "[                                           2                              2                                             ]\n",
       "[                                                                                                                        ]\n",
       "[                                 ___    I*(phi_0 - phi_1)                 ___                                           ]\n",
       "[                              -\\/ 2 *I*e                                \\/ 2                                            ]\n",
       "[             0                ----------------------------              -----                            0              ]\n",
       "[                                           2                              2                                             ]\n",
       "[                                                                                                                        ]\n",
       "[   ___    I*(phi_0 + phi_1)                                                                              ___            ]\n",
       "[-\\/ 2 *I*e                                                                                             \\/ 2             ]\n",
       "[----------------------------               0                              0                            -----            ]\n",
       "[             2                                                                                           2              ]"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "print(\"The default MS gate is defined as:\")\n",
    "\n",
    "ms = aams_matrix.subs({\"theta\": pi / 2})\n",
    "ms"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40b1cab1-db3b-4f83-bace-c24792180304",
   "metadata": {},
   "source": [
    "The more familiar $XX(\\theta)$ gate is realized by setting the first two MS angles to zero."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "76372ed1-0900-43fb-a628-b5d1f9a33fa6",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The XX(theta) gate is defined as:\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\cos{\\left(\\frac{\\theta}{2} \\right)} & 0 & 0 & - i \\sin{\\left(\\frac{\\theta}{2} \\right)}\\\\0 & \\cos{\\left(\\frac{\\theta}{2} \\right)} & - i \\sin{\\left(\\frac{\\theta}{2} \\right)} & 0\\\\0 & - i \\sin{\\left(\\frac{\\theta}{2} \\right)} & \\cos{\\left(\\frac{\\theta}{2} \\right)} & 0\\\\- i \\sin{\\left(\\frac{\\theta}{2} \\right)} & 0 & 0 & \\cos{\\left(\\frac{\\theta}{2} \\right)}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[    /theta\\                                        /theta\\]\n",
       "[ cos|-----|          0              0        -I*sin|-----|]\n",
       "[    \\  2  /                                        \\  2  /]\n",
       "[                                                          ]\n",
       "[                   /theta\\          /theta\\               ]\n",
       "[      0         cos|-----|    -I*sin|-----|        0      ]\n",
       "[                   \\  2  /          \\  2  /               ]\n",
       "[                                                          ]\n",
       "[                     /theta\\      /theta\\                 ]\n",
       "[      0        -I*sin|-----|   cos|-----|          0      ]\n",
       "[                     \\  2  /      \\  2  /                 ]\n",
       "[                                                          ]\n",
       "[      /theta\\                                    /theta\\  ]\n",
       "[-I*sin|-----|        0              0         cos|-----|  ]\n",
       "[      \\  2  /                                    \\  2  /  ]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "print(\"The XX(theta) gate is defined as:\")\n",
    "\n",
    "xx = aams_matrix.subs({\"phi_0\": 0, \"phi_1\": 0})\n",
    "xx"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fdf4b881-feb6-4c4f-a22c-7316baa1c828",
   "metadata": {},
   "source": [
    "The YY gate is achieved by setting $\\phi_0=\\phi_1 = \\pi/2$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "6f94b4ab-c966-4db0-b5eb-73594829accd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The YY(theta) gate is defined as:\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}\\cos{\\left(\\frac{\\theta}{2} \\right)} & 0 & 0 & i \\sin{\\left(\\frac{\\theta}{2} \\right)}\\\\0 & \\cos{\\left(\\frac{\\theta}{2} \\right)} & - i \\sin{\\left(\\frac{\\theta}{2} \\right)} & 0\\\\0 & - i \\sin{\\left(\\frac{\\theta}{2} \\right)} & \\cos{\\left(\\frac{\\theta}{2} \\right)} & 0\\\\i \\sin{\\left(\\frac{\\theta}{2} \\right)} & 0 & 0 & \\cos{\\left(\\frac{\\theta}{2} \\right)}\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[    /theta\\                                      /theta\\]\n",
       "[ cos|-----|         0              0        I*sin|-----|]\n",
       "[    \\  2  /                                      \\  2  /]\n",
       "[                                                        ]\n",
       "[                  /theta\\          /theta\\              ]\n",
       "[     0         cos|-----|    -I*sin|-----|       0      ]\n",
       "[                  \\  2  /          \\  2  /              ]\n",
       "[                                                        ]\n",
       "[                    /theta\\      /theta\\                ]\n",
       "[     0        -I*sin|-----|   cos|-----|         0      ]\n",
       "[                    \\  2  /      \\  2  /                ]\n",
       "[                                                        ]\n",
       "[     /theta\\                                    /theta\\ ]\n",
       "[I*sin|-----|        0              0         cos|-----| ]\n",
       "[     \\  2  /                                    \\  2  / ]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "print(\"The YY(theta) gate is defined as:\")\n",
    "\n",
    "yy = aams_matrix.subs({\"phi_0\": pi / 2, \"phi_1\": pi / 2})\n",
    "yy"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33f5e3be-05c3-477f-8120-6f3291fed599",
   "metadata": {},
   "source": [
    "We add these two-qubit gates to the IonQ native circuit class with"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "4484e10e-00a6-4b7b-9e30-d58d6cb59aa2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Define XX(θ) gate and register it\n",
    "def xx(qubit0, qubit1, theta):\n",
    "    return IonQNativeCircuit().ms(qubit0, qubit1, 0, 0, theta)\n",
    "\n",
    "\n",
    "IonQNativeCircuit.register_subroutine(xx)\n",
    "\n",
    "\n",
    "# Define ZZ(θ) gate and register it\n",
    "def yy(qubit0, qubit1, theta):\n",
    "    return IonQNativeCircuit().ms(qubit0, qubit1, pi / 2, pi / 2, theta)\n",
    "\n",
    "\n",
    "IonQNativeCircuit.register_subroutine(yy)\n",
    "\n",
    "\n",
    "# Define ZZ(θ) gate and register it\n",
    "def zz(qubit0, qubit1, theta):\n",
    "    qc = IonQNativeCircuit()\n",
    "    qc.h(qubit0).h(qubit1)\n",
    "    qc.xx(qubit0, qubit1, theta)\n",
    "    qc.h(qubit0).h(qubit1)\n",
    "    return qc\n",
    "\n",
    "\n",
    "IonQNativeCircuit.register_subroutine(zz)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "0c15c377-cad5-4dea-bdb7-6340af2d2b1d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : |     0      |    1     |  2   |     3      |    4     |  5   |\n",
      "                                                                    \n",
      "q0 : -MS(0, 0, pi)-GPi2(pi/2)-GPi(0)-MS(0, 0, pi)-GPi2(pi/2)-GPi(0)-\n",
      "      |                              |                              \n",
      "q1 : -MS(0, 0, pi)-GPi2(pi/2)-GPi(0)-MS(0, 0, pi)-GPi2(pi/2)-GPi(0)-\n",
      "\n",
      "T  : |     0      |    1     |  2   |     3      |    4     |  5   |\n"
     ]
    }
   ],
   "source": [
    "print(IonQNativeCircuit().xx(0, 1, pi).zz(0, 1, pi))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a0f3e53-4bc9-43ee-928f-71c21e78fc12",
   "metadata": {},
   "source": [
    "In the next section we breakdown how this MS gate can be used for CNot gates. "
   ]
  },
  {
   "attachments": {
    "12a78788-2032-46c7-be3e-d30193423214.png": {
     "image/png": "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YmCb6nKps0JACAgBISAEhIAQEAJiYDUHhIAQEAJCQAgIASEgBJoKATGwTXW51FkhIASEgBAQAkJACAgBMbCaA0JACAgBISAEhIAQEAJNhYAY2Ka6XOqsEBACQkAICAEhIASEgBhYzQEhIASEgBAQAkJACAiBpkJgkqbqrTrbMARGjRplPvzww4a1r4arR6BXr15m9dVXr74i1dDSCPz97383l19+eUuPUYOrHoE555zT7LzzzrEVHXfccbFpShACgwcPrhqELh0BVV2LKmh5BGB8eLH16NGj5cfaigPk2vGyGTJkSCsOT2PKEYExY8aY3r17GxY8IiEQhYB7FzBX4qhLly6aQ3HgtPH5b775xrzyyismD9ZTEtg2nkhphy4GKC1ixckvxrU416JZelKOOWmWMaiftUGA50mS+ZEkT216qFqLigBzggVyHiQd2DxQVB1CQAgIASEgBISAEBACdUNADGzdoFZDQkAICAEhIASEgBAQAnkgIAY2DxRVhxAQAkJACAgBISAEhEDdEBADWzeo1ZAQEAJCQAgIASEgBIRAHgiIgc0DRdUhBISAEBACQkAICAEhUDcExMDWDWo1JASEgBAQAkJACAgBIZAHAmJg80BRdQgBISAEhIAQEAJCQAjUDQExsHWDWg21CgJvvPGGeeihh2o6nEcffdQ8/fTTNW1DlQsBIZAMgV9//dXccMMN5osvvkhWoGC5CDxA/0X1R0Bzp3aYi4GtHbaquQURgLFcdNFFDUxsLenzzz83K664ornppptq2YzqFgJCoAIC//3vf82WW25pBgwYYCaddNIKuYuZDBPFGAYOHFjMDrZorzR3anthFYmrtviq9hZC4KWXXrKhETfccEOz33771XRkW2yxhTnooIPM5ptvbu6//36z1lpr1bQ9VS4EhEA0Arvttpu55ZZbzBNPPGGmnnrq6EwFPzvvvPOam2++2fTr18+O4dhjjy14j1uje5o7tb2OksDWFl/V3iII/Oc//zFbb721mXHGGc1f//pXM9FEtb91TjnlFLPyyivbl8748eNbBEkNQwg0DwJXXHGF+dvf/maGDx9uVlpppebpeERPN910UzNo0CAzePDgmqtARTTfdqc0d2p/yWv/Fq79GNSCEKg5Akgs3nnnHXPVVVeZGWaYIVF7bNv98MMPsZ+ffvqpbD1sV1588cXm3//+t33xlM2sRCEgBHJF4KOPPjL9+/c3q666qjnssMNyrTtLZb///nvss4TnzI8//mjIU454js0999xmn332MT///HO5rEqrAoGizR2GghAm7n1EGu+rclTEuSMVgnJXTGm5IPDKK6+YShLEiSee2MwyyyxmjjnmMFNMMUUu7eZVyZNPPmlOP/10Kw1NspWPwcTee+9t7r333opduPDCC82ee+4Zm2+hhRayL9FzzjnH7Lrrrk0vBYodqBJaAoEPP/zQjBs3ruJY2MngXp9mmmkq5m1UBu5LFo9ILHk+NYpgOo444gjDM6ASsUt0zTXXxGabfPLJzcknn2xQUTrzzDPN4YcfHpu3UQnffPONefHFFysy4926dTNzzjmn3RXr0qVLo7ob2W5R5k5HR4e54IIL7HVmLpcj7sl//vOfZpJJotnCIs6d6J6WG6XShEBKBHbccUfz6quvJi611FJLmaOOOsr07du3oS8O12G2DyGMOCrRBx98YFZYYQUz88wzm3333de8+eab5pNPPjGbbLKJ+fTTT82tt95qpR/UA6O+7rrrVqrSHHDAAfblhdTkhRdeiH3AVKxIGYRAjRGAKeKTlHhpsq29++67m6mmmippsZrne+655+wCdOGFFzZrrLFGzduLa4BdmvXXX9+MHTvW7LzzztaIjF0ZJxFGzYjnDNih1rTRRhvFVRWe51k022yzWaYYhhcmsEiEzj+6o5UYLr/PBx98sOEz++yz+6cbclyUucPgjzzySHPSSSfZBUuPHj3MqaeeagUh008/vbn66qtNz549DUISaLHFFqv4bina3BEDay+dvmqJABJY6LLLLrMPJo5hxs4991zjVs48qNmiR28Iaedmm21mMJbCeKKRlr+8OO666y77wN94443pelnaaaedrPEVEhPGxkqccRxyyCHmjjvusG54kICkofnmm8++xO6++27zwAMPmPXWWy9N8UR5kRpffvnlifIqU/Mj0KtXL7P66qvnPpARI0YYPkhh559/flv/4osvbp566inzpz/9yf7/7bffDAs9GBUkgDAe3PPPPPOM3YXJvVMZKjz77LNtqUMPPTR8RmWopuoiMKjTTjutxQv8UGH6+OOPrRT1q6++MqSPHDmyIuPhdwQJ24EHHmgYGztAboHu52nkMdJhPqg4YHzGeKH333/fzDXXXGHXEAw8//zzdhxu3uHesHfv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HWuRePvtt83vv/9uJpooXpsLVQX84uIFASmsqL4I7Lbbblb6ShCNqaeeur6N59Qa7tbwntGvXz87Bly6iYRAsyMQ/9Rs9pGp/0JACAiBGiJw2mmnmWHDhlVUI/C7sMEGG5hJJ53U+pIlWhhBDSaeeGJz2GGH+dk6HROgYc899zTo05JXVD8ErrjiChsxbvjw4U0v+d50003NoEGDbAQ4It2JhECzIyAJbLNfQfVfCAiBhiDQpUsXu6WfpvHRo0enyW7zymArNWS5FPjoo49M//79DeF6yy0wcmksQSVI6n/88cfYnEjxu3btWlaaj+T1uuuus6GfX331VZs/tkIlCIGCIyAGtuAXSN0TAkJACDQLAh9++KEZN25cxe7iT3eOOeYw00wzTcW8jcqA1BuXZYMHD26o5PuHH34wRxxxROjCrRwe+Aa+5pprYrPgCg5daoy5zjzzTKPFUSxUSmgCBJqGgUX3aO65524CSNVFISAEhEB7IgBTxCcpwciyrb377rubqaaaKmmxmufDYOvee++14XrXWGONmrcX18BPP/1k1l9/faszvfPOO1v1k4svvjiUCJ9yyilm3333tdghgd1oo43iqgrPb7LJJma22WazTDEM75xzzhmm6UAINBMChdWBxe3HcccdZ3r27GnYqsOS98Ybb7THuKbZZZddJnBN00zAq69CQAgIgVZDYMSIEYbgDe+88044tMUXX9wgReQ8H4zYkNKed955dkscd2QLLbRQquhmYeU1OsBVGnTooYfad06NmqlYLQzqtNNOa30OE8SiV69elqFFiuqkpyNHjrRS1RNPPNGsvPLKFeucZJJJzIEHHmjzXXjhhRXzK4MQKCoChWNgv/nmG8uczjXXXNbyE8aVG5cH4xJLLGHwn8jN9/XXX5uddtrJMrhjxowpKr7qlxAQAkKg7RB47733wjHjvsmPGoYhGlbx++yzjzVmI+PHH39sNttss7BMIw8+/fRTa7hFH3Cf1UhC6orgxuFHGGFCGkP4EGZXEoY0LSGFhS699FLrBSNteeUXAkVAIP3Mr2GviUqDZBW3MTiNdjcZTcKkoi+1+uqr2w/nYHa5wXEuzbaVW1WSJhICQkAICIHGIPDoo4+GDa+22mrhcenB8ssvb/DGgK4p0clgHrt3716ara7/YRghGMUpppiirm2XNoaesCOwufvuu63nC85h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"
    }
   },
   "cell_type": "markdown",
   "id": "3fc46619-f35e-456b-8ba9-bd1037c0da9b",
   "metadata": {},
   "source": [
    "### CNot gate decomposition\n",
    "\n",
    "The CNot gate is the most commonly used two-qubit entangling gate. As such, its important to recognize how to map it to the native MS gate of IonQ. By decomposing the CNot gate into a combination of single-qubit rotations and the MS gate, we can express it in terms of IonQ's native gate set.\n",
    "\n",
    "In the figure below, we show the decomposition from [1]. \n",
    "\n",
    "![Screenshot 2023-07-12 at 2.31.29 PM.png](attachment:12a78788-2032-46c7-be3e-d30193423214.png)\n",
    "\n",
    "\n",
    "[1] Maslov, Dmitri. “Basic Circuit Compilation Techniques for an Ion-Trap Quantum Machine.” New Journal of Physics 19, no. 2 (February 2017): 023035. https://doi.org/10.1088/1367-2630/aa5e47."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "0f4c9f90-7209-4cc1-9fb2-d9076c41a112",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The CNot circuit is:\n",
      "T  : |0|\n",
      "        \n",
      "q0 : -C-\n",
      "      | \n",
      "q1 : -X-\n",
      "\n",
      "T  : |0|\n",
      "The CNot unitary :\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}1.0 & 0 & 0 & 0\\\\0 & 1.0 & 0 & 0\\\\0 & 0 & 0 & 1.0\\\\0 & 0 & 1.0 & 0\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[1.0   0    0    0 ]\n",
       "[                  ]\n",
       "[ 0   1.0   0    0 ]\n",
       "[                  ]\n",
       "[ 0    0    0   1.0]\n",
       "[                  ]\n",
       "[ 0    0   1.0   0 ]"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from braket.circuits import Circuit\n",
    "\n",
    "circ = Circuit().cnot(0, 1)\n",
    "\n",
    "print(\"The CNot circuit is:\")\n",
    "print(circ)\n",
    "\n",
    "print(\"The CNot unitary :\")\n",
    "Matrix(circ.to_unitary())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "5de69858-414d-459d-9054-ea4544c51266",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The decomposed circuit is:\n",
      "T  : |   0    |      1       |    2    |    3    |\n",
      "                                                  \n",
      "q0 : -Ry(pi/2)-MS(0, 0, 1.57)-Rx(-pi/2)-Ry(-pi/2)-\n",
      "               |                                  \n",
      "q1 : ----------MS(0, 0, 1.57)-Rx(-pi/2)-----------\n",
      "\n",
      "T  : |   0    |      1       |    2    |    3    |\n"
     ]
    }
   ],
   "source": [
    "def cnot_decomposition(qubit0, qubit1):\n",
    "    circ = Circuit()\n",
    "    circ.ry(qubit0, pi / 2)\n",
    "    circ.ms(qubit0, qubit1, 0, 0)\n",
    "    circ.rx(qubit0, -pi / 2).rx(qubit1, -pi / 2)\n",
    "    circ.ry(qubit0, -pi / 2)\n",
    "    return circ\n",
    "\n",
    "\n",
    "print(\"The decomposed circuit is:\")\n",
    "print(cnot_decomposition(0, 1))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e8587c2-979a-42ae-8c33-fca93a89dcac",
   "metadata": {},
   "source": [
    "Now checking the unitary we have"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "64a66c95-296d-4e7d-974e-8841acf00a57",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}1.0 & 0 & 0 & 0\\\\0 & 1.0 & 0 & 0\\\\0 & 0 & 0 & 1.0\\\\0 & 0 & 1.0 & 0\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[1.0   0    0    0 ]\n",
       "[                  ]\n",
       "[ 0   1.0   0    0 ]\n",
       "[                  ]\n",
       "[ 0    0    0   1.0]\n",
       "[                  ]\n",
       "[ 0    0   1.0   0 ]"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "matrix = cnot_decomposition(0, 1).to_unitary()\n",
    "global_phase = np.exp(-1j * np.pi / 4)\n",
    "\n",
    "matrix = np.round(global_phase * matrix, 5)\n",
    "Matrix(matrix)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7845926",
   "metadata": {},
   "source": [
    "which exactly matches the expected CNot unitary up to the phase $e^{-i\\alpha\\pi/4}$.\n",
    "\n",
    "As a further check, we can use the `eq_up_to_phase` function from the previous section. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "0d361ac1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "eq_up_to_phase(cnot_decomposition(0, 1).to_unitary(), Circuit().cnot(0, 1).to_unitary())"
   ]
  },
  {
   "attachments": {
    "1e851789-5000-44af-b436-b54ec88a37ac.png": {
     "image/png": "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IAIiIAIiIAIiIIVJ94AIiIAIiIAIiIAIiIAIiIAIZCAghSkDGK0WAREQAREQAREQAREQAREQASlMugdEQAREQAREQAREQAREQAREIAMBKUwZwGi1CIiACIiACIiACIiACIiACEhh0j0gAiIgAiIgAiIgAiIgAiIgAhkISGHKAEarRUAEREAEREAEREAEREAEREAKk+4BERABERABERABERABERABEchAQApTBjBaLQIiIAIiIAIiIAIiIAIiIAJSmHQPiIAIiIAIiIAIiIAIiIAIiEAGAstmWK/VIpAoAh07djRz5sxJVJvV2GQSqKurS2bD1eqaJqA+sqYvf2JPfvbs2YZ7N5MMGTLEDB06NNNmra8BArnukagQSGGKiqTqqTiBzTff3IwZM6bi7VADqpPA+PHjzYQJE6rz5HRWNUGgd+/e5sgjj6yJc9VJJp9Ap06dQp2Env2hMFVdoXnz5pkBAwaU7bykMJUNtQ5UagJNmzbNOhJV6uOr/uom8MQTT1T3Cersqp5A69at1UdW/VWuvRPUs7/2rnklzlg+TJWgrmOKgAiIgAiIgAiIgAiIgAgkgoAUpkRcJjVSBERABERABERABERABESgEgSkMFWCuo4pAiIgAiIgAiIgAiIgAiKQCAJSmBJxmdRIERABERABERABERABERCBShCQwlQJ6jqmCIiACIiACIiACIiACIhAIghIYUrEZVIjRUAEREAEREAEREAEREAEKkFAClMlqOuYIiACIiACIiACIiACIiACiSAghSkRl0mNFAEREAEREAEREAEREAERqAQBKUyVoK5jikCFCbz55pvmiCOOMIsWLapwS6I9/GeffWb69Olj3n///WgrVm0iIAI1SaBa+8qoLubVV19trrvuuqiqUz0lJlCJ+/n444831ZD4XQpTiW9OVS8CcSPwyiuvmK233tosXLjQNG7cOG7NK6o9TZo0Mc8++6zZdtttzVtvvVVUXdpZBESgtglUc18Z1ZWlzz3uuOPMwIEDo6pS9ZSIQKXu559++sl06tTJ3H333SU6s/JUK4WpPJx1FBGIBYF33nnHdOjQwbZl0qRJZrnllotFu6JqRKNGjcyMGTPMDz/8YHbeeWfzySefRFW16hEBEaghAtXeV0Z1KQ877DBz0kknmSuuuMJcfPHFUVWreiImUMn7+corrzRbbrml6dGjh3n8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CIhAPgSYRZozZ4554okn/DDh7I8SdMUVV5jjjjvOpAutjZIzceJEM378+HqHIxAEszItW7Y0W221ldlyyy3rbXc/KnVcd/xc323btvWLoDRtvvnm/u9SLpDjqpzy97//3T9cJtNLv4AWREAEREAEKkZAClPF0OvAIiACtUzg559/Nvvvv79FgM8OJlnMprjZjYEDB5qDDjoorcJ01VVXmRtuuMHf183AsP+FF15o159++ulpFaZKHTefax1UmBYsWFAWhemZZ54xl19+uVVc11lnnXyaW3DZoMK09dZbF1yPdhQBERABESgtASlMpeWr2kVABEQgLYHlllvO+pKk3Zhj5fXXX2/4FCKVOm4+bWVGCQUSc7X58+ebgw8+OJ/d8y67ePFiq5yihLZu3Trv/QvdAb8ihJnAlVdeudBqtJ8IiIAIiECJCSjoQ4kBq3oREAEREIH8CCyzzDLmmGOOsTsRVr3UQoj2rl27WqWp1Mdy9eN0P3v2bPuTY0tEQAREQATiS0AKU3yvjVomAiIgAjVLAHNE5OWXXzb/+Mc/SsbhtttuM88995wZO3ZsyY6RrmIijS1cuNBuOvroo9MV0ToREAEREIGYECiLwkRUHnJrVPpDBKm77rqr4u2Ag6LMxOQ/QM0QARGIJQHM8jbYYAPbNvIilULeffddmwB4ypQppnHjxqU4RMY6p02bZrftueeeZv31189YThtEQAREQAQqT6BsPkw8/MaMGVP5M45BC0ggKBEBERABEchO4Mwzz7Sh1seNG2dOOukks/TS0Y3x/fTTT+bQQw81gwcPNu3bt8/ekIi3/vjjj4ZEwwiRDSUiIAIiIALxJlA2halp06aaVfnfvQALiQiIgAiIQHYC5A3661//anNT3X///WbvvffOvkMeW7F8oC8eMGBAHntFU/T222+3AS022WSTrMmJozmaahEBERABESiWQHTDdcW2RPuLgAiIgAiIQIAAwR+uu+46uwbFhrDpUQk5l0iO26JFC7P66qvX+7hjYCrHttNOO82tKvqbmS2XPJY8WlHOmhXdOFXQgMCbb75pjjjiCLNo0aIG2+K8gtxuzNB+//33cW6m2iYCiSFQthmmxBBRQ0VABERABGJDgJDbJ554oiH31OjRo825554bSdveeOONtGHdP/74Y9OtWzd7jHvuucc0b9480pDfI0aMMBwDU0CSC0viS4DAHB06dDB//vOfy+7jViwV7lvyihHQ5KGHHjJ/+MMfiq1S+4tATROQwlTTl18nLwIiIALxJ0AyXgIznHfeeaZHjx5mo402KrrRG2+8cdo6XBJgNmIyx4tnVMILOIoSL+BRKX5RtU311CfwzjvvWGWJtZMmTTLkL0uS8D8ydepUc8ABB9jPjBkzEncOSeKttlY/AZnkVf811hmKgAiIQKIJrLLKKubxxx83f/zjHw1R5b766qvIz+frr7+24cvvvfdev26WP/roo0hMAUnCiw8WCXmJ+rf88sv7x9FCvAj8/PPPNlnyf/7zH0PY+bXWWiteDQzZmp49e5qzzz7bzjChqEtEQAQKJyCFqXB22lMEREAERKBMBNq2bWsee+wx88UXX5hjjz028qPip7T22mubQYMGWaUGxWbgwIH2ZTmK2SBeXvFfwrdk3XXXjbz9qjA6AphNkv+LyIz77LNPdBVXoCZmZwnPj88eZqgSERCBwgjIJK8wbtpLBERABESgzAS23nprM2/ePPPss89GfmTCfLtQ35FX7lXYu3dvs/vuu5uWLVuWovqy1InCt2TJkpzHIpBFufNa5WxUyAKYTV5wwQW29MUXXxxyr/rF/v3vf5sXX3zRvPbaazYSY9euXUPPUn333XdWsfnmm2/qV5rmF4pQq1at0mz5fRWmhFdffbXZddddbc6xWbNm2VyUv5fQkgiIQBgCUpjCUFIZERABERCBWBBgdiaJMzTHHHNMLPgV2oh//vOfeflzYT5JlEH8wAgP37lz50IPXdb9mFVCiDC38sor53VsTPjYj8iO3bt3NzvssIN58MEH7YwoeShPOOEEs+yy/33teuaZZ8w666xjozS6g9x3332mV69ehnrCCPU/9dRTOYt26dLFbLvttnZ288477zSHHHJIzn1UQAREoD4BKUz1eeiXCIiACIiACIhACoE//elPhlxYvMz/7W9/q5eInuS7O+64ow2Rjv8PZV5//XUzc+ZMQ84pPkQEnDBhgskUbCPlcBX5yazQ008/bY/dv3//vNrw1ltv2ZxaREDkfFF8nBCWnIT1+OKx/Msvv5j99tvP3HXXXb7CNG3aNBucgYAgsPztt9+s4nX66adbf7eHH37YfPvtt2b//fe31TJzxIxlWMHk9MADD7TtwMywUaNGYXdVOREQAY9AYhQmTAH4rLDCCvUivfz666+GDpoPYTNTc1owvc06HGzJ6YHQEZFpfamlljIrrriiXac/IiACIiACIiAC6Qnw/CTgBtKsWTNfYWIm6YorrvBnToJ7oxiMGjXKnHXWWTb5cMeOHc1LL71k1lxzzWCx2CxjuoYQWY7Zn7CCmSLKCMrSzTffXE9Zog5m2Agecemll5rDDz/coPwgzPogBBbhmNdee63p16+ffTdB6XrkkUfMyJEjbZnPPvvMKlfDhg2zv/P9s++++9qgKQQfYdYLnzqJCIhAeAKJCfqwxRZb2H92FB8UHfdhepswsEydM3oVlBdeeMHaUTOSQjm3Dx0/63DwzSbYIbsO68Ybb7QRlLKV1zYREAEREAERqHYCTz75pH+KzFY4MzN/5f8WWI+JGr42CC/rKA1xlM8//9yM9xIJI3369LHfYf+gxOCvhPKYztyNGSOEoAvz58+3SiQzR44bg7okUWZWi/cUBIVpjz32sMv8mTt3blGmqMxIodQhhEmXiIAI5EcgMQrTX//6V/tPTieTKoxaMTLDCEpQyENAssNUwfnxoosusqFdU7fxG3OC4447zqy22mp2f2axGJFBwRo7dqydTnf7YYfMyI9EBERABERABGqBANEKnfD8zSV77bWXX4RnaRwF8zgnBBfJRyZPnmyLM5OWzmqFgV43q8aMG+aK+DM5WWONNaw5n/v96aef2lmoXXbZxa7CgmbhwoVFh6J3Ef8Ia8+AsEQERCA8gcSY5LkRGkZvyMHhRoI4VTorQsCmCqM9dErMPDHbRGeBAuU6rtTy/C7WDjldnVonAiIgAiIgAtVAADN35+fD+bhnc7ZzC76c44cTR5kzZ45tFkEqmjZtGrqJhLl/++23bfngjFBqBbyjYLLH+wgmebgQZBLM95CddtrJfhNwA2EWrBjZfvvt/d3vuecec/TRR/u/tSACIpCdwNLZN8dz64ABA+o17NZbb633O/iD6X+UJcKE0kFkU5bC2CFTN3XW1dU1sEMOHlfLIiACIiACIlBtBAj44AQlwJnbuXWp3/geB2eVUi1BUstX4jfPcwJUIB06dMirCVigOGnTpo1bbPDtFCSsZAgznkngxSwUwR8ItIE4hQlfp2IEqxk3uOz8qIqpT/uKQC0RSKTCREfiRl64WKlmcu4C3nDDDTbL9TnnnGOGDh3qVmf8LtYOOWPF2iACIiACIiACVUAg6L9EuGrnc5Pp1DCXx3fJCcEN4ibMELlQ3tttt11ezWvevLmvNOKflE6ee+45mz+MbbkUTPyL4OXM59jH+Tox6EvQqmKkffv2dnciAkpEQATCE0ikwsTpEcbUCdPcDz30kPtpv6dOnWr69u1rfZEuueSSetsy/SjWDjlTvVovAiIgAiIgAtVAgOAETjp16uQW037z4j9o0CB/G9YZKFlxk2AiZAJM5StuQBaT/0WLFvm7Y+JPXieURBdhEOXs66+/NihmJMkNClEF8a9Ggn5f+DghvOvgN12MMOCM4BP1/fffF1OV9hWBmiKQWIWJ0Rc3tcwVu/LKK/0LR2Q7osEcfPDBdn2uETB2zMcOmfLYIWNn7KbZWScRAREQAREQgWolkI//0hNPPGGVAjdzg7JExLw4ynvvvec3y5nB+StCLPCuwSDt888/b1ZddVWz2267mU033dSQrBg3ABQnwo1369bNhmDfcsstTatWrUy7du3q1b548WKryBDs4S9/+Yu/jTa54BqpqVP8QiEXaJeTN9980y3qWwREIAeBxAR9SD0PQmSecsop5rzzzrObGPXinx/nUjolErqh1LjcS6n7p/6O2g45tX79FgEREAEREIEkEwj6L3EeTZo08QMR/PDDD+bLL780CxYssP7CRGJDSNBKLqF1113X/o7jHwJJOeGcChHyGvHB34j6ML1zpnSuPvyk8EPCTymdvxOK0TvvvGNat27dIKfkvffea99vcqVDccfK9B1UCDkWyptEBEQgN4HEKkycGhFenMLEb3InkAthhx12sKM9hPIMK84Omely7JCpI1XysUNO3Ve/RUAEREAERCDJBIL+S5xHy5YtM54OCVpHjBiRtUxwZ8zRPvnkE2u1wbObQAyE08ZsDGuSYLhuIu0xOEoiez6uHKZrqUpK8BiZllH0nJDXsRhZffXVDZ9MwsxSNllvvfXSbibqL59iJVjHN998U2x12l8EaoZAYk3yuEIoOXTKTgh1Snbu++67ryBTuajskF179C0CIiACIiAC1UIg6L900003GSwz3AcFBl+g/fff354uJuuYoYUVwnozs9KsWTM7c0Vob5aZUSHYQVCuuOIKu553gFVWWcUqVOxbaCADTPKRoJl/8HjVtBx0I3DmktV0fjoXESgVgUQrTEA5/vjj67E58sgjbQdab2XIH1HZIYc8nIqJgAiI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NWtmnnrqKTNp0iSbU61YCkTDCyNt2rQJUyxrGQJX3HPPPdb0L2tBbRQBEQhFQApTKEwqJAIiIAIiIAIiUGsECJbQr1+/SE6bfFLlkrZt2xo+EhEQgWgIKOhDNBxViwiIgAiIgAiIgAiIgAiIQBUSKNsME86Mc+bMqUKE+Z8SLJo0aZL/jtpDBERABERABERABERABESgrATKpjDNmzfPdOzYsawnF+eDdejQIc7NU9tEQAREQAREQAREQAREQAQ8AmVRmIYMGWL4SERABERABERABERABERABEQgSQTkw5Skq6W2ioAIiIAIiIAIiIAIiIAIlJWAFKay4tbBREAEREAEREAEREAEREAEkkRAClOSrpbaKgIiIAIiIAIiIAIiIAIiUFYCUpjKilsHEwEREAEREAEREAEREAERSBIBKUxJulpqqwiIgAiIgAiIgAiIgAiIQFkJlCVKXlnPSAcTAREQAREQARFoQGDChAnKh9iAilbkS+DVV19Vmph8oal84glIYUr8JdQJiIAIiIAIiEB2Au3atbMF6urqshfUVhHIQWDzzTc3rVu3zlFKm0Wguggs5XWe6j2r65rqbERABERABERABERABERABCIiIB+miECqGhEQAREQAREQAREQAREQgeojIIWp+q6pzkgEREAEREAEREAEREAERCAiAlKYIgKpakRABERABERABERABERABKqPgBSm6rumOiMREAEREAEREAEREAEREIGICEhhigikqhEBERABERABERABERABEag+AlKYqu+a6oxEQAREQAREQAREQAREQAQiIiCFKSKQqkYEREAEREAEREAEREAERKD6CEhhqr5rqjMSAREQAREQAREQAREQARGIiIAUpohAqhoREAEREAEREAEREAEREIHqIyCFqfquqc5IBERABERABERABERABEQgIgJSmCICqWpEQAREQAREQAREQAREQASqj4AUpuq7pjojERABERABERABERABERCBiAhIYYoIpKoRAREQAREQAREQAREQARGoPgJSmKrvmuqMREAEREAEREAEREAEREAEIiIghSkikKpGBERABERABERABERABESg+ghIYaq+a6ozEgEREAEREAEREAEREAERiIjA/wNjboi+7V7/QwAAAABJRU5ErkJggg=="
    }
   },
   "cell_type": "markdown",
   "id": "1d544222-dd5a-4e13-9f5d-7192a9dc236d",
   "metadata": {},
   "source": [
    "### Controlled-roots of Pauli gates\n",
    "\n",
    "The arbitrary third angle in the MS gate allows more flexibility than the CNot gate. By adjusting the angle, it controls the amount of enganglement.\n",
    "\n",
    "![Screenshot 2023-07-12 at 2.31.03 PM.png](attachment:1e851789-5000-44af-b436-b54ec88a37ac.png)\n",
    "\n",
    "\n",
    "\n",
    "The arbitrary angle allows fraction powers of Pauli gates, for example the controlled-$X^{1/2}$ gate. \n",
    "\n",
    "In the following code, we check the unitary matrix for the controlled-$X^{1/2}$ gate against the MS decomposition to verify they are equivalent up to a global phase. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "5579e220-52e6-44fe-99bb-3adff135b36b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "T  : |   0   |\n",
      "              \n",
      "q0 : -C-------\n",
      "      |       \n",
      "q1 : -(X^0.5)-\n",
      "\n",
      "T  : |   0   |\n"
     ]
    },
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}1.0 & 0 & 0 & 0\\\\0 & 1.0 & 0 & 0\\\\0 & 0 & 0.5 + 0.5 i & 0.5 - 0.5 i\\\\0 & 0 & 0.5 - 0.5 i & 0.5 + 0.5 i\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[1.0   0        0            0     ]\n",
       "[                                  ]\n",
       "[ 0   1.0       0            0     ]\n",
       "[                                  ]\n",
       "[ 0    0   0.5 + 0.5*I  0.5 - 0.5*I]\n",
       "[                                  ]\n",
       "[ 0    0   0.5 - 0.5*I  0.5 + 0.5*I]"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from braket.circuits import Circuit\n",
    "\n",
    "alpha = 0.5\n",
    "\n",
    "circ = Circuit().x(1, control=0, power=alpha)\n",
    "print(circ)\n",
    "\n",
    "Matrix(np.round(circ.to_unitary(), 5))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "b6e7df57-6a69-4b3e-b297-a48bfc020117",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}1.0 & 0 & 0 & 0\\\\0 & 1.0 & 0 & 0\\\\0 & 0 & 0.5 + 0.5 i & 0.5 - 0.5 i\\\\0 & 0 & 0.5 - 0.5 i & 0.5 + 0.5 i\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[1.0   0        0            0     ]\n",
       "[                                  ]\n",
       "[ 0   1.0       0            0     ]\n",
       "[                                  ]\n",
       "[ 0    0   0.5 + 0.5*I  0.5 - 0.5*I]\n",
       "[                                  ]\n",
       "[ 0    0   0.5 - 0.5*I  0.5 + 0.5*I]"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def controlled_root_cnot_decomposition(qubit0, qubit1, alpha):\n",
    "    circ = Circuit()\n",
    "    circ.ry(qubit0, -np.pi / 2)\n",
    "    circ.ms(qubit0, qubit1, 0, 0, alpha * np.pi / 2)\n",
    "    circ.rx(qubit0, -alpha * np.pi / 2).rx(1, alpha * np.pi / 2)\n",
    "    circ.ry(qubit0, np.pi / 2)\n",
    "    return circ\n",
    "\n",
    "\n",
    "matrix = controlled_root_cnot_decomposition(0, 1, alpha).to_unitary()\n",
    "global_phase = np.exp(1j * np.pi * alpha / 4)\n",
    "\n",
    "matrix = np.round(global_phase * matrix, 4)\n",
    "Matrix(matrix)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8b636dcb",
   "metadata": {},
   "source": [
    "As a further check, we can use the `eq_up_to_phase` function from the previous section. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "aa2b6679",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "eq_up_to_phase(matrix, circ.to_unitary())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "589ad547-564f-4456-83c8-070df7fa2d29",
   "metadata": {},
   "source": [
    "We see that the two unitaries are equivalent up to the phase $e^{i\\alpha\\pi/4}$. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0acdd3f-6e41-45b3-a37f-9833e243ce18",
   "metadata": {},
   "source": [
    "## Quantum Fourier transform with native gates\n",
    "\n",
    "One application of native arbitrary angle MS gates is to the quantum Fourier transform (QFT) circuit. The QFT circuit involves a sequence of single-qubit rotations and controlled-phase operations. Note that the usual layer of SWAP gates at the end of the circuit can be dropped since the re-ordering can be done classically. This is only applicable if the QFT is the final unitary in the circuit. In this example, the classical re-ordering is performed with the function `swap_classical_bitstrings` to make it easier to compare with the usual QFT. \n",
    "\n",
    "To define a native QFT implementation, we first define the phase shift gate in terms of IonQ native gates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "bbef1c81-19a9-460a-94b9-14b01888d4c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "\n",
    "from braket.circuits import Circuit, circuit\n",
    "from braket.devices import LocalSimulator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "ef46f252-9161-45bf-9115-ea3598ba7461",
   "metadata": {},
   "outputs": [],
   "source": [
    "def cphaseshift(qubit0, qubit1, theta):\n",
    "    qc = IonQNativeCircuit()\n",
    "    qc.h(qubit1)\n",
    "    qc.ry(qubit0, -pi / 2)\n",
    "    qc.ms(qubit0, qubit1, 0, 0, theta / 2)\n",
    "    qc.rx(qubit0, -theta / 2)\n",
    "    qc.rx(qubit1, theta / 2)\n",
    "    qc.ry(qubit0, pi / 2)\n",
    "    qc.h(qubit1)\n",
    "    return qc\n",
    "\n",
    "\n",
    "IonQNativeCircuit.register_subroutine(cphaseshift)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9cec5a48",
   "metadata": {},
   "source": [
    "Again, we double check the phase with "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "id": "19828371-78ae-410d-9d9b-41bc5a33a3cf",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "angle = np.pi / 3\n",
    "circ = Circuit().cphaseshift(0, 1, angle).to_unitary()\n",
    "native_circ = IonQNativeCircuit().cphaseshift(0, 1, angle).to_unitary()\n",
    "\n",
    "eq_up_to_phase(circ, native_circ)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "id": "980ce975-dd5b-4d44-a33d-f9fb423a1c2e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/latex": [
       "$\\displaystyle \\left[\\begin{matrix}1.0 & 0 & 0 & 0\\\\0 & 1.0 & 0 & 0\\\\0 & 0 & 1.0 & 0\\\\0 & 0 & 0 & 0.5 + 0.86603 i\\end{matrix}\\right]$"
      ],
      "text/plain": [
       "[1.0   0    0          0       ]\n",
       "[                              ]\n",
       "[ 0   1.0   0          0       ]\n",
       "[                              ]\n",
       "[ 0    0   1.0         0       ]\n",
       "[                              ]\n",
       "[ 0    0    0   0.5 + 0.86603*I]"
      ]
     },
     "execution_count": 33,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Matrix(np.round(np.exp(1j * angle / 4) * native_circ, 5))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "id": "6263f1ad-434c-4556-ad2f-85edfbc86025",
   "metadata": {},
   "outputs": [],
   "source": [
    "def qft_no_swap(qubits):\n",
    "    # The final SWAP layers are omitted in favor of classical post-processing\n",
    "    qft_circ = IonQNativeCircuit()\n",
    "    num_qubits = len(qubits)\n",
    "    for k in range(num_qubits):\n",
    "        qft_circ.h(qubits[k])\n",
    "        # Then apply the controlled rotations, with weights (angles) defined by the distance to the control qubit.\n",
    "        # Start on the qubit after qubit k, and iterate until the end.  When num_qubits==1, this loop does not run.\n",
    "        for j in range(1, num_qubits - k):\n",
    "            angle = 2 * math.pi / (2 ** (j + 1))\n",
    "            qft_circ.cphaseshift(qubits[k + j], qubits[k], angle)\n",
    "    return qft_circ"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "id": "f4a401c3-ad57-4311-815b-bb05d92ab1aa",
   "metadata": {},
   "outputs": [],
   "source": [
    "num_qubits = 3\n",
    "\n",
    "device = LocalSimulator()\n",
    "qubits = range(num_qubits)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "id": "07e48e9b-9112-4b67-ae68-0d3ad6047ea2",
   "metadata": {},
   "outputs": [],
   "source": [
    "qft_circ = IonQNativeCircuit().h(1).add_circuit(qft_no_swap(qubits))\n",
    "qft_circ.state_vector()\n",
    "qft_circ.probability();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f6c767d-3f3d-40d0-973e-920b02505a8b",
   "metadata": {},
   "source": [
    "Notice the QFT circuit with IonQ native gates would be difficult to write manually. To achieve optimal performance on a QPU, the above circuit could be compiled by applying gate synthesis, however that is beyond the scope of this notebook. \n",
    "<div class=\"alert alert-block alert-info\">\n",
    "<b>Note:</b> To run the native circuits on IonQ hardware without any compiler optimizations, you must use a verbatim box. \n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "id": "b966f578-a4bc-4905-a23e-a6da224a350f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Classical post-processing to replace SWAP gates in the QFT\n",
    "\n",
    "\n",
    "def swap_classical_bitstrings(num_qubits):\n",
    "    qubits_to_swap = [\n",
    "        [qubits[i], qubits[-i - 1]] for i in range(math.floor(num_qubits / 2))\n",
    "    ]\n",
    "    swapped_bitstring_keys = []\n",
    "    for pair in qubits_to_swap:\n",
    "        for i in range(2**num_qubits):\n",
    "            format_bitstring = \"{0:0\" + str(num_qubits) + \"b}\"\n",
    "            bitstring_key = format_bitstring.format(i)\n",
    "            tmp = bitstring_key[pair[1]]\n",
    "            tmp2 = bitstring_key[pair[0]]\n",
    "            swapped_bitstring = \"\".join(\n",
    "                tmp if idx == pair[0] else tmp2 if idx == pair[1] else val\n",
    "                for idx, val in enumerate(reversed(bitstring_key))\n",
    "            )\n",
    "            if swapped_bitstring not in swapped_bitstring_keys:\n",
    "                swapped_bitstring_keys.append(swapped_bitstring)\n",
    "\n",
    "    reindex = np.argsort(swapped_bitstring_keys)\n",
    "    return swapped_bitstring_keys, reindex\n",
    "\n",
    "\n",
    "swapped_bitstring_keys, reindex = swap_classical_bitstrings(num_qubits)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "def9af99",
   "metadata": {},
   "source": [
    "Finally, we plot the output probabilities for the QFT. Below, we see the correct probabilities each bitstring. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "id": "e8e61162-033e-433c-ab24-5ff43b7548ce",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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vPOOkpOTXe5fv369hg8fru+++66FK/O8O+64Q2VlZVq2bJl69uzptO/zzz/Xvffeq9jYWL3xxhteqrDpBgwYcN79x48f1xdffOH3qwaffPKJz690nV2NbUhdXZ2OHTvm02M8q6qq6rz7t23bpqFDh/rFWM/iFJiPOnr0qGJjYxvc37lzZ1VXV7dgRc3jzTffdBkOAgMDNWzYMC1dulTDhw/36QBUX1+v4ODgBvcHBwervr6+BStqPmvXrtW6devOCT+S1LNnTz3//PO6/vrrW74wD/rss880evRode3a1eX+8vJyffHFFy1clec1Jhz4upMnT2rSpEnq27evy/1ff/21Zs2a1cJVNY+IiAhZLJYG99vt9vPu90UEIB91/fXX65FHHtGrr76qqKgop30HDhzQY4895vN/SCQzwsHw4cM1ceJEvfzyy7rqqquc9m3ZskWTJk3SLbfc4qXqPCskJOS8/0/z6NGjPv/li3369FFSUpImTZrkcv/WrVt9OrCfZUI4SEhIUFxcnMaNG+dy/yeffOLzYzyrffv2euKJJ5SUlORy/65du3T//fe3cFXNiwDko/Lz8/WrX/1KnTt3Vt++fRUdHS1Jqqys1L///W/17t1b//u//+vlKpvOhHCwcOFC3XXXXUpMTFRkZKQ6deokSdq3b58OHz6s1NRULVy40MtVesaoUaM0btw4LViwQDfeeKPCwsIknVl+t9lsslqtGjNmjJerbJprr71Wn3/+eYP727dv7xcXBpsQDm6++WYdPny4wf0dOnTwm4uCz566HTp0qMv9ERER8rcrZrgGyIfV19dr7dq12rBhwzl30wwbNswv7gD77rvvdNddd2nt2rUNhoOVK1cqIiLCu4V6wM6dO13eGdWrVy8vV+Y5J0+e1EMPPaSlS5fq9OnTjtW92tpaBQUF6b777tOCBQt8fhXIBE8//bROnTqlnJwcl/v37t2r7OxsLVu2rIUrgzuWLFmi48eP68EHH3S5v7KyUvn5+Q3Oty8iAMEn7Nixw2XQ86dwYJKqqiqVlJQ4zWdiYqJjRQgAmhsByMe5ep5KcnKyrr76ai9XBk/xy+dvGMDkZx2ZgmPTtxGAfNS+fft0++23a/369brsssucrgEqLS3VtddeqzfffNNxysiX1dbWas2aNS6D3ogRI857kbQ/8IfbiRursrJSL774orKzs71dits4Njk2/ZE/HJs/RgDyUSY8T0U686TV1NRUlZWVKSkpyemPycaNG3XppZfq//7v/9S9e3cvV+o+E5+/0RB/+IPCscmx6Y/84dj8MQKQj2rfvr3WrVt3zp1RZ5WUlOj666/X0aNHW7gyz/rlL3+pdu3aacWKFedcH1JVVaX09HQdP35ca9eu9VKFTRcQENCo52/4w//wbNu27bz7d+7cqTFjxvj0WDk2OTZ9kQnH5o9xG7yPMuF5KtKZpyAXFxe7vDg2LCxMs2fPbvC5Fb7CpOdvJCQkyGKxuLyd9ux2X3/YGscmx6YvMuHY/DECkI8y4Xkq0plnT+zZs0d9+vRxuX/Pnj0+fwu8Sc/f6NChg+bNm6cbb7zR5f7t27f7/HOdODbP4Nj0LSYcmz9GAPJRubm5qq+v1+jRoxt8nsr8+fO9XGXTjR8/Xunp6ZoxY4ZuvPFGp+sMbDabnnzySU2ePNnLVTbNXXfdpZqamgb3x8TE+M2zNxITE1VWVqYuXbq43H/48GGf/4PCscmx6YtMODZ/jGuAfJwJz1N55pln9Nxzz6miosKxBGu32xUTE6OHHnpIjz76qJcrRGO9/fbbqq6u1t133+1y/3fffae//e1vDT5d2JdwbHJs+hKTjs2zCEA+7MCBA1q6dKnLW1DvuecedezY0csVetbu3budxtnQl036ItPm0t+ZNp8cm/BFBCAf9fHHHys1NVVt27ZVSkrKOcvPNTU1Wrt2rQYOHOjlSpvX3r17lZOTo6VLl3q7FLcxl99jPv0Hc+lf/GE+f4wA5KOuueYa9e/fX/n5+edcmW+32/XAAw9o27ZtKioq8lKFLcMfnk3BXH6P+fQfzKV/8Yf5/DEugvZRn3zyiV555RWXtyVaLBY9/PDDDT6HxJf87W9/O+/+//znPy1USfMxZS4l5tOf5pO59J+5lMyYzx8jAPmomJgYFRcXN/hloMXFxY7lWl82cuTIBp9NcZavP5vClLmUmE/Jf+aTufSfuZTMmM8fIwD5qEceeUQTJ05USUmJy1tQlyxZ4he32nbu3Fl/+tOfNGLECJf7t27dqsTExBauyrNMmUuJ+fSn+WQu/WcuJTPm8xx2+KxVq1bZk5KS7EFBQXaLxWK3WCz2oKAge1JSkn316tXeLs8jbrnlFvuMGTMa3L9161a7xWJpwYqahwlzabczn/40n8yl/8yl3W7OfP4QF0H7gVOnTunAgQOSpKioKF100UVershz/t//+3+qrq5WWlqay/3V1dXatGlTg09q9TX+PJcS8+lP88lc+s9cSubNp8RdYAAAwEAB3i4AAACgpRGAAACAcQhAAADAOAQgAABgHAIQAK+4/vrr9dBDDzW4Pz4+Xnl5eS1Sy549e2SxWLR169YW+X0AvI8ABKBV+vjjjzVx4kTHe4vFojVr1jT686+88ooiIiIa1TYuLk7l5eXq06fPBVYJwFfxJGgArVLHjh1b5PfU1tYqODhYMTExLfL7ALQOrAAB8JrTp08rMzNT4eHhioqK0owZMxzfRfTDU2Dx8fGSpF//+teyWCyO95988oluuOEGtW/fXmFhYUpMTNSmTZtUWFiojIwMHTlyRBaLRRaLRTNnznT0NXv2bKWnpyssLEwTJ0485xRYYWGhLBaLbDabBg4cqLZt2yo5OVmff/65U/1PPvmkOnXqpPbt22v8+PGaNm2aEhISHPsLCws1aNAgtWvXThEREbr22mv19ddfN9c/J4ALQAAC4DXLly9XUFCQiouL9dxzzyk3N1cvvfTSOe0+/vhjSdKyZctUXl7ueD927Fhdeuml+vjjj1VSUqJp06bpoosuUnJysvLy8hQWFqby8nKVl5frkUcecfQ3f/589e/fX1u2bNGMGTMarO+JJ57Qs88+q02bNikoKEj33nuvY9+rr76qp556Ss8884xKSkp02WWXafHixY79p0+f1siRIzV06FBt27ZNRUVFmjhxot99oSTgqzgFBsBr4uLitGDBAlksFvXs2VP//ve/tWDBAk2YMMGp3dnTYREREU6nqkpLSzV16lTHt3X36NHDsS88PFwWi8Xlqa1f/OIX+v3vf+94v2fPHpf1PfXUU45H/0+bNk0333yzTpw4odDQUL3wwgu67777lJGRIUnKzs7We++9p2PHjkmSqqqqdOTIEQ0fPlyXX365JOnKK6+8oH8fAM2HFSAAXnPNNdc4rYgMHjxYu3btUl1dXaM+b7VaNX78eKWkpGju3Ln66quvGvW5gQMHNqpdv379HD937txZkrRv3z5J0ueff65BgwY5tf/h+w4dOuiee+5RamqqbrnlFj333HMqLy9v1O8F0PwIQAB81syZM7V9+3bdfPPN+sc//qHevXvr7bff/snPtWvXrlH9//ALL88Gtfr6+kbXt2zZMhUVFSk5OVmrV6/WFVdcoQ0bNjT68wCaDwEIgNds3LjR6f2GDRvUo0cPBQYGntP2oosucrkydMUVV+jhhx/We++9p9tuu03Lli2TJAUHBzd6JckdPXv2dFyLdNaP30vSVVddpaysLH300Ufq06ePVq5c2Ww1AWg8AhAAryktLZXVatXnn3+u1157TS+88IKmTJnism18fLxsNpsqKir03Xff6fjx48rMzFRhYaG+/vprrV+/Xh9//LHjOpv4+HgdO3ZMNptNBw4cUE1NjUdrnzx5sl5++WUtX75cu3bt0pNPPqlt27Y5Vop2796trKwsFRUV6euvv9Z7772nXbt2cR0Q0EpwETQAr0lPT9fx48c1aNAgBQYGasqUKU4PP/yhZ599VlarVUuWLNEll1yiL774QgcPHlR6eroqKysVFRWl2267TbNmzZIkJScn64EHHtCoUaN08OBB5eTkOG6F94SxY8fqP//5jx555BGdOHFC//3f/6177rlHxcXFkqS2bdtq586dWr58uQ4ePKjOnTvrd7/7ne6//36P1QDAfRb72YduAACa5Je//KViYmL0l7/8xdulAPgJrAABgBtqamqUn5+v1NRUBQYG6rXXXtMHH3yg999/39ulAWgEVoAAwA3Hjx/XLbfcoi1btujEiRPq2bOnpk+frttuu83bpQFoBAIQAAAwDneBAQAA4xCAAACAcQhAAADAOAQgAABgHAIQAAAwDgEIAAAYhwAEAACMQwACAADG+f9hv5Z19pXoYwAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "%matplotlib inline\n",
    "\n",
    "task = device.run(qft_circ, shots=0)\n",
    "result = task.result()\n",
    "probs_values = result.values[1]\n",
    "\n",
    "plt.bar(swapped_bitstring_keys, probs_values[reindex])\n",
    "plt.xlabel(\"bitstrings\")\n",
    "plt.xticks(range(2**num_qubits), swapped_bitstring_keys, rotation=\"vertical\")\n",
    "plt.ylabel(\"probability\");"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ca73ee26-34d9-4e67-8633-cbae2ac5af01",
   "metadata": {},
   "source": [
    "# Summary\n",
    "\n",
    "This notebook introduced the native gate set on IonQ consisting of GPI, GPi2, and arbitrary angle MS gates. It showed how common single-qubit gates can be decomposed into this gate set by using the Euler decomposition. Additionally, the decomposition methods were implemented in a subclass of the Braket `Circuit` class help with writing native circuits. \n",
    "\n",
    "For two-qubit gates, the notebook provided examples of mapping a CNot or a controlled-root of a Pauli gate into MS gates plus single-qubit rotations. This enabled the quantum Fourier transform to be implemented using the IonQ native gate set.  \n",
    "\n",
    "By leveraging the capabilities of the native gate set and the provided decomposition methods, users can effectively utilize the IonQ platform for more advanced quantum algorithms. \n",
    "\n",
    "### References \n",
    "\n",
    "[1] Maslov, Dmitri. “Basic Circuit Compilation Techniques for an Ion-Trap Quantum Machine.” New Journal of Physics 19, no. 2 (February 2017): 023035. https://doi.org/10.1088/1367-2630/aa5e47.\n",
    "\n",
    "[2] \"Getting started with Native Gates.\" https://ionq.com/docs/getting-started-with-native-gates"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "conda_braket",
   "language": "python",
   "name": "conda_braket"
  },
  "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.9.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}