MLIR Plugin #881

flowerthrower · 2025-03-20T08:12:25Z

Description

This PR introduces a MLIR plguin such that the round-trip pass can be executed with Pennylane Catalyst.
It additionally provides the plugin as a wheel.

Checklist:

The pull request only contains commits that are related to it.
I have added appropriate tests and documentation.
I have made sure that all CI jobs on GitHub pass.
The pull request introduces no new warnings and follows the project's style guidelines.

mqt_plugin_wheel/mqt_plugin/test/test_mlir_plugin.py

codecov · 2025-03-20T08:37:42Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

burgholzer · 2025-03-23T11:30:28Z

Now that #879 is merged, this needs to be rebased

# Conflicts: # .gitignore # mlir/include/mlir/Dialect/MQTOpt/IR/MQTOptTraits.h # mlir/lib/Dialect/MQTOpt/Transforms/FromQuantumComputationPattern.cpp # mlir/lib/Dialect/MQTOpt/Transforms/ToQuantumComputationPattern.cpp # mlir/tools/quantum-opt/quantum-opt.cpp

… build wheel

Signed-off-by: burgholzer <[email protected]>

burgholzer · 2025-07-31T00:10:45Z

Alright. I considerably cleaned up the implementation today.
This is getting closer to becoming mergable.
I'll leave some comments inline, where I think that changes are still due.

The biggest thing missing is a packaging setup that would allow us to release packages to PyPI. I'll try to get this done asap.

burgholzer

@flowerthrower @BertiFlorea Tagging you here explicitly so you hopefully see the comments. 😌

burgholzer · 2025-07-31T00:16:45Z

.github/workflows/ci_mlir_plugin.yml

