⚡ Optimize portable wheels with Clang and ThinLTO

Use the manylinux Clang distribution and matching LLD, Apple Clang IPO,
and speed optimization in nanobind modules. Keep macOS Python modules
in a two-level namespace.

Select portable CPU settings explicitly for wheels and retain native
source-build defaults. Test installed CMake consumers with GCC and Clang,
including all concrete DD operations, and document local build settings.

Assisted-by: GPT-6 via Codex

Author: burgholzer

.github/workflows/cd.yml

@@ -28,7 +28,7 @@ jobs:
             windows-2025,
             windows-11-arm,
           ]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@fd3d75dece69c363989347869529a5e99cdcfffc # v2.5.1
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@fd41eaef61a38f4675a11c4d766bb4c5c80affe4 # PR #464
     with:
       runs-on: ${{ matrix.runs-on }}
       setup-mlir: true

.github/workflows/ci.yml

@@ -46,7 +46,7 @@ jobs:
             preset: release
             run-on-draft: false
             setup-mlir: true
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-ubuntu.yml@fd3d75dece69c363989347869529a5e99cdcfffc # v2.5.1
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-tests-ubuntu.yml@862a912fb48d265d877d6a37a097b135d9dac6d3 # PR #491
     with:
       runs-on: ${{ matrix.runs-on }}
       compiler: ${{ matrix.compiler }}
@@ -115,7 +115,7 @@ jobs:
     name: 🇨 Coverage
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-cpp-tests)
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-coverage.yml@fd3d75dece69c363989347869529a5e99cdcfffc # v2.5.1
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-coverage.yml@862a912fb48d265d877d6a37a097b135d9dac6d3 # PR #491
     with:
       setup-mlir: true
       llvm-version: 23.1.2
@@ -127,7 +127,7 @@ jobs:
     name: 🇨 Lint
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-cpp-linter)
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-linter.yml@fd3d75dece69c363989347869529a5e99cdcfffc # v2.5.1
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-linter.yml@862a912fb48d265d877d6a37a097b135d9dac6d3 # PR #491
     with:
       clang-version: 23
       build-project: true
@@ -154,7 +154,7 @@ jobs:
       fail-fast: false
       matrix:
         runs-on: [ubuntu-26.04, ubuntu-26.04-arm, macos-26, windows-2025]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-tests.yml@fd3d75dece69c363989347869529a5e99cdcfffc # v2.5.1
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-tests.yml@862a912fb48d265d877d6a37a097b135d9dac6d3 # PR #491
     with:
       runs-on: ${{ matrix.runs-on }}
       setup-mlir: true
@@ -211,7 +211,7 @@ jobs:
             windows-2025,
             windows-11-arm,
           ]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@fd3d75dece69c363989347869529a5e99cdcfffc # v2.5.1
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-python-packaging-wheel-cibuildwheel.yml@fd41eaef61a38f4675a11c4d766bb4c5c80affe4 # PR #464
     with:
       runs-on: ${{ matrix.runs-on }}
       setup-mlir: true

.github/workflows/upstream.yml

@@ -21,7 +21,7 @@ jobs:
       fail-fast: false
       matrix:
         runs-on: [ubuntu-26.04, macos-15, windows-2025]
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-qiskit-upstream-tests.yml@fd3d75dece69c363989347869529a5e99cdcfffc # v2.5.1
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-qiskit-upstream-tests.yml@862a912fb48d265d877d6a37a097b135d9dac6d3 # PR #491
     with:
       runs-on: ${{ matrix.runs-on }}
       setup-z3: true

cmake/AddMQTPythonBinding.cmake

@@ -15,6 +15,8 @@ function(add_mqt_python_binding package_name target_name)
     ${target_name}
     # Enable free-threaded support
     FREE_THREADED
+    # Keep computation in bindings optimized for speed.
+    NOMINSIZE
     # Suppress compiler warnings from the nanobind library
     NB_SUPPRESS_WARNINGS
     # Use nanobind's shared runtime. Split mode enables the Stable ABI internally.
@@ -40,6 +42,8 @@ function(add_mqt_python_binding package_name target_name)
 
   # Keep statically linked dependencies local.
   if(APPLE)
+    # Restore the Python module namespace changed by HandleLLVMOptions, as in AddMLIRPython.
+    target_link_options(${target_name} PRIVATE "LINKER:-twolevel_namespace")
     target_link_options(${target_name} PRIVATE "LINKER:-exported_symbol,_PyInit_${module_name}")
   elseif(UNIX)
     target_link_options(${target_name} PRIVATE "LINKER:--exclude-libs,ALL")

cmake/StandardProjectSettings.cmake

