QuBitLang Circuits
Every random value generated by TrueEntropy is produced by a QuBitLang quantum circuit running on real IBM quantum hardware. This page explains the circuits used and how they guarantee true randomness.
The QRNG Hadamard Circuit
TrueEntropy's primary circuit is qrng_hadamard_v2.3. It applies a Hadamard gate to each qubit,
placing it in an equal superposition of |0⟩ and |1⟩, then measures the result. The outcome is
fundamentally unpredictable - guaranteed by quantum mechanics.
Why Hadamard?
The Hadamard gate is the gold standard for quantum random number generation because:
- Perfect 50/50 split - Transforms |0⟩ into an exact equal superposition of |0⟩ and |1⟩
- No bias - Unlike PRNGs, there is no seed, state, or pattern to exploit
- Depth-1 circuit - Single gate layer minimises decoherence and noise
- Proven by physics - The Born rule guarantees measurement outcome is fundamentally random
Circuit Pipeline
When you call the TrueEntropy API, the following pipeline executes:
| Step | Component | Description |
|---|---|---|
| 1 | API request | Your request arrives at the TrueEntropy API |
| 2 | QuBitLang compiler | The .ql circuit is compiled to Qiskit IR |
| 3 | Quantum execution | Circuit runs on IBM quantum hardware (e.g. ibm_fez) |
| 4 | Measurement | Qubits collapse - raw random bits extracted |
| 5 | Post-processing | Von Neumann debiasing applied if needed |
| 6 | NIST verification | Output tested against NIST SP800-22 statistical suite |
| 7 | API response | Random values delivered with full provenance metadata |
Scaling Qubits
TrueEntropy uses IBM's 156-qubit Heron processors. The current QRNG circuit uses 8 qubits, generating 8 random bits per shot. For larger requests, multiple circuit shots are batched automatically by the QuBitLang runtime.
Circuit Versioning
Every API response includes the exact circuit version used. This is available in both the JSON metadata
and the X-QuBitLang-Circuit response header, enabling full audit trails.
| Version | Changes | Status |
|---|---|---|
qrng_hadamard_v2.3 | Current - optimised qubit allocation, improved debiasing | Active |
qrng_hadamard_v2.2 | Added Von Neumann debiasing layer | Retired |
qrng_hadamard_v2.1 | Multi-backend failover support | Retired |
qrng_hadamard_v2.0 | Initial 8-qubit Hadamard QRNG | Retired |
Learn More
For full documentation on the QuBitLang language, compiler pipeline, and quantum circuit syntax, visit www.qubitlang.net.