Building a Quantum Coin Toss CLI with Python, Qiskit, and Matplotlib

Aman Raza — Mon, 15 Jun 2026 07:34:57 +0000

Building a Quantum Coin Toss CLI with Python, Qiskit, and Matplotlib

When people first hear about quantum computing, it can sound abstract and
intimidating. Words like superposition, measurement, and qubits feel far away
from the kind of code we usually write.

So I built a small Python project to make one quantum idea more concrete: a
quantum coin toss.

The project uses:

Python for the command-line application
Qiskit to build and simulate a quantum circuit
Matplotlib to visualize the measurement results

The goal is simple: start with one qubit, put it into superposition, measure it,
and treat the result as heads or tails.

What Is Superposition?

In classical computing, a bit is either 0 or 1.

A qubit is different. Before measurement, it can exist in a combination of both
states. This is called superposition.

For this project, the qubit starts in the |0> state. I use a Hadamard gate to
turn it into an equal superposition:

(|0> + |1>) / sqrt(2)

That means when we measure the qubit, there is about a 50% chance of getting
0 and about a 50% chance of getting 1.

In this project:

0 means heads
1 means tails

The Quantum Circuit

The core circuit is very small:

from qiskit import QuantumCircuit

circuit = QuantumCircuit(1, 1)
circuit.h(0)
circuit.measure(0, 0)

Here is what each line does:

circuit = QuantumCircuit(1, 1)

This creates a circuit with one qubit and one classical bit.

The qubit is the quantum part of the system. The classical bit stores the final
measurement result.

circuit.h(0)

This applies a Hadamard gate to qubit 0.

The Hadamard gate is the key operation in this project. It changes the qubit
from a definite |0> state into an equal superposition of |0> and |1>.

circuit.measure(0, 0)

This measures qubit 0 and stores the result in classical bit 0.

Measurement is where the quantum state collapses into one classical result:
either 0 or 1.

Turning It Into a CLI

I wanted this to be more than a notebook experiment, so I turned it into a
command-line application.

The CLI supports:

choosing the number of shots
setting a simulator seed
hiding the circuit diagram
printing a short explanation
showing or saving a Matplotlib chart

Example:

python quantum_coin_toss.py --shots 5000 --plot

In Qiskit, shots means the number of times the circuit is executed. If we run
only one shot, we get one coin toss. If we run 5000 shots, we get a distribution
of many tosses.

With enough shots, the results should usually be close to 50% heads and 50%
tails.

Running the Simulation

The simulation uses Qiskit's local Aer simulator:

from qiskit import transpile
from qiskit_aer import AerSimulator

simulator = AerSimulator(seed_simulator=seed)
compiled_circuit = transpile(circuit, simulator)
result = simulator.run(compiled_circuit, shots=shots).result()
counts = result.get_counts()

This does a few important things:

AerSimulator gives us a local quantum simulator
transpile prepares the circuit for the simulator backend
run executes the circuit many times
get_counts returns how many times each result appeared

The output might look like this:

Quantum coin toss results
Shots:       1024
Heads |0>:     515 ( 50.3%)
Tails |1>:     509 ( 49.7%)

The exact numbers can change from run to run because measurement is
probabilistic.

Visualizing the Results

I added Matplotlib so the result is easier to understand visually.

The program can show a bar chart:

python quantum_coin_toss.py --plot

Or save the chart as an image:

python quantum_coin_toss.py --save-plot results.png

The visualization compares the number of Heads |0> and Tails |1>
measurements. This makes the probabilistic behavior easier to explain,
especially to someone seeing quantum computing for the first time.

Why This Project Matters

This is a small project, but it connects several important ideas:

quantum superposition
measurement and collapse
probabilistic simulation
Python CLI design
data visualization
packaging a script as a usable tool

For me, the most important lesson was this:

The randomness does not come from Python's random module. It comes from
measuring a qubit after applying a quantum gate.

That is what makes the project different from a normal classical coin toss.

Full CLI Examples

Install the dependencies:

pip install qiskit qiskit-aer matplotlib

Run with the default 1024 shots:

python quantum_coin_toss.py

Run more tosses:

python quantum_coin_toss.py --shots 10000

Print the explanation:

python quantum_coin_toss.py --explain

Save a result chart:

python quantum_coin_toss.py --shots 5000 --save-plot results.png

What I Would Improve Next

Some possible next steps:

compare a classical coin toss and a quantum coin toss
run the circuit on real IBM Quantum hardware
add unit tests for the CLI
export results as CSV
add a small Streamlit or web interface

Final Thoughts

This project helped me understand quantum computing through code instead of
only theory.

By building a simple quantum coin toss, I learned how a qubit can be placed into
superposition, how measurement produces a classical result, and how Qiskit can
simulate that process locally.

It is a small project, but it gave me a clearer mental model of one of the most
important ideas in quantum computing.

Github: Quantum-Coin-Toss

DEV Community: Aman Raza

Building a Quantum Coin Toss CLI with Python, Qiskit, and Matplotlib