Quantum Error & Noise Simulator. A Python-native toolkit for simulating quantum errors, decoding syndromes, and visualizing error-correcting codes.
QENS provides a clean, high-level API for researchers, educators, and engineers working with quantum error correction. Run a full simulation in a single function call, compose noise models with +, and let decoders handle their own setup — all while retaining access to the full power of the SDK when you need it. Ships with built-in support for surface codes, repetition codes, and color codes, multiple decoder implementations, and publication-quality visualization — all with only numpy and matplotlib as dependencies.
pip install qensFor development (includes pytest, mypy, ruff):
git clone https://github.com/quip0/qens
cd qens
pip install -e ".[dev]"Requires Python 3.11+.
from qens import SurfaceCode, DepolarizingNoise, MatchingDecoder, simulate
code = SurfaceCode(distance=3)
noise = DepolarizingNoise(error_rate=0.01)
result = simulate(code, noise, MatchingDecoder(code), shots=10_000, seed=42)
print(f"Logical error rate: {result.logical_error_rate:.4f}")One import, four lines. The decoder prepares itself on first use, and simulate() wires up the Monte Carlo engine for you. When you need more control, the full Simulator and ThresholdExperiment APIs are still there.
Interactive Jupyter notebooks (the fastest onboarding):
| Notebook | Description |
|---|---|
| 01 — Quickstart | End-to-end first simulation: code → noise → decoder → Monte Carlo → threshold |
| 02 — Syndrome Extraction | How stabilizers detect errors; CSS structure; logical errors; noisy extraction |
| 03 — Decoder Comparison | Benchmarking lookup / MWPM / union-find: LER, timing, metadata |
Full documentation is in the docs/ directory:
| Guide | Description |
|---|---|
| Getting Started | Installation, first simulation, project structure |
| Core Concepts | QEC background, Pauli errors, CSS codes, Pauli frame model |
| Error Models | All 10 noise models with examples |
| QEC Codes | Repetition, surface, and color codes |
| Decoders | Lookup, MWPM, and union-find decoders |
| Syndrome Extraction Guide | Stabilizer measurement, XOR linearity, CSS syndromes, logical errors |
| Decoder Comparison Guide | When to use each decoder and how they trade off |
| Simulation | Monte Carlo sampling, threshold sweeps, Pauli frame simulator |
| Visualization | Circuit diagrams, lattice views, decoding graphs, plots |
| Extending QENS | Custom error models, codes, decoders, visualizers |
| API Reference | Complete reference for every class and function |
| Architecture | Package design, dependency graph, simulation pipeline |
QENS is designed to feel natural from the first line of code. The API minimizes boilerplate so you can focus on the physics:
# Compose noise with +
noise = DepolarizingNoise(0.01) + ReadoutNoise(0.005)
# Simulate in one call — decoder prepares itself automatically
result = simulate(SurfaceCode(3), noise, MatchingDecoder(code), shots=10_000)
# Or use the OOP shorthand directly on the code
result = SurfaceCode(3).simulate(noise, MatchingDecoder(code), shots=10_000)- One-call simulation --
simulate(code, noise, decoder)handles setup, sampling, and decoding in a single function. See Simulation. - Noise composition with
+--DepolarizingNoise(0.01) + ReadoutNoise(0.005)produces a flatCombinedNoiseautomatically. See Error Models. - Auto-preparing decoders -- Call
decoder.decode(syndrome)and the decoder prepares itself on first use. No manual.prepare()step needed. See Decoders. - Readable circuit API -- Long-form gate names (
pauli_x,pauli_z,controlled_z,barrier) alongside short aliases (x,z,cz) for fluent circuit construction. - 10 noise models -- Depolarizing, bit-flip, phase-flip, measurement, crosstalk, leakage, correlated Pauli, and more. See Error Models.
- QEC Codes -- Repetition, surface, and color codes with stabilizers, check matrices, and syndrome circuits. See QEC Codes.
- Decoders -- Lookup table, MWPM, and union-find decoders. See Decoders.
- Simulation -- Monte Carlo sampling, threshold sweeps, and Pauli frame simulation. See Simulation.
- Visualization -- Circuit diagrams, lattice views, decoding graphs, and statistical plots. See Visualization.
- Extensible -- ABC + Registry pattern for adding custom error models, codes, and decoders. See Extending QENS.
qens/
core/ Types, Circuit, Gate, NoiseChannel, Registry
noise/ NoiseModel ABC + 10 built-in models + CombinedNoise (+ operator)
codes/ QECCode ABC + RepetitionCode, SurfaceCode, ColorCode
decoders/ Decoder ABC + Lookup, UnionFind, MWPM (auto-prepare)
simulation/ simulate(), Simulator, PauliFrameSimulator, ThresholdExperiment
viz/ Circuit diagrams, lattice views, decoding graphs, stats plots
utils/ Pauli algebra, GF(2) sparse matrices, seeded RNG
For interactive walkthroughs, open the tutorial notebooks.
Script-based examples for quick CLI use:
python3 examples/03_custom_noise_model.py # Composed noise + visualization
python3 examples/04_visualization_gallery.py # All visualization typespytest # 207 tests
ruff check src/qens/ # LintMIT