Bivariate Bicycle Neural Decoder

Neural network decoder for IBM bivariate bicycle (BB) qLDPC codes — reproducing and extending Blue et al. (arXiv:2504.13043) and benchmarking against BP-OSD (Roffe et al. 2020) and Relay-BP (Müller et al., arXiv:2506.01779) on the [[72,12,6]] and [[144,12,12]] gross codes.

See docs/PLAN.md for the full project plan, success tiers, and phase structure.

Quickstart

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e ".[dev]"

# Sanity-check core deps:
python -c "import stim, sinter, ldpc, torch; print('ok')"

# Run tests:
pytest -q

relay-bp requires a separate install (Rust toolchain). See https://github.com/trmue/relay and Phase 3 of the plan.

Running baselines (Phase 3)

# All baselines on gross_72, T=12 rounds, default p-sweep, writes a CSV.
python scripts/06_benchmark_all.py \
    --code gross_72 --rounds 12 \
    --decoders bposd matching matching_bb \
    --shots 4096

# BP+OSD (LSD-CS, order 10) alone:
python scripts/01_run_baseline_bposd.py --code gross_72 --rounds 12 --shots 4096

# Relay-BP (requires `pip install relay-bp` first):
python scripts/02_run_baseline_relaybp.py --code gross_72 --rounds 12 --shots 4096

matching and matching_bb are sanity baselines: PyMatching's MWPM algorithm cannot decode the BB code's closed-component matching graph for a sizable fraction of syndromes, so the decoders fall back to a trivial prediction on those shots. The proper Sahay-style boundary-edge construction is a Phase-8 follow-up.

Layout

src/bb_decoder/   # library
configs/          # Hydra configs
scripts/          # entrypoints
notebooks/        # exploration + paper figures
tests/            # pytest suite
docs/PLAN.md      # full plan

References

• Bravyi et al., Nature 627, 778 (2024) — BB codes. arXiv:2308.07915
• Blue et al., arXiv:2504.13043 (2025) — ML decoder for BB codes. Primary reference.
• Müller et al., arXiv:2506.01779 (2025) — Relay-BP.
• Bausch et al., Nature (2024) and arXiv:2512.07737 — AlphaQubit / AlphaQubit 2.
• Roffe et al., Phys. Rev. Research 2, 043423 (2020) — BP-OSD.