Upgrade Guide¶

This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the changelog.

This release adds verify_with_hard_timeout(circuit1, circuit2, deadline=seconds) for checks that need forced termination. For normal checks, keep using verify(..., timeout=seconds). This cooperative timeout avoids starting a worker for each check, but a long DD operation can delay cancellation. The hard-timeout worker adds substantial latency, especially for Qiskit inputs. The function accepts file paths, OpenQASM text, and Qiskit circuits, including mixed inputs. Qiskit circuits require the qiskit extra and are serialized with QPY before the deadline starts. QuantumComputation objects are not supported. The function returns a JSON-style dictionary and raises TimeoutError when the worker is terminated. The existing verify API and its result type are unchanged.

3.10.1 ¶

This release updates the minimum required mqt-core version to 3.10.1.

CMake presets on Windows¶

All CMake presets now use Ninja. On Windows, remove -windows from preset names when configuring, building, and testing:

Previous preset	Replacement
`debug-windows`	`debug`
`release-windows`	`release`

Install Ninja and run CMake from a Visual Studio developer shell for the target architecture. Use a new build directory if an existing directory uses the Visual Studio generator.

3.10.0 ¶

This release updates the minimum required mqt-core version to 3.10.0.

Approximate equivalence checking¶

MQT QCEC now supports approximate equivalence checking based on the projective Hilbert–Schmidt distance. For shallow circuits with few gates crossing a horizontal cut, the optional hybrid Schrödinger–Feynman (HSF) checker can be enabled with check_approximate_equivalence=True and run_hsf_checker=True. Usage and limitations are described in the documentation.

Dynamic circuits¶

When transform_dynamic_circuit is enabled, some previously accepted circuits now raise an error. After resets have been eliminated, measurements must use a one-to-one mapping between qubits and classical bits. Reset a measured qubit before using it again as a gate target. Classical conditions must compare one bit against 0 or 1 using equality.

Compilation flow profiles¶

The deprecated mode argument of generate_profile() and ancilla_mode argument of verify_compilation() have been removed. AncillaMode and the mode argument of generate_profile_name() have also been removed. Remove these arguments and any imports of AncillaMode from your code.

Profiles now depend only on the Qiskit optimization level. Profile generation uses Qiskit’s default synthesis for multi-controlled gates without additional ancilla qubits. The recursion and v-chain profiles are no longer included. The remaining profiles are named qiskit_O0.profile through qiskit_O3.profile; update any paths that use the _noancilla suffix.

The filepath argument is now the second argument of generate_profile(). The configuration argument is now the fourth argument of verify_compilation(). Prefer passing these arguments by name:

generate_profile(optimization_level=1, filepath=profile_directory)
verify_compilation(original, compiled, optimization_level=1, configuration=config)

Qiskit 2.1 minimum¶

The minimum Qiskit version increases from 1.0.0 to 2.1.0, dropping support for all Qiskit 1.x releases and Qiskit 2.0. Upgrade Qiskit to 2.1.0 or newer.

Python 3.11 and Stable ABI wheels¶

MQT QCEC now requires Python 3.11 or newer. Upgrade the Python environment before installing this release.

MQT QCEC now publishes one cp311-abi3 wheel for GIL-enabled CPython 3.11 and newer. Free-threaded support starts with CPython 3.15 in a separate cp315-abi3t wheel. MQT QCEC no longer publishes free-threaded CPython 3.13 or 3.14 wheels.

This release updates nanobind to 3.0.1, which changes the nanobind ABI.

macOS support¶

MQT QCEC no longer supports x86 macOS. Use Apple silicon with macOS 13.3 or newer. The new deployment target enables std::format in libc++.

CMake 3.28 minimum¶

MQT QCEC now requires CMake 3.28 or newer. Upgrade CMake before building this release.

3.9.0 ¶

This release updates the minimum required mqt-core version to 3.9.0 and nanobind to 2.15.0.

ZX-calculus implementation¶

The ZX-calculus implementation that used to live in MQT Core is now part of MQT QCEC. The ZX checker is configured and used exactly as before, so using MQT QCEC requires no changes. However, MQT::QCEC no longer links MQT::CoreZX publicly, so C++ projects that relied on getting MQT Core’s ZX library transitively must link it explicitly.

3.8.0 ¶

This release updates the minimum required mqt-core version to 3.8.0.

3.7.0 ¶

This release updates the minimum required mqt-core version to 3.7.0 as well as the nanobind version to 2.13.0.

CMake presets¶

CMake presets have been added to provide a standardized and reproducible way to configure builds across different platforms. These presets are also used in our CI.

