Metadata-Version: 2.4
Name: aegis-qec
Version: 1.1.0
Summary: Hardware-aware quantum error-correction research toolkit with sparse-blossom MWPM.
Author: Hamid Bahri
License-Expression: MIT
Project-URL: Homepage, https://github.com/hamidbahri92/Aegis
Project-URL: Repository, https://github.com/hamidbahri92/Aegis
Project-URL: Issues, https://github.com/hamidbahri92/Aegis/issues
Project-URL: PyPI, https://pypi.org/project/aegis-qec/
Keywords: quantum-error-correction,qec,surface-code,mwpm,pymatching
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pymatching<3,>=2.4
Requires-Dist: matplotlib>=3.5.0
Provides-Extra: full
Requires-Dist: pyarrow>=10.0.0; extra == "full"
Requires-Dist: stim<2,>=1.16; extra == "full"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: stim<2,>=1.16; extra == "dev"
Provides-Extra: gui
Requires-Dist: streamlit>=1.50; extra == "gui"
Dynamic: license-file

# Aegis QEC

[![PyPI](https://img.shields.io/pypi/v/aegis-qec.svg)](https://pypi.org/project/aegis-qec/)
![Python](https://img.shields.io/pypi/pyversions/aegis-qec.svg)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/hamidbahri92/Aegis/blob/main/LICENSE)
![CI](https://github.com/hamidbahri92/Aegis/actions/workflows/ci.yml/badge.svg)

**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.

```bash
python -m pip install -U aegis-qec
```

For Stim interoperability and the broader research stack:

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

For the interactive application:

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

## First minute

Aegis has one primary command:

```bash
aegis
```

Start by checking the installation:

```bash
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:

```bash
aegis demo
```

Measure end-to-end decoder latency:

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

Launch the interactive workbench:

```bash
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

```python
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:

```text
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](https://github.com/hamidbahri92/Aegis/blob/main/docs/BENCHMARKING.md) 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.

```python
from a3d.decoder_mwpm_pm import PyMatchingMWPMDecoder

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

## Development

```bash
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](https://github.com/hamidbahri92/Aegis/blob/main/CHANGELOG.md) 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](https://github.com/hamidbahri92/Aegis/blob/main/CITATION.cff).

## License

MIT. See [LICENSE](https://github.com/hamidbahri92/Aegis/blob/main/LICENSE).
