Installation

MQT QMAP is mainly developed as a C++17 library with Python bindings. The resulting Python package is available on PyPI and can be installed on all major operating systems using all modern Python versions.

Tip

We highly recommend using uv for working with Python projects. It is an extremely fast Python package and project manager, written in Rust and developed by Astral (the same team behind ruff). It can act as a drop-in replacement for pip and virtualenv, and provides a more modern and faster alternative to the traditional Python package management tools. It automatically handles the creation of virtual environments and the installation of packages, and is much faster than pip. Additionally, it can even set up Python for you if it is not installed yet.

If you do not have uv installed yet, you can install it via:

macOS and Linux

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

$ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Check out their excellent documentation for more information.

In most practical cases (under 64-bit Linux, MacOS incl. Apple Silicon, and Windows), this requires no compilation and merely downloads and installs a platform-specific pre-built wheel.

Building from source for performance¶

In order to get the best performance and enable platform-specific optimizations that cannot be enabled on portable wheels, it is recommended to build the library from source via:

uv (recommended)

$ uv pip install mqt.qmap --no-binary mqt.qmap --no-binary mqt.core

pip

(.venv) $ pip install mqt.qmap --no-binary mqt.qmap --no-binary mqt.core

This requires a C++ compiler supporting C++17 and a minimum CMake version of 3.24. Additionally, the SMT solver Z3 has to be installed and the dynamic linker has to be able to find the library. This can be accomplished in a multitude of ways:

Under Ubuntu 20.04 and newer: sudo apt-get install libz3-dev
Under macOS: brew install z3
Alternatively: pip install z3-solver in the virtual environment
Download pre-built binaries from https://github.com/Z3Prover/z3/releases and copy the files to the respective system directories
Build Z3 from source and install it to the system

The library is continuously tested under Linux, MacOS, and Windows using the latest available system versions for GitHub Actions. In order to access the latest build logs, visit the GitHub Actions page.

Integrating MQT QMAP into your project¶

If you want to use the MQT QMAP Python package in your own project, you can simply add it as a dependency in your pyproject.toml or setup.py file. This will automatically install the MQT QMAP package when your project is installed.

uv (recommended)

$ uv add mqt.qmap

pyproject.toml

[project]
# ...
dependencies = ["mqt.qmap>=3.0.0"]
# ...

setup.py

from setuptools import setup

setup(
    # ...
    install_requires=["mqt.qmap>=3.0.0"],
    # ...
)

If you want to integrate the C++ library directly into your project, you can either

add it as a git submodule and build it as part of your project, or
use CMake’s FetchContent module.

FetchContent

This is the recommended approach for projects because it allows to detect installed versions of MQT QMAP and only downloads the library if it is not available on the system. Furthermore, CMake’s FetchContent module allows for lots of flexibility in how the library is integrated into the project.

include(FetchContent)
set(FETCH_PACKAGES "")

# cmake-format: off
set(MQT_QMAP_VERSION 3.0.0
    CACHE STRING "MQT QMAP version")
set(MQT_QMAP_REV "v3.0.0"
    CACHE STRING "MQT QMAP identifier (tag, branch or commit hash)")
set(MQT_QMAP_REPO_OWNER "cda-tum"
    CACHE STRING "MQT QMAP repository owner (change when using a fork)")
# cmake-format: on
if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.24)
  FetchContent_Declare(
    mqt-qmap
    GIT_REPOSITORY https://github.com/${MQT_QMAP_REPO_OWNER}/mqt-qmap.git
    GIT_TAG ${MQT_QMAP_REV}
    FIND_PACKAGE_ARGS ${MQT_QMAP_VERSION})
  list(APPEND FETCH_PACKAGES mqt-qmap)
else()
  find_package(mqt-qmap ${MQT_QMAP_VERSION} QUIET)
  if(NOT mqt-qmap_FOUND)
    FetchContent_Declare(
      mqt-qmap
      GIT_REPOSITORY https://github.com/${MQT_QMAP_REPO_OWNER}/mqt-qmap.git
      GIT_TAG ${MQT_QMAP_REV})
    list(APPEND FETCH_PACKAGES mqt-qmap)
  endif()
endif()

# Make all declared dependencies available.
FetchContent_MakeAvailable(${FETCH_PACKAGES})

git submodule

Integrating the library as a git submodule is the simplest approach. However, handling git submodules can be cumbersome, especially when working with multiple branches or versions of the library. First, add the submodule to your project (e.g., in the external directory) via:

$ git submodule add https://github.com/munich-quantum-toolkit/qmap.git external/mqt-qmap

Then, add the following lines to your CMakeLists.txt to make the library’s targets available in your project:

add_subdirectory(external/mqt-qmap)

Installation¶

Building from source for performance¶

Integrating MQT QMAP into your project¶