Merge branch 'main' into feat/add-noisy-circuits-dataset

Resolved conflicts and integrated changes from main:
- Updated codecov configuration with token and files parameter
- Added torch dependency to pyproject.toml
- Updated default output path to datasets/noisy_circuits
- Preserved DEM and syndrome generation features from this branch
- Removed .claude/settings.local.json from version control
- Added .claude/settings.local.json to .gitignore
- Added WIP note to README

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: GiggleLiu

.claude/settings.local.json

@@ -31,7 +31,8 @@ jobs:
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
       with:
-        file: ./coverage.xml
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: ./coverage.xml
         flags: unittests
         name: codecov-umbrella
         fail_ci_if_error: false

.github/workflows/test.yml

@@ -38,4 +38,4 @@ uv.lock
 *.blg
 *.fdb_latexmk
 *.synctex.gz
-note/belief_propagation_qec_plan.pdf
+note/belief_propagation_qec_plan.pdf.claude/settings.local.json

.gitignore

@@ -1,5 +1,7 @@
 # BPDecoderPlus: Quantum Error Correction with Belief Propagation
 
+Ｎote: This WIP project is for AI + Quantum winter school training.
+
 [![Tests](https://github.com/GiggleLiu/BPDecoderPlus/actions/workflows/test.yml/badge.svg)](https://github.com/GiggleLiu/BPDecoderPlus/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/GiggleLiu/BPDecoderPlus/branch/main/graph/badge.svg)](https://codecov.io/gh/GiggleLiu/BPDecoderPlus)
 
@@ -186,6 +188,42 @@ BPDecoderPlus/
     └── belief_propagation_qec_plan.tex
 ```
 
+## PyTorch BP Module (UAI)
+
+This repository also includes a PyTorch implementation of belief propagation for
+UAI factor graphs under `src/bpdecoderplus/pytorch_bp`.
+
+### Python Setup
+
+```bash
+pip install -e .
+```
+
+### Quick Example
+
+```python
+from bpdecoderplus.pytorch_bp import (
+    read_model_file,
+    BeliefPropagation,
+    belief_propagate,
+    compute_marginals,
+)
+
+model = read_model_file("examples/simple_model.uai")
+bp = BeliefPropagation(model)
+state, info = belief_propagate(bp)
+print(info)
+print(compute_marginals(state, bp))
+```
+
+### Examples and Tests
+
+```bash
+python examples/simple_example.py
+python examples/evidence_example.py
+pytest tests/test_bp_basic.py tests/test_uai_parser.py tests/test_integration.py tests/testcase.py
+```
+
 ## Available Decoders
 
 | Decoder | Symbol | Description |

README.md

@@ -0,0 +1,234 @@
+# Noisy Circuit Dataset (Surface Code, d=3)
+
+Circuit-level surface-code memory experiments generated with Stim for **Belief Propagation (BP) decoding** demonstrations.
+
+## Overview
+
+| Parameter | Value |
+|-----------|-------|
+| Code | Rotated surface code |
+| Distance | d = 3 |
+| Noise model | i.i.d. depolarizing |
+| Error rate | p = 0.01 |
+| Task | Z-memory experiment |
+| Rounds | 3, 5, 7 |
+
+### Noise Application Points
+- Clifford gates (`after_clifford_depolarization`)
+- Data qubits between rounds (`before_round_data_depolarization`)
+- Resets (`after_reset_flip_probability`)
+- Measurements (`before_measure_flip_probability`)
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `sc_d3_r3_p0010_z.stim` | 3 rounds, p=0.01, Z-memory |
+| `sc_d3_r5_p0010_z.stim` | 5 rounds, p=0.01, Z-memory |
+| `sc_d3_r7_p0010_z.stim` | 7 rounds, p=0.01, Z-memory |
+| `sc_d3_layout.png` | Qubit layout visualization |
+| `parity_check_matrix.png` | BP parity check matrix H |
+| `syndrome_stats.png` | Detection event statistics |
+| `single_syndrome.png` | Example syndrome pattern |
+
+## Qubit Layout
+
+The surface code layout showing qubit positions (data + ancilla):
+
+![Qubit Layout](sc_d3_layout.png)
+
+## Using This Dataset for BP Decoding
+
+### Step 1: Load Circuit and Extract Detector Error Model (DEM)
+
+The Detector Error Model is the key input for BP decoding. It describes which errors trigger which detectors.
+
+```python
+import stim
+import numpy as np
+
+# Load circuit
+circuit = stim.Circuit.from_file("datasets/noisy_circuits/sc_d3_r3_p0010_z.stim")
+
+# Extract DEM - this is what BP needs
+dem = circuit.detector_error_model(decompose_errors=True)
+print(f"Detectors: {dem.num_detectors}")      # 24
+print(f"Error mechanisms: {dem.num_errors}")  # 286
+print(f"Observables: {dem.num_observables}")  # 1
+```
+
+### Step 2: Build Parity Check Matrix H
+
+BP operates on the parity check matrix where `H[i,j] = 1` means error `j` triggers detector `i`.
+
+```python
+def build_parity_check_matrix(dem):
+    """Convert DEM to parity check matrix H and prior probabilities."""
+    errors = []
+    for inst in dem.flattened():
+        if inst.type == 'error':
+            prob = inst.args_copy()[0]
+            dets = [t.val for t in inst.targets_copy() if t.is_relative_detector_id()]
+            obs = [t.val for t in inst.targets_copy() if t.is_logical_observable_id()]
+            errors.append({'prob': prob, 'detectors': dets, 'observables': obs})
+    
+    n_detectors = dem.num_detectors
+    n_errors = len(errors)
+    
+    # Parity check matrix
+    H = np.zeros((n_detectors, n_errors), dtype=np.uint8)
+    # Prior error probabilities (for BP initialization)
+    priors = np.zeros(n_errors)
+    # Which errors flip the logical observable
+    obs_flip = np.zeros(n_errors, dtype=np.uint8)
+    
+    for j, e in enumerate(errors):
+        priors[j] = e['prob']
+        for d in e['detectors']:
+            H[d, j] = 1
+        if e['observables']:
+            obs_flip[j] = 1
+    
+    return H, priors, obs_flip
+
+H, priors, obs_flip = build_parity_check_matrix(dem)
+print(f"H shape: {H.shape}")  # (24, 286)
+```
+
+The parity check matrix structure:
+
+![Parity Check Matrix](parity_check_matrix.png)
+
+### Step 3: Sample Syndromes (Detection Events)
+
+```python
+# Compile sampler
+sampler = circuit.compile_detector_sampler()
+
+# Sample detection events + observable flip
+n_shots = 1000
+samples = sampler.sample(n_shots, append_observables=True)
+
+# Split into syndrome and observable
+syndromes = samples[:, :-1]           # shape: (n_shots, n_detectors)
+actual_obs_flips = samples[:, -1]     # shape: (n_shots,)
+
+print(f"Syndrome shape: {syndromes.shape}")
+print(f"Example syndrome: {syndromes[0]}")
+```
+
+### Step 4: BP Decoding (Pseudocode)
+
+```python
+def bp_decode(H, syndrome, priors, max_iter=50, damping=0.5):
+    """
+    Belief Propagation decoder (min-sum variant).
+    
+    Args:
+        H: Parity check matrix (n_detectors, n_errors)
+        syndrome: Detection events (n_detectors,)
+        priors: Prior error probabilities (n_errors,)
+        max_iter: Maximum BP iterations
+        damping: Message damping factor
+    
+    Returns:
+        estimated_errors: Most likely error pattern (n_errors,)
+        soft_output: Log-likelihood ratios (n_errors,)
+    """
+    n_checks, n_vars = H.shape
+    
+    # Initialize LLRs from priors: LLR = log((1-p)/p)
+    llr_prior = np.log((1 - priors) / priors)
+    
+    # Messages: check-to-variable and variable-to-check
+    # ... BP message passing iterations ...
+    
+    # Hard decision
+    estimated_errors = (soft_output < 0).astype(int)
+    
+    return estimated_errors, soft_output
+
+# Decode each syndrome
+for i in range(n_shots):
+    syndrome = syndromes[i]
+    estimated_errors, _ = bp_decode(H, syndrome, priors)
+    
+    # Predict observable flip
+    predicted_obs_flip = np.dot(estimated_errors, obs_flip) % 2
+    
+    # Check if decoding succeeded
+    success = (predicted_obs_flip == actual_obs_flips[i])
+```
+
+### Step 5: Evaluate Decoder Performance
+
+After decoding, compare predicted vs actual observable flips to measure logical error rate.
+
+```python
+def evaluate_decoder(decoder_fn, circuit, n_shots=10000):
+    """Evaluate decoder logical error rate."""
+    dem = circuit.detector_error_model(decompose_errors=True)
+    H, priors, obs_flip = build_parity_check_matrix(dem)
+    
+    sampler = circuit.compile_detector_sampler()
+    samples = sampler.sample(n_shots, append_observables=True)
+    syndromes = samples[:, :-1]
+    actual_obs = samples[:, -1]
+    
+    errors = 0
+    for i in range(n_shots):
+        est_errors, _ = decoder_fn(H, syndromes[i], priors)
+        pred_obs = np.dot(est_errors, obs_flip) % 2
+        if pred_obs != actual_obs[i]:
+            errors += 1
+    
+    return errors / n_shots
+
+# logical_error_rate = evaluate_decoder(bp_decode, circuit)
+```
+
+## Syndrome Statistics
+
+Detection event frequencies across 1000 shots (left) and baseline observable flip rate without decoding (right):
+
+![Syndrome Statistics](syndrome_stats.png)
+
+## Example Syndrome
+
+A single syndrome sample showing which detectors fired (red = triggered):
+
+![Single Syndrome](single_syndrome.png)
+
+## Regenerating the Dataset
+
+```bash
+# Install the package with uv
+uv sync
+
+# Generate circuits using the CLI
+uv run generate-noisy-circuits \
+  --distance 3 \
+  --p 0.01 \
+  --rounds 3 5 7 \
+  --task z \
+  --output datasets/noisy_circuits
+```
+
+## Extending the Dataset
+
+```bash
+# Different error rates
+uv run generate-noisy-circuits --p 0.005 --rounds 3 5 7
+
+# Different distances
+uv run generate-noisy-circuits --distance 5 --rounds 5 7 9
+
+# X-memory experiment
+uv run generate-noisy-circuits --task x --rounds 3 5 7
+```
+
+## References
+
+- [Stim Documentation](https://github.com/quantumlib/Stim)
+- [BP+OSD Decoder Paper](https://arxiv.org/abs/2005.07016)
+- [Surface Code Decoding Review](https://quantum-journal.org/papers/q-2024-10-10-1498/)