backlog-qec 0.5.0__tar.gz

backlog_qec-0.5.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.pyc
+.venv/
+
+# build outputs
+cpp/build/
+cpp/build-tsan/
+hardware/build/
+*.o
+*.cf
+
+# regenerated by the scripts
+cpp/testdata*/
+results/quick/
+results/scaling/
+results/sweep_log.txt

backlog_qec-0.5.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 0.5.0 (2026-11-05)
+
+- Correlated (two-pass) decoding in the whole-shot, sliding-window and
+  parallel-window decoders, exact against the reference decoder on the
+  reweighted graph. `correlated=True`, `alpha=`, `dem_correlations`,
+  `regularization_strength`, sinter decoder `backlog-uf-corr`.
+- The regularized reweighting rule of Hernando de la Fuente et al.
+  (arXiv:2610.26785), and an exhaustive check of what it buys: every pair of
+  faults at d = 5 decoded by every decoder.
+- `decompose_by_basis`: every error split into its X part and its Z part.
+  Correlated decoding needs it: on Stim's own decomposition it is worse than
+  plain decoding at d = 3, for PyMatching too (reported upstream as
+  [PyMatching#193](https://github.com/oscarhiggott/PyMatching/issues/193)).
+- Parallel windows: a seam starts as soon as its two cores are done (no
+  barrier), PAUSE in spin loops, no spinning on hyperthreads, exceptions on
+  worker threads carried back to the caller. `make scaling` splits the
+  speedup into work inflation and idle time.
+- Benchmarks: correlated accuracy and speed against PyMatching (same shots),
+  error suppression factor, fault enumeration, laptop scaling analysis.
+- Quickstart notebook, wheels workflow for PyPI, citation file, contributing
+  notes, related-work survey, 26 mutants.
+- Builds with Apple Clang and MSVC as well as GCC, and CI runs the C++ and
+  Python test suites on macOS and Windows on every push.
+
+## 0.4.0 (2026-11-04)
+
+- Parallel window decoding (core windows, then seams) on a thread pool, same
+  answer for any number of threads, clean under ThreadSanitizer.
+- Scheduling model and projection of the cores needed for real time; real
+  speedup measured on 2 cores, then up to 8 threads (`make scaling`).
+
+## 0.3.0 (2026-11-04)
+
+- Sliding-window decoder for streaming, windows with the same structure
+  sharing one decoder; the backlog measured with 1 µs rounds.
+
+## 0.2.0 (2026-11-04)
+
+- Weighted, event-driven Union-Find (exact equivalent of synchronous rounds),
+  a reference decoder and differential fuzzing between them.
+- Python package (pybind11), Stim error model conversion, sinter decoders.
+- Accuracy gates and benchmarks against PyMatching, mutation testing.
+
+## 0.1.0 (2026-11-04)
+
+- Stim + PyMatching baseline and threshold plot, a first C++ Union-Find
+  decoder with a command-line tool, a 1D Union-Find core in VHDL checked bit
+  for bit, CI.

backlog_qec-0.5.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use backlog in your work, please cite it as below."
+title: "backlog: a real-time Union-Find decoder for quantum error correction, from simulation to FPGA"
+abstract: >-
+  An open-source weighted Union-Find decoder for the surface code, exact to a
+  synchronous reference, with correlated (two-pass) decoding and the
+  regularized reweighting rule, sliding and parallel window decoding for
+  streaming, Stim and sinter integration, and a VHDL implementation checked
+  bit for bit against the C++ model.
+authors:
+  - family-names: "Dorélas"
+    given-names: "Jean-Cédrik"
+type: software
+license: MIT
+version: "0.5.0"
+date-released: "2026-11-05"
+repository-code: "https://github.com/jcedrik/backlog"
+keywords:
+  - quantum error correction
+  - surface code
+  - decoder
+  - union-find
+  - correlated decoding
+  - real-time decoding
+  - FPGA

backlog_qec-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to backlog
+
+Issues and pull requests are welcome: bug reports, new noise models or codes,
+faster decoding, hardware work.
+
+## Set up
+
+```bash
+git clone https://github.com/jcedrik/backlog && cd backlog
+python3 -m venv .venv && source .venv/bin/activate
+make install          # builds the C++ core, installs the package with test extras
+make test             # C++ fuzzing against the reference, pytest, CLI checks
+```
+
+You need a C++17 compiler, CMake 3.18+ and Python 3.10+. `make help` lists
+every target.
+
+## What a change needs to pass
+
+The CI runs all of these on every push; run them locally first.
+
+| Check | Command | What it guards |
+|---|---|---|
+| C++ tests | `make test-cpp` | the fast decoder equals the reference decoder edge for edge, on 75,000 random cases per fuzzer, including correlated decoding and both window decoders |
+| Python tests | `make test-py` | accuracy gates against PyMatching on real Stim circuits, sinter integration, exhaustive fault checks |
+| ThreadSanitizer | `make tsan` | no data race in the parallel window decoder |
+| Mutation testing | `make mutants` | every injected bug (26 of them) makes the suite fail; a new feature should come with a mutant its tests kill |
+| VHDL | `make hw-sim` | the hardware decoder agrees with the C++ model bit for bit |
+
+The decoder has a specification: `ReferenceDecoder` (synchronous rounds,
+written to be obviously correct). A change to the fast decoder must keep the
+two identical; a change to the semantics changes the reference first.
+
+## Benchmarks
+
+Benchmark scripts write their CSVs and figures to `results/`. If a change
+moves a published number, rerun the script that produced it and commit the
+new results with the change, with the machine it ran on.
+
+## Releasing (maintainer)
+
+Wheels for Linux, macOS and Windows are built by `.github/workflows/wheels.yml`.
+To publish to PyPI without storing a token, once:
+
+1. on pypi.org, Account settings > Publishing > Add a new pending publisher:
+   project `backlog-qec`, owner `jcedrik`, repository `backlog`, workflow
+   `wheels.yml`, environment `pypi`;
+2. on GitHub, Settings > Environments > New environment `pypi`.
+
+Then a release is: bump the version in `pyproject.toml` and
+`src/backlog/__init__.py`, add its entry to `CHANGELOG.md`, commit, then push a
+signed tag (`git tag -s v0.5.0 -m "backlog 0.5.0" && git push origin v0.5.0`).
+The PyPI page shows `docs/pypi.md`, so its links must be absolute.

backlog_qec-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean-Cédrik Dorélas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backlog_qec-0.5.0/Makefile

@@ -0,0 +1,101 @@
+PY ?= python3
+
+.PHONY: help deps install cpp test test-cpp test-py test-cli mutants tsan quick baseline plot \
+        compare plots streaming streaming-plot parallel parallel-plot scaling latency correlated \
+        correlated-speed correlated-plot faults faults-plot quickstart hw hw-sim all clean
+
+help:  ## list targets
+	@grep -E '^[a-z-]+:.*##' $(MAKEFILE_LIST) | sed -E 's/:.*## /\t/'
+
+deps:  ## install the Python dependencies of the experiments
+	$(PY) -m pip install -r requirements.txt
+
+install:  ## build the C++ core and install the backlog Python package (use a virtualenv)
+	$(PY) -m pip install ".[test]"
+
+cpp:  ## build the C++ command-line decoder and the C++ test suite
+	cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=Release
+	cmake --build cpp/build -j
+
+test: test-cpp test-py test-cli  ## all tests except the slow sweeps (run make install first)
+
+test-cpp: cpp  ## C++ unit tests + 75,000 fuzzed cases, fast decoder == reference decoder
+	cd cpp/build && ctest --output-on-failure
+
+test-py:  ## pytest: accuracy gates against PyMatching, sinter integration
+	$(PY) -m pytest -q
+
+test-cli: cpp  ## command-line decoder on graphs exported from Stim, gated against PyMatching
+	./scripts/run_tests.sh
+
+mutants:  ## mutation testing: each of 26 injected bugs must make the test suite fail (~10 min)
+	$(PY) scripts/mutation_test.py
+
+tsan:  ## C++ test suite under ThreadSanitizer: any data race fails the run (~5 min)
+	cmake -S cpp -B cpp/build-tsan -DCMAKE_BUILD_TYPE=Debug -DBACKLOG_TSAN=ON
+	cmake --build cpp/build-tsan -j --target backlog_tests
+	TSAN_OPTIONS=halt_on_error=1 ./cpp/build-tsan/backlog_tests
+
+quick:  ## tiny PyMatching threshold sweep into results/quick/ (smoke test, seconds)
+	cd python && $(PY) baseline_threshold.py --quick && $(PY) plot_threshold.py --results-dir ../results/quick
+
+baseline:  ## PyMatching-only threshold sweep (a few minutes), see results/threshold.png
+	cd python && $(PY) baseline_threshold.py --max-shots 300000 --max-errors 1000
+
+plot:  ## redraw results/threshold.png from results/threshold_data.csv
+	cd python && $(PY) plot_threshold.py
+
+compare:  ## sinter sweep, PyMatching vs weighted and unweighted UF (long, resumable)
+	cd python && $(PY) threshold_comparison.py collect && $(PY) threshold_comparison.py plot
+
+plots:  ## redraw the comparison figures from results/threshold_comparison.csv
+	cd python && $(PY) threshold_comparison.py plot
+
+streaming:  ## sliding windows: accuracy vs buffer, per-window latency, backlog (minutes, idle machine)
+	cd python && $(PY) streaming_benchmark.py accuracy && $(PY) streaming_benchmark.py latency \
+	  && $(PY) streaming_benchmark.py plot
+
+streaming-plot:  ## redraw results/streaming.png from the CSVs
+	cd python && $(PY) streaming_benchmark.py plot
+
+parallel:  ## parallel windows: accuracy, 1 vs 2 thread speedup, cores needed (minutes, idle machine)
+	cd python && $(PY) parallel_benchmark.py accuracy && $(PY) parallel_benchmark.py speedup \
+	  && $(PY) parallel_benchmark.py project && $(PY) parallel_benchmark.py plot
+
+parallel-plot:  ## redraw results/parallel.png from the saved data
+	cd python && $(PY) parallel_benchmark.py plot
+
+scaling:  ## real speedup with 1, 2, 4, ... threads up to every core here, into results/scaling/
+	cd python && $(PY) parallel_benchmark.py scaling
+
+correlated:  ## correlated decoding vs plain and vs PyMatching, same shots (~15 min on 2 cores)
+	$(PY) python/correlated_benchmark.py accuracy && $(PY) python/correlated_benchmark.py decomposition
+
+correlated-speed:  ## decoding time of plain and correlated decoders (idle machine)
+	$(PY) python/correlated_benchmark.py speed
+
+correlated-plot:  ## redraw results/correlated.png and print the Lambda table
+	$(PY) python/correlated_benchmark.py plot
+
+faults:  ## exhaustive fault enumeration, d = 3 and 5: which pairs each decoder gets wrong (~6 min)
+	$(PY) python/fault_distance.py
+
+faults-plot:  ## redraw results/fault_distance.png
+	$(PY) python/fault_distance.py --plot
+
+quickstart:  ## rebuild and run examples/quickstart.ipynb (needs nbformat, nbclient, ipykernel)
+	$(PY) examples/make_quickstart.py
+
+latency:  ## decoding time vs PyMatching, d = 3 to 13 (run on an idle machine)
+	cd python && $(PY) latency_benchmark.py
+
+hw:  ## VHDL: bit-exact simulation, synthesis, place and route
+	./hardware/run_hw.sh
+
+hw-sim:  ## VHDL: simulation only
+	./hardware/run_hw.sh sim
+
+all: test tsan mutants quick hw-sim  ## everything CI runs
+
+clean:  ## remove build outputs
+	rm -rf cpp/build cpp/build-tsan hardware/build cpp/testdata* results/quick build _skbuild

backlog_qec-0.5.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.2
+Name: backlog-qec
+Version: 0.5.0
+Summary: Real-time Union-Find decoder for quantum error correction: correlated, streaming, parallel, with Stim and sinter integration
+Keywords: quantum error correction,decoder,union-find,correlated decoding,real-time decoding,stim,sinter,surface code,fpga
+Author: Jean-Cédrik Dorélas
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Project-URL: Homepage, https://github.com/jcedrik/backlog
+Project-URL: Documentation, https://github.com/jcedrik/backlog/blob/main/docs/decoder.md
+Project-URL: Issues, https://github.com/jcedrik/backlog/issues
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: stim>=1.14
+Requires-Dist: sinter>=1.14
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pymatching>=2.3; extra == "test"
+Description-Content-Type: text/markdown
+
+# backlog
+
+**A real-time quantum error correction decoder: weighted Union-Find for the
+surface code, with correlated decoding, streaming window decoders and Stim and
+sinter integration.**
+
+- As fast as PyMatching on one core, within 0 to 20% of its accuracy.
+- Correlated (two-pass) decoding, with the regularized rule of
+  [arXiv:2610.26785](https://arxiv.org/abs/2610.26785): 32 to 67% fewer
+  logical errors than plain Union-Find at d = 7, within a few percent of
+  PyMatching's correlated matching, faster than it from d = 13.
+- Sliding-window and parallel-window decoders for streaming.
+- Tested edge for edge against a reference implementation, with exhaustive
+  fault enumeration, ThreadSanitizer and mutation testing.
+
+```bash
+pip install backlog-qec
+```
+
+```python
+import backlog, stim
+
+circuit = stim.Circuit.generated("surface_code:rotated_memory_z", distance=5, rounds=5,
+                                 after_clifford_depolarization=0.003)
+dets, obs = circuit.compile_detector_sampler().sample(100_000, separate_observables=True)
+
+decoder = backlog.UnionFindDecoder.from_circuit(circuit, correlated=True)
+print("logical error rate:", (decoder.decode_batch(dets) != obs).any(axis=1).mean())
+```
+
+As sinter decoders: `backlog-uf`, `backlog-uf-corr` (pass
+`custom_decoders=backlog.sinter_decoders()`).
+
+![Correlated decoding against plain decoding, same shots](https://raw.githubusercontent.com/jcedrik/backlog/main/results/correlated.png)
+
+Results, how it works and how to reproduce everything:
+[github.com/jcedrik/backlog](https://github.com/jcedrik/backlog) ·
+[quickstart notebook](https://github.com/jcedrik/backlog/blob/main/examples/quickstart.ipynb) ·
+[how the decoder works](https://github.com/jcedrik/backlog/blob/main/docs/decoder.md) ·
+[state of the art](https://github.com/jcedrik/backlog/blob/main/docs/related-work.md)
+
+MIT license. To cite: [CITATION.cff](https://github.com/jcedrik/backlog/blob/main/CITATION.cff).