✨ Add concatenated magic-state distillation

[burgholzer]

🤖 AI text below 🤖

Description

Add the magic-state-distillation benchmark for concatenated 15-to-1 Reed–Muller distillation. C++, Python, strict JSON, manifests, and the CLI support levels 1–4, allocating exactly 15, 225, 3,375, or 50,625 qubits. Each level consumes the retained quantum outputs of its children. The two-bit result reports any rejected block and checks the root T state; ideal inputs produce 00.

The implementation uses a fixed decoder, measurement-dependent Clifford corrections, and structured loops around a reusable block. It models ideal inputs without noise, retries, or physical error correction. Reusing the measured root for the rejection readout preserves the qubit count and permits Adaptive QIR execution through the existing result interface.

Compiled OpenQASM exposed a DD interpreter gap for parameterized qco.call gate helpers. Reuse the existing call interpreter with its parameter bindings, wire mapping, and recursion checks. Add a nested-call regression that checks global phase as well as functionality, statevectors, and sampling.

Include executable examples, generated Python stubs, and Unreleased changelog entries. No new dependencies or migrations are needed. Codex assisted with implementation, tests, documentation, and this PR.

Validation

• CI simulates level 1 only, with 16 shots for direct DD sampling, DDSIM Adaptive QIR, and DDSIM OpenQASM 3. Each returns {"00": 16}. Higher levels retain inexpensive generation and metadata checks; level 2 simulation is excluded from CI.
• With 16 shots, median sampling times over three runs were 0.190 s (direct), 0.181 s (Adaptive QIR), and 0.155 s (OpenQASM 3). The corresponding 256-shot medians were 4.163 s, 2.164 s, and 2.335 s. Generation took 0.014 s; target compilation took 0.070 s for Adaptive QIR and 0.038 s for OpenQASM 3. These are shared-host observations. The gain comes from reducing repeated adaptive executions.
• Manual validation: level 1 and level 2 (225 qubits) each returned {"00": 256} through all three execution paths with seed 17. The level 2 runs took approximately 225 s (direct), 176 s (Adaptive QIR), and 263 s (OpenQASM 3), including generation and compilation where applicable. Levels 3–4 were validated for generation and QCO conversion only.
• 108 focused Python tests passed in 4.58 s across test/python/bench/ and test/python/qdmi/test_compilation.py. The affected native sampling and generation tests passed in 0.24 s using Clang 23 Release with ThinLTO. The full native benchmark and DD suites passed during feature validation; exhaustive fault coverage still checks all single/double input Z errors and all 35 accepted triple-error patterns.
• Stub generation, whole-changed-file C++ lint, and the complete executable documentation build with local-link validation passed. Repository lint passed with pre-existing untracked audit scripts excluded from type checking through a temporary local configuration; tracked lint settings are unchanged.

Hosted CI is pending. Human review remains required before acceptance or merging.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[codecov]

Codecov Report

❌ Patch coverage is 95.87629% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/bench/JSON.cpp	83.3%	3 Missing ⚠️
mlir/lib/Dialect/QCO/Utils/DDFunctionality.cpp	50.0%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!