Installation

MQT QuSAT is primarily developed as a C++20 library with Python bindings. The Python package is available on PyPI and can be installed on all major operating systems with all officially supported Python versions.

Tip

We recommend using uv. It is a fast Python package and project manager by Astral (creators of ruff). It can replace pip and virtualenv, automatically manages virtual environments, installs packages, and can install Python itself. It is significantly faster than pip.

If you do not have uv installed, install it with:

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

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

See the uv documentation for more information.

$ uv pip install mqt.qusat

(.venv) $ python -m pip install mqt.qusat

In most cases, no compilation is required; a platform-specific prebuilt wheel is downloaded and installed.

Verify the installation:

(.venv) $ python -c "import mqt.qusat; print(mqt.qusat.__version__)"

This prints the installed package version.

Building from Source for Performance

To get the best performance and enable platform-specific optimizations not available in portable wheels, we recommend building the library from source:

$ uv pip install mqt.qusat --no-binary mqt.qusat

(.venv) $ pip install mqt.qusat --no-binary mqt.qusat

This requires a C++20-capable C++ compiler and CMake 3.24 or newer.

Integrating MQT QuSAT into Your Project

To use the MQT QuSAT Python package in your project, add it as a dependency in your pyproject.toml or setup.py. This ensures the package is installed when your project is installed.

$ uv add mqt.qusat

[project]
# ...
dependencies = ["mqt.qusat>=<version>"]
# ...

from setuptools import setup

setup(
    # ...
    install_requires=["mqt.qusat>=<version>"],
    # ...
)

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

  • install MQT QuSAT on your system and use CMake’s find_package() command to locate it, or

  • use CMake’s FetchContent module to combine both approaches.

This is the recommended approach because it lets you detect installed versions of MQT QuSAT and only downloads the library if it is not available on the system. Furthermore, CMake’s FetchContent module provides flexibility in how the library is integrated into the project.

include(FetchContent)
set(FETCH_PACKAGES "")

# cmake-format: off
set(MQT_QUSAT_MINIMUM_VERSION "<minimum_version>"
    CACHE STRING "MQT QuSAT minimum version")
set(MQT_QUSAT_VERSION "<version>"
    CACHE STRING "MQT QuSAT version")
set(MQT_QUSAT_REV "<revision>"
    CACHE STRING "MQT QuSAT identifier (tag, branch or commit hash)")
set(MQT_QUSAT_REPO_OWNER "munich-quantum-toolkit"
    CACHE STRING "MQT QuSAT repository owner (change when using a fork)")
# cmake-format: on
FetchContent_Declare(
  mqt-qusat
  GIT_REPOSITORY https://github.com/${MQT_QUSAT_REPO_OWNER}/qusat.git
  GIT_TAG ${MQT_QUSAT_REV}
  FIND_PACKAGE_ARGS ${MQT_QUSAT_MINIMUM_VERSION})
list(APPEND FETCH_PACKAGES mqt-qusat)

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

Adding the library as a git submodule is a simple approach. However, 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):

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

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

add_subdirectory(external/mqt-qusat)

You can install MQT QuSAT on your system after building it from source:

$ git clone https://github.com/munich-quantum-toolkit/qusat.git mqt-qusat
$ cd mqt-qusat
$ cmake -S . -B build
$ cmake --build build
$ cmake --install build

Then, in your project’s CMakeLists.txt, use find_package() to locate the installed library:

find_package(mqt-qusat <version> REQUIRED)

Development Setup

Set up a reproducible development environment for MQT QuSAT. This is the recommended starting point for both bug fixes and new features. For detailed guidelines and workflows, see Contributing.

  1. Get the code:

    If you do not have write access to the munich-quantum-toolkit/qusat repository, fork the repository on GitHub (see https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your fork locally.

    $ git clone git@github.com:your_name_here/qusat.git mqt-qusat

    If you have write access to the munich-quantum-toolkit/qusat repository, clone the repository locally.

    $ git clone git@github.com/munich-quantum-toolkit/qusat.git mqt-qusat

  2. Change into the project directory:

    $ cd mqt-qusat

  3. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  4. Install the project and its development dependencies:

    We highly recommend using modern, fast tooling for the development workflow. We recommend using uv. If you don’t have uv, follow the installation instructions in the recommendation above (see tip above). See the uv documentation for more information.

    Install the project (including development dependencies) with uv:

    $ uv sync

    If you really don’t want to use uv, you can install the project and the development dependencies into a virtual environment using pip.

    $ python -m venv .venv
$ source ./.venv/bin/activate
(.venv) $ python -m pip install -U pip
(.venv) $ python -m pip install -e . --group dev

  5. Install pre-commit hooks to ensure code quality:

    The project uses pre-commit hooks for running linters and formatting tools on each commit. These checks can be run manually via nox, by running:

    $ nox -s lint

    They can also be run automatically on every commit via prek (recommended). To set this up, install prek, e.g., via:

    $ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/latest/download/prek-installer.sh | sh

    $ powershell -ExecutionPolicy ByPass -c "irm https://github.com/j178/prek/releases/latest/download/prek-installer.ps1 | iex"

    $ uv tool install prek

    Then run:

    $ prek install