Quantum Random Number Generator Tutorial: Build One and Test the Output

Overview

If you want a hands-on quantum programming tutorial that stays useful after the first read, a QRNG is a strong choice. It is small enough to implement in one sitting, but rich enough to teach several core ideas: superposition, measurement, shot-based execution, backend selection, and output validation.

The basic circuit is straightforward. Start with a single qubit in the |0⟩ state. Apply a Hadamard gate to put it into an equal superposition of |0⟩ and |1⟩. Measure the qubit. In an ideal model, each measurement gives 0 or 1 with equal probability. Repeating the circuit many times produces a bitstream.

That simplicity is what makes this project useful. You can compare at least four versions of the same idea:

• Single-bit QRNG: one qubit, one measurement, one random bit per shot.
• Multi-bit QRNG: multiple qubits prepared and measured together to produce several bits at once.
• Simulator-based QRNG: useful for learning circuit structure, but not a source of physical randomness.
• Hardware-based QRNG: uses real measurement outcomes from quantum hardware, where noise and device behavior also become part of the story.

For developers, the real lesson is that building quantum circuits is only half the job. The other half is deciding how to collect results, how to test them, and how to interpret what “random” means in your implementation.

If you are new to circuit construction, it may help to read How to Build Quantum Circuits in Python: A Step-by-Step Developer Guide first. If terms like qubit, shot, and measurement still feel fuzzy, keep Quantum Computing Glossary for Developers nearby.

A minimal QRNG in Qiskit

Here is the smallest useful example. The exact API surface may change over time, but the circuit logic stays the same.

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

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

sim = AerSimulator()
job = sim.run(qc, shots=32)
result = job.result()
counts = result.get_counts()
print(counts)

Typical output is a counts dictionary with some mix of 0 and 1. On a simulator, those results come from the simulator's sampling behavior, not from physical quantum hardware. That distinction matters later when you decide what kind of project you are actually building: a quantum circuit tutorial, a randomness demo, or a production-oriented entropy source experiment.

A minimal QRNG in Cirq

If you prefer Cirq, the same idea maps cleanly.

import cirq

q = cirq.LineQubit(0)
circuit = cirq.Circuit(
    cirq.H(q),
    cirq.measure(q, key='bit')
)

simulator = cirq.Simulator()
result = simulator.run(circuit, repetitions=32)
print(result)

This is enough to see the shared pattern across SDKs: prepare, create superposition, measure, repeat.

How to compare options

The main choice in a QRNG tutorial is not the circuit. It is the implementation path around the circuit. To compare options well, evaluate them across a few practical dimensions instead of asking which tool is “best” in the abstract.

1. Learning value

If your goal is understanding quantum computing for developers, the best option is usually the one that makes the circuit and results easiest to inspect. A simulator often wins here because you can run quickly, print state information, and avoid queue delays. For debugging help, see Quantum Debugging Guide: How to Inspect Circuits, States, and Measurement Results.

2. Source of randomness

This is the most important conceptual distinction:

• Pseudorandom classical program: uses a classical algorithm to generate bits.
• Quantum circuit on a simulator: models quantum behavior, but still runs on classical hardware.
• Quantum circuit on real hardware: produces measurements from a physical quantum system.

If you are building a classroom or portfolio project, all three can teach something useful. If you specifically care about physical randomness, only hardware execution addresses that directly.

3. Output format

Decide early whether you want a stream of single bits, bytes, integers, or a file of sampled values. A common beginner mistake is to focus only on the circuit and leave the data pipeline vague. In practice, formatting matters:

• Single bits are easiest for learning.
• Bitstrings from multiple qubits are better for throughput.
• Byte-oriented output is easier to feed into tests or downstream programs.

4. Testability

A good QRNG tutorial should include verification steps. Not a proof of perfect randomness, but a realistic testing routine. At minimum, compare observed frequencies of 0 and 1 over many shots. Then add simple checks such as run lengths or pair frequencies. You are not certifying cryptographic quality here; you are confirming that your implementation behaves roughly as expected.

5. SDK ergonomics

For this project, compare SDKs by how easy it is to:

• define a one-qubit or multi-qubit circuit,
• run repeated shots,
• extract counts or measurement arrays,
• switch from simulator to hardware backends,
• save or post-process results in Python.

If you are surveying tooling beyond two frameworks, the broader list in Quantum Computing Python Libraries List: SDKs, Simulators, and Utility Tools is a useful companion.

Feature-by-feature breakdown

Below is a practical breakdown of the design choices that matter when you build quantum randomness code.

Circuit design: one qubit or many?

One qubit is the cleanest teaching example. It makes the measurement model obvious and keeps debugging simple.

Multiple qubits let you generate a bitstring per shot. For example, applying a Hadamard gate to each of 8 qubits and measuring all of them produces 8 bits per shot in an ideal model.

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

n = 8
qc = QuantumCircuit(n, n)
for i in range(n):
    qc.h(i)
qc.measure(range(n), range(n))

sim = AerSimulator()
job = sim.run(qc, shots=100)
result = job.result()
counts = result.get_counts()
print(counts)

This is still conceptually simple: each qubit is prepared independently, then measured. For a first QRNG, you do not need entanglement. In fact, adding it usually makes the output behavior harder to reason about. If you want to understand that later, read Quantum Entanglement Explained for Coders: What It Means in Real Circuits.