On Unix systems, the debug, release, and coverage presets can be used to configure, build, and test MQT QCEC.

cmake --preset release
cmake --build --preset release
ctest --preset release

Additionally, the lint preset can be used to configure and build MQT QCEC in preparation for a clang-tidy run.

If you are on Windows, use the debug-windows and release-windows presets.

3.6.0 ¶

This release brings extended support for multi-controlled gates that was introduced in https://github.com/munich-quantum-toolkit/core/pull/1380 to the ZX-calculus checker.

This release also updates the minimum required mqt-core version to 3.6.0 as well as the nanobind version to 2.12.0.

3.5.0 ¶

To comply with established guidelines for attribute names, mqt.qcec.pyqcec.StateType.random_1Q_basis has been renamed to random_1q_basis.

This release also updates the minimum required mqt-core version to 3.4.1 as well as the nanobind version to 2.11.0.

3.4.0 ¶

Python wheels¶

This release contains two changes to the distributed wheels.

First, we have removed all wheels for Python 3.13t. Free-threading Python was introduced as an experimental feature in Python 3.13. It became stable in Python 3.14.

Second, for Python 3.12+, we are now providing Stable ABI wheels instead of separate version-specific wheels. This was enabled by migrating our Python bindings from pybind11 to nanobind.

Both of these changes were made in the interest of conserving PyPI space and reducing CI/CD build times. The full list of wheels now reads:

3.10
3.11
3.12+ Stable ABI
3.14t

3.3.0 ¶

End of support for Python 3.9¶

Starting with this release, MQT QCEC no longer supports Python 3.9. This is in line with the scheduled end of life of the version. As a result, MQT QCEC is no longer tested under Python 3.9 and no longer ships Python 3.9 wheels.

3.2.0 ¶

Testing previous versions of the mqt-qcec package built via uv sync or simple (uv) pip install . generally failed due to binary incompatibility of the mqt-core compiled extension packages and the mqt-qcec one. This required building mqt-core from source and without build isolation to get a working local setup. By using the latest pybind11 release (v3), the binary compatibility between extension modules compiled under different circumstances (such as different compilers) has been greatly increased. As such, it is no longer necessary to build mqt-core from source and without build isolation when locally working on mqt-qcec. A simple uv sync is enough to successfully run pytest.

The ApplicationScheme, EquivalenceCriterion, and StateType enums are now exposed via pybind11’s new py::native_enum, which makes them compatible with Python’s enum.Enum class (PEP 435). As a result, the enums can no longer be initialized using a string. Instead of ApplicationScheme("sequential") or "sequential", use ApplicationScheme.sequential.

Finally, the minimum required C++ version has been raised from C++17 to C++20. The default compilers of our test systems support all relevant features of the standard.

3.1.0 ¶

Even tough this is not a breaking change, it is worth mentioning to developers of MQT QCEC that all Python code (except tests) has been moved to the top-level python directory. Furthermore, the C++ code for the Python bindings has been moved to the top-level bindings directory.

3.0.0 ¶

This major release introduces several breaking changes, including the removal of deprecated features and the introduction of new APIs. The following paragraphs describe the most important changes and how to adapt your code accordingly. We intend to provide a more comprehensive migration guide for future releases.

The major change in this major release is the move to the MQT Core Python package. This move allows us to make qiskit a fully optional dependency and entirely rely on the MQT Core IR for representing circuits. Additionally, the mqt-core Python package now ships all its C++ libraries as shared libraries so that these need not be fetched or built as part of the build process. This was tricky to achieve cross-platform, and you can find some more backstory in the corresponding PR. We expect this integration to mature over the next few releases. If you encounter any issues, please let us know.

Some internals of QCEC have been streamlined and refactored to improve the overall code quality and maintainability. Most notably, counterexamples are now returned as decision diagrams instead of dense arrays. This was made possible by the move to the MQT Core Python package, which now also exposes the underlying DD package to Python. The returned DDs have a get_vector() method that can be used to convert them to a dense array if needed.

MQT Core itself dropped support for several parsers in v3.0.0, including the .real, .qc, .tfc, and GRCS parsers. The .real parser lives on as part of the MQT SyReC project. All others have been removed without replacement. Consequently, these input formats are no longer supported in MQT QCEC.

MQT QCEC has moved to the munich-quantum-toolkit GitHub organization under https://github.com/munich-quantum-toolkit/qcec. While most links should be automatically redirected, please update any links in your code to point to the new location. All links in the documentation have been updated accordingly.

MQT QCEC now requires CMake 3.24 or higher. Most modern operating systems should have this version available in their package manager. Alternatively, CMake can be conveniently installed from PyPI using the cmake package.