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-plugin for connecting MQT Core with Catalyst

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-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/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.12.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 with your PennyLane code

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

Important: Use get_device() from the MQT plugin instead of qml.device() directly:

import catalyst
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
# This prevents gates from being decomposed into unitary matrices
device = get_device("lightning.qubit", wires=2)


@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])
    # Controlled gates will NOT be decomposed to matrices
    qml.ctrl(qml.PauliX(wires=0), control=1)
    catalyst.measure(0)
    catalyst.measure(1)


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


# Get the optimized MLIR representation
mlir_output = module.mlir_opt

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.12.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.