qcr:2606.69363.1

Grover's Algorithm: Worked Examples with Qiskit

This Qiskit tutorial is a collection of worked examples that show Grover's algorithm and amplitude amplification applied to concrete problems, complementing the introductory Grover tutorial with hands-on use cases. Grover's algorithm finds items satisfying an oracle in an unstructured search space with a quadratic speedup, and the power of the framework lies in how flexibly the oracle and search problem can be expressed. The notebook works through several examples: encoding boolean satisfiability-style conditions as logical-expression oracles, searching for bitstrings that meet arithmetic or combinatorial criteria, and handling cases with multiple marked solutions where the number of Grover iterations must be adjusted accordingly. For each example it constructs the oracle, builds the amplification problem, runs Grover through the Qiskit algorithms library and the Sampler primitive, and verifies that the measured results are the intended solutions. It also illustrates practical considerations such as estimating the number of solutions and the trade-off between iterations and success probability. By moving from theory to a variety of applied cases, the tutorial helps users map their own search problems onto Grover's algorithm in Qiskit. It is a practical, example-driven companion for applying quantum search.

Optimization

Qubit

Circuit-based

Uploaded 4 months ago

156

Views

GitHub

195

Citing this entry? Use this QCR ID

Uploaded by

QCR Librarian

qiskit-community/qiskit-algorithms

195

In [ ]:

# --- Setup cell added by QCR (not part of the original tutorial) ---
# Source: qiskit-community/qiskit-algorithms @ 0.4.0, Apache License 2.0.
# Installs the example's dependencies. If a later cell still reports a missing
# package, restart the runtime/kernel and run again from the top.
%pip install -q qiskit-algorithms==0.4.0 qiskit-aer qiskit-algorithms

Grover's algorithm examples

This notebook has examples demonstrating how to use the Qiskit Algorithms Grover search algorithm, with different oracles.

We strongly recommend to run this tutorial using Qiskit 2.0 or newer. Though the use of `PhaseOracle` is possible in Qiskit < 2.0, it requires the `tweedledum` library, which has been deprecated for a long time and isn't compatible with the most recent versions of Python.

This tutorial instead use the more recent PhaseOracleGate that has been introduced in Qiskit 2.1. Note that both are valid inputs for the oracle argument of the Grover class.

Finding solutions to 3-SAT problems

Let's look at an example 3-Satisfiability (3-SAT) problem and walk-through how we can use Quantum Search to find its satisfying solutions. 3-SAT problems are usually expressed in Conjunctive Normal Forms (CNF) and written in the DIMACS-CNF format. For example:

In [1]:

input_3sat_instance = """
c example DIMACS-CNF 3-SAT
p cnf 3 5
-1 -2 -3 0
1 -2 3 0
1 2 -3 0
1 -2 -3 0
-1 2 3 0
"""

The CNF of this 3-SAT instance contains 3 variables and 5 clauses:

It can be verified that this 3-SAT problem instance has three satisfying solutions:

or or

Or, expressed using the DIMACS notation:

1 -2 3, or -1 -2 -3, or 1 2 -3.

With this example problem input, we then create the corresponding oracle for our Grover search. In particular, we use the PhaseOracle component, which supports parsing DIMACS-CNF format strings and constructing the corresponding oracle circuit. Note that the PhaseOracle requires the tweedledum library if you use Qiskit in a lower version than 2.0.

In [2]:

from qiskit.exceptions import MissingOptionalLibraryError
from qiskit.circuit.library.phase_oracle import PhaseOracleGate
from qiskit.synthesis.boolean.boolean_expression import BooleanExpression

oracle = None
try:
    oracle = PhaseOracleGate(BooleanExpression.from_dimacs(input_3sat_instance).expression)
except ImportError as ex:
    print(ex)

The oracle can now be used to create a Grover instance:

In [3]:

from qiskit_algorithms import AmplificationProblem

problem = None
if oracle is not None:
    problem = AmplificationProblem(oracle)

We can then configure the backend and run the Grover instance to get the result:

In [4]:

from qiskit_algorithms import Grover
from qiskit.primitives import StatevectorSampler

grover = Grover(sampler=StatevectorSampler())
result = None
if problem is not None:
    result = grover.amplify(problem)
    print(result.assignment)

As seen above, a satisfying solution to the specified 3-SAT problem is obtained. And it is indeed one of the three satisfying solutions.

Since we used the StatevectorSampler, the complete measurement result is also returned, as shown in the plot below, where it can be seen that the binary strings 000, 011, and 101 (note the bit order in each string), corresponding to the three satisfying solutions all have high probabilities associated with them.

In [5]:

from qiskit.visualization import plot_histogram

if result is not None:
    display(plot_histogram(result.circuit_results[0]))

Boolean Logical Expressions

Qiskit's Grover can also be used to perform Quantum Search on an Oracle constructed from other means, in addition to DIMACS. For example, the PhaseOracle can actually be configured using arbitrary Boolean logical expressions, as demonstrated below.

In [6]:

expression = "(w ^ x) & ~(y ^ z) & (x & y & z)"
try:
    oracle = PhaseOracleGate(expression)
    problem = AmplificationProblem(oracle)
    grover = Grover(sampler=StatevectorSampler())
    result = grover.amplify(problem)
    display(plot_histogram(result.circuit_results[0]))
except MissingOptionalLibraryError as ex:
    print(ex)

In the example above, the input Boolean logical expression '(w ^ x) & ~(y ^ z) & (x & y & z)' should be quite self-explanatory, where ^, ~, and & represent the Boolean logical XOR, NOT, and AND operators, respectively. It should be quite easy to figure out the satisfying solution by examining its parts: w ^ x calls for w and x taking different values; ~(y ^ z) requires y and z be the same; x & y & z dictates all three to be True. Putting these together, we get the satisfying solution (w, x, y, z) = (False, True, True, True), which our Grover's result agrees with.

In [7]:

import tutorial_magics

%qiskit_version_table
%qiskit_copyright

Version Information

Software	Version
`qiskit`	2.0.3
`qiskit_algorithms`	0.4.0
System information
Python version	3.13.5
OS	Linux
Thu Aug 07 00:26:23 2025 CEST

This code is a part of a Qiskit project

This code is licensed under the Apache License, Version 2.0. You may
obtain a copy of this license in the LICENSE.txt file in the root directory
of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.

Any modifications or derivative works of this code must retain this
copyright notice, and modified files need to carry a notice indicating
that they have been altered from the originals.

Join the Discussion

Comments (0)

No comments yet. Be the first to share your thoughts!

Indexed by QCR Librarian

This entry was created automatically from publicly available records. QCR links to public sources and only stores repository content where the license permits redistribution.

Claim this entry →

Versions

v1 Latest

Jun 16, 2026

qcr:2606.69363.1

Cite all versions? Use the base QCR ID to always reference the latest version of this entry.

Tools used

Qiskit

Keywords

grover

oracle

qiskit

examples