Grover's Algorithm

Important

This repository has accompanying blog posts on my blog!

• Quantum Search Algorithm: Short, Twitter/X-inspired thread format
• Quantum Search Algorithm (Full): Full explanation with additional details

These blog posts are much more readable and user-friendly than this repository by itself and GitHub. If you're interested in sharing or reading this repository as a blog post, please feel free to refer to the aforementioned links!

Requirements

• ONLY CHOOSE ONE OF THESE OPTIONS:
  • Python 3.12 (includes venv)
  • Anaconda
  • Miniconda (my personal preference)

Tip

If you have trouble deciding, please refer to the table below

Python 3.12	Anaconda	Miniconda
Familiar with Python	New to Conda and/or Python	Familiar with both Conda and Python
Comfortable using CLI	Not familiar with using CLI and prefer GUI	Comfortable using CLI
ONLY plan on using Python 3.12	Like the convenience of having different versions of Python, IDES, and 1,500+ scientific packages automatically installed at once	Want fast access to different versions of Python and the Conda commands and plan to sort out the other programs later
Smallest footprint (~30 MB); only installs the core interpreter and standard library for Python	Have the time and space (a few minutes and ~5 GB)	Lightweight (~400 MB); only includes Python, Conda, the packages they both depend on, and a small number of other useful packages
May struggle with complex scientific packages	Can install external libraries (e.g. C++, Fortran tools) needed for data science and machine learning	Can install external libraries (e.g. C++, Fortran tools) needed for data science and machine learning

Typing out entire Conda commands can sometimes be tedious, so I wrote a shell script (conda_shortcuts.sh) to define shortcuts for commonly used Conda commands.

Example: Delete/remove a Conda environment named test_env

• Shortcut command

  rmenv test_env

• Manually typing out the entire command

  conda env remove -n test_env && rm -rf $(conda info --base)/envs/test_env

The shortcut has 80.8% less characters!

Installation

1. Enter the directory where you want the repository (grovers-algorithm) to be cloned
   • POSIX

     cd ~/path/to/directory

   • Windows

     cd C:\Users\user\path\to\directory

2. Clone the repository (grovers-algorithm)

   git clone https://github.com/lynkos/grovers-algorithm.git

3. Enter (i.e. cd command) grovers-algorithm directory

   cd grovers-algorithm

4. Create and activate a virtual environment, then install the required packages by following the instructions for either venv OR Conda Virtual Environment below

Important

To avoid duplicate virtual environments, ONLY follow the instructions for either venv (if you installed Python 3.12) OR Conda Virtual Environment (if you installed Anaconda or Miniconda), NOT both!

venv

If you installed Python 3.12, follow these instructions:

1. Confirm Python 3.12 is installed

   python3.12 --version

2. Create a virtual environment named grovenv

   python3.12 -m venv grovenv

3. Activate the virtual environment (grovenv)
   • POSIX

     grovenv/bin/activate

   • Windows

     grovenv\Scripts\activate

4. Install the required packages from requirements.txt

   pip install -r requirements.txt

Conda

If you installed Anaconda or Miniconda, follow these instructions:

1. Confirm Conda is installed

   conda --version

2. Ensure Conda is up to date

   conda update conda

3. Create a virtual environment from environment.yml

   conda env create -f environment.yml

4. Activate the virtual environment (grovenv)

   conda activate grovenv

5. Confirm that the virtual environment (grovenv) is active
   • If active, the virtual environment's name should be in parentheses () or brackets [] before your command prompt, e.g.

     (grovenv) $
     

   • If necessary, see which environments are available and/or currently active (active environment denoted with asterisk (*))

     conda info --envs

     OR

     conda env list

Usage

Tip

If you're unsure about which subsection(s) to follow, please refer to the table below

Visual Studio Code	Command Line
Beginner/User-friendly	Recommended if familiar with using terminals/shells/CLIs
GUI	CLI
Click a button to run program	Execute a command in terminal/shell/CLI to run program