@@ -49,11 +49,6 @@ if(DEFINED ENV{DEPLOY})
       $ENV{DEPLOY}
       CACHE BOOL "Use deployment configuration from environment" FORCE)
   message(STATUS "Setting deployment configuration to '${DEPLOY}' from environment")
-elseif(DEFINED ENV{CI})
-  set(DEPLOY
-      ON
-      CACHE BOOL "Set deployment configuration to ON for CI" FORCE)
-  message(STATUS "Setting deployment configuration to '${DEPLOY}' for CI")
 endif()
 
 # set deployment specific options

docs/installation.md

@@ -74,10 +74,19 @@ python -c "import mqt.core; print(mqt.core.__version__)"
 
 This prints the installed package version.
 
-## Building from Source for Performance
+## Build performance
 
-To get the best performance and enable platform-specific optimizations not
-available in portable wheels, we recommend building the library from source:
+Release wheels use portable CPU settings and the assertion-free LLVM/MLIR 23.1.2
+SDK. Linux wheels target manylinux_2_28 and use Clang 22 with LLD and ThinLTO;
+macOS wheels use Apple Clang and ThinLTO with a macOS 13.3 deployment target.
+The wheels include native shared libraries and a CMake package for C++
+applications. Consumers do not need the compiler's LTO plugin, but must use a
+compatible C++ standard library and ABI. Use the QDMI C interface for device
+plugins.
+
+### Building from source
+
+Build from source to tune Core for the machine that will run it:
 
 ::::{tab-set}
 :sync-group: installer
