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