Move QFw to Qiskit 2.5 for the MQT compiler

.github/workflows/test-reusable.yml

@@ -9,6 +9,7 @@
 #   - ci-mock: pytest tests under tests/mock
 #   - ci-qdmi: released provider adapters
 #   - ci-pulser: the Pulser client against released Pulser
+#   - ci-resolve: the requirements files resolve together with overrides
 #
 # Note: QFw integration tests require a running distributed framework
 # (PRTE, DEFw, QPM services, simulator binaries) and cannot run on standard
@@ -55,6 +56,21 @@ jobs:
     - name: Test adapters and serialization without provider submission
       run: python -m pytest -q tests/qiskit/test_qdmi_adapters.py tests/qiskit/test_braket_qdmi.py tests/qiskit/test_ibm_qdmi.py
 
+  ci-resolve:
+    name: ci-resolve (requirements resolve)
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: astral-sh/setup-uv@v5
+    - name: Resolve the files the build installs, with overrides
+      # Mirrors the uv pip install command in README.md. Resolution only reads
+      # package metadata, so nothing is installed.
+      run: |
+        uv pip compile \
+          --override setup/overrides.txt \
+          setup/build-requirements.txt setup/requirements.txt \
+          -o "$RUNNER_TEMP/resolved.txt"
+
   ci-pulser:
     name: ci-pulser (released Pulser)
     runs-on: ubuntu-latest

README.md

@@ -53,14 +53,14 @@ QFw services. For an existing checkout that was not cloned with
 git submodule update --init --recursive
 ```
 
-Create or activate the shared Python environment that QFw should use:
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if it is
+not already available, then create or activate the shared Python environment
+that QFw should use:
 
 ```bash
-python3 -m venv /path/to/qfw-venv
+uv venv /path/to/qfw-venv
 source /path/to/qfw-venv/bin/activate
-python -m pip install --upgrade pip setuptools wheel
-python -m pip install -r setup/build-requirements.txt
-python -m pip install -r setup/requirements.txt
+uv pip install -r setup/build-requirements.txt -r setup/requirements.txt --override setup/overrides.txt
 ```
 
 Install QFw with the CMake-backed installer. Use `--with-defw` when this
@@ -439,7 +439,7 @@ simulator modes may still require one.
 Run these checks when editing QFw itself:
 
 ```bash
-python -m pip install flake8 pytest
+uv pip install flake8 pytest
 ./.github/scripts/ci-syntax.sh
 ./.github/scripts/ci-mock.sh
 ```

docs/recipes/install-nonstandard-location.md

@@ -20,12 +20,13 @@ export QFW_INSTALL_PREFIX="${QFW_SHARED_ROOT}/qfw-release-v0.1-install"
 
 ## 2. Prepare the Python environment
 
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first if
+it is not already available.
+
 ```bash
-python3 -m venv "${QFW_VENV}"
+uv venv "${QFW_VENV}"
 source "${QFW_VENV}/bin/activate"
-python -m pip install --upgrade pip setuptools wheel
-python -m pip install -r "${QFW_SRC}/setup/build-requirements.txt"
-python -m pip install -r "${QFW_SRC}/setup/requirements.txt"
+uv pip install -r "${QFW_SRC}/setup/build-requirements.txt" -r "${QFW_SRC}/setup/requirements.txt" --override "${QFW_SRC}/setup/overrides.txt"
 ```
 
 Provider clients and simulator-specific Python packages should be installed in

docs/recipes/install-standard-location.md

@@ -21,18 +21,18 @@ export QFW_CURRENT=/opt/openqse/qfw/current
 ## 2. Prepare site-owned directories and the Python environment
 
 Run these commands as the account responsible for the QFw installation. The
-exact ownership policy is site-specific.
+exact ownership policy is site-specific. Install
+[uv](https://docs.astral.sh/uv/getting-started/installation/) first if it is
+not already available.
 
 ```bash
 sudo install -d -o "${USER}" -g "$(id -gn)" \
   "$(dirname "${QFW_RELEASE_PREFIX}")" \
   "$(dirname "${QFW_VENV}")"
 
-python3 -m venv "${QFW_VENV}"
+uv venv "${QFW_VENV}"
 source "${QFW_VENV}/bin/activate"