Python Script

Note

Although they both perform the same function, there's a discernable difference between grovers_algorithm.py and grovers_algorithm.ipynb. The former is a Python script, the latter is a Jupyter notebook.

Command Line (Recommended)

Run grovers_algorithm.py

python src/grovers_algorithm.py

Command Line Arguments

Option	Type	Description	Default
-H, --help		Show help message and exit
-T, --title <title>	str	Window title	"Grover's Algorithm"
-n, --n-qubits <n_qubits>	int	Number of qubits	5
-s, --search <search>	int	Nonnegative integers to search for	11 9 0 3 (i.e., { 11, 9, 0, 3 })
-S, --shots <shots>	int	Number of simulations	1000
-f, --font-size <font_size>	int	Histogram's font size	10
-p, --print	bool	Whether or not to print quantum circuit(s)	False
-c, --combine	bool	Whether to combine all non-winning states into 1 bar labeled "Others" or not	False

Visual Studio Code

1. Open grovers_algorithm.py
2. Run grovers_algorithm.py: Click ▷ (i.e. Play button) in the upper-right corner

Jupyter Notebook

Visual Studio Code (Recommended)

1. Open the Command Palette with the relevant keyboard shortcut
   • Mac: ⌘ + Shift + P
   • Windows: CTRL + Shift + P
2. Search and select Python: Select Interpreter
3. Select the virtual environment (grovenv)
4. Open grovers_algorithm.ipynb
5. Confirm grovenv is the selected kernel
6. Run grovers_algorithm.ipynb by clicking Run All

Command Line

Note

Make sure the virtual environment (grovenv) is activated before running the following commands

1. Install ipykernel in the virtual environment (grovenv)
   • venv

     python -m pip install ipykernel

   • Conda

     conda install -n grovenv ipykernel

2. Add the virtual environment (grovenv) as a Jupyter kernel

   python -m ipykernel install --user --name=grovenv
   

3. Open grovers_algorithm.ipynb in the currently running notebook server, starting one if necessary

   jupyter notebook src/grovers_algorithm.ipynb
   

4. Select the virtual environment (grovenv) as the kernel before running grovers_algorithm.ipynb

Cleanup

1. [Optional] Deactivate the virtual environment (grovenv) to clean up and remove it
   • venv

     deactivate

   • Conda

     conda deactivate
     

2. Close the terminal

Examples

These serve as example outputs/results of the running Grover's algorithm (i.e. files in src)

Quantum Circuits

Generated by grovers_algorithm.ipynb (i.e. Jupyter notebook)

Oracle

Diffuser

Grover

Figures

Generated by grovers_algorithm.ipynb (i.e. Jupyter notebook)

Bloch Sphere

City Plot

Hinton Plot

Q-Sphere

Simulations

Histograms visualize the outcome/results of 1000 simulations of Grover's algorithm

Python

Generated by grovers_algorithm.py (i.e. Python script)

Tip

Hovering above a bar in the histogram displays that state's frequency

Histogram of the outcome of 1000 simulations of Grover's algorithm

Histogram of the outcome of 1000 simulations of Grover's algorithm, with all non-target states combined into a single bar

Jupyter Notebook

Generated by grovers_algorithm.ipynb (i.e. Jupyter notebook)

Histogram of the outcome of 1000 simulations of Grover's algorithm

Resources

• Anaconda Documentation
• Conda Documentation
• Getting Started with Conda
• Jupyter Notebook Documentation
• Jupyter Project Documentation [PDF]
• Technical Support - Jupyter Google Group
• Qiskit Documentation
• Documentation for Visual Studio Code
• Using Jupyter Notebooks in Visual Studio Code

Credit

Special thanks to Simanraj Sadana for "Grover's search algorithm for n qubits with optimal number of iterations", which has been a helpful reference and an informative read

License

Distributed under the MIT License, Copyright © 2023 – 2025 Kiran Brahmatewari