⚡ Optimize wheels and isolate native runtimes

[burgholzer]

🤖 AI text below 🤖

Description

Optimize portable release wheels and provide relocatable QDMI device bundles with a smaller native interface. This combines the build work and #2724 in one PR.

• Build Linux wheels with Clang/LLD ThinLTO and macOS wheels with Apple Clang ThinLTO. Keep speed optimization in Python bindings, portable deployment settings in cibuildwheel/Slurm, and native CPU tuning for local source builds.

• Keep native DD and device dependencies static. Python DD/MLIR modules share one private DD library; only the two DD-facing adapters compile separately. Wheels expose the QDMI C runtime and both native tools through CMake. Source installations provide the C++ SDK and static DD through the Development component.

• Copy device libraries and declared worker/manifest/configuration files on incremental builds without relinking consumers. Preserve signing-aware macOS RPATH and Windows DLL names/locations. Private Python support libraries remain unexported.

• Remove unused mqt-cc plugin exports, reuse the compiler context, and discard unused non-Debug link sections. Fold the benchmark launcher into _commands.py, centralize static export definitions, and test console entry points without private imports.

• Keep MSVC IPO for production artifacts. Native MSVC test builds default IPO off because /GL libraries repeat code generation at every test link; -DENABLE_IPO=ON remains available explicitly. This addresses the native Windows build timeout with one default policy. Automatic-export DLLs still disable IPO because CMake cannot scan /GL objects.

• Keep QIR C entry points noexcept, recover known allocation failures through existing error outputs, and contain other failures within the isolated worker.

• Reject unavailable CMake components before importing targets so FetchContent can fall back to source. Honor installation and static-library switches, support native documentation builds, and enforce C++20 with extensions confined to the dependency that requires them. Resolve Windows DLL paths from the installed distribution.

• Retain conditional uv caching for native sources, headers, TableGen, CMake, bundled data, and build settings; uncommitted docs, tests, Python, and stub edits do not rebuild the native package.

Size and performance

Measurements below are from the qualified 83be162a artifacts, before the subsequent native-test policy and build-infrastructure fixes. Repaired manylinux ARM64 wheel, with the same -O3/ThinLTO policy:

Artifact	Before consolidation (#2724)	Consolidated
Complete wheel	66.21 MiB	43.39 MiB
mqt-cc compressed	16.59 MiB	8.07 MiB
Benchmark command compressed	14.67 MiB	6.72 MiB
DDSIM worker compressed	24.09 MiB	18.38 MiB

Measured hosted standard wheels compared with the previous #2715 build without mqt-cc:

Platform	Previous #2715	Consolidated
Linux ARM64	49.17 MiB	43.39 MiB
Linux x64	51.34 MiB	45.66 MiB
macOS ARM64	27.18 MiB	33.88 MiB
Windows x64	29.11 MiB	35.69 MiB
Windows ARM64	27.77 MiB	34.09 MiB

The complete ten-wheel set plus source distribution grows from 372.49 to 389.19 MiB (+4.48%), with mqt-cc included on every platform. macOS and Windows growth is approximately the compiler's compressed size; Linux discards enough unused code to more than recover that cost. No compiler features or worker isolation were removed. Two alternating 20-run compiler probes produced identical output: QFT48 to QIR median 88.2 → 86.3 ms; a 48-qubit layered circuit to optimized QCO 141.5 → 139.5 ms. These are local checks for regressions, not general performance claims.

Validation

• Fixture cleanup on 7bf2fd800: removed the incremental test script and its consumer/input scaffolding. The existing eight runtime-file installation and configuration checks pass, as does repository lint. Ponytail review of the follow-up and connected build paths found no remaining actionable issues. Hosted checks for this revision are pending.
• Local validation on 656af4bcc before fixture cleanup: 3,986 native tests passed with one existing skip; repository lint and the C++ lint session passed. Component fallback, optional components, native documentation, disabled installation with MLIR/bindings enabled, and incremental QDMI staging passed focused probes. Ad hoc incremental staging probes passed with Ninja and Ninja Multi-Config; the retained fixture covers installation and configuration validation. A 26-case uv probe verifies selective invalidation; Windows installation-path selection was checked with a mocked Windows API. Hosted Linux/macOS/Windows C++ and Python checks, the aggregate check, and Slurm integration passed for 656af4bcc.
• The results below qualify earlier revisions; fresh platform wheels and native Windows/macOS execution have not been repeated for 656af4bcc.
• CI on 593810944 passed every Linux/macOS/Windows C++ and Python job, lint, coverage collection, and the aggregate check. Documentation and Slurm integration also passed.
• Windows x64 and ARM64 each passed 3,985 native tests with one unsupported-device skip. Cached builds took 1m30s and 1m59s respectively, with 94.92% compiler-cache hits; these are not clean-build benchmarks.
• Wheel packaging passed on all five platforms, covering all ten wheels. These artifacts were built on 83be162a; 593810944 changed only the MSVC native-test IPO default and its documentation, with production settings unchanged.
• Local ARM64 native release: 3,985 passed, one expected skip. Repaired manylinux wheel: 1,934 Python tests passed, two dependency/Python-version skips; auditwheel and strict abi3audit passed.
• Console entry tests: 14 passed, with 100% Python line coverage for _commands.py. Separate subprocess smoke tests run both native tools.
• C and C++ CMake runtime consumers without LLVM/MLIR, relocated DDSIM worker execution, SC configurations, and source static DD consumers with GCC 13/Clang 23 passed. Full executable documentation covered 18 notebooks and generated links.
• Repaired Windows artifacts retain the three public import libraries. Device DLLs and the DDSIM worker have only platform runtime dependencies; native tools resolve private support DLLs beside their executables. Public driver/device exports contain only their C APIs.

AI assistance covered implementation, specialist build/package review, failure diagnosis, and validation. Human review is required before 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.
• 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 83.46457% with 21 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QIR/Execution/Runtime/QIR.cpp	80.1%	21 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

This revamps the CMake, installation, and wheel configuration for MQT Core. It also produces optimized wheels and should, as a result, boost performance.
Additionally, this PR now also ships mqt-cc as part of the PyPI wheel 🎉