{
"cells": [
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"cellView": "form",
"execution": {
"iopub.execute_input": "2024-12-15T11:07:02.389456Z",
"iopub.status.busy": "2024-12-15T11:07:02.389232Z",
"iopub.status.idle": "2024-12-15T11:07:02.393133Z",
"shell.execute_reply": "2024-12-15T11:07:02.392524Z"
},
"id": "906e07f6e562"
},
"outputs": [],
"source": [
"# @title Copyright 2020 The Cirq Developers\n",
"# Licensed under the Apache License, Version 2.0 (the \"License\");\n",
"# you may not use this file except in compliance with the License.\n",
"# You may obtain a copy of the License at\n",
"#\n",
"# https://www.apache.org/licenses/LICENSE-2.0\n",
"#\n",
"# Unless required by applicable law or agreed to in writing, software\n",
"# distributed under the License is distributed on an \"AS IS\" BASIS,\n",
"# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n",
"# See the License for the specific language governing permissions and\n",
"# limitations under the License."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "291eb7f565e0"
},
"source": [
"# Quantum approximate optimization algorithm for the Ising model"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "4dec45d973fc"
},
"source": [
"
"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "gAxVvd1LF3l4"
},
"source": [
"This notebook provides an introduction to the Quantum Approximate Optimization Algorithm (QAOA) using Cirq. The presentation mostly follows [Farhi et al](https://arxiv.org/abs/1411.4028). We will show how to construct the QAOA circuit and use it to solve optimization problems."
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:02.395930Z",
"iopub.status.busy": "2024-12-15T11:07:02.395705Z",
"iopub.status.idle": "2024-12-15T11:07:20.831569Z",
"shell.execute_reply": "2024-12-15T11:07:20.830851Z"
},
"id": "RlJBDvNgC00H"
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"installing cirq...\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"\u001b[31mERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.\r\n",
"tensorflow-metadata 1.16.1 requires protobuf<4.21,>=3.20.3; python_version < \"3.11\", but you have protobuf 4.25.5 which is incompatible.\u001b[0m\u001b[31m\r\n",
"\u001b[0m"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"installed cirq.\n"
]
}
],
"source": [
"try:\n",
" import cirq\n",
"except ImportError:\n",
" print(\"installing cirq...\")\n",
" !pip install cirq --quiet\n",
" import cirq\n",
"\n",
" print(\"installed cirq.\")"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.835016Z",
"iopub.status.busy": "2024-12-15T11:07:20.834149Z",
"iopub.status.idle": "2024-12-15T11:07:20.838087Z",
"shell.execute_reply": "2024-12-15T11:07:20.837455Z"
},
"id": "FTrmLyq4C2gf"
},
"outputs": [],
"source": [
"from typing import Sequence, Tuple\n",
"import numpy as np\n",
"import sympy\n",
"import matplotlib.pyplot as plt"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "70311a0a937e"
},
"source": [
"## Description of the QAOA"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "8A7a3jcql1l5"
},
"source": [
"Suppose we have a function $C(z)$ which we want to minimize. Here, $z$ denotes a collection of variables $z = z_1,z_2,\\ldots, z_n$, where each $z_j$ can be either $+1$ or $-1$. (The important thing here is that each $z_j$ has *two possible values*. By convention, we choose those values to be $\\pm 1$). The QAOA is a general-purpose algorithm whose goal is to produce an assignment of the $z_j$ that gives a relatively low value of $C(z)$. It's not guaranteed to give the lowest possible value of $C(z)$ (hence \"approximate\" in the name) except in a particular limit which we will discuss.\n",
"\n",
"The QAOA acts on $n$ qubits where, as you might guess, each qubit represents one of the variables $z_1, ..., z_n$, and the $2^n$ states of the computational basis correspond to the $2^n$ possible assignments of the $z$ variables. To be more specific, let's agree that the value of $z_j$ corresponds to the measurement outcome of the Pauli-$Z$ operator on the $j$th qubit. (There is a potential confusion here because the state $| 0 \\rangle$ corresponds to $z = +1$, while the state $| 1\\rangle$ corresponds to $z=-1$. This is unfortunate, but is something that we'll just have to deal with.)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "q4F7ccpiGOn4"
},
"source": [
"The QAOA is fairly simple to explain, though the reasons behind why it works are not obvious at first glance. As usual, we begin with all of our qubits initialized in the $|0\\rangle$ state. The first step is to act with $H^{\\otimes n}$, the Hadamard operator on each qubit. This prepares an equal superposition of all bitstrings, i.e., an equal superposition of all possible $z$ assignments:\n",
"\n",
"$$\n",
"H^{\\otimes n} |0^n\\rangle =\\frac{1}{2^{n/2}} \\sum_{z \\in \\{0,1\\}^n} |z\\rangle.\n",
"$$\n",
"\n",
"This should be thought of as the \"real\" initial state of the algorithm (as opposed to thinking of the $|0\\rangle$ state as the initial state). The point of the remaining steps is to affect the amplitudes such that those with small $C(z)$ values grow while those with large $C(z)$ values shrink. In this way, when we measure the qubits we'll be more likely to find a bitstring with a small value of $C(z)$."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "AW1bxjmdHw44"
},
"source": [
"The meat of the algorithm relies on the following unitary operator:\n",
"\n",
"$$\n",
"U(\\gamma, C) = e^{i \\pi \\gamma C(Z) / 2} .\n",
"$$\n",
"\n",
"This operator deserves some explanation. First, $\\gamma$ is a parameter which we will later treat as a variational parameter, adjusting its value to produce the best possible result. $C$ here is the function we are trying to minimize, and the notation $C(Z)$ is supposed to tell you to plug in the Pauli-$Z$ operator for each qubit in place of the argument $z$. For example, if \n",
"\n",
"$$\n",
"C(z) = 3z_1 z_2 - z_2z_3 + z_4 ,\n",
"$$\n",
"\n",
"then\n",
"\n",
"$$\n",
"C(Z) = 3Z_1 Z_2 - Z_2Z_3 + Z_4.\n",
"$$\n",
"\n",
"It doesn't look like much happened, but the point here is that $C(z)$ is a number while $C(Z)$ is a matrix. That matrix is diagonal in the computational basis, and those diagonal entries represent all the possible values of $C(z)$.\n",
"\n",
"After acting with $H^{\\otimes n}$, we act with $U(\\gamma, C)$. The result is still a sum over all possible bit-strings, but now the coefficients are complex phases which depend on $C$. At this point there is still an equal probability to measure any particular string, though, because Born's rule only depends on the square of the amplitude. So, the algorithm is not done yet."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "ocxry8MKJFeD"
},
"source": [
"The next step of the algorithm is to act with the unitary operator\n",
"\n",
"$$\n",
"U(\\beta,B) = e^{i\\pi\\beta B/2},~~~ B = \\sum_{j=1}^n X_j ,\n",
"$$\n",
"\n",
"where $\\beta$ is another variational parameter. Since the Pauli-$X$ operators on each qubit commute with each other, we can alternatively write this as\n",
"\n",
"$$\n",
"U(\\beta, B) = \\prod_{j=1}^n e^{i\\pi\\beta X_j/2} .\n",
"$$\n",
"\n",
"So this is just a rotation of each qubit around the $X$-axis on the Bloch sphere by an amount determined by $\\beta$. This operation is _not_ diagonal in the computational basis, and the resulting state will not be an equal superposition over all bitstrings. So after this step there will be constructive and destructive interference, which hopefully leads to enhancement of states corresponding to small values of $C$. This $U(\\beta, B)$ is sometimes called a \"mixing\" operation. Note that, up to an inconsequential global phase, we can also write\n",
"\n",
"$$\n",
"U(\\beta, B) = \\prod_{j=1}^n X_j^{\\beta} .\n",
"$$"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "RFgdxbSlLh0y"
},
"source": [
"The total circuit consists of repeating the previous two steps a total of $p\\geq 1$ times, where the choice of $p$ is up to you. The parameters $\\gamma$ and $\\beta$ can be chosen independently at each step. So at the conclusion of the circuit, the state of the qubits is\n",
"\n",
"$$\n",
"|\\gamma,\\beta\\rangle = U(\\beta_p,B)U(\\gamma_p,C)\\cdots U(\\beta_1,B)U(\\gamma_1,C)H^{\\otimes n}|0^n\\rangle.\n",
"$$\n",
"\n",
"If we choose $\\gamma$ and $\\beta$ so that the expectation value\n",
"\n",
"$$\n",
"F(\\gamma,\\beta) = \\langle \\gamma,\\beta|C(Z)|\\gamma,\\beta\\rangle\n",
"$$\n",
"\n",
"is minimized, then measuring the state $|\\gamma,\\beta\\rangle$ in the computational basis gives us a good candidate bitstring for the minimum of $C(z)$. That's the whole thing!"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "MK02MlydMUqL"
},
"source": [
"In summary we have to perform the following tasks in order to implement the QAOA:\n",
"\n",
"1. Figure out how to perform the $U(\\gamma, C)$ operation in Cirq for our choice of $C$.\n",
"2. Create a quantum circuit alternating $U(\\gamma, C)$ and $U(\\beta, B)$ operations as many times as desired. \n",
"3. Find the optimal value of the variational parameters in our circuit.\n",
"4. Measure the output of our circuit."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "ae8fb76ad322"
},
"source": [
"## Toy problem: Ground state of the Ising model"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "X15yPl_KQ20Z"
},
"source": [
"The Ising Model defines the energy function\n",
"\n",
"$$\n",
"E = -\\sum_{\\langle i,j \\rangle} Z_i Z_j - \\sum_i h_i Z_i,\n",
"$$\n",
"\n",
"where the notation $\\langle i,j\\rangle$ means a sum over all nearest-neighbor pairs. The picture here is that the qubits live on the vertices of a graph, and the edges of the graph define which qubits are neighbors. We'll just take our graph to be a rectangular lattice with some number of rows and some number of columns. The numbers $h_i$ have the physical interpretation of an external magnetic field.\n",
"\n",
"We are interested in finding a low-lying state of the Ising Model, by which we mean a state that has a relatively low amount of energy. This is a difficult problem in general. The pairwise interaction terms would tell you that neighboring qubits should be in the same state to lower the energy, while the magnetic field terms tell you that a given qubit wants to point \"in the same direction\" as its local field, and the strength of that preference depends on the magnitude of the field. These two different kinds of pressure are not always in agreement!\n",
"\n",
"This type of problem is a perfect candidate for the QAOA, where we use the energy $E$ as our cost function $C$."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "377aad71d045"
},
"source": [
"### Implementing $U(\\gamma, C)$"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "VFwmWPf7D057"
},
"source": [
"The first thing we need to do is create the operation $U(\\gamma, C)$ where $C$ is equal to the Ising model energy function. Note that since all terms in the energy function commute, we can decompose this operation as\n",
"\n",
"$$\n",
"U(\\gamma, C) = \\prod_{\\langle i,j\\rangle}e^{-i\\pi\\gamma Z_iZ_j/2} \\prod_i e^{-i\\pi \\gamma h_i Z_i/2}.\n",
"$$\n",
"\n",
"This requires that we have the two-qubit gate $\\exp(-i\\pi\\gamma ZZ/2)$ at our disposal. In matrix form, this is\n",
"\n",
"$$\n",
"\\begin{align}\n",
"\\exp(-i \\pi\\gamma Z\\otimes Z/2) = \\begin{bmatrix}\n",
"e^{-i\\pi \\gamma/2} & 0 &0&0\\\\\n",
"0 & e^{i\\pi \\gamma/2} &0&0\\\\\n",
"0&0& e^{i\\pi \\gamma/2} &0 \\\\\n",
"0&0 & 0 & e^{-i\\pi \\gamma/2}\n",
"\\end{bmatrix}\n",
"\\end{align}\n",
"$$\n",
"\n",
"Cirq has a built-in gate `cirq.ZZ` which is equivalent to this once you account for a global phase."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.841901Z",
"iopub.status.busy": "2024-12-15T11:07:20.841439Z",
"iopub.status.idle": "2024-12-15T11:07:20.847138Z",
"shell.execute_reply": "2024-12-15T11:07:20.846532Z"
},
"id": "3CZsDwTlDy_h"
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"a: ───ZZ───────\n",
" │\n",
"b: ───ZZ^0.3───\n"
]
}
],
"source": [
"\"\"\"Example of using the ZZ gate.\"\"\"\n",
"# Get two qubits.\n",
"a = cirq.NamedQubit(\"a\")\n",
"b = cirq.NamedQubit(\"b\")\n",
"\n",
"# Pick a value for gamma.\n",
"gamma = 0.3\n",
"\n",
"# Display the circuit.\n",
"circuit = cirq.Circuit(cirq.ZZ(a, b) ** gamma)\n",
"print(circuit)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "WvFVcT2de0V6"
},
"source": [
"We should also check that the unitary is what we expect."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.849961Z",
"iopub.status.busy": "2024-12-15T11:07:20.849422Z",
"iopub.status.idle": "2024-12-15T11:07:20.866922Z",
"shell.execute_reply": "2024-12-15T11:07:20.866306Z"
},
"id": "CazWJFM5eGgB"
},
"outputs": [],
"source": [
"\"\"\"Check the unitary of the ZZ gate.\"\"\"\n",
"# Unitary we want to implement.\n",
"expected_unitary = np.array(\n",
" [\n",
" [np.exp(-1j * np.pi * gamma / 2), 0, 0, 0],\n",
" [0, np.exp(1j * np.pi * gamma / 2), 0, 0],\n",
" [0, 0, np.exp(1j * np.pi * gamma / 2), 0],\n",
" [0, 0, 0, np.exp(-1j * np.pi * gamma / 2)],\n",
" ]\n",
")\n",
"\n",
"# Unitary we are implementing.\n",
"actual_unitary = cirq.unitary(circuit)\n",
"\n",
"# Check that they are equal up to global phase.\n",
"cirq.testing.assert_allclose_up_to_global_phase(\n",
" actual_unitary, expected_unitary, atol=1e-5\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "cy1ns-RLMzp3"
},
"source": [
"The magnetic field terms can be handled in a similar way. The single-qubit unitary\n",
"\n",
"$$\n",
"\\exp(-i\\pi \\gamma hZ/2) = \\begin{bmatrix}\n",
"e^{-i\\pi \\gamma h/2} & 0 \\\\\n",
"0 & e^{i\\pi \\gamma h/2}\n",
"\\end{bmatrix}\n",
"$$\n",
"\n",
"is equivalent to `cirq.Z**(h*gamma)` up to global phase."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.869826Z",
"iopub.status.busy": "2024-12-15T11:07:20.869578Z",
"iopub.status.idle": "2024-12-15T11:07:20.873960Z",
"shell.execute_reply": "2024-12-15T11:07:20.873272Z"
},
"id": "4e25d4a9e5fd"
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"a: ───Z^0.39───\n"
]
}
],
"source": [
"\"\"\"Example of using the Z gate.\"\"\"\n",
"# Value of the external magenetic field.\n",
"h = 1.3\n",
"\n",
"# Display the circuit.\n",
"circuit = cirq.Circuit(cirq.Z(a) ** (gamma * h))\n",
"print(circuit)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "1e735a3a1797"
},
"source": [
"As before, we can check this unitary is what we expect."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.877068Z",
"iopub.status.busy": "2024-12-15T11:07:20.876378Z",
"iopub.status.idle": "2024-12-15T11:07:20.881868Z",
"shell.execute_reply": "2024-12-15T11:07:20.881109Z"
},
"id": "7b78132a891e"
},
"outputs": [],
"source": [
"\"\"\"Check the unitary of the Z gate.\"\"\"\n",
"# Unitary we want to implement.\n",
"expected_unitary = np.array(\n",
" [[np.exp(-1j * np.pi * gamma * h / 2), 0], [0, np.exp(1j * np.pi * gamma * h / 2)]]\n",
")\n",
"\n",
"# Unitary we are implementing.\n",
"actual_unitary = cirq.unitary(circuit)\n",
"\n",
"# Check that they are equal up to global phase.\n",
"cirq.testing.assert_allclose_up_to_global_phase(\n",
" expected_unitary, actual_unitary, atol=1e-5\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "51cff3fcb275"
},
"source": [
"Now that we know how to implement both $Z_i Z_j$ and $Z_i$, we can implement the full $U(\\gamma, C)$ operator."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "1b6e1cf7ec1b"
},
"source": [
"### Exercise: More general two-qubit gate"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "esgOuHF_FT_2"
},
"source": [
"The Ising Model is particularly simple because the nearest-neighbor interaction $Z_i Z_j$ is already given in terms of a product of Pauli matrices. But suppose instead that the cost function was a sum of terms that looked like\n",
"\n",
"$$\n",
"C(z_i,z_j) = \\begin{cases}\n",
"c_{00} \\text{ if } z_i =1,~z_j=1,\\\\\n",
"c_{01} \\text{ if } z_i =1,~z_j=-1,\\\\\n",
"c_{10} \\text{ if } z_i =-1,~z_j=1,\\\\\n",
"c_{11} \\text{ if } z_i =-1,~z_j=-1 \n",
"\\end{cases}\n",
"$$\n",
"\n",
"for some numbers $c_{ab}$. How would you make the analogous two-qubit gate for this case? You can either make a custom gate from scratch, or build a solution from the standard elementary gates."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.884520Z",
"iopub.status.busy": "2024-12-15T11:07:20.884278Z",
"iopub.status.idle": "2024-12-15T11:07:20.887335Z",
"shell.execute_reply": "2024-12-15T11:07:20.886684Z"
},
"id": "d33731f88da5"
},
"outputs": [],
"source": [
"# Your code here!"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "0d66998d0966"
},
"source": [
"### Implementing the full circuit"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "uaDb6B_jPgrb"
},
"source": [
"We will focus on the Ising model on a rectangular lattice with an arbitrary number of rows and columns. Here are some things to think about:\n",
"\n",
"1. `cirq.GridQubit`s are natural because our qubits actually do live on a grid. Cirq does not care what kind of qubit you make, though.\n",
"2. It's a good idea to define separate functions to place the C and B layers for the circuit. Really these should be generators that yield the required gates.\n",
"3. You might consider wrapping everything inside a class. We won't do that here, but if you want to play around with different numbers of rows/columns or different numbers of B/C layers it can be convenient.\n",
"\n",
"First, we'll define the basic parameters of our model and the generators for the different layers."
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.890461Z",
"iopub.status.busy": "2024-12-15T11:07:20.889897Z",
"iopub.status.idle": "2024-12-15T11:07:20.894102Z",
"shell.execute_reply": "2024-12-15T11:07:20.893425Z"
},
"id": "NPeFsF6yFvGr"
},
"outputs": [],
"source": [
"\"\"\"Define problem parameters and get a set of GridQubits.\"\"\"\n",
"# Set the dimensions of the grid.\n",
"n_cols = 3\n",
"n_rows = 3\n",
"\n",
"# Set the value of the external magnetic field at each site.\n",
"h = 0.5 * np.ones((n_rows, n_cols))\n",
"\n",
"# Arranging the qubits in a list-of-lists like this makes them easy to refer to later.\n",
"qubits = [[cirq.GridQubit(i, j) for j in range(n_cols)] for i in range(n_rows)]"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.896818Z",
"iopub.status.busy": "2024-12-15T11:07:20.896223Z",
"iopub.status.idle": "2024-12-15T11:07:20.901041Z",
"shell.execute_reply": "2024-12-15T11:07:20.900452Z"
},
"id": "2b287acf9127"
},
"outputs": [],
"source": [
"def gamma_layer(gamma_value: float, h: np.ndarray) -> Sequence[cirq.Operation]:\n",
" \"\"\"Generator for U(gamma, C) layer of QAOA\n",
"\n",
" Args:\n",
" gamma: Float variational parameter for the circuit\n",
" h: Array of floats of external magnetic field values\n",
" \"\"\"\n",
" for i in range(n_rows):\n",
" for j in range(n_cols):\n",
" if i < n_rows - 1:\n",
" yield cirq.ZZ(qubits[i][j], qubits[i + 1][j]) ** gamma_value\n",
" if j < n_cols - 1:\n",
" yield cirq.ZZ(qubits[i][j], qubits[i][j + 1]) ** gamma_value\n",
" yield cirq.Z(qubits[i][j]) ** (gamma_value * h[i, j])"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.903942Z",
"iopub.status.busy": "2024-12-15T11:07:20.903332Z",
"iopub.status.idle": "2024-12-15T11:07:20.906913Z",
"shell.execute_reply": "2024-12-15T11:07:20.906305Z"
},
"id": "7782b09bd0dc"
},
"outputs": [],
"source": [
"def beta_layer(beta_value: float) -> Sequence[cirq.Operation]:\n",
" \"\"\"Generator for U(beta, B) layer (mixing layer) of QAOA\"\"\"\n",
" for row in qubits:\n",
" for qubit in row:\n",
" yield cirq.X(qubit) ** beta_value"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "M-3Tg-_dlOn0"
},
"source": [
"Let's test these functions by constructing the circuit. Try making a circuit with different numbers of layers. How would you automatically make a circuit with a specified number of layers? Make sure the parameters of these layers are distinct `sympy.Symbol`s for later optimization. Print the circuit to see that it's doing what you want it to do."
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.910123Z",
"iopub.status.busy": "2024-12-15T11:07:20.909555Z",
"iopub.status.idle": "2024-12-15T11:07:20.919847Z",
"shell.execute_reply": "2024-12-15T11:07:20.919273Z"
},
"id": "4ZmjE6pmtUoG"
},
"outputs": [
{
"data": {
"text/html": [
"
"
],
"text/plain": [
" ┌──────────────────┐ ┌──────────────────┐\n",
"(0, 0): ───H───ZZ───────ZZ───────Z^(0.5*𝛄)──────────────────────────────────────────────────────────────────────────────────────────────X^(β)───\n",
" │ │\n",
"(0, 1): ───H───┼────────ZZ^(𝛄)───ZZ──────────ZZ────────Z^(0.5*𝛄)────────────────────────────────────────────────────────────────────────X^(β)───\n",
" │ │ │\n",
"(0, 2): ───H───┼─────────────────┼───────────ZZ^(𝛄)────ZZ────────────────────Z^(0.5*𝛄)──────────────────────────────────────────────────X^(β)───\n",
" │ │ │\n",
"(1, 0): ───H───ZZ^(𝛄)───ZZ───────┼───────────ZZ────────┼────────Z^(0.5*𝛄)───────────────────────────────────────────────────────────────X^(β)───\n",
" │ │ │ │\n",
"(1, 1): ───H────────────┼────────ZZ^(𝛄)──────ZZ^(𝛄)────┼────────ZZ───────────ZZ───────────Z^(0.5*𝛄)─────────────────────────────────────X^(β)───\n",
" │ │ │ │\n",
"(1, 2): ───H────────────┼──────────────────────────────ZZ^(𝛄)───┼────────────ZZ^(𝛄)───────ZZ────────────────────Z^(0.5*𝛄)───────────────X^(β)───\n",
" │ │ │\n",
"(2, 0): ───H────────────ZZ^(𝛄)──────────────────────────────────┼────────────ZZ───────────┼────────Z^(0.5*𝛄)────────────────────────────X^(β)───\n",
" │ │ │\n",
"(2, 1): ───H────────────────────────────────────────────────────ZZ^(𝛄)───────ZZ^(𝛄)───────┼─────────────────────ZZ──────────Z^(0.5*𝛄)───X^(β)───\n",
" │ │\n",
"(2, 2): ───H──────────────────────────────────────────────────────────────────────────────ZZ^(𝛄)────────────────ZZ^(𝛄)──────Z^(0.5*𝛄)───X^(β)───\n",
" └──────────────────┘ └──────────────────┘"
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"\"\"\"Create the QAOA circuit.\"\"\"\n",
"# Use sympy.Symbols for the 𝛾 and β parameters.\n",
"gamma = sympy.Symbol(\"𝛄\")\n",
"beta = sympy.Symbol(\"β\")\n",
"\n",
"# Start in the H|0> state.\n",
"qaoa = cirq.Circuit(cirq.H.on_each(qubits))\n",
"\n",
"# Implement the U(gamma, C) operator.\n",
"qaoa.append(gamma_layer(gamma, h))\n",
"\n",
"# Implement the U(beta, B) operator.\n",
"qaoa.append(beta_layer(beta), strategy=cirq.InsertStrategy.NEW_THEN_INLINE)\n",
"\n",
"# Display the QAOA circuit.\n",
"qaoa"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "9fc72a4fb3d3"
},
"source": [
"### Computing the energy"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "3HtlMxa6QpVo"
},
"source": [
"To train the QAOA circuit (that is, find the optimal values of the parameters) we're going to need to be able to compute the expectation value of the Ising model energy.\n",
"\n",
"If we were using real hardware, the only way to compute the expectation value of the energy would be to estimate it by sampling. Using a simulator we can alternatively compute the wavefunction and then calculate the expectation value from that. Not only does this save us from having to worry about statistical error, it also tends to be faster that simulating the sampling process.\n",
"\n",
"We divide the total energy by the number of qubits because we expect the energy to scale with the size of the system."
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.951081Z",
"iopub.status.busy": "2024-12-15T11:07:20.950852Z",
"iopub.status.idle": "2024-12-15T11:07:20.956428Z",
"shell.execute_reply": "2024-12-15T11:07:20.955864Z"
},
"id": "-9etj1AeK6dG"
},
"outputs": [],
"source": [
"def energy_from_wavefunction(wf: np.ndarray, h: np.ndarray) -> float:\n",
" \"\"\"Computes the energy-per-site of the Ising model directly from the\n",
" a given wavefunction.\n",
"\n",
" Args:\n",
" wf: Array of size 2**(n_rows * n_cols) specifying the wavefunction.\n",
" h: Array of shape (n_rows, n_cols) giving the magnetic field values.\n",
"\n",
" Returns:\n",
" energy: Float equal to the expectation value of the energy per site\n",
" \"\"\"\n",
" n_sites = n_rows * n_cols\n",
"\n",
" # Z is an array of shape (n_sites, 2**n_sites). Each row consists of the\n",
" # 2**n_sites non-zero entries in the operator that is the Pauli-Z matrix on\n",
" # one of the qubits times the identities on the other qubits. The\n",
" # (i*n_cols + j)th row corresponds to qubit (i,j).\n",
" Z = np.array(\n",
" [(-1) ** (np.arange(2**n_sites) >> i) for i in range(n_sites - 1, -1, -1)]\n",
" )\n",
"\n",
" # Create the operator corresponding to the interaction energy summed over all\n",
" # nearest-neighbor pairs of qubits\n",
" ZZ_filter = np.zeros_like(wf, dtype=float)\n",
" for i in range(n_rows):\n",
" for j in range(n_cols):\n",
" if i < n_rows - 1:\n",
" ZZ_filter += Z[i * n_cols + j] * Z[(i + 1) * n_cols + j]\n",
" if j < n_cols - 1:\n",
" ZZ_filter += Z[i * n_cols + j] * Z[i * n_cols + (j + 1)]\n",
"\n",
" energy_operator = -ZZ_filter - h.reshape(n_sites).dot(Z)\n",
"\n",
" # Expectation value of the energy divided by the number of sites\n",
" return np.sum(np.abs(wf) ** 2 * energy_operator) / n_sites"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "fjFPEQuyvxjR"
},
"source": [
"We'll also need a helper function that computes the expected value of the energy given some parameters of the QAOA."
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.959203Z",
"iopub.status.busy": "2024-12-15T11:07:20.958651Z",
"iopub.status.idle": "2024-12-15T11:07:20.962779Z",
"shell.execute_reply": "2024-12-15T11:07:20.961960Z"
},
"id": "XOYLY_u5K7z0"
},
"outputs": [],
"source": [
"def energy_from_params(\n",
" gamma_value: float, beta_value: float, qaoa: cirq.Circuit, h: np.ndarray\n",
") -> float:\n",
" \"\"\"Returns the energy given values of the parameters.\"\"\"\n",
" sim = cirq.Simulator()\n",
" params = cirq.ParamResolver({\"𝛄\": gamma_value, \"β\": beta_value})\n",
" wf = sim.simulate(qaoa, param_resolver=params).final_state_vector\n",
" return energy_from_wavefunction(wf, h)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "909ff1474e87"
},
"source": [
"### Optimizing the parameters"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "r-CjbPwkRI_I"
},
"source": [
"Now we need to figure out the best values of $\\gamma$ and $\\beta$ by minimizing the expectation value of the energy. We'll start by doing a brute-force search of the parameter space for illustrative purposes."
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:20.966190Z",
"iopub.status.busy": "2024-12-15T11:07:20.965551Z",
"iopub.status.idle": "2024-12-15T11:07:36.631014Z",
"shell.execute_reply": "2024-12-15T11:07:36.630263Z"
},
"id": "hM2Zd_kTI578"
},
"outputs": [],
"source": [
"\"\"\"Do a grid search over values of 𝛄 and β.\"\"\"\n",
"# Set the grid size and range of parameters.\n",
"grid_size = 50\n",
"gamma_max = 2\n",
"beta_max = 2\n",
"\n",
"# Do the grid search.\n",
"energies = np.zeros((grid_size, grid_size))\n",
"for i in range(grid_size):\n",
" for j in range(grid_size):\n",
" energies[i, j] = energy_from_params(\n",
" i * gamma_max / grid_size, j * beta_max / grid_size, qaoa, h\n",
" )"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "b9b6bb9ad449"
},
"source": [
"We can visualize the energy landscape as follows."
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:36.634749Z",
"iopub.status.busy": "2024-12-15T11:07:36.634462Z",
"iopub.status.idle": "2024-12-15T11:07:36.910326Z",
"shell.execute_reply": "2024-12-15T11:07:36.909680Z"
},
"id": "AFP2Ofi0KTfq"
},
"outputs": [
{
"data": {
"image/png": "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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"\"\"\"Plot the energy as a function of the parameters 𝛄 and β found in the grid search.\"\"\"\n",
"plt.ylabel(r\"$\\gamma$\")\n",
"plt.xlabel(r\"$\\beta$\")\n",
"plt.title(\"Energy as a function of parameters\")\n",
"plt.imshow(energies, extent=(0, beta_max, gamma_max, 0))\n",
"plt.colorbar()\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "1pWhCblZASbb"
},
"source": [
"We see that the energy function has a number of interesting properties. First, note that the function is periodic in $\\beta$ and $\\gamma$ with shorter periods than one might naively expect given the definition of the gates. The details of why that's true will take us away from the main content of this tutorial, but it's a good thing to understand so that the parameter space can be efficiently truncated.\n",
"\n",
"The other main thing to notice is that there are many local minima and maxima. This makes it challenging to use gradient-based methods for optimization, which we'll explicitly see next. Part of the challenge for algorithms of this type is finding efficient ways to optimize the parameters."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "0888d57915c6"
},
"source": [
"#### Gradient descent"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "9MwLJ0LCC0un"
},
"source": [
"For practice let's try to minimize the expectation value of the energy using gradient descent. We know that there are local minima that we might get stuck in, depending on initialization, but it's still a worthwhile exercise.\n",
"\n",
"The first step is to define a function which approximates the gradient of the energy. We'll do this by symmetric difference, i.e., $f'(x) \\approx (f(x+\\epsilon)-f(x-\\epsilon))/(2\\epsilon)$. You should experiment with different values of $\\epsilon$ as well as different formulas for the gradient. "
]
},
{
"cell_type": "code",
"execution_count": 18,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:36.913946Z",
"iopub.status.busy": "2024-12-15T11:07:36.913339Z",
"iopub.status.idle": "2024-12-15T11:07:36.918314Z",
"shell.execute_reply": "2024-12-15T11:07:36.917735Z"
},
"id": "_Ge8sxrab6hV"
},
"outputs": [],
"source": [
"def gradient_energy(\n",
" gamma: float, beta: float, qaoa: cirq.Circuit, h: np.ndarray\n",
") -> Tuple[float, float]:\n",
" \"\"\"Uses a symmetric difference to calculate the gradient.\"\"\"\n",
" eps = 10**-3 # Try different values of the discretization parameter\n",
"\n",
" # Gamma-component of the gradient\n",
" grad_g = energy_from_params(gamma + eps, beta, qaoa, h)\n",
" grad_g -= energy_from_params(gamma - eps, beta, qaoa, h)\n",
" grad_g /= 2 * eps\n",
"\n",
" # Beta-compoonent of the gradient\n",
" grad_b = energy_from_params(gamma, beta + eps, qaoa, h)\n",
" grad_b -= energy_from_params(gamma, beta - eps, qaoa, h)\n",
" grad_b /= 2 * eps\n",
"\n",
" return grad_g, grad_b"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "xaRHKo2LDwdm"
},
"source": [
"Now we'll implement a gradient descent algorithm that minimizes the energy. Note that it will get stuck in local minima depending on the initialization."
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:36.920775Z",
"iopub.status.busy": "2024-12-15T11:07:36.920541Z",
"iopub.status.idle": "2024-12-15T11:07:40.842591Z",
"shell.execute_reply": "2024-12-15T11:07:40.841927Z"
},
"id": "BYcCDiYDB8ef"
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Step: 0 Energy: 0.35551818400921953\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Step: 25 Energy: -0.6065682037739306\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Step: 50 Energy: -0.6068782208686925\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Step: 75 Energy: -0.6068782576010108\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Step: 100 Energy: -0.6068782110887696\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Step: 125 Energy: -0.6068782176487275\n"
]
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Step: 150 Energy: -0.6068782556047962\n",
"\n",
"Learned gamma: 0.19753251184032644\n",
"Learned beta: 0.2684372230510191\n"
]
}
],
"source": [
"\"\"\"Run a simple gradient descent optimizer.\"\"\"\n",
"gamma, beta = 0.2, 0.7 # Try different initializations\n",
"eta = 10**-2 # Try adjusting the learning rate.\n",
"\n",
"# Perform gradient descent for a given number of steps.\n",
"num_steps = 150\n",
"for i in range(num_steps + 1):\n",
" # Compute the gradient.\n",
" grad_g, grad_b = gradient_energy(gamma, beta, qaoa, h)\n",
"\n",
" # Update the parameters.\n",
" gamma -= eta * grad_g\n",
" beta -= eta * grad_b\n",
"\n",
" # Status updates.\n",
" if not i % 25:\n",
" print(\"Step: {} Energy: {}\".format(i, energy_from_params(gamma, beta, qaoa, h)))\n",
"\n",
"print(\"\\nLearned gamma: {}\\nLearned beta: {}\".format(gamma, beta, qaoa, h))"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "d27161500fd6"
},
"source": [
"### Getting the approximate solutions"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "6UpLOKeso7uo"
},
"source": [
"We've optimized our parameters. How well did we do?"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "_Pv7GZX0EJdr"
},
"source": [
"For a $3\\times 3$ grid we have $9$ qubits and $12$ interacting nearest-neighbor pairs. If all of the qubits are in the $|0\\rangle$ state or all are in the $|1\\rangle$ state, then the energy-per-qubit is $-12/9 = -1.33$ at zero external magnetic field $h$, and will be close to that if the magnetic field is small. Notice that the QAOA algorithm we analyzed above is __not__ getting close to that ground state. Is this a problem?\n",
"\n",
"Well, not really. The QAOA algorithm still succeeds if we can find the ground state after a small number of measurements. The QAOA prepares a certain state which is a linear combination of the ground state and many other states. When we measure the qubits, we find the ground-state configuration with some probability. If that probability is relatively large, then after a reasonably small number of measurements we'll locate the ground state.\n",
"\n",
"Practically speaking, this means we should measure the state prepared by the QAOA several times and record the lowest-energy state we find. The QAOA can be successful by biasing these measurements toward the ground state, even if they do not produce the ground state with $100\\%$ probability."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "9epP9VB8GGgD"
},
"source": [
"Let's make a copy of our qaoa circuit for measurement purposes and attach a measurement gate to each qubit."
]
},
{
"cell_type": "code",
"execution_count": 20,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:40.845826Z",
"iopub.status.busy": "2024-12-15T11:07:40.845532Z",
"iopub.status.idle": "2024-12-15T11:07:40.869218Z",
"shell.execute_reply": "2024-12-15T11:07:40.868641Z"
},
"id": "bIoIBl-aSjKE"
},
"outputs": [
{
"data": {
"text/html": [
"
"
],
"text/plain": [
" ┌──────────────────┐ ┌──────────────────┐\n",
"(0, 0): ───H───ZZ───────ZZ───────Z^(0.5*𝛄)──────────────────────────────────────────────────────────────────────────────────────────────X^(β)───M('m')───\n",
" │ │ │\n",
"(0, 1): ───H───┼────────ZZ^(𝛄)───ZZ──────────ZZ────────Z^(0.5*𝛄)────────────────────────────────────────────────────────────────────────X^(β)───M────────\n",
" │ │ │ │\n",
"(0, 2): ───H───┼─────────────────┼───────────ZZ^(𝛄)────ZZ────────────────────Z^(0.5*𝛄)──────────────────────────────────────────────────X^(β)───M────────\n",
" │ │ │ │\n",
"(1, 0): ───H───ZZ^(𝛄)───ZZ───────┼───────────ZZ────────┼────────Z^(0.5*𝛄)───────────────────────────────────────────────────────────────X^(β)───M────────\n",
" │ │ │ │ │\n",
"(1, 1): ───H────────────┼────────ZZ^(𝛄)──────ZZ^(𝛄)────┼────────ZZ───────────ZZ───────────Z^(0.5*𝛄)─────────────────────────────────────X^(β)───M────────\n",
" │ │ │ │ │\n",
"(1, 2): ───H────────────┼──────────────────────────────ZZ^(𝛄)───┼────────────ZZ^(𝛄)───────ZZ────────────────────Z^(0.5*𝛄)───────────────X^(β)───M────────\n",
" │ │ │ │\n",
"(2, 0): ───H────────────ZZ^(𝛄)──────────────────────────────────┼────────────ZZ───────────┼────────Z^(0.5*𝛄)────────────────────────────X^(β)───M────────\n",
" │ │ │ │\n",
"(2, 1): ───H────────────────────────────────────────────────────ZZ^(𝛄)───────ZZ^(𝛄)───────┼─────────────────────ZZ──────────Z^(0.5*𝛄)───X^(β)───M────────\n",
" │ │ │\n",
"(2, 2): ───H──────────────────────────────────────────────────────────────────────────────ZZ^(𝛄)────────────────ZZ^(𝛄)──────Z^(0.5*𝛄)───X^(β)───M────────\n",
" └──────────────────┘ └──────────────────┘"
]
},
"execution_count": 20,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"\"\"\"Add measurements to the QAOA circuit.\"\"\"\n",
"measurement_circuit = qaoa.copy()\n",
"measurement_circuit.append(\n",
" cirq.measure(*[qubit for row in qubits for qubit in row], key=\"m\")\n",
")\n",
"measurement_circuit"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "_OOqzrQwGTJZ"
},
"source": [
"Now we'll measure the output of the circuit repeatedly for a good set of angles $\\gamma$ and $\\beta$. Note that these are simply found from inspecting the above heatmap of the energy found via grid search."
]
},