-python -m pip install --upgrade pip setuptools wheel
-python -m pip install -r "${QFW_SRC}/setup/build-requirements.txt"
-python -m pip install -r "${QFW_SRC}/setup/requirements.txt"
+uv pip install -r "${QFW_SRC}/setup/build-requirements.txt" -r "${QFW_SRC}/setup/requirements.txt" --override "${QFW_SRC}/setup/overrides.txt"
 ```
 
 Install provider and simulator dependencies in the venv or supply them through

docs/usage.md

@@ -70,11 +70,9 @@ export QFW_VENV="$QFW_BASE/qfw-venv"
 export QFW_BUILD="$QFW_BASE/qfw-build"
 export QFW_PREFIX="$QFW_BASE/qfw-install"
 
-python3 -m venv "$QFW_VENV"
+uv venv "$QFW_VENV"
 source "$QFW_VENV/bin/activate"
-python -m pip install --upgrade pip setuptools wheel
-python -m pip install -r "$QFW_SRC/setup/build-requirements.txt"
-python -m pip install -r "$QFW_SRC/setup/requirements.txt"
+uv pip install -r "$QFW_SRC/setup/build-requirements.txt" -r "$QFW_SRC/setup/requirements.txt" --override "$QFW_SRC/setup/overrides.txt"
 
 cmake -S "$QFW_SRC" -B "$QFW_BUILD" \
   -DCMAKE_BUILD_TYPE=RelWithDebInfo \
@@ -184,14 +182,14 @@ git submodule update --init --recursive
 <details id="python-environment">
 <summary><strong>3. Create A Python Environment</strong></summary>
 
-Create the environment on storage visible to every node that will use it:
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) first if
+it is not already available. Create the environment on storage visible to every
+node that will use it:
 
 ```bash
-python3 -m venv /path/to/qfw-venv
+uv venv /path/to/qfw-venv
 source /path/to/qfw-venv/bin/activate
-python -m pip install --upgrade pip setuptools wheel
-python -m pip install -r setup/build-requirements.txt
-python -m pip install -r setup/requirements.txt
+uv pip install -r setup/build-requirements.txt -r setup/requirements.txt --override setup/overrides.txt
 ```
 
 Install any simulator, application, or hardware-provider Python dependencies

setup/overrides.txt

@@ -0,0 +1,24 @@
+# Dependency overrides, passed as `uv pip install --override` alongside the
+# requirements files. An override replaces a package's declared constraint
+# everywhere in the resolution, so keep this list short and justified.
+
+# IMPORTANT: Please do not remove this file even if there are no
+# remaining overrides: every build passes --override and will fail
+# if this file is missing.
+
+# pennylane-qiskit 0.45.0 declares qiskit<=2.3.0, but MQT requires qiskit 2.5.
+# pennylane-qiskit 0.45.0 appears to work with 2.5, so we've pinned it in
+# setup/requirements.txt and added this override here. Without this override,
+# resolution will fail outright: pennylane-qiskit 0.45.0 caps qiskit at <=2.3.0,
+# which conflicts with the qiskit==2.5.2 pin.
+#
+# When pennylane-qiskit is updated to use the newer version of qiskit
+# (maybe with this PR https://github.com/PennyLaneAI/pennylane-qiskit/pull/719)
+# you can drop this override line and the pinned version in setup/requirements.txt,
+# but keep this file.
+#
+# Why is '[qasm3-import]' added to this requirement?
+# An override replaces the whole requirement, extras included. mqt-core[qiskit]
+# and iqm-qdmi[qiskit] ask for qiskit[qasm3-import], so the extra is repeated
+# here to keep qiskit-qasm3-import and openqasm3 installed.
+qiskit[qasm3-import]==2.5.2

setup/requirements.txt

@@ -1,10 +1,14 @@
-qiskit==2.2.3
+# mqt.core.mlir binds Qiskit's C API per minor release and accepts only the
+# 2.5 series, so this pin tracks the Qiskit the MQT compiler was built for.
+qiskit==2.5.2
 qiskit_aer==0.17.2
 qiskit-algorithms
 qiskit-optimization
 supermarq
 pennylane
-pennylane-qiskit
+# Declares qiskit<=2.3.0 while working with 2.5; setup/overrides.txt lifts
+# that cap. Pinned so the override is only ever applied to a tested release.
+pennylane-qiskit==0.45.0
 qiskit-ibm-runtime
 # qiskit-ibm-runtime asks for ibm-platform-services>=0.22.6, and iqm-client
 # below pins requests==2.32.3 exactly. ibm-platform-services 0.77.0 moved to