SurfQ

SurfQ is a Python framework for efficiently simulating surface codes under noise. The aim is to enable detailed investigation of the behavior of surface codes under different physical error models, supporting advanced fault-tolerant protocols such as lattice surgery, state injection, and magic state distillation as future extensions.

License

This project is released under the GNU Affero General Public License v3.0 (AGPL-3.0) or later.

Please see the LICENSE file for the full text of the license.

Features

• Intuitive surface code representation
• Apply quantum operations: X, Z, H, CNOT, and syndrome measurement
• Simulate various noise channels: Pauli noise, depolarizing, bit-flip, phase-flip errors
• Analyse logical error rates and syndrome measurement statistics for error correction
• Modular and extensible framework for surface code simulation and fault-tolerant quantum protocols

Usage

This package is available on PyPi. To use it you can simply install on your environment with pip:

pip install surfq

Alternatively, if you are using uv package manager, you can get started by simply:

uvx juv init notebook.ipynb
uvx juv run notebook.ipynb --with surfq

Then to get started in python:

from surfq import Lattice

l = Lattice(5)
l[1,1:4].X()
l.show()

Examples

This project contains a set of example scripts to experiment with. We recommend using uv for seamless dependency management.

• Decoding Test 1: This script showcases a successful example of the current in-progress work on decoding error syndromes.

uv run examples/decoding_1.py

• Decoding Test 2: This script showcases a wrong example of the current in-progress work on decoding error syndromes.

uv run examples/decoding_2.py

Notebooks

This project contains a set of notebooks to experiment with. We recommend using juv for seamless dependency management.

• Tutorial: This notebook goes through the basics of Quantum Error Correction, Stabilizer Formalism and the Surface Code, while leveraging surq to make the surface code more interactive and more easily illustrated.

uvx juv run notebooks/tutorial/notebook.py

Testing

Run the unit test suite with:

uv run pytest

References

• Improved Simulation of Stabilizer Circuits – Aaronson and Gottesman, 2004
• Stim: a fast stabilizer circuit simulator – Gidney, 2021
• STABSim: A Parallelized Clifford Simulator with Features Beyond Direct Simulation – Garner et al., 2025
• The Heisenberg Representation of Quantum Computers - Gottesman, 1998