Metadata-Version: 2.4
Name: surfq
Version: 0.1.4
Summary: A surface code simulator
Author-email: João Ramos <1joaoramos1@gmail.com>
License-Expression: AGPL-3.0-or-later
Keywords: python,project,surfq
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.10.5
Requires-Dist: networkx>=3.5
Requires-Dist: numpy>=2.3.2
Requires-Dist: pyqt6>=6.9.1
Requires-Dist: seaborn>=0.13.2
Dynamic: license-file

# 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](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](https://pypi.org/project/surfq/). To use it you can simply install on your environment with *pip*:

```shell
pip install surfq
```


Alternatively, if you are using [uv](https://docs.astral.sh/uv/) package manager, you can get started by simply:

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

Then to get started in python:

```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](https://github.com/manzt/juv) for seamless dependency management.

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

```shell
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.

```shell
uv run examples/decoding_2.py
```

## Notebooks

This project contains a set of notebooks to experiment with. We recommend using [juv](https://github.com/manzt/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.

```shell
uvx juv run notebooks/tutorial/notebook.py
```


## Testing

Run the unit test suite with:

``` 
uv run pytest
```

## References

- [Improved Simulation of Stabilizer Circuits](https://arxiv.org/pdf/quant-ph/0406196v5) – Aaronson and Gottesman, 2004
- [Stim: a fast stabilizer circuit simulator](https://arxiv.org/abs/2103.02202) – Gidney, 2021
- [STABSim: A Parallelized Clifford Simulator with Features Beyond Direct Simulation](https://arxiv.org/abs/2507.03092) – Garner et al., 2025
- [The Heisenberg Representation of Quantum Computers](https://arxiv.org/abs/quant-ph/9807006) - Gottesman, 1998
