✨ Integrate QDMI Devices

[MatthiasReumann]

🤖 AI text below 🤖

Summary

This is the final integration slice of the compiler-target series. It:

• snapshots a configured circuit-model QDMI device as an immutable
  mlir::CompilerTarget, including names, topology, coherence data, operation
  capabilities, and available calibration;
• exposes the same target compilation workflow through C++, Python, and
  source-build mqt-cc;
• adds mqt-cc device listing, explicit registry configuration, and stable-ID
  device selection without introducing another driver or target abstraction;
• keeps generic optimization before target-native synthesis and final
  conformance verification.

The bridge validates that QDMI operation support fits the compiler's homogeneous
bidirectional target model. Directional operations must report both ordered
orientations on every supported pair, while operand-symmetric operations such as
CZ may report each undirected edge once. Devices without topology and operation
site restrictions retain the all-to-all convention used by DDSIM. Neutral-atom
zone models are rejected with a focused diagnostic.

Design

CompilerTarget remains owned by the MLIR compiler and independent of FoMaC,
QDMI, and the legacy CoreIR target. The optional adapter is the only library
linking FoMaC to the compiler target. It snapshots all data eagerly, so
compilation does not retain a device or session handle.

Python exposes CompilerTarget.from_device, QCOProgram.compile_for_target,
and compile_program(..., target=...). The C++ adapter and mqt-cc workflow are
source-build interfaces; this PR does not create a partial installed MLIR SDK
boundary or change wheel shipment for mqt-cc.

Validation

• 223 compiler unit tests
• 10 focused adapter and mqt-cc CTests
• 29 focused Python MLIR tests
• provider-disabled compiler build
• authoritative stub regeneration
• changed-source clang-tidy
• strict warning-free documentation build
• complete repository lint and git diff --check
• independent exact-head design and correctness review

Closes #1082

[codecov]

Codecov Report

❌ Patch coverage is 94.23077% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Compiler/FoMaCAdapter.cpp	94.1%	9 Missing ⚠️

📢 Thoughts on this report? Let us know!

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

[MatthiasReumann]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added QDMI support for discovering available quantum devices and selecting a compilation target.
  • Added configuration-file support for initializing device sessions.
  • Added device-aware transpilation and mapping for superconducting hardware connectivity.
  • Intermediate compilation records now include post-transpilation outputs.

• Documentation

  • Updated the unreleased changelog with QDMI integration details.

• Bug Fixes

  • Improved handling and reporting when a requested device cannot be found.

Walkthrough

Adds QDMI and device-aware support, changes mapping to use shared superconducting devices, inserts optional transpilation into the compiler pipeline, and adds mqt-cc options for listing and selecting QDMI devices.

Changes

Device-Driven Transpilation

