Add noisy circuit dataset and documentation (Issue #12)

[ChanceSiyuan]

Summary

This PR implements comprehensive noisy circuit dataset generation with DEM extraction, UAI format conversion, and syndrome sampling capabilities. All documentation has been consolidated into a unified getting started guide, and the dataset is organized into well-structured subdirectories.

Issues Addressed

Issue #12: Noisy Circuit Dataset ✅

• Created datasets/circuits/ with three surface code circuits
• All circuits use d=3 surface code with p=0.01 depolarizing noise
• Circuits include detectors and logical observables for BP decoding

Issue #4: Detector Error Model Generation ✅

• Implemented extract_dem() to generate DEMs from circuits
• Added save_dem() to write .dem files in stim format
• Created generate_dem_from_circuit() for CLI integration
• Added --generate-dem flag to CLI
• DEMs saved in datasets/dems/ directory
• UAI Format Support:
  • Implemented dem_to_uai() to convert DEM to UAI format
  • Added save_uai() and generate_uai_from_circuit()
  • Added --generate-uai flag to CLI
  • UAI files saved in datasets/uais/ directory
  • UAI files enable integration with TensorInference.jl
• Comprehensive test coverage in tests/test_dem.py (19 tests)

Issue #5: Syndrome Database Generation ✅

• Implemented sample_syndromes() to generate detection events
• Added save_syndrome_database() to write .npz files
• Created generate_syndrome_database_from_circuit() for CLI integration
• Added --generate-syndromes flag to CLI
• Syndromes saved in datasets/syndromes/ directory
• Comprehensive test coverage in tests/test_syndrome.py

Dataset Organization

Well-structured dataset with separate subdirectories by file type:

datasets/
├── circuits/     # Circuit files (.stim)
├── dems/         # Detector error models (.dem)
├── uais/         # UAI format files (.uai)
└── syndromes/    # Syndrome databases (.npz)

Documentation

New unified guide:

• examples/GETTING_STARTED.md - Comprehensive guide covering:
  • Quick start instructions
  • Step-by-step pipeline explanation
  • UAI format introduction for beginners
  • Detailed format documentation (.stim, .dem, .uai, .npz)
  • Code examples for all use cases
  • Troubleshooting and best practices

Other documentation:

• datasets/README.md - Dataset overview with organization structure
• examples/minimal_example.py - Full pipeline demonstration

Removed redundant files:

• Merged datasets/SYNDROME_DATASET.md into unified guide
• Merged examples/PIPELINE_ILLUSTRATION.md into unified guide

Testing

✅ All 62 tests passing
✅ Circuit generation validated
✅ DEM extraction tested (.dem and .uai formats)
✅ Syndrome sampling tested
✅ CLI integration verified
✅ CI passing on Python 3.10, 3.11, 3.12

Usage Examples

# Generate circuits with DEMs and syndromes
python -m bpdecoderplus.cli -d 3 -r 3 5 7 --generate-dem --generate-syndromes 1000

# Generate circuits with UAI format for probabilistic inference
python -m bpdecoderplus.cli -d 3 -r 3 5 7 --generate-uai

# Generate all formats
python -m bpdecoderplus.cli -d 3 -r 3 5 7 --generate-dem --generate-uai --generate-syndromes 1000

UAI Format

The UAI format represents the DEM as a Markov network:

• Each detector is a binary variable (0 or 1)
• Each error mechanism is a factor/clique
• Factor tables encode error probabilities
• Compatible with TensorInference.jl and other probabilistic inference tools

This enables:

• Exact inference (partition function calculation)
• Marginal probability computation
• MAP (maximum a posteriori) inference
• Integration with tensor network methods

Closes

Closes #12
Closes #4
Closes #5

🤖 Generated with Claude Code

[GiggleLiu]

Looks great! please resolve the conflicts in this pr.

[GiggleLiu]

Good try, impressive speed.

[GiggleLiu]

instead of using markdown, please setup a documentation, and deploy it to GitHub pages.

[GiggleLiu]

All review comments have been addressed:

1. ✅ Claude files removed - Removed .claude/settings.local.json from version control and added to .gitignore (commit 1458f69)

2. ✅ Scripts organized - Moved generate_demo_dataset.py and validate_dataset.py to dedicated scripts/ directory (commit d1dc69f)

3. ✅ Documentation with GitHub Pages - Set up MkDocs with Material theme and automated deployment workflow (commit 8aa716d)

   • Documentation will be deployed to GitHub Pages automatically when merged to main
   • Local preview available with make docs-serve
   • Proper navigation structure with getting started, usage guide, API reference, and mathematical description

4. ✅ Conflicts resolved - Successfully merged with main branch, all conflicts resolved (commit 1458f69)

Ready for final review!