+  #    name: 🧩 Test MLIR Catalyst Plugin with LLVM@${{ matrix.llvm-version }} on ${{ matrix.runs-on }}
+  #    runs-on: ${{ matrix.runs-on }}
+  #    strategy:
+  #      matrix:
+  #        runs-on: [ubuntu-24.04, ubuntu-24.04-arm, macos-14]
+  #        llvm-version: [19, 20]
+  #      fail-fast: false
+  #    env:
+  #      CMAKE_BUILD_PARALLEL_LEVEL: 4
+  #      CTEST_PARALLEL_LEVEL: 4
+  #      FORCE_COLOR: 3
+  #    steps:
+  #      # Check out the repository
+  #      - uses: actions/checkout@v4
+  #        with:
+  #          fetch-depth: 0
+  #
+  #      # install a specific version of the LLVM toolchain
+  #      - name: Install llvm and mlir
+  #        if: runner.os == 'Linux'
+  #        run: |
+  #          sudo apt-get update
+  #          wget https://apt.llvm.org/llvm.sh -O ${{ runner.temp }}/llvm_install.sh
+  #          chmod +x ${{ runner.temp }}/llvm_install.sh
+  #          if sudo ${{ runner.temp }}/llvm_install.sh ${{ matrix.llvm-version }}; then
+  #            sudo apt-get install -y libmlir-${{ matrix.llvm-version }}-dev \
+  #                                    mlir-${{ matrix.llvm-version }}-tools \
+  #                                    clang-${{ matrix.llvm-version}} \
+  #                                    clang-tools-${{ matrix.llvm-version }} \
+  #             || exit 1
+  #          else
+  #            echo "Installation from script failed."
+  #            exit 1
+  #          fi
+  #          echo "CC=gcc-14" >> $GITHUB_ENV
+  #          echo "CXX=g++-14" >> $GITHUB_ENV
+  #          echo "MLIR_DIR=/usr/lib/llvm-${{ matrix.llvm-version }}/lib/cmake/mlir" >> $GITHUB_ENV
+  #          echo "LLVM_DIR=/usr/lib/llvm-${{ matrix.llvm-version }}/lib/cmake/llvm" >> $GITHUB_ENV
+  #
+  #      # Install llvm and ninja
+  #      - name: Install llvm@${{ matrix.llvm-version }} and Ninja via Homebrew
+  #        if: runner.os == 'macOS'
+  #        run: brew install llvm@${{ matrix.llvm-version }} ninja
+  #
+  #      # Set compiler and environment variables
+  #      - name: Set compiler and CMake environment variables
+  #        if: runner.os == 'macOS'
+  #        run: |
+  #          if [ "$(uname -m)" = "x86_64" ]; then
+  #            LLVM_PREFIX="/usr/local/opt/llvm@${{ matrix.llvm-version }}"
+  #          else
+  #            LLVM_PREFIX="/opt/homebrew/opt/llvm@${{ matrix.llvm-version }}"
+  #          fi
+  #
+  #          echo "CC=$LLVM_PREFIX/bin/clang" >> $GITHUB_ENV
+  #          echo "CXX=$LLVM_PREFIX/bin/clang++" >> $GITHUB_ENV
+  #          echo "LLVM_DIR=$LLVM_PREFIX/lib/cmake/llvm" >> $GITHUB_ENV
+  #          echo "MLIR_DIR=$LLVM_PREFIX/lib/cmake/mlir" >> $GITHUB_ENV
+  #
+  #      # set up ccache for faster C++ builds
+  #      - name: Setup ccache
+  #        uses: Chocobo1/setup-ccache-action@v1
+  #        with:
+  #          prepend_symlinks_to_path: false
+  #          override_cache_key: mlir-plugin-${{ matrix.runs-on }}-llvm-${{ matrix.llvm-version }}
+  #
+  #      # Set up uv for faster Python package management
+  #      - name: Install the latest version of uv
+  #        uses: astral-sh/setup-uv@v6
+  #        with:
+  #          python-version: 3.13
+  #          activate-environment: true
+  #
+  #      # Build the plugin package
+  #      - name: Build mqt-core-catalyst-plugin
+  #        working-directory: plugins/catalyst
+  #        run: uv sync --verbose --active
+  #
+  #        # Print shared library dependencies for the plugin
+  #      - name: Print shared library dependencies for mqt-core-catalyst-plugin
+  #        run: |
+  #          if [ "$(uname)" = "Linux" ]; then
+  #              ldd .venv/lib/python3.13/site-packages/mqt/core/plugins/catalyst/mqt-core-catalyst-plugin.so || true
+  #          elif [ "$(uname)" = "Darwin" ]; then
+  #              otool -l .venv/lib/python3.13/site-packages/mqt/core/plugins/catalyst/mqt-core-catalyst-plugin.dylib || true
+  #          fi
+  #
+  #      # Print shared library dependencies for Catalyst
+  #      - name: Print shared library dependencies for Catalyst
+  #        run: |
+  #          if [ "$(uname)" = "Linux" ]; then
+  #              ldd $(which catalyst) || true
+  #          elif [ "$(uname)" = "Darwin" ]; then
+  #              otool -l $(which catalyst) || true
+  #          fi
+  #
+  #      # Run the plugin tests
+  #      - name: Run pytest for mqt-core-catalyst-plugin
+  #        working-directory: plugins/catalyst
+  #        run: python -m pytest -s --verbose


I'd still like to investigate at some point whether there is anything we can do to make this work with pre-compiled LLVM versions. But this will have to wait for a future PR. It would be great to create a tracking issue for this though.

burgholzer · 2025-07-31T00:18:19Z

plugins/catalyst/README.md

