⚡ Optimize release wheels with matched LTO and BOLT

[burgholzer]

🤖 AI text below 🤖

Description

Use full LTO in Core release wheels and the matched assertion-free Linux SDK; the macOS SDK uses cached ThinLTO to fit hosted build limits. Apply BOLT to Linux wheel binaries. Windows LTO stays disabled. Regular C++ and Python CI uses assertion-enabled SDKs; CD wheel jobs and their pull-request checks use the release variant.

Linux SDK and wheels share pinned manylinux 2.28 image digests from cibuildwheel 4.2.0; macOS selects Xcode 26.6. Linux BOLT links use GNU ld: mold 2.42.0 emitted invalid relocation symbol indices in the local full-LTO build. The SDK supplies the common optimizer and instrumentation runtime. Core trains DD, compiler, DDSIM/QIR JIT, and benchmark paths, uses LLVM stripping, repairs the wheel, regenerates RECORD hashes, and validates the repaired artifact before accepting it.

Keep section garbage collection for the DDSIM device and benchmark executable, shared sccache support across the container boundary, and the small packaged C++ SDK. Remove MSVC /Zm10. Split LLVM's compiler definitions into proper CMake arguments so the explicit C++ ABI macro does not absorb subsequent flags and break nanobind imports.

Local ARM64 comparison from identical LTO links and packaging: 43,964,801 → 39,808,676 bytes (9.5% smaller) with BOLT -lite. Four held-out workloads improve by 1.4–3.4%. These are bounded measurements, not a cross-platform speedup claim. The broader BOLT rewrite increased wheel size by 40.6%, so it is not selected.

A separate matched GCC 14 ARM64 comparison against the assertion-enabled/native-SDK policy measures 9.1% less time for vectors, 10.2% for matrix multiplication, 19.2% for OpenQASM to QCO, and 13.5% for Qiskit round trips. This measures assertions-off plus SDK/Core LTO and BOLT together, not assertion removal alone. The audit records the Linux BOLT OOM reproduction and swap validation, plus the macOS ThinLTO tradeoff and pending hosted checks.

Dependency gate: requires munich-quantum-software/portable-mlir-toolchain#94 and publication of its new archives, munich-quantum-software/setup-mlir#255, and munich-quantum-toolkit/workflows#464. Current workflow pins point to the companion review commits. Finalize the pins after those changes land; the current SDK release has no assertion-free assets.

Validation:

• Full matched SDK and Core builds in the pinned Linux ARM64 container; SDK tools relinked with GNU ld before BOLT. Relocated SDK integration, LTO consumer linking, and BOLT failure restoration pass.
• The repaired BOLT wheel passes 1,184 Python tests. One optional qirrunner module is skipped because it is not installed; training separately checks QIR JIT through DDSIM.
• Installed-wheel CMake consumer and driver session creation pass. Training validates QC/jeff generation, dynamic library loading, numerical DD results, and repaired-wheel imports.
• Repository lint passes; cibuildwheel 4.2 accepts Python 3.11–3.15 and 3.15t identifiers. Earlier Clang 23 checks verified full-LTO compile and link flags.
• Local evidence covers Linux ARM64 and the stable Python ABI. x86-64, macOS, Windows, free-threaded wheels, and hosted cache behavior remain unverified for these changes.

The audit records measurements, packaging constraints, and the separate compiler-PGO investigation. AI assistance: implemented and validated with GPT-6 via Codex.

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!