
{
"cell_type": "code",
"execution_count": 21,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:40.871925Z",
"iopub.status.busy": "2024-12-15T11:07:40.871472Z",
"iopub.status.idle": "2024-12-15T11:07:40.888875Z",
"shell.execute_reply": "2024-12-15T11:07:40.888311Z"
},
"id": "KbIu8eyNSK_t"
},
"outputs": [],
"source": [
"\"\"\"Sample from the QAOA circuit.\"\"\"\n",
"num_reps = 1000 # Try different numbers of repetitions.\n",
"gamma_value, beta_value = 0.2, 0.25 # Try different values of the parameters.\n",
"\n",
"# Sample from the circuit.\n",
"simulator = cirq.Simulator()\n",
"params = cirq.ParamResolver({\"𝛄\": gamma_value, \"β\": beta_value})\n",
"result = simulator.run(measurement_circuit, param_resolver=params, repetitions=num_reps)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "EudMLjzNGadh"
},
"source": [
"Finally, we'll compute the energy for each of our measurement outcomes and look at the statistics. We start with a helper function which calculates the energy given a set of measurement outcomes."
]
},
{
"cell_type": "code",
"execution_count": 22,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:40.891472Z",
"iopub.status.busy": "2024-12-15T11:07:40.891243Z",
"iopub.status.idle": "2024-12-15T11:07:40.895864Z",
"shell.execute_reply": "2024-12-15T11:07:40.895191Z"
},
"id": "Oa6kAObJTZRi"
},
"outputs": [],
"source": [
"def compute_energy(meas: np.ndarray) -> float:\n",
" \"\"\"Returns the energy computed from measurements.\n",
"\n",
" Args:\n",
" meas: Measurements/samples.\n",
" \"\"\"\n",
" Z_vals = 1 - 2 * meas.reshape(n_rows, n_cols)\n",
" energy = 0\n",
" for i in range(n_rows):\n",
" for j in range(n_cols):\n",
" if i < n_rows - 1:\n",
" energy -= Z_vals[i, j] * Z_vals[i + 1, j]\n",
" if j < n_cols - 1:\n",
" energy -= Z_vals[i, j] * Z_vals[i, j + 1]\n",
" energy -= h[i, j] * Z_vals[i, j]\n",
" return energy / (n_rows * n_cols)"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "kkUl5LYnG7E7"
},
"source": [
"Now we consider the 10 most common outputs of our measurements and compute the energies of those."
]
},