diff --git a/docs/tutorials/advanced-techniques-for-qaoa.ipynb b/docs/tutorials/advanced-techniques-for-qaoa.ipynb index 3c62a7d241c..6bfea4cde71 100644 --- a/docs/tutorials/advanced-techniques-for-qaoa.ipynb +++ b/docs/tutorials/advanced-techniques-for-qaoa.ipynb @@ -9,15 +9,29 @@ "title: Advanced techniques for QAOA\n", "description: This notebook introduces advanced techniques to improve the performance of the Quantum Approximate Optimization Algorithm (QAOA) with a large number of qubits.\n", "---\n", - "\n", - "\n", - "{/* cspell:ignore setminus pysat lbrack IEICE frameon */}\n", + "{/* cspell:ignore pysat, lbrack, frameon, IEICE */}\n", "\n", "# Advanced techniques for QAOA\n", "\n", "*Usage estimate: 3 minutes on a Heron r2 processor (NOTE: This is an estimate only. Your runtime may vary.)*" ] }, + { + "cell_type": "markdown", + "id": "1a6bbeef-966f-45e1-89aa-e964ef891eeb", + "metadata": {}, + "source": [ + "## Prerequisites and learning outcomes\n", + "\n", + "We suggest that users are familiar with the following topics before going through this tutorial.\n", + "* The basics of the Quantum Approximate Optimization Algorithm (QAOA). See [Solve utility-scale quantum optimization problems](/docs/tutorials/quantum-approximate-optimization-algorithm) and this lesson on [Utility-scale QAOA](/learning/courses/quantum-computing-in-practice/utility-scale-qaoa#utility-scale-qaoa) for an introduction to QAOA.\n", + "\n", + "After going through this tutorial, users should be able to:\n", + "* Utilize advanced techniques to extract the best performance from large scale QAOA circuits\n", + "\n", + "For a detailed walk-through of the contents of this tutorial, see this [Qiskit video](https://youtu.be/rBfK-l-qSNk?si=PC28gFAdu4JYSYdk)." + ] + }, { "cell_type": "markdown", "id": "ea97567d-810f-4cca-8edf-a47d70ea870a", @@ -25,14 +39,16 @@ "source": [ "## Background\n", "\n", - "This notebook introduces advanced techniques to improve the performance of the **Quantum Approximate Optimization Algorithm (QAOA)** with a large number of qubits.\n", - "See the [Solve utility-scale quantum optimization problems](/docs/tutorials/quantum-approximate-optimization-algorithm) tutorial for an introduction to QAOA.\n", + "This tutorial introduces two advanced techniques to improve the performance of the **Quantum Approximate Optimization Algorithm (QAOA)** at a large number of qubits.\n", + "\n", "\n", "The advanced techniques in this notebook include:\n", "\n", - "* **SWAP strategy with SAT initial mapping**: This is a specifically designed transpiler pass for QAOA that uses a SWAP strategy and a SAT solver together to improve the selection of which physical qubits on the QPU to use. The SWAP strategy exploits the commutativity of the QAOA operators to reorder gates so that layers of SWAP gates can be simultaneously executed, thus reducing the depth of the circuit [\\[1\\]](#references). The SAT solver is used to find an initial mapping that minimizes the number of SWAP operations needed to map the qubits in the circuit to the physical qubits on the device [\\[2\\]](#references) .\n", - "* **CVaR cost function**: Typically the expected value of the cost Hamiltonian is used as the cost function for QAOA, but as was shown in [\\[3\\]](#references) , focusing on the tail of the distribution, rather than the expected value, can improve the performance of QAOA for combinatorial optimization problems. The CVaR accomplishes this. For a given set of shots with corresponding objective values of the considered optimization problem, the Conditional Value at Risk (CVaR) with confidence level $\\alpha \\in [0, 1]$ is defined as the average of the $\\alpha$ best shots [\\[3\\]](#references).\n", - "Thus, $\\alpha = 1$ corresponds to the standard expected value, while $\\alpha=0$ corresponds to the minimum of the given shots, and $\\alpha \\in (0, 1)$ is a tradeoff between focusing on better shots, while still applying some averaging to smooth out the optimization landscape. Additionally, the CVaR can be used as an error mitigation technique to improve the quality of the objective value estimation [\\[4\\]](#references)." + "* **SWAP strategy with SAT initial mapping**: This is a specifically designed transpiler pass for QAOA that uses a SWAP strategy and a SAT solver together to improve the selection of which physical qubits on the QPU to use. The SWAP strategy exploits the commutativity of the QAOA operators to reorder gates so that layers of SWAP gates can be simultaneously executed, thus reducing the depth of the circuit [\\[1\\]](#references). The SAT solver is used to find an initial mapping that minimizes the number of SWAP operations needed to map the qubits in the circuit to the physical qubits on the device [\\[2\\]](#references).\n", + "* **CVaR cost function**: Typically the expected value of the cost Hamiltonian is used as the cost function for QAOA, but as was shown in [\\[3\\]](#references), focusing on the tail of the distribution, rather than the expected value, can improve the performance of QAOA for combinatorial optimization problems. The CVaR accomplishes this. For a given set of shots with corresponding objective values of the considered optimization problem, the Conditional Value at Risk (CVaR) with confidence level $\\alpha \\in [0, 1]$ is defined as the average of the $\\alpha$ best shots [\\[3\\]](#references).\n", + "Thus, $\\alpha = 1$ corresponds to the standard expected value, while $\\alpha=0$ corresponds to the minimum of the given shots, and $\\alpha \\in (0, 1)$ is a tradeoff between focusing on better shots, while still applying some averaging to smooth out the optimization landscape. Additionally, the CVaR can be used as an error mitigation technique to improve the quality of the objective value estimation [\\[4\\]](#references).\n", + "\n", + "By the end of this tutorial, you should be able to use these techniques to get the best results from running QAOA for your optimization problems." ] }, { @@ -105,16 +121,34 @@ "In this example, we use a graph with 100 nodes that is based on a hardware coupling map." ] }, + { + "cell_type": "markdown", + "id": "663d13f5-a5f7-4b67-a89b-26deb41224ec", + "metadata": {}, + "source": [ + "## Small-scale simulator example\n", + "\n", + "Since the goal of this tutorial is to show how QAOA performs at scales beyond what a simulator can handle, we will forgo this step." + ] + }, + { + "cell_type": "markdown", + "id": "6ca05a7c-5fde-4485-a3ad-c0ba02844e50", + "metadata": {}, + "source": [ + "## Large-scale hardware example" + ] + }, { "cell_type": "markdown", "id": "b825afbf-10fd-4926-bd65-05272044f107", "metadata": {}, "source": [ - "## Step 1: Map classical inputs to a quantum problem\n", + "### Step 1: Map classical inputs to a quantum problem\n", "\n", - "### Graph → Hamiltonian\n", + "#### Graph → Hamiltonian\n", "\n", - "First, map the problem onto a quantum circuit that is suited for the QAOA. Details on this process can be found in the [introductory QAOA tutorial.](/docs/tutorials/quantum-approximate-optimization-algorithm)" + "First, let's map the problem onto a quantum circuit that is suited for the QAOA. Details on this process can be found in the [introductory QAOA tutorial](/docs/tutorials/quantum-approximate-optimization-algorithm)." ] }, { @@ -142,7 +176,7 @@ }, { "cell_type": "code", - "execution_count": 96, + "execution_count": null, "id": "e04ce982-8294-4ebe-8dcc-f74205938800", "metadata": {}, "outputs": [ @@ -158,12 +192,15 @@ } ], "source": [ + "# Check if the coupling map is symmetric. We will add a conditional below\n", + "# to avoid over-counting edges for symmetric/bi-directional coupling maps.\n", + "\n", "backend.coupling_map.is_symmetric" ] }, { "cell_type": "code", - "execution_count": 97, + "execution_count": null, "id": "8b864d32-9483-45ea-831f-60488e330adb", "metadata": {}, "outputs": [ @@ -186,7 +223,12 @@ "\n", "for edge in backend.coupling_map:\n", " if (edge[0] < n) and (edge[1] < n):\n", - " if (edge[1], edge[0], w) not in elist:\n", + " # Conditional to avoid over-counting edges\n", + " if (\n", + " edge[1],\n", + " edge[0],\n", + " w,\n", + " ) not in elist:\n", " elist.append((edge[0], edge[1], w))\n", "\n", "graph_100.add_edges_from(elist)\n", @@ -252,9 +294,9 @@ "id": "4e576068-53e7-4a06-a83b-87e95de141e9", "metadata": {}, "source": [ - "## Step 2: Optimize problem for quantum hardware execution\n", + "### Step 2: Optimize problem for quantum hardware execution\n", "\n", - "### SWAP strategy with the SAT initial mapping\n", + "#### SWAP strategy with the SAT initial mapping\n", "\n", "We will demonstrate how to build and optimize QAOA circuits using the **SWAP strategy with SAT initial mapping**, a specifically designed transpiler pass for QAOA applied to quadratic problems.\n", "\n", @@ -299,7 +341,7 @@ "source": [ "#### Remap the graph using a SAT mapper\n", "\n", - "Even when a circuit consists of commuting gates (this is the case for the QAOA circuit, but also for Trotterized simulations of Ising Hamiltonians), finding a good initial mapping is a challenging task. The SAT-based approach presented in [\\[2\\]](#references) enables the discovery of effective initial mappings for circuits with commuting gates, resulting in a significant reduction in the number of required SWAP layers. This approach has been demonstrated to scale to up to *500 qubits*, as illustrated in the paper.\n", + "Even when a circuit consists of commuting gates (this is the case for the QAOA circuit, but also for Trotterized simulations of Ising Hamiltonians), finding a good initial mapping is a challenging task. When we use the SAT-based approach presented in [\\[2\\]](#references), we can discover effective initial mappings for circuits with commuting gates, resulting in a significant reduction in the number of required SWAP layers. This approach has been demonstrated to scale to up to *500 qubits*, as illustrated in the paper.\n", "\n", "The following code demonstrates how to use the `SATMapper` from Matsuo et al. to remap the graph. This process allows the problem to be mapped to a more optimal initial state for a specified SWAP strategy, resulting in a significant reduction in the number of SWAP layers required to execute the circuit.\n", "\n", @@ -608,7 +650,7 @@ "We only want to apply the SWAP strategies to the cost operator layer, so we start by creating the isolated block that we will later transform and append to the final QAOA circuit.\n", "\n", "For this, we can use the [`QAOAAnsatz`](/docs/api/qiskit/qiskit.circuit.library.QAOAAnsatz) class from Qiskit. We input an empty circuit to the `initial_state` and `mixer_operator` fields to make sure we are building an isolated cost operator layer.\n", - "We also define the edge_coloring map so that RZZ gates are positioned next to SWAP gates. This strategic placement allows us to exploit CX cancellations, optimizing the circuit for better performance.\n", + "We also define the `edge_coloring` map so that RZZ gates are positioned next to SWAP gates. This strategic placement allows us to exploit CX cancellations, optimizing the circuit for better performance.\n", "This process is executed within the `create_qaoa_swap_circuit` function." ] }, @@ -813,14 +855,6 @@ "id": "82ae28b3-85eb-4487-8100-1e622e93cccf", "metadata": {}, "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "/Users/mirko/Workspace/documentation/.venv/lib/python3.13/site-packages/qiskit/circuit/quantumcircuit.py:4625: UserWarning: Trying to add QuantumRegister to a QuantumCircuit having a layout\n", - " circ.add_register(qreg)\n" - ] - }, { "data": { "text/plain": [ @@ -847,11 +881,9 @@ "id": "e2afd1a7-0980-433b-a3a8-303d7e7718b1", "metadata": {}, "source": [ - "## Step 3: Execute using Qiskit primitives\n", - "\n", - "### Define a CVaR cost function\n", + "## Step 3: Execute using Qiskit Runtime primitives\n", "\n", - "This example shows how to use the Conditional Value at Risk (CVaR) cost function introduced in [\\[3\\]](#references) within the variational quantum optimization algorithms.\n", + "Let's now prepare for hardware execution. Our first step will be to define a Conditional Value at Risk (CVaR) cost function, which was introduced in [\\[3\\]](#references) for use within the paradigm of variational quantum optimization algorithms.\n", "\n", "The CVaR of a random variable $X$ for a confidence level $α ∈ (0, 1]$ is defined as\n", "$CVaR_{\\alpha}(X) = \\mathbb{E} \\lbrack X | X \\leq F_X^{-1}(\\alpha) \\rbrack$\n", @@ -1026,7 +1058,7 @@ "id": "63fa2ab4-5354-4022-ab46-e9bbf73870de", "metadata": {}, "source": [ - "The CVaR can be used as an error mitigation technique as previously discussed [\\[4\\]](#references). In this example, we determine $\\alpha$ and the number of shots according to the circuit's error rate." + "The CVaR can be used as an error mitigation technique as previously discussed [\\[4\\]](#references). In this example, we determine $\\alpha$ and the number of shots according to the [error per layered gate](/docs/guides/qpu-information#2q-error-layered) (EPLG) associated with the circuit." ] }, { @@ -1073,7 +1105,7 @@ }, { "cell_type": "code", - "execution_count": 110, + "execution_count": null, "id": "382e8acd-d0d0-4302-99aa-b64e5dd31e17", "metadata": {}, "outputs": [ @@ -1127,6 +1159,9 @@ " sampler.options.dynamical_decoupling.sequence_type = \"XY4\"\n", " sampler.options.twirling.enable_gates = True\n", " sampler.options.twirling.enable_measure = True\n", + " sampler.options.environment.job_tags = [\n", + " \"TUT_AQAOA\"\n", + " ] # add tag for your job execution\n", "\n", " result = minimize(\n", " qaoa_sampler_cost_fun,\n", @@ -1148,7 +1183,9 @@ "id": "1d190fa4-3bbe-412a-b296-6dddd3ad2b12", "metadata": {}, "source": [ - "## Step 4: Post-process and return result in desired classical format" + "## Step 4: Post-process and return result in desired classical format\n", + "\n", + "Let's now visualize our results and then post-process them to find the value of the cut." ] }, { @@ -1190,12 +1227,12 @@ "id": "38aadfcb-aec9-4dbb-a9d3-319239eae196", "metadata": {}, "source": [ - "The following retrieves the best solution from the sampled bitstrings" + "The following retrieves the best solution from the sampled bitstrings:" ] }, { "cell_type": "code", - "execution_count": 112, + "execution_count": null, "id": "7e8af29e-c99b-41f2-b6dd-2be471e1af21", "metadata": {}, "outputs": [ @@ -1208,7 +1245,7 @@ } ], "source": [ - "# sort the result_dict[iter_counts]['evaluated'] by the CVaR value\n", + "# Sort the result_dict[iter_counts]['evaluated'] by the CVaR value\n", "sorted_result_dict = [\n", " (k, v)\n", " for k, v in sorted(\n", @@ -1229,10 +1266,10 @@ "Consider the Hamiltonian $H_C$ for the **Max-Cut** problem. Let each vertex of the graph be associated with a qubit in state $|0\\rangle$ or $|1\\rangle$, where the value denotes the set the vertex is in. The goal of the problem is to maximize the number of edges $(v_1, v_2)$ for which $v_1 = |0\\rangle$ and $v_2 = |1\\rangle$, or vice versa. If we associate the $Z$ operator with each qubit, where\n", "\n", "$$\n", - " Z|0\\rangle = |0\\rangle \\qquad Z|1\\rangle = -|1\\rangle\n", + " Z|0\\rangle = |0\\rangle \\qquad Z|1\\rangle = -|1\\rangle,\n", "$$\n", "\n", - "then an edge $(v_1, v_2)$ belongs to the cut if the eigenvalue of $(Z_1|v_1\\rangle) \\cdot (Z_2|v_2\\rangle) = -1$; in other words, the qubits associated with $v_1$ and $v_2$ are different. Similarly, $(v_1, v_2)$ does not belong to the cut if the eigenvalue of $(Z_1|v_1\\rangle) \\cdot (Z_2|v_2\\rangle) = 1$" + "then an edge $(v_1, v_2)$ belongs to the cut if the eigenvalue of $(Z_1|v_1\\rangle) \\cdot (Z_2|v_2\\rangle) = -1$; in other words, the qubits associated with $v_1$ and $v_2$ are different. Similarly, $(v_1, v_2)$ does not belong to the cut if the eigenvalue of $(Z_1|v_1\\rangle) \\cdot (Z_2|v_2\\rangle) = 1$." ] }, { @@ -1346,14 +1383,18 @@ }, { "cell_type": "markdown", - "id": "c048cd84-d6e8-4b8a-926e-a7f7724a86e2", + "id": "a6a5bbfe-a159-4dc1-9333-488737aff503", "metadata": {}, "source": [ - "## Tutorial survey\n", + "## Next steps\n", + "\n", + "\n", "\n", - "Please take one minute to provide feedback on this tutorial. Your insights will help us improve our content offerings and user experience.\n", + "If you found this work interesting, you might be interested in the following material:\n", "\n", - "[Link to survey](https://your.feedback.ibm.com/jfe/form/SV_cZwpScxyXVDpIeq)" + "* [The intractable decathlon](https://arxiv.org/pdf/2504.03832): a listing of 10 optimization problems that are difficult for classical optimization algorithms, and which may be good use cases to test the techniques introduced in this tutorial.\n", + "* [A repo of best practices for quantum optimization](https://github.com/qiskit-community/qopt-best-practices) to further improve the results of your QAOA-based workflow.\n", + "" ] } ], diff --git a/scripts/config/cspell/dictionaries/qiskit.txt b/scripts/config/cspell/dictionaries/qiskit.txt index 10edc429a19..c4681380c12 100644 --- a/scripts/config/cspell/dictionaries/qiskit.txt +++ b/scripts/config/cspell/dictionaries/qiskit.txt @@ -425,6 +425,7 @@ cidx rbrack bitorder cvar +setminus qudits qutrits quasiprobabilities