🔀 Backport compatible main changes for MQT Core 3.9.0

[burgholzer]

🤖 AI text below 🤖

Description

Backport the remaining suitable changes from main to v3.x for MQT Core 3.9.0. One pull request presents the complete stable-branch result and avoids repeated CI runs. Separate signed commits preserve upstream provenance, authorship, and revert boundaries.

The series includes:

• QDMI queue telemetry, existing-job retrieval, and generic custom-operation lists from ✨ Expose QDMI queue length and job position #2010, ✨ Add support for retrieving existing QDMI jobs by ID #2008, and ✨ Query custom operation lists through FoMaC #2042;
• the Slurm license selector, two-node Slurm 25.11 fixture, and tutorial from ✨ Select QDMI devices from Slurm license environments #2025 and 🧪 Test QDMI device admission with Slurm #2043;
• runtime-configurable neutral-atom and superconducting devices and reusable IQM Garnet and Emerald models from ✨ Make the NA QDMI device runtime configurable #1974, ✨ Make the SC QDMI device runtime configurable #1980, and ✨ Bundle reusable IQM Garnet and Emerald device models #1992;
• the applicable QDMI Qiskit adapter changes from 🚸 Simplify QDMI adapter construction #2084: typed overrides, stable IDs, lazy discovery, primitive factories, and explicit shot and precision defaults;
• removal of dead pybind11 CMake support from 💥 Remove dead pybind11 CMake support #2106 and removal of [tool.qdmi] configuration from 💥 Drop QDMI configuration through pyproject.toml #2116;
• CPython 3.15, dynamic metadata, nanobind 2.14, recursive-stub, optional-wheel, build, CI, dependency, hook, and optional-import maintenance;
• Sphinx-LLM and documentation-build improvements from 🔧 Maintenance round #1989, 🔧 Add a lower bound for sphinx-llm #2046, and ⚡ Speed up documentation builds #1988; and
• final-design and writing guidance from 📝 Add final-design guidance for AI-assisted changes #2072.

v3 boundary

• LLVM/MLIR remains optional and uses LLVM/MLIR 21.
• The QDMI namespace and deprecated FoMaC aliases from ♻️ Establish the QDMI Python namespace (backport #2074) #2113 remain available for the v3 deprecation cycle.
• QDMIBackend.from_device_id() retains the compatible session_parameters={...} mapping and rejects duplicate values supplied through typed keywords.
• QDMISampler and QDMIEstimator no longer accept the generic options={...} mapping. Direct constructors and backend factories use explicit default_shots and default_precision arguments, as on main.
• CompilerTarget.from_device_id() is omitted because v3 has no Python MLIR compiler-target binding.
• Persistent qdmi.json configuration remains supported. The deprecated [tool.qdmi] parser and its vendored TOML dependency are removed.
• The unused pybind11 binding helper is removed. The nanobind helper is now the sole add_mqt_python_binding function.
• The Slurm API selects the device named by mutable SLURM_JOB_LICENSES metadata. Slurm licenses control admission. Provider credentials or operating-system isolation authorize access.
• Compiler-target, QCO/QTensor, typed OpenQASM, newer QIR-runtime, and QIR-Runner changes are omitted because their source or runtime layers are not present on v3 or require LLVM/MLIR 22. The ZX removal from 🔥 Remove the ZX-calculus library from MQT Core #2082 remains v4-only.
• Lock-only maintenance from ⬆️🔒️ Lock file maintenance #2033 is represented by the final aggregate lock.

Validation

• complete non-MLIR release build with LLVM 21.1.8 llc: passed;
• native CTest suite: 1,742 passed, with two intentional provider job-ID skips;
• complete Python suite: 550 passed, with five documented optional-feature skips;
• focused Python 3.10 QDMI and Qiskit suite: 420 passed, with two expected MLIR skips;
• recursive stubs: passed without a tracked diff;
• editable package build and installation: passed;
• Sphinx documentation: passed with the existing v3 warning baseline and produced non-empty llms.txt and llms-full.txt;
• complete lint, workflow, lock, type, signature, ancestry, and git diff --check gates: passed.

The privileged Slurm workflow remains an exact-head CI check because it requires Docker, systemd, cgroup v2, and two Slurm compute containers.

Checklist

• The commits are focused and preserve upstream provenance.
• Behavioral changes have tests and migration guidance.
• Documentation and changelog entries describe the final v3 behavior.
• Applicable local build, test, lint, stub, and documentation gates pass.
• AI-assisted public text includes the required disclosure.

Codex assisted with the backport analysis, implementation, tests, documentation, validation, history reconstruction, and adversarial review. The author reviewed the resulting changes and remains responsible for them.

[codecov]

Codecov Report

❌ Patch coverage is 91.46810% with 111 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/qdmi/devices/na/Configuration.cpp	89.4%	37 Missing ⚠️
src/qdmi/devices/sc/Configuration.cpp	90.2%	22 Missing ⚠️
src/qdmi/devices/sc/Device.cpp	91.7%	18 Missing ⚠️
src/qdmi/common/DeviceConfiguration.cpp	79.7%	15 Missing ⚠️
src/qdmi/devices/na/Device.cpp	94.1%	12 Missing ⚠️
src/fomac/Slurm.cpp	92.1%	5 Missing ⚠️
src/na/operations/GlobalOp.cpp	66.6%	1 Missing ⚠️
src/qdmi/driver/Driver.cpp	95.0%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!