Note

This project is intended primarily as a demonstration and learning resource. It is provided for educational purposes and may not be suitable for production use.

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 the Munich Quantum Software Company (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 NOT YET 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)

# 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 f8cb7987c64dcffb72414a40560055cb717dbf74

# Configure & build MLIR (Release is recommended)
cmake -S llvm -B build_llvm -G Ninja \
  -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 \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_CXX_VISIBILITY_PRESET=default

cmake --build build_llvm --config Release

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

2) Create a local env and build the plugin

TODO: Update once published on PyPI

# From your repo root
cd /path/to/your/mqt-core-plugins-catalyst/plugins/catalyst

# Create and activate a venv (optional)
uv venv .venv
. .venv/bin/activate

# Install Catalyst and build the plugin
uv pip install pennylane-catalyst==0.13.0

uv sync --verbose --active
  --config-settings=cmake.define.CMAKE_BUILD_TYPE=Release
  --config-settings=cmake.define.Python3_EXECUTABLE="$(which python)"
  --config-settings=cmake.define.MLIR_DIR="$MLIR_DIR"
  --config-settings=cmake.define.LLVM_DIR="$LLVM_DIR"

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.

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_device

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


# Wrap your circuit with the conversion passes
@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])


# JIT compile using qjit
@qml.qjit(target="mlir", autograph=True)
def module() -> None:
    return circuit()


# --- Custom pipeline to capture intermediate MLIR ---
custom_pipeline = [
    # Only use the two MQT passes for demonstration
    ("to-mqtopt", ["builtin.module(catalystquantum-to-mqtopt)"]),
    ("to-catalystquantum", ["builtin.module(mqtopt-to-catalystquantum)"]),
]


# JIT compilation with intermediate MLIR files saved
@qml.qjit(target="mlir", autograph=True, keep_intermediate=2, pipelines=custom_pipeline)
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()
catalyst_mlir = mlir_dir / "0_catalyst_module.mlir"
mlir_to_mqtopt = mlir_dir / "1_CatalystQuantumToMQTOpt.mlir"
mlir_to_catalyst = mlir_dir / "4_MQTOptToCatalystQuantum.mlir"

# Read MLIR files
with catalyst_mlir.open("r", encoding="utf-8") as f:
    mlir_before_conversion = f.read()
with mlir_to_mqtopt.open("r", encoding="utf-8") as f:
    mlir_after_conversion = f.read()
with mlir_to_catalyst.open("r", encoding="utf-8") as f:
    mlir_after_roundtrip = f.read()

# Print MLIR contents
print("=== MLIR before conversion to MQTOpt ===")
print(mlir_before_conversion)
print("=== MLIR after conversion to MQTOpt ===")
print(mlir_after_conversion)
print("=== MLIR after roundtrip back to CatalystQuantum ===")
print(mlir_after_roundtrip)

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)

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: f8cb7987c64dcffb72414a40560055cb717dbf74).
• PennyLaneAI/catalyst: A package that enables just-in-time (JIT) compilation of hybrid quantum-classical programs implemented with PennyLane (version == 0.13.0).
• 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.