Skip to content

UPGRADING.md

Latest commit

 

History

History
331 lines (247 loc) · 14.4 KB

UPGRADING.md

File metadata and controls

331 lines (247 loc) · 14.4 KB
Raw

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.

Unreleased

3.10.0

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

Photonic subcircuit compiler

Install mqt.qmap[photonics] to use compile_subcircuit from mqt.qmap.ph.subcircuit_compilation. The target and chip dimensions must be positive and even, and the target must be smaller than the chip. The compiler returns a flat list of phase angles in layer order and the physical input and output ports. Paper evaluation tools and their dependencies live in eval/ph.

QDMI client API

Include na/qdmi/Client.hpp for QMAP's neutral-atom client and qdmi/Client.hpp for MQT Core's generic client. The generic C++ namespace is qdmi, and its CMake target is MQT::CoreQDMI.

Neutral-atom stack

The neutral-atom computation IR and circuit operations previously supplied by MQT Core now live in QMAP under the na/ir headers. This includes NAComputation, its entities and operations, and the move, bridge, and AOD circuit operations. Move and bridge operations use NAStandardOperation and remain custom operations to MQT Core. They do not support quantum controls.

The hybrid mapper's AtomMove fields now describe their semantics explicitly: origin, target, requiresLoad, and requiresStore replace c1, c2, load1, and load2, respectively.

MQT QMAP now ships and registers the neutral-atom QDMI device and exposes its client integration as mqt.qmap.na.qdmi. Its stable device ID is mqt.qmap.na.default. The provider reads its bundled description automatically and can be configured through the MQT_QMAP_QDMI_NA_CONFIG_JSON and MQT_QMAP_QDMI_NA_CONFIG_FILE environment variables. Device discovery opens each registered ID once; separate devices may have the same display name.

Neutral-atom OpenQASM serialization

Include na/ir/OpenQASMSerializer.hpp and call na::serializeOpenQASM(computation, stream) to serialize circuits containing move, bridge, or AOD operations. Link MQT::QMapNAIR. Core's qasm3::Serializer traverses compound and conditional operations; QMAP supplies the extended neutral-atom leaf syntax.

Circuit transformations

MQT QMAP now owns circuit transformations that MQT Core removed from qc::CircuitOptimizer. Apply these C++ replacements:

  • Replace qc::CircuitOptimizer::singleQubitGateFusion with qmap::singleQubitGateFusion.
  • Replace qc::CircuitOptimizer::decomposeSWAP with qmap::decomposeSWAP. The QMAP function recursively decomposes uncontrolled SWAPs and preserves controlled SWAPs.
  • Replace qc::CircuitOptimizer::cancelCNOTs with qmap::cancelCNOTs.
  • Replace qc::CircuitOptimizer::replaceMCXWithMCZ with qmap::replaceMCXWithMCZ.
  • Replace qc::CircuitOptimizer::flattenOperations(qc) with qc.flattenOperations().
  • Replace qc::CircuitOptimizer::removeFinalMeasurements(qc) with qc.removeFinalMeasurements().

For the QMAP-owned replacements, include datastructures/CircuitOptimizations.hpp and link MQT::QMapDS.

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 QMAP now requires Python 3.11 or newer. Upgrade the Python environment before installing this release.

MQT QMAP 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 QMAP 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 QMAP 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 QMAP now requires CMake 3.28 or newer. Upgrade CMake before building this release.

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.9.0

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

3.8.0

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

3.7.0

This release updates the minimum required mqt-core version to 3.6.0 as well as the nanobind version to 2.12.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 QMAP.

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

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

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

3.6.0

Renamings

To comply with established guidelines for function and attribute names, this release includes the following renamings:

  • mqt.qmap.plugins.qiskit.sc.compile has been renamed to compile_.
  • mqt.qmap.sc.map has been renamed to map_.
  • mqt.qmap.sc.Configuration.include_WCNF has been renamed to include_wcnf.
  • mqt.qmap.sc.MappingResult.input has been renamed to input_.

Stable ABI wheels

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

The full list of wheels now reads:

  • 3.10
  • 3.11
  • 3.12+ Stable ABI
  • 3.14t

3.5.0

As part of this release, the scheduler of the zoned neutral atom compiler now features a new parameter max_filling_factor. It allows limiting the maximum number of parallel entangling gates relative to the maximum capacity of the entangling zone. Note, the default is set to 0.9.

The code generator of the zoned neutral atom compiler is updated to also handle routings that only satisfy relaxed routing constraints. In contrast to the strict routing, a relaxed routing can change the relative order of atoms. The constraint that remains is that atoms previously in one row (column) must remain in the same row (column) after the routing.

Additionally, we also introduce an extension to the Hybrid Neutral Atom Mapper (HyRoNA), which unifies gate-based routing (SWAP/BRIDGE) with atom shuttling, pass-by, and an optional flying ancilla to find the most suitable routing.

Existing workflows should continue to function. The optionally new parameters are usePassBy=False, numFlyingAncillas=0, and maxBridgeDistance=0 which can all be disabled with the above values to recover the previous behavior. Enabling/increasing the corresponding parameters allows enabling individually single routing strategies.

The hybrid mapper now also optionally yields a .naviz output which can be handled similarly to the zoned architecture compiler.

Removal of Python 3.13t wheels

Free-threading Python was introduced as an experimental feature in Python 3.13. It became stable in Python 3.14. To conserve space on PyPI and to reduce the CI/CD build times, we have removed all wheels for Python 3.13t. We continue to provide wheels for the regular Python versions 3.10 to 3.14, as well as 3.14t.

3.4.0

End of support for Python 3.9

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

3.3.0

Testing previous versions of the mqt-qmap 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-qmap 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 (and mqt-qcec for testing) from source and without build isolation when locally working on mqt-qmap. A simple uv sync is enough to successfully run pytest.

All Python enums (e.g., sc.Method) 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 Method("exact") or "exact", use Method.exact.

This release restructures the neutral atom compiler which has consequences for its configuration and the reporting of statistics. The placement and routing stages have been merged into a single layout synthesis stage. There is a new PlaceAndRouteSynthesizer that combines the previously separate placement and routing stages. Consequently, the configuration for the placement and routing stages must now be wrapped in a configuration for the layout synthesis stage when using the C++ API. The Python API did not change in this regard. Furthermore, when reporting the statistics of the neutral atom compiler, the statistics for placement and routing are now reported as part of the layout synthesis statistics. The latter affects both the C++ and Python APIs.

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.2.0

With this release, the Python package has been restructured. In particular, the mqt.qmap.pyqmap module has been discontinued. Classes and functions can now be imported from the more descriptive mqt.qmap.clifford_synthesis, mqt.qmap.hybrid_mapper, mqt.qmap.na, and mqt.qmap.sc modules. The superconducting module's compile() function has been moved to mqt.qmap.plugins.qiskit.sc. The entrypoints synthesize_clifford() and optimize_clifford() of the Clifford synthesis module have been moved to mqt.qmap.plugins.qiskit.clifford_synthesis.

3.1.0

This minor release initiates the efforts to re-structure the Python bindings and make them more modular. Even tough this is not a breaking change, it is worth mentioning to developers of MQT QMAP 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. 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.

Support for BackendV1 Qiskit backends has been removed in accordance with Qiskit's 2.0 release dropping support for these backends. If you still require support for these backends, please use the last version of MQT QMAP that supports them, which is 2.8.0. However, we strongly recommend that you upgrade to Qiskit 2.0 or higher and use the new BackendV2 interface.

Teleportation support for the heuristic mapping has been removed. If you still require this feature, please use the last version of MQT QMAP that supports it, which is 2.8.0.

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 QMAP.

MQT QMAP has moved to the munich-quantum-toolkit GitHub organization under https://github.com/munich-quantum-toolkit/qmap. 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 QMAP 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.