⚡️ Simplify routing and standardize benchmark experiments

[burgholzer]

🤖 AI text below 🤖

Description

Mapping currently builds repair graphs for equal layouts, copies adjacency lists during cycle search, and carries duplicate routing state. Skip that work, remove the unused graph distance matrix and related APIs, and update parent routing state directly. Keep branch-join heuristics, A* ordering, and traversal semantics unchanged.

Diagnose qubit-carrying calls, multi-block entry functions, and invalid mapping options before mutation. Preserve classical calls and document the dense temporary routing workspace. Payload capability checks and control-flow legalization remain owned by #2162.

Keep the complete one-off benchmark under .agents/benchmarks/routing/: source, explicit CMake hook, collection and plotting scripts, raw samples, and figure. It builds against a selected checkout without edits to production or test build files. AGENTS.md defines shared requirements for matched before/after runs, correctness and quality checks, raw data, plots, revision attribution, and reproducibility; PLANS.md and AUDITS.md link to those requirements. Benchmark files are excluded from routine pre-commit, Ruff, ty, and local/CI C++ lint; benchmark execution is validated explicitly.

Benchmarks

Compared with 91a9e0ba514af938680cdd394d6d63195872dc9a, on DGX Spark with GCC 13.3.0 and LLVM/MLIR 23.1.0, release builds without IPO, pinned to CPU 0. Nine alternating process pairs, five samples after warmup per workload; bars show medians and interquartile ranges.

• Unchanged branch layouts: 1.56–1.82× faster, across 16, 64, and 256 target sites.
• Eight-qubit, 64-CX routing workload: timings differ by less than 3%; this does not establish a speedup.
• Synthetic acyclic-star cycle searches: 1.78–4.69× faster. This is a helper benchmark, not a mapper speedup on typical coupling graphs.
• Every measured mapped-IR hash and SWAP count matches before and after.

Benchmark source, workload definitions, raw samples, and plotting instructions are reproducible. The benchmark executable is optional and excluded from the default build and CTest; plotting adds no project dependency.

Validation

• The relocated harness builds against baseline and candidate checkouts; all 45 outputs per variant match the recorded IR hashes and SWAP counts. A candidate build with tests disabled, a normal configuration without the benchmark target, collection/plotting smoke runs, and C++ lint without the benchmark hook passed. Historical timing samples remain attributed to their original revisions.

• 104 mapping tests, 192 QCO utility tests, and 182 compiler tests passed locally.

• uvx nox -s lint passed.

• Full changed-file uvx nox -s cpp-lint -- 91a9e0ba514af938680cdd394d6d63195872dc9a passed.

• A disposable combination with ✨ Legalize control flow for selected payloads #2162 at 1c5d4cc667046e9d3270898bfa658c786d74368d applied cleanly through three-way patch application. All 100 existing mapping tests passed. The combined compiler suite passed 193/195: PayloadControlRejectsLinearStateInGenericSCFControl and PayloadControlRejectsUnstructuredCFG fail during parsing because their allocations violate main's entry-block rule. Both failures reproduce with these routing changes removed, before mapping runs. This is not a claim that the complete ✨ Legalize control flow for selected payloads #2162 stack is green.

This changes unreleased v4 functionality; no standalone changelog entry or migration section is required. Codex assisted with implementation, regression tests, benchmarks, and this description. Human review remains required before acceptance or merge.

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

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[burgholzer]

Let's get this in ⚡