Skip to content

feat: add RotatedSurfaceCode and RotatedSurfaceCodeLoom to simulator utilities#57

Open
Cherie000 wants to merge 25 commits into
mainfrom
staging_qec
Open

feat: add RotatedSurfaceCode and RotatedSurfaceCodeLoom to simulator utilities#57
Cherie000 wants to merge 25 commits into
mainfrom
staging_qec

Conversation

@Cherie000

Copy link
Copy Markdown
Collaborator

Summary

This PR adds two new files to src/quantum_gates/_utility/ implementing
end-to-end rotated surface code simulations using the MrAnderson simulator.

New Files

RotatedSurfaceCodeLoom.py

A surface code simulation pipeline built on top of the loom framework.
Uses EkaToQasmConverter to generate a Qiskit circuit from a declarative
surface code description, runs it through MrAnderson, and decodes the logical error rate via PyMatching,
using Stim to construct the detector error model.

Key features:

  • Supports distance-$d$ rotated surface code with configurable cycles, shots, and noise
  • Two simulation backends: MrAnderson (custom statevector) and AER (Qiskit stabilizer)
  • Stim-based noise model and detector error model for PyMatching decoding
  • Returns logical error rate directly

RotatedSurfaceCode.py

A self-contained rotated surface code implementation built directly in Qiskit,
without the loom framework.

Key features:

  • Constructs the full surface code lattice geometry (data qubits, X/Z stabilizers, neighbors)
  • Builds stabilizer measurement cycles with reset, entanglement, and measurement layers
  • Supports optional fault injection via error parameter
  • Includes a full decoding pipeline: parity-check matrix construction, PyMatching
    decoding per cycle, and Z-correction of data qubits
  • Compatible with both MrAnderson (CustomNoiseChannelsGates) and Aer backends

Dependencies added (docs/requirements.txt)

  • pymatching
  • stim
  • el-loom

Notes

  • These files serve as concrete end-to-end usage examples of the MrAnderson
    simulator on a fault-tolerant quantum error correction protocol
  • RotatedSurfaceCodeLoom.py depends on the loom ecosystem;
    RotatedSurfaceCode.py is standalone
  • Both files are intended to live in src/quantum_gates/_utility/

@Cherie000 Cherie000 self-assigned this May 4, 2026
@Cherie000 Cherie000 linked an issue May 4, 2026 that may be closed by this pull request
@Cherie000 Cherie000 changed the title Staging qec feat: add RotatedSurfaceCode and RotatedSurfaceCodeLoom to simulator utilities May 4, 2026

@romanwixinger romanwixinger left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work @Cherie000 ! Let us discuss how we can test the surface code. Maybe you have ideas from your own experiments that we can tap into.

Comment thread docs/requirements.txt

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Check if we still need this full list after the changes I did to the docs in https://github.com/CERN-QTI/quantum-gates/pull/55/changes. I guess the dependencies for the build process of the docs should now come from the setup.cfg.

@@ -0,0 +1,285 @@

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Cleanup the formatting of the imports. No extra lines on top and two lines between the last import and the class definition.

matcher = pymatching.Matching(dem)
return matcher, converter

def MrAnderson_run_circ_backend(self):

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Make method names lowercase. I know that we have the gates uppercase but this is just for legacy reasons and because it is easier to read.

self.noise = noise
self.p = p

# ── Build experiment and interpret ───────────────────────────────────

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Cleanup comments, no extra "─".

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Name the file in lowercase.

noise_model = NoiseModel()

# Single-qubit gate depolarizing noise
#single_qubit_error = depolarizing_error(p, 1)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Check if still needed.

device_param_lookup['p_int'][i, i+1] = found_p_int
device_param_lookup['p_int'][i+1, i] = found_p_int
return device_param_lookup
def _transpile_circ(self):

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Format the methods, one line between methods.

from qiskit_aer import AerSimulator
from qiskit_aer.noise import NoiseModel, depolarizing_error

from loom.eka import Eka, Lattice

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like how you organized the imports!

@@ -0,0 +1,14 @@
# tests/test_rotated_surface_code.py
from quantum_gates._utility.RotatedSurfaceCodeLoom import RotatedSurfaceCodeLoom

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Make sure to expose the new functionality to the outside. The imports in the future should not have to use ._utility "private underscore" for functionality that should be public.

Comment thread src/surface_code_ler.png

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Todo: Move to the docs.

@NathanPaceydev

Copy link
Copy Markdown
Collaborator

Since the SC both rotated and planar implement "large" circuits it would be good to also run a profiler on the classes and see what speed-ups we could apply!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Integrate surface code.

3 participants