Installation

MQT Qudits 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.qudits

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

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

Verify the installation:

(.venv) $ python -c "import mqt.qudits; print(mqt.qudits.__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.qudits --no-binary mqt.qudits

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

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

Integrating MQT Qudits into Your Project

To use the MQT Qudits 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.qudits

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

from setuptools import setup

setup(
    # ...
    install_requires=["mqt.qudits>=<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 Qudits 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 Qudits 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_QUDITS_MINIMUM_VERSION "<minimum_version>"
    CACHE STRING "MQT Qudits minimum version")
set(MQT_QUDITS_VERSION "<version>"
    CACHE STRING "MQT Qudits version")
set(MQT_QUDITS_REV "<revision>"
    CACHE STRING "MQT Qudits identifier (tag, branch or commit hash)")
set(MQT_QUDITS_REPO_OWNER "munich-quantum-toolkit"
    CACHE STRING "MQT Qudits repository owner (change when using a fork)")
# cmake-format: on
FetchContent_Declare(
  mqt-qudits
  GIT_REPOSITORY https://github.com/${MQT_QUDITS_REPO_OWNER}/qudits.git
  GIT_TAG ${MQT_QUDITS_REV}
  FIND_PACKAGE_ARGS ${MQT_QUDITS_MINIMUM_VERSION})
list(APPEND FETCH_PACKAGES mqt-qudits)

# 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/qudits.git external/mqt-qudits

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

add_subdirectory(external/mqt-qudits)

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

$ git clone https://github.com/munich-quantum-toolkit/qudits.git mqt-qudits
$ cd mqt-qudits
$ 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-qudits <version> REQUIRED)

Development Setup

Set up a reproducible development environment for MQT Qudits. 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/qudits 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/qudits.git mqt-qudits

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

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

  2. Change into the project directory:

    $ cd mqt-qudits

  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 development tools:

    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.

    We also recommend installing pre-commit to automatically run checks before each commit and nox to automate common development tasks.

    The easiest way to install pre-commit and nox is via uv:

    $ uv tool install pre-commit
$ uv tool install nox

    On macOS with Homebrew, you can install pre-commit and nox with:

    $ brew install pre-commit nox

    If you prefer to use pipx, you can install pre-commit and nox with:

    $ pipx install pre-commit
$ pipx install nox

    If you prefer to use regular pip (preferably in a virtual environment), you can install pre-commit and nox with:

    $ pip install pre-commit nox

    Then enable the pre-commit hooks with:

    $ pre-commit install