Add syndrome database generation (Issue #5)

- Add syndrome.py module for sampling and saving syndromes
- Integrate syndrome generation into CLI with --generate-syndromes flag
- Add comprehensive test suite for syndrome operations
- Add make generate-syndromes target for easy database creation
- Support npz format with metadata for efficient storage

Features:
- Sample detection events from circuits
- Save/load syndrome databases with metadata
- Generate databases directly from circuit files
- CLI integration for automated workflow

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

Author: ChanceSiyuan

Makefile

@@ -1,13 +1,14 @@
-.PHONY: help install setup test test-cov generate-dataset clean
+.PHONY: help install setup test test-cov generate-dataset generate-syndromes clean
 
 help:
 	@echo "Available targets:"
-	@echo "  install          - Install uv package manager"
-	@echo "  setup            - Set up development environment with uv"
-	@echo "  generate-dataset - Generate noisy circuit dataset"
-	@echo "  test             - Run tests"
-	@echo "  test-cov         - Run tests with coverage report"
-	@echo "  clean            - Remove generated files and caches"
+	@echo "  install            - Install uv package manager"
+	@echo "  setup              - Set up development environment with uv"
+	@echo "  generate-dataset   - Generate noisy circuit dataset"
+	@echo "  generate-syndromes - Generate syndrome database (1000 shots)"
+	@echo "  test               - Run tests"
+	@echo "  test-cov           - Run tests with coverage report"
+	@echo "  clean              - Remove generated files and caches"
 
 install:
 	@command -v uv >/dev/null 2>&1 || { \
@@ -21,6 +22,9 @@ setup: install
 generate-dataset:
 	uv run generate-noisy-circuits --distance 3 --p 0.01 --rounds 3 5 7 --task z --output datasets/noisy_circuits
 
+generate-syndromes:
+	uv run generate-noisy-circuits --distance 3 --p 0.01 --rounds 3 5 7 --task z --output datasets/noisy_circuits --generate-syndromes 1000
+
 test:
 	uv run pytest
 

src/bpdecoderplus/cli.py

@@ -1,5 +1,5 @@
 """
-Command-line interface for generating noisy surface-code circuits.
+Command-line interface for generating noisy surface-code circuits and syndrome databases.
 """
 
 from __future__ import annotations
@@ -15,6 +15,7 @@
     run_smoke_test,
     write_circuit,
 )
+from bpdecoderplus.syndrome import generate_syndrome_database_from_circuit
 
 
 def create_parser() -> argparse.ArgumentParser:
@@ -63,6 +64,12 @@ def create_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Skip compiling and sampling for quick validation",
     )
+    parser.add_argument(
+        "--generate-syndromes",
+        type=int,
+        metavar="NUM_SHOTS",
+        help="Generate syndrome database with specified number of shots",
+    )
     return parser
 
 
@@ -110,6 +117,13 @@ def main(argv: list[str] | None = None) -> int:
         write_circuit(circuit, output_path)
         print(f"Wrote {output_path}")
 
+        # Generate syndrome database if requested
+        if args.generate_syndromes:
+            syndrome_path = generate_syndrome_database_from_circuit(
+                output_path, args.generate_syndromes
+            )
+            print(f"Wrote {syndrome_path}")
+
     print("Done.")
     return 0
 

src/bpdecoderplus/syndrome.py

