DEV Community

Cover image for Building a Quantum Coin Toss CLI with Python, Qiskit, and Matplotlib
Aman Raza
Aman Raza

Posted on

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

#quantumcomputing #python #qiskit #beginners

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

Here is what each line does:

circuit = QuantumCircuit(1, 1)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode

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%)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Or save the chart as an image:

python quantum_coin_toss.py --save-plot results.png
Enter fullscreen mode Exit fullscreen mode

Quantum Coin Toss Plot

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
Enter fullscreen mode Exit fullscreen mode

Run with the default 1024 shots:

python quantum_coin_toss.py
Enter fullscreen mode Exit fullscreen mode

Run more tosses:

python quantum_coin_toss.py --shots 10000
Enter fullscreen mode Exit fullscreen mode

Print the explanation:

python quantum_coin_toss.py --explain
Enter fullscreen mode Exit fullscreen mode

Save a result chart:

python quantum_coin_toss.py --shots 5000 --save-plot results.png
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)