🚧 Integrate QDMI Devices

[MatthiasReumann]

Description

This is a work-in-progress pull request adding an arch option to the mqt-cc tool that specifies the target QPU architecture / device. Eventually, the provided name should be used to load a dynamic device library and setup the QDMI device accordingly.

If the architecture option is provided, the mqt-cc tool should perform transpilation. That is native gate-set decomposition, and if the architecture has a coupling map, the superconducting mapping pass¹. Otherwise, these steps are skipped and the compilation is thus hardware-agnostic.

My hope is that by doing / discussing this now, we can immediately test and benchmark multiple architectures more easily.

Resolves #1082.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• I have disclosed the use of AI tools in the PR description as per our AI Usage Guidelines.
• AI-assisted commits include an Assisted-by: [Model Name] via [Tool Name] footer.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

Footnotes

1. --fit-topology (or --fit-coupling-map) could potentially be a more suitable name instead of the generic --place-and-route. ↩

[codecov]

Codecov Report

❌ Patch coverage is 15.00000% with 34 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Compiler/CompilerPipeline.cpp	8.6%	21 Missing ⚠️
mlir/lib/Compiler/Qdmi.cpp	0.0%	13 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

Cpp-Linter Report ⚠️

Some files did not pass the configured checks!

clang-tidy (v22.1.8) reports: 6 concern(s)

• mlir/tools/mqt-cc/mqt-cc.cpp:12:10: error: [clang-diagnostic-error]

  'mlir/Compiler/qdmi.h' file not found

     12 | #include "mlir/Compiler/qdmi.h"
        |          ^~~~~~~~~~~~~~~~~~~~~~

• mlir/tools/mqt-cc/mqt-cc.cpp:26:1: warning: [misc-include-cleaner]

  included header ToolOutputFile.h is not used directly

     26 | #include <llvm/Support/ToolOutputFile.h>
        | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     27 | #include <llvm/Support/raw_ostream.h>

• mlir/tools/mqt-cc/mqt-cc.cpp:35:1: warning: [misc-include-cleaner]

  included header AsmState.h is not used directly

     35 | #include <mlir/IR/AsmState.h>
        | ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     36 | #include <mlir/IR/MLIRContext.h>

• mlir/tools/mqt-cc/mqt-cc.cpp:46:1: warning: [misc-include-cleaner]

  included header memory is not used directly

     46 | #include <memory>
        | ^~~~~~~~~~~~~~~~~
     47 | #include <optional>

• mlir/tools/mqt-cc/mqt-cc.cpp:195:10: warning: [misc-include-cleaner]

  no header providing "fomac::Session" is directly included

     11 |   fomac::Session session; // Config?
        |          ^

• mlir/tools/mqt-cc/mqt-cc.cpp:215:3: warning: [bugprone-branch-clone]

  if with identical then and else branches

    215 |   if (inputFilename.getValue().ends_with(".qasm")) {
        |   ^
  /home/runner/work/core/core/mlir/tools/mqt-cc/mqt-cc.cpp:217:5: note: else branch starts here
    217 |   } else {
        |     ^

Have any feedback or feature suggestions? Share it here.

[MatthiasReumann]

@burgholzer (cc: @ystade)

This pull request now implements a very basic QDMI V1 integration into our compiler collection. Before continuing, I want to discuss the following issues.

Optionally enable QDMI

As of now, the current implementation tightly couples the mqt-cc with QDMI. Wouldn't it be nice to have QDMI as a compile-option in CMake? Something like ENABLE_QDMI_INTEGRATION (analogous to LLVM's ENABLE_ASSERTIONS) which adds the CLI Options, and generally the QDMI logic via preprocessor definitions? If so, we could still compile the mqt-cc without QDMI.

Extract Nested Classes

In order to augment the FoMaC device classes, I think it would be nice to extract them outside the Session class. Any opinions on that? It is kind of awkward to always write out fomac::Session::Device. Especially if we ever want to have specializations such as SuperconductingDevice, etc.

Trailing Return Types (Nitpick, sorry!)

I am really not that sure if the FoMaC classes benefit from the benefits of trailing return types. The auto in the following examples just feels somewhat wrong. Modern & fancy but wrong.

// fomac/FoMaC.cpp
auto getParametersNum(const std::vector<Site>& sites = {},
                       const std::vector<double>& params = {}) const -> size_t;
// qdmi/sc/Device.hpp
auto sessionFree(MQT_SC_QDMI_Device_Session session) -> void;

I've taken the liberty to implement some of the above FoMaC changes this morning (+ some improvements using modern C++ concepts) in FoMaC.hpp and FoMaC.cpp for you to better understand what I meant.

---

Any comments appreciated! Many thanks 🙏

[burgholzer]

@burgholzer (cc: @ystade)

This pull request now implements a very basic QDMI V1 integration into our compiler collection. Before continuing, I want to discuss the following issues.

Optionally enable QDMI

As of now, the current implementation tightly couples the mqt-cc with QDMI. Wouldn't it be nice to have QDMI as a compile-option in CMake? Something like ENABLE_QDMI_INTEGRATION (analogous to LLVM's ENABLE_ASSERTIONS) which adds the CLI Options, and generally the QDMI logic via preprocessor definitions? If so, we could still compile the mqt-cc without QDMI.

Hm. I'd argue that if we view QDMI as the primary way to add architecture information to mqt-cc, it should be(come) an essential part of it. Would we ever compile mqt-cc without QDMI support? In what kind of circumstances would that yield a benefit?

Extract Nested Classes

In order to augment the FoMaC device classes, I think it would be nice to extract them outside the Session class. Any opinions on that? It is kind of awkward to always write out fomac::Session::Device. Especially if we ever want to have specializations such as SuperconductingDevice, etc.

We have an open tracking issue going in that direction #1358. See also #1363 (comment)
Your proposed refactoring sounds fine as a start.

Trailing Return Types (Nitpick, sorry!)

I am really not that sure if the FoMaC classes benefit from the benefits of trailing return types. The auto in the following examples just feels somewhat wrong. Modern & fancy but wrong.

// fomac/FoMaC.cpp
auto getParametersNum(const std::vector<Site>& sites = {},
                       const std::vector<double>& params = {}) const -> size_t;
// qdmi/sc/Device.hpp
auto sessionFree(MQT_SC_QDMI_Device_Session session) -> void;

Feel free to get rid of them. I am personally not the biggest fan of these either way.

I've taken the liberty to implement some of the above FoMaC changes this morning (+ some improvements using modern C++ concepts) in FoMaC.hpp and FoMaC.cpp for you to better understand what I meant.

Thanks, I'll take a look! 👍🏼

Any comments appreciated! Many thanks 🙏

[MatthiasReumann]

In what kind of circumstances would that yield a benefit?

I was kind of thinking about IBM Benchpress. Not sure if we could still use QDMI here that easily.

We have an open tracking issue going in that direction #1358. See also #1363 (comment)

Oh. Great! I'll have a look at these and try to incorporate them in the refactoring.

Thanks, I'll take a look!

I've also opened #1849 to ease the comparison to the old implementation.

[burgholzer]

In what kind of circumstances would that yield a benefit?

I was kind of thinking about IBM Benchpress. Not sure if we could still use QDMI here that easily.

I was hoping that we could take the input from benchpress and wrap it in QDMI at runtime.
Somewhat relates to #1226 but on a broader scale

We have an open tracking issue going in that direction #1358. See also #1363 (comment)

Oh. Great! I'll have a look at these and try to incorporate them in the refactoring.

Take those with a grain of salt though. It's been a while that they have been written and some circumstances might have changed since then. Still good to have a look though.

[ystade]

A little late, but since I was tagged, I also wanted to comment:

Trailing return types

I guess I am responsible for them. I love them because when you read auto as func or so, the function signature becomes very similar to other languages. For me, it feels natural to have the return type at the end of the function. Anyway, I agree that this depends very much on taste, and I will go along with the majority.

FoMaC Concept

I guess everything has already been said here. I can just repeat here that in the future we want to directly build on QDMI and want to get rid of FoMaC or rather replace that by a C++ abstraction of QDMI.