MLIR-Based MQT Core / Catalyst Plugin

This package provides a Catalyst plugin based on MLIR. It allows you to use MQT Core's MLIR dialects and transformations within Xanadu's Catalyst framework.

If you have any questions, feel free to create a discussion or an issue on GitHub.

Contributors and Supporters

The Munich Quantum Toolkit (MQT) is developed by the Chair for Design Automation at the Technical University of Munich and supported by MQSC. Among others, it is part of the Munich Quantum Software Stack (MQSS) ecosystem, which is being developed as part of the Munich Quantum Valley (MQV) initiative.

Thank you to all the contributors who have helped make the MLIR-based MQT Core / Catalyst plugin a reality!

The MQT will remain free, open-source, and permissively licensed—now and in the future. We are firmly committed to keeping it open and actively maintained for the quantum computing community.

To support this endeavor, please consider:

• Starring and sharing our repositories: https://github.com/munich-quantum-toolkit
• Contributing code, documentation, tests, or examples via issues and pull requests
• Citing the MQT in your publications (see Cite This)
• Citing our research in your publications (see References)
• Using the MQT in research and teaching, and sharing feedback and use cases
• Sponsoring us on GitHub: https://github.com/sponsors/munich-quantum-toolkit

Getting Started

mqt-core-plugins-catalyst is available on PyPI.

Because pennylane-catalyst pins to a specific LLVM/MLIR revision, you must build that LLVM/MLIR locally and point CMake at it.

1) Build the exact LLVM/MLIR revision (locally)

If you want to use a fast pre-built MLIR installation locally (recommended), we provide installation scripts. The scripts require a specific LLVM hash (i.e., 8f264586d7521b0e305ca7bb78825aa3382ffef7) and the desired installation directory to be passed. The scripts automatically download and use a platform-specific zstd binary for decompression, so only tar needs to be installed on the host system.

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

# Export this for your shell/session
export MLIR_DIR="/path/to/installation/lib/cmake/mlir"

Alternatively (but much more time-consuming); you can build MLIR from source as follows:

# Pick a workspace (optional)
mkdir -p ~/dev && cd ~/dev

# Clone the exact LLVM revision Catalyst expects
git clone https://github.com/llvm/llvm-project.git
cd llvm-project
git checkout 8f264586d7521b0e305ca7bb78825aa3382ffef7

# Configure & build MLIR (Release is recommended)
cmake -S llvm -B build_llvm -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_VISIBILITY_PRESET=default \
  -DLLVM_ENABLE_PROJECTS=mlir \
  -DLLVM_BUILD_EXAMPLES=OFF \
  -DLLVM_BUILD_TESTS=OFF \
  -DLLVM_INCLUDE_TESTS=OFF \
  -DLLVM_INCLUDE_EXAMPLES=OFF \
  -DLLVM_ENABLE_ASSERTIONS=ON \
  -DLLVM_ENABLE_ZLIB=FORCE_ON \
  -DLLVM_ENABLE_ZSTD=OFF \
  -DLLVM_ENABLE_RTTI=ON \
  -DLLVM_ENABLE_EH=ON

cmake --build build_llvm --config Release

# Export this for your shell/session
export MLIR_DIR="$PWD/build_llvm/lib/cmake/mlir"

2) Install the plugin

Install the MQT Core Catalyst Plugin using uv:

uv pip install mqt-core-plugins-catalyst

Alternatively, you can build and install the plugin from source:

# Clone the repository
git clone https://github.com/munich-quantum-toolkit/core-plugins-catalyst.git
cd core-plugins-catalyst

# Build and install the plugin
# This automatically creates a venv, downloads Python if necessary, and installs the project
MLIR_DIR="$MLIR_DIR" uv sync

# Or, if the environment variables are already set from step 1:
uv sync

3) Use the MQT plugin and explore intermediate MLIR representations

The MQT plugin provides device configuration utilities to prevent Catalyst from decomposing gates into unitary matrices, enabling lossless roundtrip conversions.

You can inspect the intermediate MLIR representations during the roundtrip between CatalystQuantum and MQTOpt dialects.

Example: Create a test script

Create a file test_example.py:

from __future__ import annotations
from pathlib import Path
from typing import Any

import pennylane as qml
from catalyst.passes import apply_pass
from mqt.core.plugins.catalyst import get_catalyst_plugin_abs_path, get_device

# Use get_device() to configure the device for MQT plugin compatibility
device = get_device("lightning.qubit", wires=2)
plugin_path = str(get_catalyst_plugin_abs_path())