+# MQT Core Catalyst MLIR Plugin
+
+This sub-package of MQT Core provides a [Catalyst](https://github.com/PennyLaneAI/catalyst) plugin for the [MLIR](https://mlir.llvm.org/) framework.
+It allows you to use MQT Core's MLIR dialects and transformations within the Catalyst framework, enabling advanced quantum circuit optimizations and transformations.
+
+TODO: extend this section with more details about the Catalyst plugin, its features, and how to use it.
+
+If you have any questions, feel free to create a [discussion](https://github.com/munich-quantum-toolkit/core/discussions) or an [issue](https://github.com/munich-quantum-toolkit/core/issues) on [GitHub](https://github.com/munich-quantum-toolkit/core).
+
+## Contributors and Supporters
+
+The _[Munich Quantum Toolkit (MQT)](https://mqt.readthedocs.io)_ is developed by the [Chair for Design Automation](https://www.cda.cit.tum.de/) at the [Technical University of Munich](https://www.tum.de/) and supported by the [Munich Quantum Software Company (MQSC)](https://munichquantum.software).
+Among others, it is part of the [Munich Quantum Software Stack (MQSS)](https://www.munich-quantum-valley.de/research/research-areas/mqss) ecosystem, which is being developed as part of the [Munich Quantum Valley (MQV)](https://www.munich-quantum-valley.de) initiative.
+
+<p align="center">
+  <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/munich-quantum-toolkit/.github/refs/heads/main/docs/_static/mqt-logo-banner-dark.svg" width="90%">
+   <img src="https://raw.githubusercontent.com/munich-quantum-toolkit/.github/refs/heads/main/docs/_static/mqt-logo-banner-light.svg" width="90%" alt="MQT Partner Logos">
+  </picture>
+</p>
+
+Thank you to all the contributors who have helped make MQT Core a reality!
+
+<p align="center">
+<a href="https://github.com/munich-quantum-toolkit/core/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=munich-quantum-toolkit/core" />
+</a>
+</p>
+
+## Getting Started
+
+TODO
+
+## System Requirements
+
+TODO
+
+## Cite This
+
+If you want to cite MQT Core, please use the following BibTeX entry:
+
+```bibtex
+TODO
+```
+
+---


This is still pretty much to be done

burgholzer · 2025-07-31T00:22:24Z

plugins/catalyst/lib/mqt-plugin.cpp

+mlirGetDialectPluginInfo() {
+  return {MLIR_PLUGIN_API_VERSION, "MQTOpt", LLVM_VERSION_STRING,
+          [](DialectRegistry* registry) {
+            registry->insert<::mqt::ir::opt::MQTOptDialect>();
+          }};
+}
+
+/// The pass plugin registration mechanism.
+/// Necessary symbol to register the pass plugin.
+extern "C" LLVM_ATTRIBUTE_WEAK PassPluginLibraryInfo mlirGetPassPluginInfo() {
+  return {MLIR_PLUGIN_API_VERSION, "MQTOptPasses", LLVM_VERSION_STRING, []() {
+            mqt::ir::opt::registerMQTOptPasses();


In the future, we will most likely want to expose all of our dialects and transformations/conversions here. Could be worth tracking that in an issue.

burgholzer · 2025-07-31T00:25:51Z

plugins/catalyst/test/Conversion/mqtopt.mlir

These files are here, but they are not at all executed.
I'd very much argue that we need more explicit testing for the plugin.
Either in the form of C++ tests running these FileCheck files or via more extensive Python-side tests. I am fairly confident that some of the conversions are not yet correct.
It might be easier to write FileCheck tests than Python tests. Although I am not 100% sure.

burgholzer · 2025-07-31T00:27:41Z

plugins/catalyst/test/python/test_plugin.py

The amount of testing of the plugin is clearly still lacking quite a bit.
This has become quite obvious because it didn't even catch a bug that would flip the controls and targets of any controlled operation that got translated leading to incorrect programs.
So this definitely needs more tests that actually test more than the simple error-free execution of the passes.

burgholzer · 2025-07-31T00:31:43Z

plugins/catalyst/lib/Conversion/CatalystQuantumToMQTOpt/CatalystQuantumToMQTOpt.cpp

+ * Licensed under the MIT License
+ */
+
+#include "mlir/Conversion/CatalystQuantumToMQTOpt/CatalystQuantumToMQTOpt.h"


We still need to do something about clang-tidy not working correctly for the plugin.
The main reason for that is that the plugin build is completely loose from the main mqt-core build. Hence, there is no compilation database, and clang-tidy has problems finding the headers in the build directory.

As a first step, we should probably figure out how to best ignore the plugins directory from the clang-tidy run. However, mid-term, I would really want to have a clang-tidy check running properly over the code here. CLion locally revealed dozens of warnings that were fixed in the last couple of commits.

burgholzer · 2025-07-31T00:36:05Z

plugins/catalyst/lib/Conversion/MQTOptToCatalystQuantum/MQTOptToCatalystQuantum.cpp

+    // RZX(θ) = H(q2) CNOT(q1,q2) RZ(θ)(q2) CNOT(q1,q2) H(q2)
+    auto h1 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{}, inQubitsValues,
+        "H", false, inCtrlQubits, ValueRange{});
+
+    auto cnot1 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{}, h1.getResults(),
+        "CNOT", false, inCtrlQubits, ValueRange{});
+
+    auto rz = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{theta},
+        cnot1.getResults(), "RZ", false, inCtrlQubits, ValueRange{});
+
+    auto cnot2 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{}, rz.getResults(),
+        "CNOT", false, inCtrlQubits, ValueRange{});
+
+    auto h2 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{},
+        cnot2.getResults(), "H", false, inCtrlQubits, ValueRange{});


This (as well as some of the constructions below) cannot be correct yet as the number of qubits in the various operations is not correct.
A Hadamard only acts on one qubit, so it cannot take both input qubits as an argument. Similarly, the CNOT can not work just on the qubit resulting from the CNOT.
Proper testing would have revealed that.

In this case, the code can even be simplified: the sequence of CNOT, Rz, CNOT forms an RZZ gate. May as well use that. And the controls only need to be applied to that RZZ gate; both H gates can remain uncontrolled because they cancel whenever the controls of the RZZ gate are not activated.

burgholzer · 2025-07-31T00:37:01Z

plugins/catalyst/lib/Conversion/MQTOptToCatalystQuantum/MQTOptToCatalystQuantum.cpp

+    // XXminusYY(θ,β) = RX(π/2)(q1) RY(π/2)(q2) CNOT(q1,q2) RZ(θ)(q2)
+    // CNOT(q1,q2) RZ(β)(q1) RZ(β)(q2) RX(-π/2)(q1) RY(-π/2)(q2)
+    auto pi2 = rewriter.create<ConstantOp>(op.getLoc(),
+                                           rewriter.getF64FloatAttr(M_PI_2));
+    auto negPi2 = rewriter.create<ConstantOp>(
+        op.getLoc(), rewriter.getF64FloatAttr(-M_PI_2));
+
+    auto rx1 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{pi2},
+        inQubitsValues, "RX", false, inCtrlQubits, ValueRange{});
+
+    auto ry1 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{pi2},
+        rx1.getResults(), "RY", false, inCtrlQubits, ValueRange{});
+
+    auto cnot1 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{}, ry1.getResults(),
+        "CNOT", false, inCtrlQubits, ValueRange{});
+
+    auto rz1 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{theta},
+        cnot1.getResults(), "RZ", false, inCtrlQubits, ValueRange{});
+
+    auto cnot2 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{}, rz1.getResults(),
+        "CNOT", false, inCtrlQubits, ValueRange{});
+
+    auto rz2 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{beta},
+        cnot2.getResults(), "RZ", false, inCtrlQubits, ValueRange{});
+
+    auto rz3 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{beta},
+        rz2.getResults(), "RZ", false, inCtrlQubits, ValueRange{});
+
+    auto rx2 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{negPi2},
+        rz3.getResults(), "RX", false, inCtrlQubits, ValueRange{});
+
+    auto ry2 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{negPi2},
+        rx2.getResults(), "RY", false, inCtrlQubits, ValueRange{});
+
+    rewriter.replaceOp(op, ry2.getResults());


