Aegis QEC

Aegis QEC is a hardware-aware quantum error-correction research toolkit built around PyMatching sparse-blossom minimum-weight perfect matching. It adds surface-code graph construction, calibrated weights, erasure and leakage information, correlation-aware experiments, Stim detector-error-model interoperability, benchmarking tools, and an optional interactive workbench.

The PyPI distribution is aegis-qec. The stable public Python namespace is aegis_qec. The historical a3d namespace remains available for compatibility.

Install

Aegis QEC 1.1 requires Python 3.10 or newer. Continuous integration validates the supported release surfaces on Linux and Windows with Python 3.10 and 3.12.

python -m pip install -U aegis-qec

For Stim interoperability and the broader research stack:

python -m pip install -U "aegis-qec[full]"

For the interactive application:

python -m pip install -U "aegis-qec[gui]"

First minute

Aegis has one primary command:

aegis

Start by checking the installation:

aegis doctor

The doctor reports the installed Aegis version, Python version, PyMatching version, active MWPM backend, optional Stim and Streamlit availability, and the result of a small known-answer sparse-blossom decode.

Run a deterministic example:

aegis demo

Measure end-to-end decoder latency:

aegis benchmark --decoder mwpm --distance 5 --rounds 6 --steps 200

Launch the interactive workbench:

aegis gui

The older commands remain available for compatibility and advanced workflows: aegis-run, aegis-metrics, aegis-threshold, aegis-export-header, aegis-bench, aegis-gui, and aegis-ci.

Python API

from aegis_qec import AegisConfig, DecoderRuntime, RotatedSurfaceLayout

cfg = AegisConfig(distance=5, rounds=6)
layout = RotatedSurfaceLayout(cfg.distance)
runtime = DecoderRuntime(cfg, layout)

n_x = len(runtime.builder.node_order("X"))
n_z = len(runtime.builder.node_order("Z"))

result_x, result_z = runtime.decode_from_syndromes_uniform(
    [0] * n_x,
    [0] * n_z,
)

print(result_x.avg_cost, result_z.avg_cost)

AegisConfig() defaults to the mwpm decoder. In Aegis QEC 1.1, that production MWPM path is PyMatching 2.4+ sparse blossom. Experimental OSD polishing, correlation-aware variants, union-find decoding, belief-propagation reweighting, and Transformer reweighting are opt-in.

Sparse blossom

Aegis translates its decoding graph into a PyMatching graph, maps explicit Aegis boundary edges to PyMatching virtual boundaries, and assigns each Aegis edge a PyMatching fault identifier. The returned correction vector can therefore be mapped back to concrete Aegis correction edges.

The production backend identifies itself as:

pymatching-sparse-blossom

Aegis does not silently replace sparse blossom with the historical NetworkX MWPM implementation.

About the >100,000× result

The greater-than-100,000-times figure is not an Aegis-wide performance claim. It is the result reported for PyMatching's published surface-code benchmark against NetworkX.

Aegis uses that PyMatching implementation, but Aegis end-to-end execution can also include graph construction, result reconstruction, optional reweighting, logging, and other work. When quoting performance, name the workload, code distance, number of rounds, decoder, dependency versions, hardware, and whether the measurement is kernel-only or end-to-end.

See benchmarking documentation for the evidence policy and benchmark definitions.

Reference: Oscar Higgott and Craig Gidney, Sparse Blossom: correcting a million errors per core second with minimum-weight matching, Quantum 9, 1600 (2025), DOI 10.22331/q-2025-01-20-1600.

Interactive workbench

The Streamlit application is designed around experiments rather than internal class names. It shows the active environment and backend, labels the recommended sparse-blossom path separately from experimental decoders, and provides three guided activities:

• a deterministic synthetic decode with timing and correction summaries;
• an end-to-end latency experiment with p50, p95, and p99 measurements;
• a correction-validation sweep for synthetic detection-event inputs.

The validation sweep is deliberately not presented as a circuit-level logical-error-rate measurement. See the benchmarking documentation for the distinction.

Stim and detector error models

A Stim detector error model describes error mechanisms, detector connectivity, and observables. It does not contain the observed detection events for a particular shot. Aegis therefore requires explicit observed detector bits when decoding a DEM.

from a3d.decoder_mwpm_pm import PyMatchingMWPMDecoder

decoder = PyMatchingMWPMDecoder()
prediction = decoder.decode_from_dem(
    "error(0.01) D0 D1\n",
    syndrome=[1, 1],
)

Development

git clone https://github.com/hamidbahri92/Aegis.git
cd Aegis
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,gui]"
aegis-ci

On Windows PowerShell, activate the environment with .\.venv\Scripts\Activate.ps1.

Hosted CI and aegis-ci both enforce a repository-wide real-defect Ruff gate, stricter linting on the Aegis QEC release surfaces, the test suite, and package build validation. Hosted CI additionally builds the distribution, checks its long description with Twine, installs the built wheel, and exercises the user-facing commands.

Release identity

Use Aegis QEC as the product name in prose. Use aegis-qec for the PyPI distribution and aegis_qec for the public Python import. a3d is a compatibility namespace.

Version 1.1.0 is the release that establishes this identity, makes sparse-blossom MWPM the true default path, and introduces the unified aegis command.

See the changelog for release notes.

Citation

If Aegis QEC contributes to published work, cite Aegis and the underlying decoder implementation used by the experiment. Sparse-blossom algorithm and performance claims should credit Higgott and Gidney. Machine-readable citation metadata is provided in CITATION.cff.

License

MIT. See LICENSE.