@@ -0,0 +1,139 @@
+"""
+Syndrome database generation module for noisy surface-code circuits.
+
+This module provides functions to sample detection events (syndromes) from
+circuits and save them in a structured format for decoder training/testing.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any
+
+import numpy as np
+import stim
+
+
+def sample_syndromes(
+    circuit: stim.Circuit,
+    num_shots: int,
+    include_observables: bool = True,
+) -> tuple[np.ndarray, np.ndarray | None]:
+    """
+    Sample detection events (syndromes) from a circuit.
+
+    Args:
+        circuit: Stim circuit to sample from.
+        num_shots: Number of syndrome samples to generate.
+        include_observables: Whether to include observable flip outcomes.
+
+    Returns:
+        Tuple of (syndromes, observables) where:
+        - syndromes: Array of shape (num_shots, num_detectors)
+        - observables: Array of shape (num_shots,) if include_observables else None
+    """
+    sampler = circuit.compile_detector_sampler()
+    samples = sampler.sample(num_shots, append_observables=include_observables)
+
+    if include_observables:
+        syndromes = samples[:, :-1]
+        observables = samples[:, -1]
+        return syndromes, observables
+    else:
+        return samples, None
+
+
+def save_syndrome_database(
+    syndromes: np.ndarray,
+    observables: np.ndarray | None,
+    output_path: pathlib.Path,
+    metadata: dict[str, Any] | None = None,
+) -> None:
+    """
+    Save syndrome database to disk in npz format.
+
+    Args:
+        syndromes: Array of detection events, shape (num_shots, num_detectors).
+        observables: Array of observable flips, shape (num_shots,), or None.
+        output_path: Path to save the database (.npz file).
+        metadata: Optional metadata dictionary to save alongside the data.
+    """
+    save_dict = {"syndromes": syndromes}
+
+    if observables is not None:
+        save_dict["observables"] = observables
+
+    if metadata is not None:
+        # Save metadata as JSON string in the npz file
+        save_dict["metadata"] = np.array([json.dumps(metadata)])
+
+    np.savez_compressed(output_path, **save_dict)
+
+
+def load_syndrome_database(
+    input_path: pathlib.Path,
+) -> tuple[np.ndarray, np.ndarray | None, dict[str, Any] | None]:
+    """
+    Load syndrome database from disk.
+
+    Args:
+        input_path: Path to the database file (.npz).
+
+    Returns:
+        Tuple of (syndromes, observables, metadata) where:
+        - syndromes: Array of shape (num_shots, num_detectors)
+        - observables: Array of shape (num_shots,) or None
+        - metadata: Dictionary of metadata or None
+    """
+    data = np.load(input_path, allow_pickle=True)
+
+    syndromes = data["syndromes"]
+    observables = data.get("observables", None)
+
+    metadata = None
+    if "metadata" in data:
+        metadata = json.loads(str(data["metadata"][0]))
+
+    return syndromes, observables, metadata
+
+
+def generate_syndrome_database_from_circuit(
+    circuit_path: pathlib.Path,
+    num_shots: int,
+    output_path: pathlib.Path | None = None,
+) -> pathlib.Path:
+    """
+    Generate and save syndrome database from a circuit file.
+
+    Args:
+        circuit_path: Path to the circuit file (.stim).
+        num_shots: Number of syndrome samples to generate.
+        output_path: Optional output path. If None, uses circuit_path with .npz extension.
+
+    Returns:
+        Path to the saved database file.
+    """
+    # Load circuit
+    circuit = stim.Circuit.from_file(str(circuit_path))
+
+    # Generate output path if not provided
+    if output_path is None:
+        output_path = circuit_path.with_suffix(".npz")
+
+    # Sample syndromes
+    syndromes, observables = sample_syndromes(circuit, num_shots, include_observables=True)
+
+    # Create metadata
+    dem = circuit.detector_error_model()
+    metadata = {
+        "circuit_file": str(circuit_path.name),
+        "num_shots": num_shots,
+        "num_detectors": dem.num_detectors,
+        "num_observables": dem.num_observables,
+    }
+
+    # Save database
+    save_syndrome_database(syndromes, observables, output_path, metadata)
+
+    return output_path

tests/test_syndrome.py

@@ -0,0 +1,172 @@
+"""Tests for syndrome database generation module."""
+
+from __future__ import annotations
+
+import pathlib
+import tempfile
+
+import numpy as np
+import pytest
+import stim
+
+from bpdecoderplus.circuit import generate_circuit
+from bpdecoderplus.syndrome import (
+    generate_syndrome_database_from_circuit,
+    load_syndrome_database,
+    sample_syndromes,
+    save_syndrome_database,
+)
+
+
+class TestSampleSyndromes:
+    """Tests for sample_syndromes function."""
+
+    def test_basic_sampling(self):
+        """Test basic syndrome sampling."""
+        circuit = generate_circuit(distance=3, rounds=3, p=0.01, task="z")
+        syndromes, observables = sample_syndromes(circuit, num_shots=10)
+
+        assert syndromes.shape[0] == 10
+        assert observables.shape == (10,)
+        assert syndromes.dtype == np.uint8
+        assert observables.dtype == np.uint8
+
+    def test_without_observables(self):
+        """Test sampling without observables."""
+        circuit = generate_circuit(distance=3, rounds=3, p=0.01, task="z")
+        syndromes, observables = sample_syndromes(
+            circuit, num_shots=10, include_observables=False
+        )
+
+        assert syndromes.shape[0] == 10
+        assert observables is None
+
+    def test_num_detectors(self):
+        """Test that number of detectors matches circuit."""
+        circuit = generate_circuit(distance=3, rounds=3, p=0.01, task="z")
+        dem = circuit.detector_error_model()
+        syndromes, _ = sample_syndromes(circuit, num_shots=5)
+
+        assert syndromes.shape[1] == dem.num_detectors
+
+
+class TestSaveSyndromeDatabase:
+    """Tests for save_syndrome_database function."""
+
+    def test_save_with_observables(self):
+        """Test saving database with observables."""
+        syndromes = np.random.randint(0, 2, size=(10, 24), dtype=np.uint8)
+        observables = np.random.randint(0, 2, size=10, dtype=np.uint8)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_path = pathlib.Path(tmpdir) / "test.npz"
+            save_syndrome_database(syndromes, observables, output_path)
+
+            assert output_path.exists()
+
+    def test_save_without_observables(self):
+        """Test saving database without observables."""
+        syndromes = np.random.randint(0, 2, size=(10, 24), dtype=np.uint8)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_path = pathlib.Path(tmpdir) / "test.npz"
+            save_syndrome_database(syndromes, None, output_path)
+
+            assert output_path.exists()
+
+    def test_save_with_metadata(self):
+        """Test saving database with metadata."""
+        syndromes = np.random.randint(0, 2, size=(10, 24), dtype=np.uint8)
+        observables = np.random.randint(0, 2, size=10, dtype=np.uint8)
+        metadata = {"distance": 3, "rounds": 3, "p": 0.01}
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_path = pathlib.Path(tmpdir) / "test.npz"
+            save_syndrome_database(syndromes, observables, output_path, metadata)
+
+            assert output_path.exists()
+
+
+class TestLoadSyndromeDatabase:
+    """Tests for load_syndrome_database function."""
+
+    def test_load_with_observables(self):
+        """Test loading database with observables."""
+        syndromes = np.random.randint(0, 2, size=(10, 24), dtype=np.uint8)
+        observables = np.random.randint(0, 2, size=10, dtype=np.uint8)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_path = pathlib.Path(tmpdir) / "test.npz"
+            save_syndrome_database(syndromes, observables, output_path)
+
+            loaded_syndromes, loaded_observables, _ = load_syndrome_database(output_path)
+
+            np.testing.assert_array_equal(loaded_syndromes, syndromes)
+            np.testing.assert_array_equal(loaded_observables, observables)
+
+    def test_load_without_observables(self):
+        """Test loading database without observables."""
+        syndromes = np.random.randint(0, 2, size=(10, 24), dtype=np.uint8)
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_path = pathlib.Path(tmpdir) / "test.npz"
+            save_syndrome_database(syndromes, None, output_path)
+
+            loaded_syndromes, loaded_observables, _ = load_syndrome_database(output_path)
+
+            np.testing.assert_array_equal(loaded_syndromes, syndromes)
+            assert loaded_observables is None
+
+    def test_load_with_metadata(self):
+        """Test loading database with metadata."""
+        syndromes = np.random.randint(0, 2, size=(10, 24), dtype=np.uint8)
+        observables = np.random.randint(0, 2, size=10, dtype=np.uint8)
+        metadata = {"distance": 3, "rounds": 3, "p": 0.01}
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_path = pathlib.Path(tmpdir) / "test.npz"
+            save_syndrome_database(syndromes, observables, output_path, metadata)
+
+            _, _, loaded_metadata = load_syndrome_database(output_path)
+
+            assert loaded_metadata == metadata
+
+
+class TestGenerateSyndromeDatabaseFromCircuit:
+    """Tests for generate_syndrome_database_from_circuit function."""
+
+    def test_generate_from_circuit_file(self):
+        """Test generating database from circuit file."""
+        circuit = generate_circuit(distance=3, rounds=3, p=0.01, task="z")
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            circuit_path = pathlib.Path(tmpdir) / "test.stim"
+            circuit_path.write_text(str(circuit))
+
+            db_path = generate_syndrome_database_from_circuit(circuit_path, num_shots=20)
+
+            assert db_path.exists()
+            assert db_path.suffix == ".npz"
+
+            # Load and verify
+            syndromes, observables, metadata = load_syndrome_database(db_path)
+            assert syndromes.shape[0] == 20
+            assert observables.shape == (20,)
+            assert metadata["num_shots"] == 20
+            assert metadata["circuit_file"] == "test.stim"
+
+    def test_custom_output_path(self):
+        """Test generating database with custom output path."""
+        circuit = generate_circuit(distance=3, rounds=3, p=0.01, task="z")
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            circuit_path = pathlib.Path(tmpdir) / "test.stim"
+            circuit_path.write_text(str(circuit))
+
+            custom_output = pathlib.Path(tmpdir) / "custom_db.npz"
+            db_path = generate_syndrome_database_from_circuit(
+                circuit_path, num_shots=15, output_path=custom_output
+            )
+
+            assert db_path == custom_output
+            assert db_path.exists()