@@ -106,6 +115,32 @@ This requires a C++20-capable
 [C++ compiler](https://en.wikipedia.org/wiki/List_of_compilers#C++_compilers)
 and [CMake](https://cmake.org/) 3.28 or newer.
 
+Release source builds default to `DEPLOY=OFF`, which enables native CPU tuning
+and LTO when the compiler supports them. On Linux, Clang with its matching LLD
+linker is a useful choice; on macOS, use Apple Clang from Xcode. For example,
+with Clang 23 installed on Linux:
+
+```console
+CC=clang-23 CXX=clang++-23 uv pip install mqt.core --no-binary mqt.core \
+  -Ccmake.define.CMAKE_LINKER_TYPE=LLD
+```
+
+Keep native builds on compatible CPUs. For redistribution, set
+`-Ccmake.define.DEPLOY=ON` and choose the target platform's compiler and system
+baseline. Cibuildwheel sets deployment mode explicitly for release wheels. The
+`DEPLOY` environment variable overrides the CMake setting.
+
+Clang and Apple Clang use ThinLTO through CMake's `ENABLE_IPO` option. For a
+local C++ build, `cmake --preset release` selects the same release defaults;
+pass `-DENABLE_IPO=OFF` to disable LTO. GCC can use mold 3 or newer with
+`-DCMAKE_LINKER_TYPE=MOLD`. Clang with mold also needs a matching LLVM LTO
+plugin; LLD includes the required support.
+
+Native tuning and LTO apply to the Core code being compiled. Prebuilt LLVM/MLIR
+SDK libraries retain their own build settings, and LTO does not optimize across
+separate shared libraries. Benchmark your application before changing the
+compiler or LTO settings.
+
 ## Integrating MQT Core into Your Project
 
 To use the MQT Core Python package in your project, add it as a dependency in

pyproject.toml

@@ -254,36 +254,54 @@ build = "cp3*"
 skip = [ "*-musllinux_*", "cp314t-*" ]
 archs = "auto64"
 build-frontend = "uv"
-test-command = "pytest test/python"
+test-command = "python test/cmake/check_installed.py && pytest test/python"
 test-groups = [ "test" ]
 test-sources = [
   "bindings/mlir/qiskit/SupportedVersions.inc",
   "json",
   "scripts/check_docs_links.py",
   "scripts/qiskit_c_api_adopt.py",
+  "test/cmake",
   "test/circuits",
   "test/python",
   "test/slurm/run_integration.py",
   "vendor/qiskit-c-api/2.5.0",
 ]
 
 [tool.cibuildwheel.linux]
-environment = { DEPLOY = "ON", PATH = "$PATH:/root/.local/bin", MLIR_DIR = "/opt/llvm-23.1.2/lib/cmake/mlir" }
+config-settings = { "cmake.define.ENABLE_IPO" = "ON", "cmake.define.CMAKE_LINKER_TYPE" = "LLD" }
+environment = { DEPLOY = "ON", CC = "clang", CXX = "clang++", PATH = "/opt/clang/bin:$PATH:/root/.local/bin", MLIR_DIR = "/opt/llvm-23.1.2/lib/cmake/mlir" }
+environment-pass = [
+  "CMAKE_C_COMPILER_LAUNCHER",
+  "CMAKE_CXX_COMPILER_LAUNCHER",
+  "SCCACHE_GHA_ENABLED",
+  "SCCACHE_GHA_RW_MODE",
+  "SCCACHE_IDLE_TIMEOUT",
+  "ACTIONS_CACHE_SERVICE_V2",
+  "ACTIONS_RESULTS_URL",
+  "ACTIONS_RUNTIME_TOKEN",
+]
 before-all = """
+manylinux-install-clang -v 22.1.8.1
 uv tool install "sccache>=0.10.0"
 mkdir -p /tmp/setup-mlir
 curl -fLsS https://github.com/munich-quantum-software/setup-mlir/archive/8d3eae73d0f0196fd30c787d91ebd2018cb6c709.tar.gz | tar -xz -C /tmp/setup-mlir --strip-components=1
 bash /tmp/setup-mlir/installation/setup-mlir.sh -v 23.1.2 -p /opt/llvm-23.1.2 -a OFF
 """
 before-test = "uvx sccache --show-stats"
+test-command = """\
+  CC=gcc CXX=g++ python test/cmake/check_installed.py && python test/cmake/check_installed.py && pytest test/python\
+  """
 # QIR-Runner's Linux wheels require a newer glibc than the manylinux_2_28
 # containers used to build and test MQT Core's broadly compatible wheels.
 test-groups = [ "test-base" ]
 
 [tool.cibuildwheel.macos]
-environment = { MACOSX_DEPLOYMENT_TARGET = "13.3" }
+config-settings = { "cmake.define.ENABLE_IPO" = "ON" }
+environment = { DEPLOY = "ON", MACOSX_DEPLOYMENT_TARGET = "13.3" }
 
 [tool.cibuildwheel.windows]
+environment = { DEPLOY = "ON" }
 repair-wheel-command = "delvewheel repair -w {dest_dir} {wheel} --namespace-pkg mqt --ignore-existing"
 
 [[tool.cibuildwheel.overrides]]

test/CMakeLists.txt

@@ -11,5 +11,9 @@ add_subdirectory(bench)
 add_subdirectory(dd)
 add_subdirectory(qdmi)
 
+# Wheel tests run this probe against the installed package; retain its compile command for lint.
+add_executable(mqt-core-dd-consumer EXCLUDE_FROM_ALL cmake/installed_consumer/dd_consumer.cpp)
+target_link_libraries(mqt-core-dd-consumer PRIVATE MQT::CoreDD)
+
 # copy test circuits to build directory
 file(COPY ${PROJECT_SOURCE_DIR}/test/circuits DESTINATION ${CMAKE_CURRENT_BINARY_DIR})

test/cmake/check_installed.py

@@ -0,0 +1,42 @@
+# Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+# Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+"""Build and run a C++ consumer of the installed wheel."""
+
+from __future__ import annotations
+
+# This standalone check executes trusted build tools and the installed test binary.
+# ruff: file-ignore[implicit-namespace-package, subprocess-without-shell-equals-true, start-process-with-partial-path]
+import subprocess
+import tempfile
+from importlib.metadata import distribution
+from pathlib import Path
+
+
+def main() -> None:
+    """Check installed libraries, package settings, and the device helper."""
+    source = Path(__file__).parent / "installed_consumer"
+    with tempfile.TemporaryDirectory() as directory:
+        subprocess.run(
+            [
+                "cmake",
+                "-S",
+                str(source),
+                "-B",
+                directory,
+                "-DCMAKE_BUILD_TYPE=Release",
+                "-DCMAKE_PREFIX_PATH=" + str(distribution("mqt-core").locate_file("mqt/core")),
+            ],
+            check=True,
+        )
+        subprocess.run(["cmake", "--build", directory, "--config", "Release", "--parallel", "2"], check=True)
+        subprocess.run(["ctest", "--test-dir", directory, "-C", "Release", "--output-on-failure"], check=True)
+
+
+if __name__ == "__main__":
+    main()

test/cmake/installed_consumer/CMakeLists.txt

@@ -96,3 +96,13 @@ add_custom_command(
     ${CMAKE_COMMAND} -E compare_files
     "${CMAKE_CURRENT_BINARY_DIR}/$<CONFIG>/consumer-device.qdmi.json"
     "$<TARGET_FILE_DIR:consumer-device>/consumer-device.qdmi.json")
+
+enable_testing()
+add_executable(dd-consumer dd_consumer.cpp)
+target_link_libraries(dd-consumer PRIVATE MQT::CoreDD)
+add_test(NAME dd-consumer COMMAND dd-consumer)
+if(WIN32)
+  set_tests_properties(
+    dd-consumer PROPERTIES ENVIRONMENT_MODIFICATION
+                           "PATH=path_list_prepend:$<TARGET_FILE_DIR:MQT::CoreDD>")
+endif()