
{
"cell_type": "code",
"execution_count": 23,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:40.898304Z",
"iopub.status.busy": "2024-12-15T11:07:40.898091Z",
"iopub.status.idle": "2024-12-15T11:07:40.904063Z",
"shell.execute_reply": "2024-12-15T11:07:40.903556Z"
},
"id": "t2SHZj_-TTFS"
},
"outputs": [],
"source": [
"\"\"\"Compute the energies of the most common measurement results.\"\"\"\n",
"# Get a histogram of the measurement results.\n",
"hist = result.histogram(key=\"m\")\n",
"\n",
"# Consider the top 10 of them.\n",
"num = 10\n",
"\n",
"# Get the most common measurement results and their probabilities.\n",
"configs = [c for c, _ in hist.most_common(num)]\n",
"probs = [v / result.repetitions for _, v in hist.most_common(num)]"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "37ec9e5b702b"
},
"source": [
"We can now plot the probabilities of the most common measurement results as well as the energies associated with these results."
]
},
{
"cell_type": "code",
"execution_count": 24,
"metadata": {
"execution": {
"iopub.execute_input": "2024-12-15T11:07:40.906575Z",
"iopub.status.busy": "2024-12-15T11:07:40.906356Z",
"iopub.status.idle": "2024-12-15T11:07:41.135989Z",
"shell.execute_reply": "2024-12-15T11:07:41.135014Z"
},
"id": "6-jbvrc_WOgP"
},
"outputs": [
{
"data": {
"image/png": "iVBORw0KGgoAAAANSUhEUgAAAiwAAAGzCAYAAAAMr0ziAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjAsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvlHJYcgAAAAlwSFlzAAAPYQAAD2EBqD+naQAAM5NJREFUeJzt3XtcVVX+//E3FzmQCiokhKI45V2TQiHU1IpCJZNKRdNBHRur8RrleMm8ZEY3jUZMZR5TmUE6WWmZmUppFykVdMpvpWZ5KQPUChQLFfbvj36cOnKRo8hZ0uv5eJyHD9ZZe+/P2pwDb9dZe+NmWZYlAAAAg7m7ugAAAIBzIbAAAADjEVgAAIDxCCwAAMB4BBYAAGA8AgsAADAegQUAABiPwAIAAIxHYAEAAMYjsMCl3NzcNHbs2Grb34svvig3Nzdt3779nH179eqlXr162b/ev3+/3Nzc9OKLL9rbZs2aJTc3t2qrrzrk5uZqwIAB8vf3l5ubm5KTk11dEgBcdAQWlFH6S7/04e3trVatWmns2LHKzc11dXku99hjj2nVqlUuO/7999+vd999V1OnTtWyZcvUu3fvCvuuWLFCw4YNU8uWLeXm5uYQ0M5WVFSkyZMnKzg4WD4+PoqMjNSGDRuqVNOIESPk5uYmX19f/fLLL2We37t3r/319PTTT1dpn87asmWLZs2apZ9//tmp7TZt2qQ77rhDQUFB8vLyUuPGjdWvXz+9/vrrF6XO2mbNmjXq3bu3/P397T8rHnzwQR07duy893n48GHNmjVLO3furL5CK5Genk7wvwQQWFChRx55RMuWLVNKSoq6du2qRYsWKSoqSidPnnR1adVi/fr1Wr9+faV9pk+fXuYXsKsDy3vvvaf+/fvrwQcf1LBhw9SmTZsK+y5atEirV69WSEiIGjZsWOl+R4wYofnz52vo0KF69tln5eHhob59++qjjz6qUl2enp46efKk3nrrrTLPpaWlydvbu0r7OV9btmzR7NmznQosM2fO1A033KBdu3bpnnvu0eLFizVp0iSdOHFCd955p9LT0y9ewbXAgw8+qH79+iknJ0eTJ09WSkqKoqOjlZKSok6dOmn37t3ntd/Dhw9r9uzZBBY48HR1ATBXnz591LlzZ0nS3XffLX9/f82fP1+rV6/WkCFDyt2msLBQdevWrckyz5uXl9c5+3h6esrT06y3SV5enho0aFClvsuWLVOTJk3k7u6uDh06VNhv69atWr58uZ566ik9+OCDkqSEhAR16NBB//znP7Vly5ZzHstms6lbt2565ZVXNGjQIIfn0tPTFRsbq9dee61KddeElStX6pFHHtGAAQOUnp6uOnXq2J+bNGmS3n33XZ0+fdqFFZrtlVde0bx58xQfH6+0tDR5eHjYnxsxYoRuuOEGDRw4UNnZ2ca9h3BpYoYFVXbjjTdKkr799ltJv/1Qqlevnvbt26e+ffuqfv36Gjp0qKTfgssDDzygkJAQ2Ww2tW7dWk8//bQq+uPgaWlpat26tby9vRUeHq4PPvjA4fkDBw7oH//4h1q3bi0fHx/5+/tr4MCB2r9/f7n7O3nypO655x75+/vL19dXCQkJ+umnnxz6nL2GpTxnr2Fxc3NTYWGhli5dav+IY8SIEXr//ffl5uamN954o8w+0tPT5ebmpszMzEqP9c0332jgwIFq1KiRLrvsMl133XV6++237c+XflRnWZYWLlxoP35lQkJC5O5+7rf5ypUr5eHhodGjR9vbvL29NWrUKGVmZurQoUPn3Ick3XXXXXrnnXccZjm2bdumvXv36q677ip3m3ONu9SCBQvUvn17XXbZZWrYsKE6d+5snwGZNWuWJk2aJElq0aKF/dxU9PqQpIcffliNGjXS888/7xBWSsXExOjWW2+1f52Xl6dRo0YpMDBQ3t7e6tSpk5YuXeqwTek6qKeffloLFy7UX/7yF1122WW65ZZbdOjQIVmWpTlz5qhp06by8fFR//799eOPPzrsIzQ0VLfeeqs2bdqkzp07y8fHRx07dtSmTZskSa+//ro6duxof6/s2LGjTO3vvfeerr/+etWtW1cNGjRQ//799eWXXzr0KX1tf/311xoxYoQaNGggPz8/jRw5skqzqLNnz1bDhg2VmprqEFYkKSIiQpMnT9bnn3+ulStXOoxtxIgRZfb1x/fipk2b1KVLF0nSyJEj7d/L0rVlvXr1UocOHZSVlaWuXbvKx8dHLVq00OLFix32Wfp+Ofs1sGnTJrm5udnPZ69evfT222/rwIED9mOFhoba+1f2ukPNIrCgyvbt2ydJ8vf3t7edOXNGMTExaty4sZ5++mndeeedsixLt912m5555hn17t1b8+fPV+vWrTVp0iQlJiaW2e/mzZs1ceJEDRs2TI888oiOHTum3r17a9euXfY+27Zt05YtWzR48GD961//0r333quMjAz16tWr3B+uY8eO1ZdffqlZs2YpISFBaWlpiouLqzAwVdWyZctks9l0/fXXa9myZVq2bJnuuece9erVSyEhIUpLSyuzTVpamq688kpFRUVVuN/c3Fx17dpV7777rv7xj39o7ty5+vXXX3XbbbfZQ1CPHj20bNkySdLNN99sP3512LFjh1q1aiVfX1+H9oiICEmq8tT8HXfcITc3N4f1H+np6WrTpo2uvfbaMv2rMm5J+ve//63x48erXbt2Sk5O1uzZsxUWFqZPP/3UftzSWb9nnnnGfm4uv/zycuvcu3evvvrqK8XFxal+/frnHNcvv/yiXr16admyZRo6dKieeuop+fn5acSIEXr22WfL9E9LS9Nzzz2ncePG6YEHHtDmzZs1aNAgTZ8+XevWrdPkyZM1evRovfXWW/YZrT/6+uuvddddd6lfv35KSkrSTz/9pH79+iktLU3333+/hg0bptmzZ2vfvn0aNGiQSkpK7Ntu3LhRMTExysvL06xZs5SYmKgtW7aoW7du5Qa4QYMG6fjx40pKStKgQYP04osvavbs2ZWej71792r37t3q379/mddMqYSEBEm/rXFxRtu2bfXII49IkkaPHm3/Xvbo0cPe56efflLfvn0VHh6uJ598Uk2bNtV9992n559/3qljSdJDDz2ksLAwBQQE2I9V+vHQuV53qGEWcJYXXnjBkmRt3LjROnLkiHXo0CFr+fLllr+/v+Xj42N99913lmVZ1vDhwy1J1pQpUxy2X7VqlSXJevTRRx3aBwwYYLm5uVlff/21vU2SJcnavn27ve3AgQOWt7e3dfvtt9vbTp48WabOzMxMS5L10ksvlak9PDzcOnXqlL39ySeftCRZq1evtrf17NnT6tmzp/3rb7/91pJkvfDCC/a2mTNnWme/TerWrWsNHz68TD1Tp061bDab9fPPP9vb8vLyLE9PT2vmzJll+v/RxIkTLUnWhx9+aG87fvy41aJFCys0NNQqLi62t0uyxowZU+n+ytO+fXuH8Z793I033lim/f/+7/8sSdbixYsr3ffw4cOtunXrWpb12/f5pptusizLsoqLi62goCBr9uzZ9vP71FNP2ber6rj79+9vtW/fvtIannrqKUuS9e2331baz7Isa/Xq1ZYk65lnnjlnX8uyrOTkZEuS9fLLL9vbTp06ZUVFRVn16tWzCgoKLMv6/TV0+eWXO7wOpk6dakmyOnXqZJ0+fdrePmTIEMvLy8v69ddf7W3Nmze3JFlbtmyxt7377ruWJMvHx8c6cOCAvX3JkiWWJOv999+3t4WFhVmNGze2jh07Zm/73//+Z7m7u1sJCQn2ttLX9t/+9jeHsd5+++2Wv79/peej9D1+rvPn6+trXXvttQ5jK++9c/Z7cdu2bWXei3/sK8maN2+eva2oqMg+7tL3fenPgrNfD++//36ZcxYbG2s1b968zLGq8rpDzWGGBRWKjo7W5ZdfrpCQEA0ePFj16tXTG2+8oSZNmjj0u++++xy+Xrt2rTw8PDR+/HiH9gceeECWZemdd95xaI+KilJ4eLj962bNmql///569913VVxcLEny8fGxP3/69GkdO3ZMV111lRo0aKDs7OwytY8ePdphmv++++6Tp6en1q5d6+RZqLqEhAQVFRU5TIGvWLFCZ86c0bBhwyrddu3atYqIiFD37t3tbfXq1dPo0aO1f/9+ffHFFxetbum3GQSbzVamvXShbHlX/lTkrrvu0qZNm5STk6P33ntPOTk5FX4cVNVxN2jQQN999522bdvmzLAqVFBQIElVml0prTMoKMhh7VadOnU0fvx4nThxQps3b3boP3DgQPn5+dm/joyMlCQNGzbMYT1HZGSkTp06pe+//95h+3bt2jnMyJVuf+ONN6pZs2Zl2r/55htJ0g8//KCdO3dqxIgRatSokb3f1VdfrZtvvrnc1/+9997r8PX111+vY8eO2c9ReY4fPy7p3Oevfv36le7nfHl6euqee+6xf+3l5aV77rlHeXl5ysrKqrbjVPfrDheGwIIKLVy4UBs2bND777+vL774Qt98841iYmIc+nh6eqpp06YObQcOHFBwcHCZH2Zt27a1P/9HLVu2LHPsVq1a6eTJkzpy5Iik335hzpgxw74mJiAgQJdffrl+/vln5efnl9n+7H3Wq1dPV1xxRaVrGi5UmzZt1KVLF4ePhdLS0nTdddfpqquuqnTbAwcOqHXr1mXaKzpn1c3Hx0dFRUVl2n/99Vf781VVup5pxYoVSktLU5cuXSocf1XHPXnyZNWrV08RERFq2bKlxowZo48//rjKNZ2t9GOM0l+853LgwAG1bNmyzHqgir4/fwwVkuzhJSQkpNz2s9dXne/2pXVUdE6PHj2qwsLCSo9VejXZ2TX9Uel7+1zn7/jx41UOhc4IDg4us7i/VatWklSt7/Hqft3hwhBYUKGIiAhFR0erV69eatu2bbmLN202W5UWdV6ocePGae7cuRo0aJD++9//av369dqwYYP8/f0dPr93tYSEBG3evFnfffed9u3bp08++eScsysmuOKKK/TDDz+UaS9tCw4OrvK+bDab7rjjDi1dulRvvPFGhbMrzmjbtq12796t5cuXq3v37nrttdfUvXt3zZw587z2V3op+Oeff37BtZXn7EWo52q3zlpbdaHbO+N89lka1D777LMK+xw4cEAFBQVq166dva2iReKlM6nVqTqOVd2vO1wYAguqXfPmzXX48OEy//v66quv7M//0d69e8vsY8+ePbrsssvsiyZXrlyp4cOHa968eRowYIBuvvlmde/evcJ7bpy9zxMnTuiHH35wWP1/viq7Mmfw4MHy8PDQK6+8orS0NNWpU0fx8fHn3Gfz5s3LvWdFReesuoWFhWnPnj1lpu9LFxeGhYU5tb+77rpLO3bs0PHjxzV48OAK+zkz7rp16yo+Pl4vvPCCDh48qNjYWPsiXany78vZWrVqpdatW2v16tU6ceLEOfs3b95ce/fuLROOa+r7U1WldVR0TgMCAqrltgOtWrVSq1attGrVqgpnWV566SVJcrjSqmHDhuW+Z8+eoTrX9/Lw4cNlZor27NkjSfb3eOlM0dnHK2+2srLjnet1h5pDYEG169u3r4qLi5WSkuLQ/swzz8jNzU19+vRxaM/MzHRYh3Lo0CGtXr1at9xyi/1/fx4eHmX+x7dgwYIK/7eUmprqcA+NRYsW6cyZM2WOfT7q1q1bYVAKCAhQnz599PLLLystLU29e/dWQEDAOffZt29fbd261eHS58LCQqWmpio0NNThf6kXw4ABA1RcXKzU1FR7W1FRkV544QVFRkaW+SjiXG644QbNmTNHKSkpCgoKqrBfVcd99l1Tvby81K5dO1mWZf8+l/4iruqN42bPnq1jx47p7rvv1pkzZ8o8v379evsVLn379lVOTo5WrFhhf/7MmTNasGCB6tWrp549e1bpmBfbFVdcobCwMC1dutThPOzatUvr169X3759q+1YM2bM0E8//aR77723zPswKytLTzzxhDp06KA777zT3n7l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bdu2zdWl1HrffPONFi1apMTERE2bNk3btm3T+PHj5eXlpeHDh7u6vFpnypQpKigoUJs2beTh4aHi4mLNnTtXQ4cOdXVpf0oEFtRaY8aM0a5du/TRRx+5upRa69ChQ5owYYI2bNhQq/72l6lKSkrUuXNnPfbYY5Kka665Rrt27dLixYsJLBfBf//7X6WlpSk9PV3t27fXzp07NXHiRAUHB3O+XYDAcpEFBATIw8NDubm5Du25ubkKCgpyUVW139ixY7VmzRp98MEHatq0qavLqbWysrKUl5ena6+91t5WXFysDz74QCkpKSoqKpKHh4cLK6xdrrjiCrVr186hrW3btnrttddcVFHtNmnSJE2ZMkWDBw+WJHXs2FEHDhxQUlISgcUFWMNykXl5eSk8PFwZGRn2tpKSEmVkZCgqKsqFldVOlmVp7NixeuONN/Tee++pRYsWri6pVrvpppv0+eefa+fOnfZH586dNXToUO3cuZOwUs26detW5jL9PXv2qHnz5i6qqHY7efKk3N0df016eHiopKTERRX9uTHDUgMSExM1fPhwde7cWREREUpOTlZhYaFGjhzp6tJqnTFjxig9PV2rV69W/fr1lZOTI0ny8/OTj4+Pi6urferXr19mfVDdunXl7+/PuqGL4P7771fXrl312GOPadCgQdq6datSU1OVmprq6tJqpX79+mnu3Llq1qyZ2rdvrx07dmj+/Pn629/+5urS/pws1IgFCxZYzZo1s7y8vKyIiAjrk08+cXVJtZKkch8vvPCCq0v70+jZs6c1YcIEV5dRa7311ltWhw4dLJvNZrVp08ZKTU11dUm1VkFBgTVhwgSrWbNmlre3t/WXv/zFeuihh6yioiJXl/anxH1YAACA8VjDAgAAjEdgAQAAxiOwAAAA4xFYAACA8QgsAADAeAQWAABgPAILAAAwHoEFAAAYj8ACAACMR2ABAADGI7AAAADj/T/RXpqFgsTKgQAAAABJRU5ErkJggg==",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"image/png": "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448/biSZY8eOubTn5OQYb29vk5ycXOrYvw+nHTp0MPfdd59z3VtvvWW8vb3N4cOHiwScsuy3Mb/9HAtD7DPPPGMWLlxoxowZY26++WZjjDEZGRlm0qRJRpIZMmSI89js3bu3xJrr1KljGjRoUOp+/d6AAQOMJNOrVy8zf/58079/fyPJ9OjRw6VfZGSkadKkialdu7aZMGGCmT17tqlTp4655pprzCuvvGLq1atnpk+fbqZPn26CgoJMo0aNTH5+vsv7+Pr6mubNm5uhQ4ea+fPnmw4dOjg/rMPDw83DDz9s5s6da6699lpTqVIl88MPPzi3z8jIMLVq1TIBAQHm0UcfNbNmzTKtWrUy3t7eLud8YcBp06aNiY6ONrNnzzYTJkww/v7+pl27dhc8HuHh4SYqKqrUPlFRUaZu3bou+1aWgPPyyy8bh8NhbrrpJufPcvPmzS59W7Zsae68804zb948069fPyPJ5bwra8D54osvTN++fY0kM3v2bOf7nT59+oLnHSoOAg48qvBDsrjF4XA4+xX+xVW9enWTmZnpbH/77beNJPPuu+8627p06WJatmzp8q/sgoIC06FDB9O4ceMi733jjTe6BJScnBxTvXp1c8MNN5jc3Fxn+5IlS4wkl4Dz73//20gy77//vst+XXfddS79ivPWW28ZSebxxx93ae/Vq5fx8vIye/bscbbdcsst5tprry11vOKUFnCGDx9uKlWqVOy60NBQEx8fX+rYvw848+bNMwEBAebs2bPGGGN69+5tbr31VmOMKRJwyrrfs2fPNpLMTz/9VGIN27Ztu+BVm0JZWVlGkvnLX/5ywb7GGJOenm4kmcGDB7u0jxkzxkgyGzZscLZFRkYaSc4PZGP+d274+fm5BN3nnnuuyFW4wiD1+yt+//3vf42fn5/x8vIyK1ascLbv2rXL5cPaGGNGjhxpJJmPP/7Y2Xbq1ClTv359ExUV5QxThQGnWbNmJicnx9n3mWeeMZLMV199VeLxOHnyZJmO31133WUkmezsbOe+lSXgGGNM1apVnVdtiut71113ubQ/+OCDRpL54osvjDFlDzjGGDNz5kyXqzaFynLeoWLgKSpcEebPn69169a5LO+//36Rfvfcc4/LfSE33XSTJOmHH36QJGVmZmrDhg3q06ePTp06pRMnTujEiRP6+eef1bVrV33//fc6fPiw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rKVLlyohIUEtW7YsMpPxiRMn9M9//tPl3I2Pj9fYsWN19913O2fJXrBggf70pz9px44dLuNHR0frgw8+0KxZsxQeHq769es7b8qWfpuo8a677lJcXJzS0tL0yiuv6N5771WrVq2cfQYPHqzp06dr8ODBatu2rTZt2lTsZJfR0dGSpEcffVTx8fGqUqWK7rzzzjKdd6ggPPgEF1DqY+L63eOev5/o73w67/FPY36b9Kx///4mLCzMVKlSxdSpU8fccccd5vXXXy/y3iVNMjhnzhwTGRlpHA6Hadeunfn0009NdHS0iYuLK7Z/t27dijwqfCGnTp0yo0aNMuHh4aZKlSqmcePGxU54V57HxEuaAE/nPeJeaNGiRaZJkybGx8fHNGzY0MyePbvI+xenrJM0FjfRX1n2e/369eYvf/mLCQ8PNz4+PiY8PNz07dvXfPfddy5jvf3226Z58+amcuXKZX5k/LvvvjOJiYkmKirK+Pj4mICAANOxY0czd+5cl+kFcnNzzcSJE039+vVNlSpVTERERKkT/Z1Pkhk+fLhLW3HncuFEf+cr6ede3PsVTvQXHBxsfH19Tbt27Uqc6O+1114rtqayHDtjfpt4sG/fvqZ27dqmSpUqJiwszPTt27fEx8zXrl1rWrRoYXx8fEyTJk3MK6+8Uuxj4rt27TI333yz8fPzK3aiv2+//db06tXLBAQEmGrVqpmkpCSXif6MMebs2bNm0KBBJigoyAQEBJg+ffqY48ePF/v3xOTJk02dOnWMt7e385Hxsp53uPJ5GXMRd6oBV5GCggKFhobqr3/9q55//vki6++++2599dVXRe7dAXBxJkyYoIkTJ+qnn35SjRo1PF0OKgjuwQGK8euvvxZ5ouSll15SZmamOnXqVKT/0aNHtXr16jLdXAwAcD/uwQGK8dlnn2nUqFHq3bu3qlevrh07dmjx4sVq0aKFy/w2+/bt06effqp//OMfqlKlih544AEPVg0AKETAAYoRFRWliIgIzZkzR5mZmQoJCVH//v01ffp0lxlgP/roI91///2qV6+eli5dqrCwMA9WDQAodFnuwZk/f75mzpypjIwMtWrVSnPnzlW7du1K7P/aa69p3Lhx2r9/vxo3bqwZM2Y4H9mUfpuMavz48Xr++ed18uRJdezYUQsWLCgyyyUAALg6uf0enFdffVXJyckaP368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",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"Fraction of outputs displayed: 0.26\n"
]
}
],
"source": [
"\"\"\"Plot the most common measurement results and their energies.\"\"\"\n",
"# Plot probabilities of the most common bitstrings.\n",
"plt.title(\"Probability of {} Most Common Outputs\".format(num))\n",
"plt.bar([x for x in range(len(probs))], probs)\n",
"plt.show()\n",
"meas = [\n",
" [int(s) for s in \"\".join([str(b) for b in bin(k)[2:]]).zfill(n_rows * n_cols)]\n",
" for k in configs\n",
"]\n",
"costs = [compute_energy(np.array(m)) for m in meas]\n",
"\n",
"# Plot energies of the most common bitstrings.\n",
"plt.title(\"Energy of {} Most Common Outputs\".format(num))\n",
"plt.bar([x for x in range(len(costs))], costs)\n",
"plt.show()\n",
"print(\"Fraction of outputs displayed: {}\".format(np.sum(probs).round(2)))"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "4gj23-BnHEtS"
},
"source": [
"We see that, for a good choice of $\\gamma$ and $\\beta$, ground state is the most probable outcome.\n",
"\n",
"Try changing the values of $\\gamma$ and $\\beta$ away from the optimal ones. You'll see that this experiment no longer finds the ground state for us."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "aad607c31941"
},
"source": [
"### Exercise: Experiment with different numbers of layers"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "iIUkW0w4FGfa"
},
"source": [
"See if you can get a closer to the true ground state (i.e. a larger fraction of measurements yielding the minimal energy) by adding more layers to the circuit."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "a34f4a88d8d9"
},
"source": [
"### Exercise: Try a different graph and/or different interaction strengths"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "9JRyH-WDVfMp"
},
"source": [
"Instead of a square lattice, you can try to formulate the Ising model on any graph you like. This just changes which qubits you link in the $U(\\gamma, C)$ layer. Each edge of the graph could also come with a different interaction coefficient, so that instead of $\\exp(i\\pi \\gamma Z_i Z_j/2)$ for that edge you would have $\\exp(i\\pi \\gamma J_{ij} Z_i Z_j / 2)$ for some matrix $J_{ij}$ of coefficients. Note that you have to change both the $U(\\gamma, C)$ layer and the definition of the energy function to make this work."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "6a635c04373d"
},
"source": [
"### Exercise: Repeat using sampling"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "--aUfkiaUb3S"
},
"source": [
"On real hardware, we need to use sampling to estimate expectation values. Adjust your code so that sampling is used instead of wavefunction evaluation. How many samples do you need to take to get good results? Try different values."
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "9f75ef0e4437"
},
"source": [
"### Exercise: Transverse field Ising model"
]
},
{
"cell_type": "markdown",
"metadata": {
"id": "klGsAVyNtxl2"
},
"source": [
"The Ising Model with transverse field replaces the $\\sum h_i Z_i$ term with a $\\sum h_i X_i$ term. Can we use the QAOA here as well? What are the differences? This is no longer a classical problem: in general the ground state will now be a superposition of elements of the computational basis. Can you make a circuit that prepares a state close to the ground state?"
]
}
],
"metadata": {
"colab": {
"collapsed_sections": [],
"name": "qaoa_ising.ipynb",
"toc_visible": true
},
"kernelspec": {
"display_name": "Python 3",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.16"
}
},
"nbformat": 4,
"nbformat_minor": 0
}
![](\"https://quantumai.google/site-assets/images/buttons/quantumai_logo_1x.png\"){kind=logo}
View on QuantumAI\n",
" ![](\"https://quantumai.google/site-assets/images/buttons/colab_logo_1x.png\"){kind=logo}
Run in Google Colab\n",
" ![](\"https://quantumai.google/site-assets/images/buttons/github_logo_1x.png\"){kind=logo}
View source on GitHub\n",
" ![](\"https://quantumai.google/site-assets/images/buttons/download_icon_1x.png\"){kind=icon}
Download notebook\n",
"