diff --git a/docs/tutorials/grovers-algorithm.ipynb b/docs/tutorials/grovers-algorithm.ipynb index b942ad84cdb..ce5512165aa 100644 --- a/docs/tutorials/grovers-algorithm.ipynb +++ b/docs/tutorials/grovers-algorithm.ipynb @@ -2,48 +2,62 @@ "cells": [ { "cell_type": "markdown", - "id": "9857bace", + "id": "76d7b924", "metadata": {}, "source": [ "---\n", "title: Grover's algorithm\n", - "description: Learn the basics of quantum computing, and how to use IBM Quantum services and QPUs to solve real-world problems.\n", + "description: Use Grover's algorithm to search an unstructured database with a quadratic speedup.\n", "---\n", "\n", + "{/* cspell:ignore fontsize */}\n", "\n", "# Grover's algorithm\n", - "*Usage estimate: under one minute on Eagle r3 processor (NOTE: This is an estimate only. Your runtime might vary.)*" + "\n", + "*Usage estimate: under one minute on an Eagle r3 processor (NOTE: This is an estimate only. Your runtime might vary.)*" ] }, { "cell_type": "markdown", - "id": "9f72eb0a", + "id": "88aa4204", "metadata": {}, "source": [ + "## Learning outcomes\n", + "After completing this tutorial, you can expect to understand the following information:\n", + "- How to construct Grover oracles that mark one or more computational basis states\n", + "- How to use the `grover_operator()` function from the Qiskit circuit library\n", + "- How to determine the optimal number of Grover iterations for a given problem\n", + "- How to execute Grover's algorithm using the Qiskit Runtime Sampler primitive\n", + "\n", + "## Prerequisites\n", + "It is recommended that you familiarize yourself with these topics:\n", + "- [Fundamentals of quantum algorithms: Grover's algorithm](/learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/introduction)\n", + "- [Basics of quantum information](/learning/courses/basics-of-quantum-information)\n", + "\n", + "\n", "## Background\n", "\n", - "Amplitude amplification is a general purpose quantum algorithm, or subroutine, that can be used to obtain a quadratic speedup over a handful of classical algorithms. [Grover’s algorithm](https://arxiv.org/abs/quant-ph/9605043) was the first to demonstrate this speedup on unstructured search problems. Formulating a Grover's search problem requires an oracle function that marks one or more computational basis states as the states we are interested in finding, and an amplification circuit that increases the amplitude of marked states, consequently suppressing the remaining states.\n", + "Amplitude amplification is a general-purpose quantum algorithm, or subroutine, that can be used to obtain a quadratic speedup over a handful of classical algorithms. [Grover's algorithm](https://arxiv.org/abs/quant-ph/9605043) was the first to demonstrate this speedup on unstructured search problems. Formulating a Grover's search problem requires an oracle function that marks one or more computational basis states as the states we are interested in finding, and an amplification circuit that increases the amplitude of marked states, consequently suppressing the remaining states.\n", "\n", "Here, we demonstrate how to construct Grover oracles and use the [`grover_operator()`](/docs/api/qiskit/qiskit.circuit.library.grover_operator) from the Qiskit circuit library to easily set up a Grover's search instance. The runtime `Sampler` primitive allows seamless execution of Grover circuits." ] }, { "cell_type": "markdown", - "id": "152c479f", + "id": "5bbba268", "metadata": {}, "source": [ "## Requirements\n", "\n", - "Before starting this tutorial, ensure that you have the following installed:\n", + "Before starting this tutorial, be sure you have the following installed:\n", "\n", - "* Qiskit SDK v1.4 or later, with [visualization](/docs/api/qiskit/visualization) support\n", - "* Qiskit Runtime (`pip install qiskit-ibm-runtime`) v0.36 or later" + "- Qiskit SDK v2.0 or later, with [visualization](/docs/api/qiskit/visualization) support\n", + "- Qiskit Runtime v0.22 or later (`pip install qiskit-ibm-runtime`)" ] }, { - "attachments": {}, "cell_type": "markdown", - "id": "54602708", + "id": "bfccad15", "metadata": {}, "source": [ "## Setup" @@ -108,40 +122,23 @@ ] }, { - "attachments": {}, "cell_type": "markdown", - "id": "cde40906", + "id": "77e41aba", "metadata": {}, "source": [ - "## Step 1: Map classical inputs to a quantum problem\n", + "## Small-scale simulator example\n", "\n", - "Grover's algorithm requires an [oracle](/learning/courses/fundamentals-of-quantum-algorithms/grover-algorithm/introduction) that specifies one or more marked computational basis states, where \"marked\" means a state with a phase of -1. A controlled-Z gate, or its multi-controlled generalization over $N$ qubits, marks the $2^{N}-1$ state (`'1'`*$N$ bit-string). Marking basis states with one or more `'0'` in the binary representation requires applying X-gates on the corresponding qubits before and after the controlled-Z gate; equivalent to having an open-control on that qubit. In the following code, we define an oracle that does just that, marking one or more input basis states defined through their bit-string representation. The `MCMT` gate is used to implement the multi-controlled Z-gate." + "In this section, we walk through each step of Grover's algorithm at a small scale using a local simulator, before running the same problem on real quantum hardware." ] }, { - "cell_type": "code", - "execution_count": 2, - "id": "6e419a8a", + "cell_type": "markdown", + "id": "0c0fb667", "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "'ibm_brisbane'" - ] - }, - "execution_count": 2, - "metadata": {}, - "output_type": "execute_result" - } - ], "source": [ - "# To run on hardware, select the backend with the fewest number of jobs in the queue\n", - "service = QiskitRuntimeService()\n", - "backend = service.least_busy(\n", - " operational=True, simulator=False, min_num_qubits=127\n", - ")\n", - "backend.name" + "### Step 1: Map classical inputs to a quantum problem\n", + "\n", + "Grover's algorithm requires an [oracle](/learning/modules/computer-science/grovers#introduction) that specifies one or more marked computational basis states, where \"marked\" means a state with a phase of -1. A controlled-Z gate, or its multi-controlled generalization over $N$ qubits, marks the $2^{N}-1$ state (`'1'`\\*$N$ bit-string). Marking basis states with one or more `'0'` in the binary representation requires applying X-gates on the corresponding qubits before and after the controlled-Z gate, which is equivalent to having an open-control on that qubit. In the following code, we define an oracle that marks one or more input basis states defined through their bitstring representation. The `MCMT` gate is used to implement the multi-controlled Z-gate." ] }, { @@ -157,7 +154,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 2, "id": "c150298f", "metadata": {}, "outputs": [ @@ -167,55 +164,7 @@ "\"Output" ] }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "marked_states = [\"011\", \"100\"]\n", - "\n", - "oracle = grover_oracle(marked_states)\n", - "oracle.draw(output=\"mpl\", style=\"iqp\")" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "7baca7e2-99fc-4089-b5d8-30da56816a6a", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "marked_states = [\"011\", \"100\"]\n", - "\n", - "oracle = grover_oracle(marked_states)\n", - "oracle.draw(output=\"mpl\", style=\"iqp\")" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "d3a26fc9-9090-4527-a749-a412661260b6", - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "\"Output" - ] - }, - "execution_count": 5, + "execution_count": 2, "metadata": {}, "output_type": "execute_result" } @@ -240,7 +189,7 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 3, "id": "283d5265", "metadata": {}, "outputs": [ @@ -250,7 +199,7 @@ "\"Output" ] }, - "execution_count": 6, + "execution_count": 3, "metadata": {}, "output_type": "execute_result" } @@ -271,7 +220,7 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 4, "id": "f4c3d4b5", "metadata": {}, "outputs": [], @@ -295,7 +244,7 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 5, "id": "4933ae44", "metadata": {}, "outputs": [ @@ -305,7 +254,7 @@ "\"Output" ] }, - "execution_count": 8, + "execution_count": 5, "metadata": {}, "output_type": "execute_result" } @@ -323,76 +272,72 @@ }, { "cell_type": "markdown", - "id": "97eb3019", + "id": "0649c854", "metadata": {}, "source": [ - "## Step 2: Optimize problem for quantum hardware execution" + "### Step 2: Optimize problem for quantum hardware execution\n", + "\n", + "For the small-scale simulation, we transpile the circuit without targeting specific hardware." ] }, { "cell_type": "code", - "execution_count": 9, - "id": "c9a3020e", + "execution_count": 6, + "id": "c4f67f35", "metadata": {}, "outputs": [ { "data": { "text/plain": [ - "\"Output" + "\"Output" ] }, - "execution_count": 9, + "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ - "target = backend.target\n", - "pm = generate_preset_pass_manager(target=target, optimization_level=3)\n", - "\n", + "pm = generate_preset_pass_manager(optimization_level=3)\n", "circuit_isa = pm.run(qc)\n", "circuit_isa.draw(output=\"mpl\", idle_wires=False, style=\"iqp\")" ] }, { - "attachments": {}, "cell_type": "markdown", - "id": "c5edec73", + "id": "4e0d4d90", "metadata": {}, "source": [ - "## Step 3: Execute using Qiskit primitives\n", + "### Step 3: Execute using Qiskit primitives\n", "\n", - "Amplitude amplification is a sampling problem that is suitable for execution with the [`Sampler`](/docs/api/qiskit-ibm-runtime/sampler-v2) runtime primitive.\n", - "\n", - "Note that the `run()` method of [Qiskit Runtime `SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2) takes an iterable of `primitive unified blocks (PUBs)`. For Sampler, each PUB is an iterable in the format `(circuit, parameter_values)`. However, at a minimum, it takes a list of quantum circuit(s)." + "Amplitude amplification is a sampling problem that is suitable for execution with the [`SamplerV2`](/docs/api/qiskit-ibm-runtime/sampler-v2) primitive. Here we use the `StatevectorSampler` from `qiskit.primitives` for local simulation." ] }, { "cell_type": "code", - "execution_count": 10, - "id": "0eb154d4", + "execution_count": 7, + "id": "7666ad7c", "metadata": {}, "outputs": [], "source": [ - "# To run on local simulator:\n", - "# 1. Use the StatevectorSampler from qiskit.primitives instead\n", - "sampler = Sampler(mode=backend)\n", - "sampler.options.default_shots = 10_000\n", - "result = sampler.run([circuit_isa]).result()\n", + "from qiskit.primitives import StatevectorSampler\n", + "\n", + "sampler = StatevectorSampler()\n", + "result = sampler.run([circuit_isa], shots=10_000).result()\n", "dist = result[0].data.meas.get_counts()" ] }, { "cell_type": "markdown", - "id": "87484abf", + "id": "5c8263c7", "metadata": {}, "source": [ - "## Step 4: Post-process and return result in desired classical format" + "### Step 4: Post-process and return result in desired classical format" ] }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 8, "id": "a5ef9913", "metadata": {}, "outputs": [ @@ -402,25 +347,204 @@ "\"Output" ] }, - "execution_count": 11, + "execution_count": 8, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "plot_distribution(dist)" + ] + }, + { + "cell_type": "markdown", + "id": "2b45b2ee", + "metadata": {}, + "source": [ + "## Hardware example" + ] + }, + { + "cell_type": "markdown", + "id": "5fb22680", + "metadata": {}, + "source": [ + "### Steps 1-4\n", + "\n", + "Grover's algorithm is fundamentally a fault-tolerant algorithm — the multi-controlled Z gates at the heart of the oracle and diffusion operator lead to two-qubit gate depths that grow very rapidly with the number of qubits (as we will show in the next section). This means the algorithm does not scale well on today's noisy hardware. For this reason, we demonstrate the hardware execution at the same small scale as the simulator example above, rather than attempting a larger problem size." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "be3c3d9e", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ + "# -------------------------Step 1-------------------------\n", + "marked_states = [\"011\", \"100\"]\n", + "\n", + "oracle = grover_oracle(marked_states)\n", + "grover_op = grover_operator(oracle)\n", + "\n", + "optimal_num_iterations = math.floor(\n", + " math.pi\n", + " / (4 * math.asin(math.sqrt(len(marked_states) / 2**grover_op.num_qubits)))\n", + ")\n", + "\n", + "qc = QuantumCircuit(grover_op.num_qubits)\n", + "qc.h(range(grover_op.num_qubits))\n", + "qc.compose(grover_op.power(optimal_num_iterations), inplace=True)\n", + "qc.measure_all()\n", + "\n", + "# -------------------------Step 2-------------------------\n", + "service = QiskitRuntimeService()\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=127\n", + ")\n", + "\n", + "target = backend.target\n", + "pm = generate_preset_pass_manager(target=target, optimization_level=3)\n", + "circuit_isa = pm.run(qc)\n", + "\n", + "# -------------------------Step 3-------------------------\n", + "sampler = Sampler(mode=backend)\n", + "sampler.options.default_shots = 10_000\n", + "sampler.options.environment.job_tags = [\"TUT-GA\"]\n", + "result = sampler.run([circuit_isa]).result()\n", + "dist = result[0].data.meas.get_counts()\n", + "\n", + "# -------------------------Step 4-------------------------\n", "plot_distribution(dist)" ] }, { "cell_type": "markdown", - "id": "2bdde144", + "id": "12e72eab", "metadata": {}, "source": [ - "## Tutorial survey\n", + "## Discussion: Two-qubit gate depth scaling\n", "\n", - "Please take this short survey to provide feedback on this tutorial. Your insights will help us improve our content offerings and user experience.\n", + "A key reason Grover's algorithm is considered a fault-tolerant algorithm is the rapid growth of the circuit's two-qubit gate depth as the number of qubits increases. The multi-controlled Z gate at the core of both the oracle and the diffusion operator decomposes into a number of two-qubit gates that grows exponentially with the number of control qubits. Combined with the fact that the optimal number of Grover iterations itself grows as $O(\\sqrt{2^n})$, the overall two-qubit depth quickly becomes impractical for noisy hardware.\n", "\n", - "[Link to survey](https://your.feedback.ibm.com/jfe/form/SV_0j1SlLPkooyeFJY)" + "Below, we construct Grover circuits for increasing qubit counts, transpile them, and plot the resulting two-qubit gate depth to illustrate this scaling." + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "abc6b43c", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "n=3: optimal_iters=2, 2Q depth=39\n", + "n=4: optimal_iters=3, 2Q depth=111\n", + "n=5: optimal_iters=4, 2Q depth=466\n", + "n=6: optimal_iters=6, 2Q depth=1646\n", + "n=7: optimal_iters=8, 2Q depth=3550\n", + "n=8: optimal_iters=12, 2Q depth=7989\n", + "n=9: optimal_iters=17, 2Q depth=14824\n" + ] + }, + { + "data": { + "text/plain": [ + "\"Output" + ] + }, + "metadata": {}, + "output_type": "display_data" + } + ], + "source": [ + "import matplotlib.pyplot as plt\n", + "\n", + "num_qubits_list = list(range(3, 10))\n", + "two_q_depths = []\n", + "backend = service.least_busy(\n", + " operational=True, simulator=False, min_num_qubits=127\n", + ")\n", + "for n in num_qubits_list:\n", + " # Mark a single state for simplicity\n", + " marked = [\"1\" * n]\n", + " oracle_n = grover_oracle(marked)\n", + " grover_op_n = grover_operator(oracle_n)\n", + "\n", + " # Optimal number of iterations\n", + " num_iters = math.floor(\n", + " math.pi / (4 * math.asin(math.sqrt(len(marked) / 2**n)))\n", + " )\n", + "\n", + " # Build the full Grover circuit\n", + " qc_n = QuantumCircuit(n)\n", + " qc_n.h(range(n))\n", + " qc_n.compose(grover_op_n.power(num_iters), inplace=True)\n", + " qc_n.measure_all()\n", + "\n", + " # Transpile to a basis gate set and count 2Q depth\n", + " pm_n = generate_preset_pass_manager(backend=backend, optimization_level=3)\n", + " qc_transpiled = pm_n.run(qc_n)\n", + "\n", + " # Compute depth restricted to 2-qubit operations\n", + " depth_2q = qc_transpiled.depth(lambda x: x.operation.num_qubits == 2)\n", + "\n", + " two_q_depths.append(depth_2q)\n", + " print(f\"n={n}: optimal_iters={num_iters}, 2Q depth={depth_2q}\")\n", + "\n", + "# Plot\n", + "fig, ax = plt.subplots(figsize=(8, 5))\n", + "ax.plot(\n", + " num_qubits_list,\n", + " two_q_depths,\n", + " \"o-\",\n", + " linewidth=2,\n", + " markersize=8,\n", + " color=\"#6929C4\",\n", + ")\n", + "ax.set_xlabel(\"Number of qubits\", fontsize=13)\n", + "ax.set_ylabel(\"Two-qubit gate depth\", fontsize=13)\n", + "ax.set_title(\"Grover's algorithm: 2Q depth scaling\", fontsize=14)\n", + "ax.set_yscale(\"log\")\n", + "ax.grid(True, alpha=0.3)\n", + "ax.set_xticks(num_qubits_list)\n", + "plt.tight_layout()\n", + "plt.show()" + ] + }, + { + "cell_type": "markdown", + "id": "f3ddda55", + "metadata": {}, + "source": [ + "As the plot shows, the two-qubit gate depth grows extremely rapidly with the number of qubits — roughly exponentially. This makes Grover's algorithm impractical on current noisy quantum hardware beyond very small problem sizes. The algorithm remains an important target for future fault-tolerant quantum computers, where error correction will allow deep circuits to be executed reliably." + ] + }, + { + "cell_type": "markdown", + "id": "cf6e8fe6", + "metadata": {}, + "source": [ + "## Next steps\n", + "\n", + "If you found this work interesting, you might be interested in the following material:\n", + "- [Qiskit circuit library: `grover_operator()` API reference](/docs/api/qiskit/qiskit.circuit.library.grover_operator)\n", + "- The [QAOA tutorial](/docs/tutorials/quantum-approximate-optimization-algorithm) and [utility-scale QAOA lesson](/learning/courses/quantum-computing-in-practice/utility-scale-qaoa) give near-term examples of optimization with quantum computers\n", + "- For a more in-depth look at near-term algorithms, see the [Quantum computing in practice](/learning/courses/quantum-computing-in-practice) course\n", + "" ] } ], diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/283d5265-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/283d5265-0.avif index 34516152c85..94446db4103 100644 Binary files a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/283d5265-0.avif and b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/283d5265-0.avif differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/4933ae44-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/4933ae44-0.avif index da4ba560e1b..e77dacf5cf2 100644 Binary files a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/4933ae44-0.avif and b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/4933ae44-0.avif differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/7baca7e2-99fc-4089-b5d8-30da56816a6a-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/7baca7e2-99fc-4089-b5d8-30da56816a6a-0.avif deleted file mode 100644 index 3a9a2cb9232..00000000000 Binary files a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/7baca7e2-99fc-4089-b5d8-30da56816a6a-0.avif and /dev/null differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/a5ef9913-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/a5ef9913-0.avif index 3a528ebb281..d8dd93b4f14 100644 Binary files a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/a5ef9913-0.avif and b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/a5ef9913-0.avif differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/abc6b43c-1.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/abc6b43c-1.avif new file mode 100644 index 00000000000..84c90a1b1fa Binary files /dev/null and b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/abc6b43c-1.avif differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/be3c3d9e-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/be3c3d9e-0.avif new file mode 100644 index 00000000000..3d73640bedb Binary files /dev/null and b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/be3c3d9e-0.avif differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c150298f-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c150298f-0.avif index 3a9a2cb9232..822b6efc65c 100644 Binary files a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c150298f-0.avif and b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c150298f-0.avif differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c4f67f35-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c4f67f35-0.avif new file mode 100644 index 00000000000..e77dacf5cf2 Binary files /dev/null and b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c4f67f35-0.avif differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c9a3020e-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c9a3020e-0.avif deleted file mode 100644 index 797e3822440..00000000000 Binary files a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/c9a3020e-0.avif and /dev/null differ diff --git a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/d3a26fc9-9090-4527-a749-a412661260b6-0.avif b/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/d3a26fc9-9090-4527-a749-a412661260b6-0.avif deleted file mode 100644 index 3a9a2cb9232..00000000000 Binary files a/public/docs/images/tutorials/grovers-algorithm/extracted-outputs/d3a26fc9-9090-4527-a749-a412661260b6-0.avif and /dev/null differ