{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Quantum Phase Estimation\n", "\n", "**Download this notebook - {nb-download}`phase_estimation.ipynb`**\n", "\n", "When constructing circuits for quantum algorithms it is useful to think of higher level operations than just individual quantum gates. In `pytket` we can construct circuits using box structures which abstract away the complexity of the underlying circuit. This notebook is intended to complement the [boxes section](https://docs.quantinuum.com/tket/user-guide/manual/manual_circuit.html#boxes) of the user manual which introduces the different box types.\n", "\n", "To demonstrate boxes in `pytket` we will consider the Quantum Phase Estimation algorithm (QPE). This is an important subroutine in several quantum algorithms including Shor's algorithm and fault-tolerant approaches to quantum chemistry.\n", "\n", "## Overview of Phase Estimation\n", "\n", "The Quantum Phase Estimation algorithm can be used to estimate the eigenvalues of some unitary operator $U$ to some desired precision.\n", "\n", "The eigenvalues of $U$ lie on the unit circle, giving us the following eigenvalue equation\n", "\n", "$$\n", "\\begin{equation}\n", "U |\\psi \\rangle = e^{2 \\pi i \\theta} |\\psi\\rangle\\,, \\quad 0 \\leq \\theta \\leq 1\n", "\\end{equation}\n", "$$\n", "\n", "Here $|\\psi \\rangle$ is an eigenstate of the operator $U$. In phase estimation we estimate the eigenvalue $e^{2 \\pi i \\theta}$ by approximating $\\theta$.\n", "\n", "\n", "The circuit for Quantum phase estimation is itself composed of several subroutines which we can realise as circuit boxes." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "![](images/qpe_circuit.png \"Quantum Phase Estimation Circuit\"){align=center}" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "QPE is generally split up into three stages\n", "\n", "1. Firstly we prepare an initial state $|\\psi\\rangle$ in one register. In parallel we prepare a uniform superposition state using Hadamard gates on some ancilla (measurement) qubits. The number of ancilla qubits determines how precisely we can estimate the phase $\\theta$.\n", "\n", "2. Secondly we apply successive controlled $U$ gates. This has the effect of \"kicking back\" phases onto the ancilla qubits according to the eigenvalue equation above.\n", "\n", "3. Finally we apply the inverse Quantum Fourier Transform ($QFT^\\dagger$). This essentially plays the role of destructive interference, suppressing amplitudes from \"undesirable states\" and hopefully allowing us to measure a single outcome (or a small number of outcomes) with high probability.\n", "\n", "\n", "There is some subtlety around the first point. The initial state used can be an exact eigenstate of $U$ however this may be difficult to prepare if we don't know the eigenvalues of $U$ in advance. Alternatively we could use an initial state that is a linear combination of eigenstates, as the phase estimation will project into the eigenspace of $U$." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We also assume that we can implement $U$ with a quantum circuit. In chemistry applications $U$ could be of the form $U=e^{-iHt}$ where $H$ is the Hamiltonian of some system of interest. In the textbook algorithm, the number of controlled unitaries we apply scales exponentially with the number of measurement qubits. This allows more precision at the expense of a larger quantum circuit." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## The Quantum Fourier Transform" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Before considering the other parts of the QPE algorithm, lets focus on the Quantum Fourier Transform (QFT) subroutine.\n", "\n", "Mathematically, the QFT has the following action.\n", "\n", "$$\n", "\\begin{equation}\n", "QFT : |j\\rangle\\ \\longmapsto \\frac{1}{\\sqrt{N}} \\sum_{k=0}^{N - 1} e^{2 \\pi ijk/N}|k\\rangle, \\quad N= 2^n\n", "\\end{equation}\n", "$$\n", "\n", "This is essentially the Discrete Fourier transform except the input is a quantum state $|j\\rangle$.\n", "\n", "We can build the circuit for the $n$ qubit QFT using $n$ Hadamard gates $\\lfloor{\\frac{n}{2}}\\rfloor$ swap gates and $\\frac{n(n-1)}{2}$ controlled unitary rotations $\\text{CU1}$.\n", "\n", "$$\n", " \\begin{equation}\n", "U1(\\phi) =\n", " \\begin{pmatrix}\n", " 1 & 0 \\\\\n", " 0 & e^{i \\pi \\phi}\n", " \\end{pmatrix}\\, , \\quad\n", " CU1(\\phi) =\n", " \\begin{pmatrix}\n", " 1 & 0 & 0 & 0 \\\\\n", " 0 & 1 & 0 & 0 \\\\\n", " 0 & 0 & 1 & 0 \\\\\n", " 0 & 0 & 0 & e^{i \\pi \\phi}\n", " \\end{pmatrix}\n", " \\end{equation}\n", "$$\n", "\n", "The circuit for the Quantum Fourier transform on three qubits is the following\n", "\n", "![](images/qft.png \"QFT Circuit\"){align=center}\n", "\n", "We can build this circuit in `pytket` by adding gate operations manually:" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "lets build the QFT for three qubits" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "
\n", " \n", "
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from pytket.circuit import Circuit\n", "from pytket.circuit.display import render_circuit_jupyter as draw\n", "\n", "qft3_circ = Circuit(3)\n", "qft3_circ.H(0)\n", "qft3_circ.CU1(0.5, 1, 0)\n", "qft3_circ.CU1(0.25, 2, 0)\n", "qft3_circ.H(1)\n", "qft3_circ.CU1(0.5, 2, 1)\n", "qft3_circ.H(2)\n", "qft3_circ.SWAP(0, 2)\n", "\n", "draw(qft3_circ)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can generalise the quantum Fourier transform to $n$ qubits by iterating over the qubits as follows" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "def build_qft_circuit(n_qubits: int) -> Circuit:\n", " circ = Circuit(n_qubits, name=\"$$QFT$$\")\n", " for i in range(n_qubits):\n", " circ.H(i)\n", " for j in range(i + 1, n_qubits):\n", " circ.CU1(1 / 2 ** (j - i), j, i)\n", " for k in range(0, n_qubits // 2):\n", " circ.SWAP(k, n_qubits - k - 1)\n", " return circ" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "
\n", " \n", "
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "qft4_circ: Circuit = build_qft_circuit(4)\n", "draw(qft4_circ)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now that we have the generalised circuit we can wrap it up in a `CircBox` which can then be added to another circuit as a subroutine." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "
\n", " \n", "
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from pytket.circuit import CircBox\n", "\n", "qft4_box: CircBox = CircBox(qft4_circ)\n", "qft_circ = Circuit(4).add_gate(qft4_box, [0, 1, 2, 3])\n", "draw(qft_circ)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note how the `CircBox` inherits the name `QFT` from the underlying circuit." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Recall that in our phase estimation algorithm we need to use the inverse QFT.\n", "\n", "$$\n", "\\begin{equation}\n", "\\text{QFT}^† : \\frac{1}{\\sqrt{N}} \\sum_{k=0}^{N - 1} e^{2 \\pi ijk/N}|k\\rangle \\longmapsto |j\\rangle\\,, \\quad N= 2^n\n", "\\end{equation}\n", "$$\n", "\n", "\n", "Now that we have the QFT circuit we can obtain the inverse by using `CircBox.dagger`. We can also verify that this is correct by inspecting the circuit inside with `CircBox.get_circuit()`." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "
\n", " \n", "
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "inv_qft4_box = qft4_box.dagger\n", "# Explicitly set the name of the `CircBox` to $$QFT^\\dagger$$\n", "inv_qft4_box.circuit_name = \"$$QFT^\\dagger$$\"\n", "qft_inv_circ = Circuit(4)\n", "qft_inv_circ.add_gate(inv_qft4_box, [0, 1, 2, 3])\n", "draw(qft_inv_circ)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Building the Phase Estimation Circuit" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We can now define a function to build our entire QPE circuit. We can make this function take a state preparation circuit and a unitary circuit as input as well. The function also has the number of measurement qubits as input which will determine the precision of our phase estimate." ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [], "source": [ "from pytket.circuit import QControlBox, DiagonalBox\n", "\n", "def build_phase_estimation_circuit(\n", " n_measurement_qubits: int, state_prep: CircBox, unitary: CircBox | DiagonalBox\n", ") -> Circuit:\n", "\n", " # Define a Circuit with a measurement and prep register\n", " qpe_circ: Circuit = Circuit()\n", " n_state_prep_qubits = state_prep.n_qubits\n", " measurement_register = qpe_circ.add_q_register(\"m\", n_measurement_qubits)\n", " state_prep_register = qpe_circ.add_q_register(\"p\", n_state_prep_qubits)\n", " qpe_circ.add_gate(state_prep, list(state_prep_register))\n", "\n", " # Create a controlled unitary with a single control qubit\n", " controlled_u_gate = QControlBox(unitary, 1)\n", "\n", " # Add Hadamard gates to every qubit in the measurement register\n", " for m_qubit in measurement_register:\n", " qpe_circ.H(m_qubit)\n", "\n", " # Add all (2**n_measurement_qubits - 1) of the controlled unitaries sequentially\n", " for m_qubit in range(n_measurement_qubits):\n", " control_index = n_measurement_qubits - m_qubit - 1\n", " control_qubit = [measurement_register[control_index]]\n", " for _ in range(2**m_qubit):\n", " qpe_circ.add_gate(\n", " controlled_u_gate, control_qubit + list(state_prep_register)\n", " )\n", "\n", " # Finally, append the inverse qft and measure the qubits\n", " qft_box = CircBox(build_qft_circuit(n_measurement_qubits))\n", " inverse_qft_box = qft_box.dagger\n", " inverse_qft_box.circuit_name = \"$$QFT^{\\dagger}$$\"\n", " qpe_circ.add_gate(inverse_qft_box, list(measurement_register))\n", " qpe_circ.measure_register(measurement_register, \"c\")\n", " return qpe_circ" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Phase Estimation with a Trivial Eigenstate\n", "\n", "Lets test our circuit construction by preparing a trivial $|11\\rangle$ eigenstate of the diagonal $U$ gate. \n", "\n", "$$\n", "U = \\begin{pmatrix}\n", "1 & 0 & 0 & 0 \\\\\n", "0 & 1 & 0 & 0 \\\\\n", "0 & 0 & e^{ i \\frac{\\pi}{4}} & 0 \\\\\n", "0 & 0 & 0 & e^{ i \\frac{\\pi}{8}}\n", "\\end{pmatrix}\n", "$$" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "$$\n", "\\begin{equation}\n", "U|11\\rangle = e^{ i \\frac{\\pi}{8}}|11\\rangle = e^{2 \\pi i \\theta} |11\\rangle\\implies \\theta = \\frac{1}{16}\n", "\\end{equation}\n", "$$\n", "\n", "We can easily prepare this $|11\\rangle$ eigenstate with two Pauli $X$ gates." ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [], "source": [ "prep_circuit = Circuit(2).X(0).X(1) # prepare the |11> eigenstate of D\n", "prep_circuit.name = \"$$P_{|\\psi\\\\rangle}$$\"\n", "\n", "prep_box = CircBox(prep_circuit)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Finally we can use the [DiagonalBox](inv:#*pytket.circuit.DiagonalBox) to realise a circuit implementation of our operator $U$" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [], "source": [ "from pytket.circuit import DiagonalBox\n", "import numpy as np\n", "\n", "u_diagonal = np.array([1, 1, np.e**(1j * np.pi/4), np.e**(1j * np.pi/8)])\n", "d_box = DiagonalBox(u_diagonal)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now that we have all of the pieces together we can build a phase estimation circuit to estimate the eigenvalues of $U$ with four measurement qubits to estimate the phase." ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [], "source": [ "qpe_circ_trivial = build_phase_estimation_circuit(\n", " n_measurement_qubits=4,\n", " state_prep=prep_box, \n", " unitary=d_box)" ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "
\n", " \n", "
\n", "\n" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "draw(qpe_circ_trivial)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Try clicking on the boxes in the rendered display above to see the circuits which define the $P_{|\\psi \\rangle}$ and $QFT^\\dagger$ subroutines." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Lets use the noiseless [AerBackend](inv:#*pytket.extensions.qiskit.backends.aer.AerBackend) simulator from pytket-qiskit to run our phase estimation circuit." ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [], "source": [ "from pytket.extensions.qiskit import AerBackend\n", "\n", "backend = AerBackend()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Before we can execute the QPE circuit on the Aer simulator we need to decompose the [DiagonalBox](inv:#*pytket.circuit.DiagonalBox), [CircBox](inv:#*pytket.circuit.CircBox) and {py:class}`~pytket.circuit.QControlBox`primitives. " ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 12, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from pytket.passes import DecomposeBoxes\n", "\n", "DecomposeBoxes().apply(qpe_circ_trivial)" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [], "source": [ "n_shots = 1000\n", "result = backend.run_circuit(qpe_circ_trivial, n_shots)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "plotting function for QPE Notebook" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [], "source": [ "from pytket.backends.backendresult import BackendResult\n", "import matplotlib.pyplot as plt\n", "\n", "def plot_qpe_results(\n", " sim_result: BackendResult,\n", " n_strings: int = 4,\n", " dark_mode: bool = False,\n", " y_limit: int = 1000,\n", ") -> None:\n", " \"\"\"\n", " Plots results in a barchart given a BackendResult. the number of stings displayed\n", " can be specified with the n_strings argument.\n", " \"\"\"\n", " counts_dict = sim_result.get_counts()\n", " sorted_shots = counts_dict.most_common()\n", " n_most_common_strings = sorted_shots[:n_strings]\n", " x_axis_values = [str(entry[0]) for entry in n_most_common_strings] # basis states\n", " y_axis_values = [entry[1] for entry in n_most_common_strings] # counts\n", "\n", " if dark_mode:\n", " plt.style.use(\"dark_background\")\n", " \n", " fig = plt.figure()\n", " ax = fig.add_axes((0, 0, 0.4, 0.5))\n", " color_list = [\"orange\"] * (len(x_axis_values))\n", " ax.bar(\n", " x=x_axis_values,\n", " height=y_axis_values,\n", " color=color_list,\n", " )\n", " ax.set_title(label=\"Results\")\n", " plt.ylim([0, y_limit])\n", " plt.xlabel(\"Basis State\")\n", " plt.ylabel(\"Number of Shots\")\n", " plt.show()" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "plot_qpe_results(result, y_limit=int(1.2 * n_shots))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We see that our measurements always give the computational basis state $|0001\\rangle$. This is the integer $j=1$ encoded in 4 bits. From this we can easily calculate the phase estimate which in this highly idealised case will be exact." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "$$\n", "\\begin{equation}\n", "\\theta_{estimate} = \\frac{j}{2^m}\n", "\\end{equation}\n", "$$" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Where $m$ is the number of measurement qubits. In this case $m=4$." ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [], "source": [ "from pytket.backends.backendresult import BackendResult\n", "\n", "def single_phase_from_backendresult(result: BackendResult) -> float:\n", " # Extract most common measurement outcome\n", " basis_state = result.get_counts().most_common()[0][0]\n", " bitstring = \"\".join([str(bit) for bit in basis_state])\n", " integer_j = int(bitstring, 2)\n", "\n", " # Calculate theta estimate\n", " return integer_j / (2 ** len(bitstring))" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "0.0625\n" ] } ], "source": [ "theta = single_phase_from_backendresult(result)\n", "\n", "print(theta)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Our output is exactly $\\theta = \\frac{1}{2^4} = \\frac{1}{16}=0.0625$ as we would expect from looking at our matrix $U$." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Phase Estimation with Time Evolution" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In the phase estimation algorithm we repeatedly perform controlled unitary operations. In the textbook variant of QPE presented here, the number of controlled unitaries will be $2^m - 1$ where $m$ is the number of measurement qubits." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In the example above we've shown a trivial instance of QPE where we know the exact phase in advance. For more realistic applications of QPE we will have some non-trivial state preparation required.\n", "\n", "For chemistry or condensed matter physics $U$ typically be the time evolution operator $U(t) = e^{- i H t}$ where $H$ is the problem Hamiltonian.\n", "Suppose that we had the following decomposition for $H$ in terms of Pauli strings $P_j$ and complex coefficients $\\alpha_j$.\n", "\n", "$$\n", "\\begin{equation}\n", "H = \\sum_j \\alpha_j P_j\\,, \\quad \\, P_j \\in \\{I, \\,X, \\,Y, \\,Z\\}^{\\otimes n}\n", "\\end{equation}\n", "$$\n", "\n", "Here the term Pauli strings refers to tensor products of Pauli operators. These strings form an orthonormal basis for $2^n \\times 2^n$ matrices." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If we have a Hamiltonian in the form above, we can then implement $U(t)$ as a sequence of Pauli gadget circuits. We can do this with the {py:class}`~pytket.circuit.PauliExpBox` construct in pytket. For more on {py:class}`~pytket.circuit.PauliExpBox` see the [user manual](https://docs.quantinuum.com/tket/user-guide/manual/manual_circuit.html#pauli-exponential-boxes)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once we have a circuit to implement our time evolution operator $U(t)$, we can construct the controlled $U(t)$ operations using {py:class}`~pytket.circuit.QControlBox`. If our base unitary is a sequence of `PauliExpBox`(es) then there is some structure we can exploit to simplify our circuit. See this [blog post](https://docs.quantinuum.com/tket/blog/posts/controlled_gates/) on {py:class}`~pytket.circuit.ConjugationBox` for more." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As an exercise, try to use phase estimation to calculate the ground state of diatomic hydrogen $H_2$." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Suggestions for further reading\n", "\n", "* Quantinuum paper on Bayesian phase estimation -> https://arxiv.org/pdf/2306.16608.pdf\n", "* [Blog post on `ConjugationBox`](https://docs.quantinuum.com/tket/blog/posts/controlled_gates/)" ] } ], "metadata": { "kernelspec": { "display_name": ".venv", "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.11.2" } }, "nbformat": 4, "nbformat_minor": 4 }