# Define your quantum circuit
@apply_pass("mqt.mqtopt-to-catalystquantum")
@apply_pass("mqt.catalystquantum-to-mqtopt")
@qml.qnode(device)
def circuit() -> None:
    qml.Hadamard(wires=0)
    qml.CNOT(wires=[0, 1])


# Custom pipeline to capture intermediate MLIR
custom_pipeline = [
    ("Init", ["builtin.module(canonicalize)"]),  # Initial Catalyst MLIR
    ("ToMQTOpt", ["builtin.module(catalystquantum-to-mqtopt)"]),
    ("ToCatalystQuantum", ["builtin.module(mqtopt-to-catalystquantum)"]),
]


# JIT compilation with intermediate MLIR files saved
@qml.qjit(
    target="mlir",
    autograph=True,
    keep_intermediate=2,
    pipelines=custom_pipeline,
    pass_plugins={plugin_path},
    dialect_plugins={plugin_path},
)
def module() -> Any:
    return circuit()


# Trigger compilation and optimized MLIR generation
module.mlir_opt

# Catalyst writes intermediate MLIR files to the current working directory
mlir_dir = Path.cwd()
mlir_init = mlir_dir / "1_AfterInit.mlir"
mlir_to_mqtopt = mlir_dir / "2_AfterToMQTOpt.mlir"
mlir_to_catalyst = mlir_dir / "3_AfterToCatalystQuantum.mlir"

# Read MLIR files
print("=== Initial Catalyst MLIR ===")
if mlir_init.exists():
    print(mlir_init.read_text())

print("\n=== After CatalystQuantum → MQTOpt conversion ===")
if mlir_to_mqtopt.exists():
    print(mlir_to_mqtopt.read_text())

print("\n=== After MQTOpt → CatalystQuantum roundtrip ===")
if mlir_to_catalyst.exists():
    print(mlir_to_catalyst.read_text())

Alternative: You can also configure an existing device:

from mqt.core.plugins.catalyst import configure_device_for_mqt

device = qml.device("lightning.qubit", wires=2)
device = configure_device_for_mqt(device)

Run the example

uv run test_example.py

You should see three MLIR representations showing the transformation through the MQT dialects and back.

Verify the installation

You can run the test suite to verify everything is working:

# Run pytest using uv
uv run pytest test -v

# Alternatively run the tests using nox (handles all dependencies automatically)
uvx nox -s tests

System Requirements

Building the MQT Core Catalyst Plugin requires a C++ compiler with support for C++20 and CMake 3.24 or newer. Building (and running) is continuously tested under Linux and macOS using the latest available system versions for GitHub Actions. The MQT Core Catalyst Plugin is compatible with Python version 3.11 and newer.

The MQT Core Catalyst Plugin relies on some external dependencies:

• llvm/llvm-project: A toolkit for the construction of highly optimized compilers, optimizers, and run-time environments (specific revision: 8f264586d7521b0e305ca7bb78825aa3382ffef7).
• PennyLaneAI/catalyst: A package that enables just-in-time (JIT) compilation of hybrid quantum-classical programs implemented with PennyLane.
• MQT Core: Provides the MQTOpt MLIR dialect and supporting infrastructure.

Note, both LLVM/MLIR and Catalyst are currently restricted to specific versions. You must build LLVM/MLIR locally from the exact revision specified above and configure CMake to use it (see installation instructions).

Cite This

If you want to cite MQT Core Catalyst Plugin, please use the following BibTeX entry:

@inproceedings{Hopf_Integrating_Quantum_Software_2026,
author = {Hopf, Patrick and Ochoa Lopez, Erick and Stade, Yannick and Rovara, Damian and Quetschlich, Nils and Florea, Ioan Albert and Izaac, Josh and Wille, Robert and Burgholzer, Lukas},
booktitle = {SCA/HPCAsia 2026: Supercomputing Asia and International Conference on High Performance Computing in Asia Pacific Region},
doi = {10.1145/3773656.3773658},
month = jan,
publisher = {Association for Computing Machinery},
series = {SCA/HPCAsia 2026},
title = {{Integrating Quantum Software Tools with(in) MLIR}},
year = {2026}
}

Acknowledgements

The Munich Quantum Toolkit has been supported by the European Research Council (ERC) under the European Union's Horizon 2020 research and innovation program (grant agreement No. 101001318), the Bavarian State Ministry for Science and Arts through the Distinguished Professorship Program, as well as the Munich Quantum Valley, which is supported by the Bavarian state government with funds from the Hightech Agenda Bayern Plus.