Simulator or hardware?

Simulator advantages:

• fast iteration,
• easy debugging,
• stable learning environment,
• good for code structure and testing workflow.

Simulator limitations:

• does not give you physical entropy,
• may hide backend-specific issues,
• can encourage overconfidence about circuit behavior.

Hardware advantages:

• real quantum measurements,
• better for understanding device constraints,
• more authentic end-to-end workflow.

Hardware limitations:

• queueing or access constraints,
• backend changes over time,
• noise can skew observed distributions,
• harder to reproduce the same run conditions.

The most useful approach is usually staged: develop locally on a simulator, then run the same circuit on available hardware and compare outputs.

Testing the output

This is where a QRNG project becomes more than a toy. Start with practical tests that any developer can implement.

1. Frequency balance

Generate many bits and count how often 0 and 1 appear. For a fair one-qubit Hadamard circuit, the counts should be reasonably close over a large sample. “Reasonably close” matters more than “exactly equal.”

bits = "0110100110010110"  # example
zeros = bits.count("0")
ones = bits.count("1")
print(zeros, ones)

2. Run inspection

Look for suspiciously long runs such as many repeated 0s or 1s in short samples. Runs happen naturally in random data, so the point is not to ban them. The point is to detect obvious implementation bugs, such as accidentally reusing one measurement result or formatting output incorrectly.

3. Pair frequency

Count 00, 01, 10, and 11 pairs in the bitstream. Large imbalances can reveal issues in post-processing even when single-bit frequencies look fine.

4. Repeatability of your code path

Your randomness output should vary, but your pipeline should be repeatable. That means the same script should consistently produce valid-length output, parse results correctly, and save data in the same format.

For most tutorial projects, these tests are enough. If you later want deeper statistical evaluation, add it as a separate phase rather than overloading the first version.

Post-processing choices

Post-processing is often where hidden bias enters. Keep it simple:

• Do not drop “unwanted” bits just because a sample looks uneven.
• Do not silently reorder bitstrings without documenting the convention.
• Be explicit about endian or bit order assumptions in your SDK.
• Store raw outputs before applying transformations.

These habits make your QRNG project easier to compare across frameworks and easier to revisit after SDK updates.

What this project teaches beyond randomness

A QRNG is a compact introduction to the same workflow patterns you will use in more advanced topics like Grover's Algorithm, Quantum Fourier Transform, or QAOA: define a circuit, run it repeatedly, inspect measurements, and interpret imperfect results carefully.

Best fit by scenario

If you are unsure which version of this project to build, choose based on your actual goal.

Best for beginners: single-qubit simulator QRNG

Use one qubit, one Hadamard, one measurement, and a few hundred or thousand shots. This version is ideal if your main goal is to understand what a qubit tutorial looks like in code and how measurement creates output.

Best for portfolio projects: multi-bit QRNG with testing script

Use several qubits, batch output into bytes or strings, and add automated tests for frequency and pair counts. This version shows stronger engineering habits and gives you something concrete to discuss in interviews or personal documentation.

Best for framework comparison: implement the same QRNG in Qiskit and Cirq

Keep the circuit identical and compare developer experience, measurement handling, and result extraction. This is one of the cleanest ways to evaluate a Qiskit tutorial against a Cirq tutorial without getting distracted by advanced algorithm details.

Best for realism: simulator first, hardware second

Write one script that can target both. Run locally for development, then switch to a real backend when available. Record any differences in counts, execution friction, and result formatting. That gives you a practical quantum SDK guide mindset instead of a one-off demo.

Best for teaching others: QRNG plus visualization

Print the circuit diagram, show a sample histogram of counts, and explain the output in plain language. This is especially useful if you are writing internal documentation, preparing a workshop, or mentoring developers who find quantum concepts too abstract.

When to revisit

A good evergreen project is one you can return to as the ecosystem changes. A QRNG tutorial has that quality because the core idea stays stable while the surrounding tools evolve.

Revisit this project when any of the following changes:

• SDK APIs change: circuit creation, simulator imports, or result objects may shift over time.
• New backend options appear: especially if you can compare local simulation with managed or hardware execution.
• Tooling improves: better debugging, visualization, or testing utilities can make your implementation clearer.
• Your goal changes: from learning quantum basics to benchmarking frameworks or exploring hardware behavior.
• You want more rigorous validation: move from simple counts to richer statistical checks in a separate testing layer.

To keep the project maintainable, treat it like a small software artifact rather than a one-time notebook. A practical checklist:

1. Keep the circuit logic isolated from result processing.
2. Save raw measurement output alongside summarized counts.
3. Write one function that converts measurement results into a bitstream.
4. Write a separate test module for frequency, runs, and pair counts.
5. Document whether results came from a simulator or real hardware.
6. Re-run the same script whenever you switch SDK versions or backends.

If you do that, your QRNG becomes a reusable benchmark for your own learning. It also becomes a reference point when comparing quantum software tools later.

The simplest next step is this: build version one today on a simulator, then create version two with multi-qubit output and a small validation script. Once both are working, try the same project in a second SDK or on a different backend. That progression turns a short quantum random number generator tutorial into a durable developer exercise that remains useful as the ecosystem changes.

And if you want to extend the project further, pair it with a broader quantum simulator guide so you can compare runtime behavior, developer ergonomics, and debugging features across tools.