Layer / File(s)	Summary
Graph, device, and QDMI support mlir/include/mlir/Support/*, mlir/lib/Support/*, mlir/lib/Dialect/QCO/Utils/Graph.cpp	Moves Graph into mlir, adds SuperconductingDevice, implements QDMI session and device lookup utilities, and updates support-library source discovery and FoMaC linkage.
Mapping pass consumes SuperconductingDevice mlir/include/mlir/Dialect/QCO/Transforms/Mapping/Mapping.h, mlir/lib/Dialect/QCO/Transforms/Mapping/*	createMappingPass accepts a shared device, routing uses device adjacency and distance APIs, and the internal AugmentedDevice is removed.
Device-aware pipeline and CLI flow mlir/include/mlir/Compiler/CompilerPipeline.h, mlir/lib/Compiler/CompilerPipeline.cpp, mlir/tools/mqt-cc/mqt-cc.cpp	Adds device configuration and transpilation snapshots, conditionally runs mapping and cleanup stages, and adds QDMI listing, configuration, and device-selection options.
Mapping tests use shared devices mlir/unittests/Dialect/QCO/Transforms/Mapping/test_mapping.cpp	Tests construct shared SuperconductingDevice instances, pass them to the mapping pass, and validate executability through device queries.
Release and source annotations CHANGELOG.md, src/fomac/FoMaC.cpp	Documents QDMI integration and adds a non-functional FoMaC job-parameter comment.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant mqt_cc
  participant QDMI
  participant QuantumCompilerPipeline
  participant MappingPass
  User->>mqt_cc: Select QDMI device
  mqt_cc->>QDMI: Prepare session and resolve device
  mqt_cc->>QuantumCompilerPipeline: Set config.device
  QuantumCompilerPipeline->>MappingPass: Run device-based transpilation
  MappingPass-->>QuantumCompilerPipeline: Return transformed IR
  QuantumCompilerPipeline-->>mqt_cc: Return compilation record

Loading

Possibly related PRs

• munich-quantum-toolkit/core#1600: Changes the mapping pass API for injected architecture information.
• munich-quantum-toolkit/core#1709: Updates mapping and device-connectivity modeling.
• munich-quantum-toolkit/core#1710: Updates compiler pipeline configuration and stage orchestration.

Suggested labels: QDMI, feature

Suggested reviewers: burgholzer, denialhaag

Poem

I hopped through graphs of qubits bright,
QDMI brought devices into sight.
Mapping followed each coupling trail,
While transpilation filled the compiler’s sail.
A carrot-sized CLI now makes the choice—
And every stage can raise its voice. 🐇

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.91% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description is detailed, but it omits the required template sections and checklist and describes changes not reflected in the changeset.	Rewrite the description to match the implemented QDMI, SuperconductingDevice, mapping, and mqt-cc changes, then include the required issue, dependencies, checklist, and validation details.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR satisfies #1082 by letting users supply hardware architecture as a compilation parameter via QDMI device selection.
Out of Scope Changes check	✅ Passed	The changes are focused on QDMI integration and supporting refactors, tests, build updates, and docs.
Title check	✅ Passed	The title clearly identifies the primary change: integrating QDMI device support into the compiler.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/arch-option-and-qdmi

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 9

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@mlir/include/mlir/Support/Qdmi.h`:
- Around line 20-26: Add Doxygen-style documentation comments on the header
declarations for mlir::qdmi::listAvailableDevices and mlir::qdmi::getDevice.
Describe each function’s purpose, its session parameter, the output stream
behavior for listAvailableDevices, and what getDevice returns when given a
device name; place the comments directly above the declarations in Qdmi.h to
match project convention.

In `@mlir/lib/Compiler/CompilerPipeline.cpp`:
- Around line 176-210: Remove the unused local SuperconductingDevice in the
CompilerPipeline transpilation block and update the stage counting logic so
totalStages includes the two device-dependent stages when config_.device is set.
In the pipeline around runStage, keep the mapping pass using
qco::createMappingPass and eliminate the dead scDevice construction, then adjust
the totalStages calculation near the pipeline setup so prettyPrintStage reports
the correct progress for both optional transpilation and QCO cleanup stages.

In `@mlir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp`:
- Around line 206-209: The constructor doc comment for MappingPass is stale and
still refers to a coupling set instead of the current device-based API. Update
the comment above MappingPassPassPass? constructor in MappingPass to describe
constructing the pass from a SuperconductingDevice, matching the
std::shared_ptr<SuperconductingDevice> parameter and keeping the wording aligned
with the current interface.

In `@mlir/lib/Support/SuperconductingDevice.cpp`:
- Around line 57-58: The coupling map handling in SuperconductingDevice
currently leaves the QDMI edge-direction semantics unresolved, which can make
adjacency checks inconsistent. Update the logic around the QDMI site-to-graph
construction so the relevant Graph/coupling set representation matches QDMI’s
actual edge semantics, and ensure areAdjacent(u, v) succeeds for both directions
if the source data is undirected. Use the SuperconductingDevice construction
path and the areAdjacent adjacency behavior as the main points to verify the
fix.
- Around line 29-36: In SuperconductingDevice::distanceBetween, replace the
UINT64_MAX sentinel check with std::numeric_limits<size_t>::max() so it matches
Graph::getDistMatrix()’s initialization and stays portable. Update the
comparison in distanceBetween to use the size_t max value, and ensure the needed
numeric_limits include is available through the existing includes rather than
relying on UINT64_MAX.
- Around line 50-72: The current getCouplingGraph implementation uses raw
site.getIndex() values from fomac::Device when constructing Graph, but those IDs
may be non-contiguous or offset, so remap all site IDs to a dense 0-based index
space before filling the qubit vector and coupling pairs. Update the logic in
SuperconductingDevice::getCouplingGraph to build a stable old-to-new index
mapping from device->getSites() and apply it to both the qubit list and the
coupling set so Graph receives valid contiguous indices.

In `@mlir/tools/mqt-cc/mqt-cc.cpp`:
- Around line 194-218: In mqt-cc.cpp, handle the requested-device failure in the
main compile flow by returning a nonzero exit code immediately after `getDevice`
fails and `listAvailableDevices(session, llvm::errs())` is printed, so the
pipeline does not continue with a null `config.device`. Also update the
intermediate-dump path in the compilation output to print the transpilation
records captured by `recordIntermediates`, specifically adding the
`afterTranspilation` and `afterTranspilationCanon` outputs in the section around
the existing “After Final QCO Canonicalization” and “After QCO-to-QC Conversion”
messages.
- Line 16: The include in mqt-cc.cpp uses the wrong header casing, which can
fail on case-sensitive filesystems. Update the include in the same spot to match
the actual header name, using the Qdmi.h casing so it aligns with
mlir/Support/Qdmi.h and the rest of the build references.

In `@mlir/unittests/Dialect/QCO/Transforms/Mapping/test_mapping.cpp`:
- Around line 134-145: The helper getNineQubitSquareGrid is mislabeled in its
comment: it constructs a 3×3 grid of 9 qubits, not a 9×9 topology. Update the
documentation comment above getNineQubitSquareGrid in test_mapping.cpp to
describe the actual 3×3 square-grid coupling set so the topology name matches
the connectivity.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 21adacff-e169-4b63-8e06-220ffd4384ed

📥 Commits

Reviewing files that changed from the base of the PR and between eff728d and d95ae33.

📒 Files selected for processing (14)

• mlir/include/mlir/Compiler/CompilerPipeline.h
• mlir/include/mlir/Dialect/QCO/Transforms/Mapping/Mapping.h
• mlir/include/mlir/Support/Graph.h
• mlir/include/mlir/Support/Qdmi.h
• mlir/include/mlir/Support/SuperconductingDevice.h
• mlir/lib/Compiler/CompilerPipeline.cpp
• mlir/lib/Dialect/QCO/Transforms/CMakeLists.txt
• mlir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp
• mlir/lib/Dialect/QCO/Utils/Graph.cpp
• mlir/lib/Support/CMakeLists.txt
• mlir/lib/Support/Qdmi.cpp
• mlir/lib/Support/SuperconductingDevice.cpp
• mlir/tools/mqt-cc/mqt-cc.cpp
• mlir/unittests/Dialect/QCO/Transforms/Mapping/test_mapping.cpp

[MatthiasReumann]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@mlir/include/mlir/Support/SuperconductingDevice.h`:
- Around line 45-46: Document the edge-case contract for
SuperconductingDevice::distanceBetween so callers know what it returns when u ==
v and when no path exists between qubits. Update the Doxygen comment on
distanceBetween to explicitly state the expected behavior for reachable versus
unreachable nodes, and make sure the wording prevents misuse by callers like the
heuristic in Mapping.cpp that subtracts 1 from the returned value.

In `@mlir/lib/Compiler/CompilerPipeline.cpp`:
- Line 214: The stage labels in CompilerPipeline comments are duplicated after
the earlier renumbering, so update the QIR stage comments in the pipeline to use
the correct sequential numbers. In CompilerPipeline, adjust the comments around
the QIR-related stages so they no longer say Stage 9/Stage 10 and instead match
the actual device-configured ordering (QIR stages 11 and 12), keeping the labels
consistent with the surrounding stage comments.

In `@mlir/lib/Support/Qdmi.cpp`:
- Around line 23-24: The loop in Qdmi.cpp is copying each device unnecessarily
because `session.getDevices()` yields `fomac::Device` objects and only
`getName()` is used. Update the range-based loop in the QDMI output code to
iterate with `const auto&` instead of `auto`, so the devices are read by
reference without extra copies.
- Around line 32-37: Replace the manual iterator search in the device lookup
with `std::find_if` for a more idiomatic and concise implementation. Update the
loop in the device-search logic to use `std::find_if` over `devices`, keeping
the same name-matching predicate on `getName()` and preserving the existing
behavior of returning the matching iterator or `devices.end()` when not found.

In `@mlir/lib/Support/SuperconductingDevice.cpp`:
- Around line 51-56: The getCouplingGraph logic currently relies on an assert
after calling device->getCouplingMap(), which can be compiled out and leave
siteCoupling dereferenced in release builds. Replace that assert with an
explicit runtime failure in getCouplingGraph before any use of
siteCoupling->size() or *siteCoupling, and keep the same guard covering all
subsequent coupling-map access so a missing map is handled safely.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fcf330bd-3fe1-49ea-bc63-80915d3ca0cc

📥 Commits

Reviewing files that changed from the base of the PR and between 7f6ee4b and 3691dcd.

📒 Files selected for processing (14)

• mlir/include/mlir/Compiler/CompilerPipeline.h
• mlir/include/mlir/Dialect/QCO/Transforms/Mapping/Mapping.h
• mlir/include/mlir/Support/Graph.h
• mlir/include/mlir/Support/Qdmi.h
• mlir/include/mlir/Support/SuperconductingDevice.h
• mlir/lib/Compiler/CompilerPipeline.cpp
• mlir/lib/Dialect/QCO/Transforms/CMakeLists.txt
• mlir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp
• mlir/lib/Dialect/QCO/Utils/Graph.cpp
• mlir/lib/Support/CMakeLists.txt
• mlir/lib/Support/Qdmi.cpp
• mlir/lib/Support/SuperconductingDevice.cpp
• mlir/tools/mqt-cc/mqt-cc.cpp
• mlir/unittests/Dialect/QCO/Transforms/Mapping/test_mapping.cpp

[MatthiasReumann]

@burgholzer @ystade

I think this one is ready to discuss.

• I've added a SuperconductingDevice¹ class that acts as an adapter for QDMI, coupling maps, and whatever is to follow (V2 at some point, I guess).
• The CLI is defined as follows (prefix: qdmi)

--qdmi-list-devices         // List all available QDMI devices. 
--qdmi-device=iqm-radiance  // Specify the device used for hardware-specific passes. 
--qdmi-config=./qdmi.json   // Specify session config, additional devices and their respective configs. 

• The specified device is loaded and stored in the QuantumCompilerConfig. The QDMI device is then used in the hardware-specific phase to construct the SuperconductingDevice. I assume superconducting devices only. Future work might implement a "dispatcher" to create the correct pass pipeline for the respective device's constraints.

---

CLI Example

matthias:~$ cat ~/Downloads/qdmi.json
{
    "devices": [
        {
            "libName": "/Users/matthias/Documents/projects/core/build/src/qdmi/devices/sc/libmqt-core-qdmi-sc-device.dylib",
            "prefix": "MQT_SC",
            "deviceConfig": {
                "baseUrl": "...",
                "token": "...",
                "authFile": "...",
                "authUrl": "...",
                "username": "...",
                "password": "...",
                "custom1": "...",
                "custom2": "...",
                "custom3": "...",
                "custom4": "...",
                "custom5": "..."
            }
        }
    ]
}
matthias:~$ mqt-cc --qdmi-list-devices --qdmi-config ~/Downloads/qdmi.json
[2026-07-09 14:03:58.473] [info] [Driver.cpp:193] Device session parameter BASE URL not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter TOKEN not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter AUTH FILE not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter AUTH URL not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter USERNAME not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter PASSWORD not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter CUSTOM1 not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter CUSTOM2 not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter CUSTOM3 not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter CUSTOM4 not supported by device (skipped)
[2026-07-09 14:03:58.474] [info] [Driver.cpp:193] Device session parameter CUSTOM5 not supported by device (skipped)
Available QDMI devices:
	MQT NA Default QDMI Device // Statically loaded.
	MQT SC Default QDMI Device // Statically loaded.
	MQT Core DDSIM QDMI Device // Statically loaded.
	MQT SC Default QDMI Device // Dynamically loaded.

Footnotes

1. I consciously avoided SCDevice because of "super-computing"; and generally to avoid acronyms as much as possible :) ↩

[burgholzer]

I have not yet had the chance to look through everything in detail here yet, but I have one general high-level observation already:

A lot of the QDMI-related functionality is built "outside" of QDMI here (building on top of FoMaC; relying on addDevice..).
I would argue that we need to take this one step further. These enhancements should directly go into the QDMI Driver so that the driver itself reads the config file and uses that to make its devices available.
The build should likely write a config file as part of the build, where one needs to be a bit careful about the library paths being embedded in the config because one needs to ensure that the config file also works in an install tree of MQT Core (such as in the Python bindings). We already perform some kind of shenanigans around that with the builtin devices and how they are hardcoded in the driver. The config file should replace the existing approach.
More generally, I believe that quite some of the functionality in the QDMI.h header should likely be functionality that is added to the FoMaC and/or Driver classes directly.

@MatthiasReumann does that make sense? Can you work with that?

[MatthiasReumann]

@burgholzer: I would argue that we need to take this one step further.

I'll try to summarize my thoughts on this. Let me know, if the following is valid.

These enhancements should directly go into the QDMI Driver so that the driver itself reads the config file and uses that to make its devices available.

Generally understood.

The build should likely write a config file as part of the build, where one needs to be a bit careful about the library paths being embedded in the config because one needs to ensure that the config file also works in an install tree of MQT Core (such as in the Python bindings). We already perform some kind of shenanigans around that with the builtin devices and how they are hardcoded in the driver. The config file should replace the existing approach.

I wonder: Is there any valid reason to link devices statically in the mqt-core driver? Wouldn't it be quite elegant if the mqt-core driver takes a config file at runtime (via function call or CLI) and loads the specified devices at boot-time?¹ I guess this would avoid any of the build shenanigans described by you. However, we could still supply a builtin-devices.json (maybe even auto-generate it) to the QDMI devices generated by the generator:

<cmake world>
generateIQMSpark()
generateIQMRadiance()
generateIBMHeron()

generateJSONConfig()

<c++ world>
Driver::get().init("config.json");

Because isn't the purpose of the mqt-core driver to be "plug-and-play"?

More generally, I believe that quite some of the functionality in the QDMI.h header should likely be functionality that is added to the FoMaC and/or Driver classes directly.

Understood.

---

Currently, what really confuses me - and I just realized - is that the Driver.cpp implements the QDMI client functions. So the driver is in fact the client in mqt-core.

Footnotes

1. which is actually already happening (just via CMake magic). ↩

[ystade]

@MatthiasReumann I skimmed through the conversation here, and to me, everything makes a lot of sense. I do not have additional comments that go beyond Lukas' ones right now. Let me know whether you would like to have feedback on any particular point.

[burgholzer]

Alright. Iterated on this quite a bit with the help of gpt-5.6-sol.
The comments in this review are not intended for @MatthiasReumann, but for iteration work on the PR that I am planning.
Let's see how quickly the iteration converges.
But I think this is starting to look really clean.

[burgholzer]

Alright. This feels like it is ready 🚀
Feels great to have QDMI integrated into the Compiler Collection 🥳