Installation

MQT core-plugins-catalyst 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.core-plugins-catalyst

(.venv) $ python -m pip install mqt.core-plugins-catalyst

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

Verify the installation:

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

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

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

Integrating MQT core-plugins-catalyst into Your Project

To use the MQT core-plugins-catalyst 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.core-plugins-catalyst

[project]
# ...
dependencies = ["mqt.core-plugins-catalyst>=<version>"]
# ...

from setuptools import setup

setup(
    # ...
    install_requires=["mqt.core-plugins-catalyst>=<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 core-plugins-catalyst 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 core-plugins-catalyst 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_CORE-PLUGINS-CATALYST_MINIMUM_VERSION "<minimum_version>"
    CACHE STRING "MQT core-plugins-catalyst minimum version")
set(MQT_CORE-PLUGINS-CATALYST_VERSION "<version>"
    CACHE STRING "MQT core-plugins-catalyst version")
set(MQT_CORE-PLUGINS-CATALYST_REV "<revision>"
    CACHE STRING "MQT core-plugins-catalyst identifier (tag, branch or commit hash)")
set(MQT_CORE-PLUGINS-CATALYST_REPO_OWNER "munich-quantum-toolkit"
    CACHE STRING "MQT core-plugins-catalyst repository owner (change when using a fork)")
# cmake-format: on
FetchContent_Declare(
  mqt-core-plugins-catalyst
  GIT_REPOSITORY https://github.com/${MQT_CORE-PLUGINS-CATALYST_REPO_OWNER}/core-plugins-catalyst.git
  GIT_TAG ${MQT_CORE-PLUGINS-CATALYST_REV}
  FIND_PACKAGE_ARGS ${MQT_CORE-PLUGINS-CATALYST_MINIMUM_VERSION})
list(APPEND FETCH_PACKAGES mqt-core-plugins-catalyst)

# 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/core-plugins-catalyst.git external/mqt-core-plugins-catalyst

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

add_subdirectory(external/mqt-core-plugins-catalyst)

You can install MQT core-plugins-catalyst on your system after building it from source:

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

Development Setup

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

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

    $ git clone git@github.com/munich-quantum-toolkit/core-plugins-catalyst.git mqt-core-plugins-catalyst

  2. Change into the project directory:

    $ cd mqt-core-plugins-catalyst

  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

  6. If you plan to contribute to MQT core-plugins-catalyst, you will also need to install MLIR. The section below describes how to do this.

Setting Up MLIR

MQT core-plugins-catalyst requires MLIR, which is part of the LLVM project, to be available when building from source. To successfully build MQT core-plugins-catalyst, you must make an installation of MLIR available to the C++ builds on your platform.

We highly recommend using the prebuilt MLIR distribution provided by the portable-mlir-toolchain project. These can be conveniently installed with the setup-mlir scripts as described below.

Downloading the MLIR Distribution

The setup-mlir repository provides installation scripts for all supported operating systems. You must pass the LLVM version (e.g., 22.1.0) and the installation prefix (directory) where MLIR should be extracted. The scripts download a platform-specific archive. The only requirement is that the tar command is available on the system.

Note

tar is included by default on Windows 10 and Windows 11. On older Windows versions, you can install it, for example, via Chocolatey: choco install tar.

Run the Bash script with the desired LLVM version and installation path:

$ curl -LsSf https://github.com/munich-quantum-software/setup-mlir/releases/latest/download/setup-mlir.sh | bash -s -- -v 22.1.0 -p /path/to/installation

Replace /path/to/installation with the directory where the LLVM distribution should be installed (e.g., /opt/llvm-22.1.0).

Run the PowerShell script with the desired LLVM version and installation path:

$ powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://github.com/munich-quantum-software/setup-mlir/releases/latest/download/setup-mlir.ps1))) -llvm_version 22.1.0 -install_prefix \path\to\installation"

Replace \path\to\installation with the directory where the LLVM distribution should be installed (e.g., C:\llvm-22.1.0). For debug builds on Windows, add the -use_debug flag to the script invocation.

For supported LLVM versions, commit hashes, and other options, see the setup-mlir repository and its version-manifest.json.

Note

If you want to build MLIR from source, you can follow the instructions in the portable-mlir-toolchain repository. This is not recommended unless you need a specific configuration that is not available in the prebuilt distributions, as building MLIR from source can be complex and time-consuming.

Making MLIR Available to the Build

After installing MLIR, point the build system to it by setting the CMake variable MLIR_DIR to the CMake configuration directory of the installation:

$ cmake -S . -B build -DMLIR_DIR=/path/to/installation/lib/cmake/mlir

Replace /path/to/installation with the actual path to the MLIR installation from the previous step.

Alternatively, you can set the MLIR_DIR environment variable to the same path before running CMake:

$ export MLIR_DIR=/path/to/installation/lib/cmake/mlir

$ $env:MLIR_DIR = "C:\path\to\installation\lib\cmake\mlir"

Disabling MLIR

If you do not need MLIR-based functionality, you can disable it by setting the BUILD_MQT_CORE-PLUGINS-CATALYST_MLIR option to OFF. This disables all MLIR-related features in MQT core-plugins-catalyst and removes the dependency on MLIR.

$ cmake -S . -B build -DBUILD_MQT_CORE-PLUGINS-CATALYST_MLIR=OFF