This construction also does not work.

burgholzer · 2025-07-31T00:38:29Z

plugins/catalyst/lib/Conversion/MQTOptToCatalystQuantum/MQTOptToCatalystQuantum.cpp

+    // Peres = Toffoli(q2,q1,q0) CNOT(q2,q1)
+    auto ccnot1 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{}, inQubitsValues,
+        "Toffoli", false, inCtrlQubits, ValueRange{});
+
+    auto cnot2 = rewriter.create<catalyst::quantum::CustomOp>(
+        op.getLoc(), outQubitTypes, TypeRange{}, ValueRange{},
+        ccnot1.getResults(), "CNOT", false, inCtrlQubits, ValueRange{});


This is not correct. The Peres Gate in mqt-core is a two-target gate that decomposes down to a CNOT and an X gate. It does not use 3 qubits. Same holds for the inverse.

burgholzer · 2025-07-31T00:40:12Z

plugins/catalyst/lib/Conversion/MQTOptToCatalystQuantum/MQTOptToCatalystQuantum.cpp

+// -- GPhaseOp (gphase)
+template <>
+StringRef ConvertMQTOptSimpleGate<opt::GPhaseOp>::getGateName(
+    [[maybe_unused]] std::size_t numControls) {
+  return "gphase";
+}


I am not 100% sure this is correct. If I remember correctly, Catalyst has its separate operation for the global phase. I might be mistaken, though.

🚧 add plugin files

15151e4

github-project-automation bot added this to MQT Core Mar 20, 2025

github-project-automation bot moved this to In Progress in MQT Core Mar 20, 2025

github-advanced-security bot found potential problems Mar 20, 2025

