Add noisy circuit dataset for BP decoding demonstration

[ChanceSiyuan]

Summary

• Add Stim circuits for rotated surface code (d=3) Z-memory experiments with circuit-level depolarizing noise (p=0.01) at 3, 5, 7 measurement rounds
• Add Python script scripts/generate_noisy_circuits.py to generate customizable noisy circuits
• Add comprehensive README with BP decoding tutorial, including code examples for extracting detector error model, building parity check matrix, and decoding syndromes
• Add visualization images (qubit layout, parity check matrix structure, syndrome statistics)

Test plan

• Generated circuits compile successfully with Stim detector sampler
• README code examples are verified working
• Review documentation for completeness and clarity

[GiggleLiu]

• Please follow the python best practise of create a package, not just scripts.
• Use uv to manage the environment.
• Write tests.

[GiggleLiu]

• d should be a variable in code base (can be fixed in generation script/Makefile)

[GiggleLiu]

How to generate new datasets? Create something like:

$ make dataset rotated-surface-code d=3 r=3 p=0.01

Please show me the generated noisy circuit.

[GiggleLiu]

well done, good structure.

[GiggleLiu]

please setup unit tests and CI/CD

[Copilot]

Pull request overview

This PR adds a comprehensive dataset and tooling for demonstrating Belief Propagation (BP) decoding on noisy surface code circuits. It includes pre-generated Stim circuits for rotated surface code (d=3) Z-memory experiments with circuit-level depolarizing noise (p=0.01) at 3, 5, and 7 measurement rounds, along with a Python package (bpdecoderplus) that provides a CLI for generating customizable noisy circuits and a detailed README with BP decoding tutorials.

Changes:

• Added Python package bpdecoderplus with CLI for generating noisy surface code circuits
• Added three pre-generated Stim circuit files for d=3, p=0.01, Z-memory at 3/5/7 rounds
• Added comprehensive documentation with BP decoding tutorial and code examples

Reviewed changes

Copilot reviewed 13 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/bpdecoderplus/__init__.py	Package initialization exposing circuit generation API
src/bpdecoderplus/circuit.py	Core circuit generation functions for noisy surface codes
src/bpdecoderplus/cli.py	Command-line interface for circuit generation
tests/test_circuit.py	Comprehensive unit tests for circuit generation module
tests/test_cli.py	Unit tests for CLI functionality
tests/__init__.py	Test package initialization
pyproject.toml	Project configuration with dependencies and build settings
datasets/noisy_circuits/sc_d3_r3_p0010_z.stim	Generated Stim circuit for 3 rounds
datasets/noisy_circuits/sc_d3_r5_p0010_z.stim	Generated Stim circuit for 5 rounds
datasets/noisy_circuits/sc_d3_r7_p0010_z.stim	Generated Stim circuit for 7 rounds
datasets/noisy_circuits/README.md	Tutorial documentation for BP decoding with code examples
Makefile	Build automation for setup, testing, and dataset generation
.gitignore	Updated ignore patterns for Python and development artifacts

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ChanceSiyuan]

All Review Comments Addressed ✅

I've addressed all the review comments:

1. ✅ Python Package Structure (not scripts)

• Status: Completed in earlier commit
• Implementation: Proper package structure at src/bpdecoderplus/
  • src/bpdecoderplus/__init__.py
  • src/bpdecoderplus/circuit.py - Core circuit generation
  • src/bpdecoderplus/cli.py - CLI interface
• Tests: Comprehensive test suite in tests/

2. ✅ Use uv for Environment Management

• Status: Completed in commit 133c617
• Implementation:
  • Added [tool.uv] section to pyproject.toml
  • Configured dev-dependencies for pytest
  • Updated README with uv commands

3. ✅ Write Tests

• Status: Already present
• Implementation:
  • tests/test_circuit.py - 76 test cases for circuit generation
  • tests/test_cli.py - CLI integration tests
  • All tests passing locally

4. ✅ Variable d in Codebase

• Status: Completed
• Implementation: d (distance) is a CLI argument in cli.py:36-38
  • Default: d=3
  • Configurable via --distance flag

5. ✅ Make Command for Dataset Generation

• Status: Completed in commit 133c617
• Implementation: Makefile with targets:

  make install          # Install uv
  make setup            # Set up environment
  make generate-dataset # Generate circuits (d=3, p=0.01, r=3,5,7)
  make test             # Run tests
  make clean            # Clean up

6. ✅ CI/CD Setup

• Status: Completed in commit 504d0ee
• Implementation: .github/workflows/test.yml
  • Runs on push and PR
  • Tests on Python 3.10, 3.11, 3.12
  • Uses uv for dependency management
  • Automated test execution

---

Summary: All review comments have been resolved. The PR now has:

• ✅ Proper Python package structure
• ✅ uv package management
• ✅ Comprehensive test suite
• ✅ Makefile for automation
• ✅ CI/CD with GitHub Actions

Ready for final review and merge.