View reviewed changes

mqt_plugin_wheel/mqt_plugin/test/test_mlir_plugin.py Fixed Show fixed Hide fixed

mqt_plugin_wheel/mqt_plugin/test/test_mlir_plugin.py Fixed Show fixed Hide fixed

🧪 update test

63ddd2f

flowerthrower added MLIR Anything related to MLIR feature New feature or request labels Mar 20, 2025

🚧 clean up quantum-opt

54f1f19

flowerthrower and others added 20 commits March 24, 2025 14:46

🚧 remove catalyst test

00b3d40

✨ add Hadamard gate

92b4742

🚧 update test

ee108b7

🚧 add lit test for plugin roundtrip

c3eea64

🔥 removed plugin test (not possible yet)

3fb5ce3

🎨 per-commit

07e5130

🔥 remove local use makefile

17c1e22

🚧 revert some changes

bb3cd4e

➖ remove linklib

54d8064

➖ remove linklib

a6eb526

🎨 pre-commit fixes

ce51d4c

Remove hack for CMake policy CMP0057 in CMakeLists.txt

fa7d8ef

Merge remote-tracking branch 'origin/mlir-plugin' into mlir-plugin

d299c2a

🏗️ Make structural changes, configure python environment with locally…

45e12b2

… build wheel

🔧 Improve cmake config

82a4da3

🔥 Remove leftover file

94be1e4

🎨 Simplify cmake for now

73477c0

✅ Remove test with hard-coded path

838d88d

🎨 Try python setup

6597c73

burgholzer added 27 commits July 30, 2025 17:35

🔧 move prerelease config to comments

0b0b6d8

Signed-off-by: burgholzer <[email protected]>

🔥 remove unused CMake file

fbfcf8c

Signed-off-by: burgholzer <[email protected]>

🔥 remove unused variable

41ad6a7

Signed-off-by: burgholzer <[email protected]>

🚸 enable optional coverage collection

1667c4a

Signed-off-by: burgholzer <[email protected]>

🔧 optimize CMake configuration with header file sets

5b1f072

Signed-off-by: burgholzer <[email protected]>

🎨 add format and linting config to plugin

32c4fdf

♻️ first round of plugin code cleanup

48ea811

🔥 remove LLVM 21 from the testing matrix

6a6c59f

👷 add Linux ARM to test matrix for plugin

ee084fd

♻️ simplify conversion patterns

f9b32a2

🐛 fix control and target ordering in MQTOpt to Catalyst translation

db60591

🐛 fix pattern for XXminusYY

6e829f2

🔥 Comment out CI runs not using exact LLVM commit

54859f9

✨ enable support for CSWAP from catalyst

d2c7fec

✨ enable support for S and T from catalyst

ee20add

✨ enable support for ISWAP from catalyst

aa6bce6

✨ enable support for Identity from catalyst

9daf5d3

✨ enable support for SX from catalyst

87ab895

✨ enable support for ECR from catalyst

ed9a3f3

🎨 directly use string comparisons

2374378

🎨 reduce boilerplate code

fec7946

⏪ restore boilerplate code for unresolved materialization

d80d1e4

♻️ streamline conversion to catalyst

12c47bf

♻️ assume SX and ECR to be legal and supported

9a52a78

✨ add support for CSWAP in conversion to catalyst

857b368

♻️ simplify V and Vdg gate sequence

4a7bf6e

🐛 fix DCX implementation

778ae8f

🚨 fix missing header

b053818

burgholzer requested changes Jul 31, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

MLIR Plugin #881

MLIR Plugin #881

Uh oh!

flowerthrower commented Mar 20, 2025

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Mar 20, 2025 •

edited

Loading

Uh oh!

burgholzer commented Mar 23, 2025

Uh oh!

burgholzer commented Jul 31, 2025

Uh oh!

burgholzer left a comment

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

burgholzer Jul 31, 2025

Uh oh!

Uh oh!

MLIR Plugin #881

Are you sure you want to change the base?

MLIR Plugin #881

Uh oh!

Conversation

flowerthrower commented Mar 20, 2025

Description

Checklist:

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Mar 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

burgholzer commented Mar 23, 2025

Uh oh!

burgholzer commented Jul 31, 2025

Uh oh!

burgholzer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov bot commented Mar 20, 2025 •

edited

Loading