🔌 MLIR - Integrate DD-based QIR runtime with QDMI and compiler (end-to-end)

[burgholzer]

Background

We’ve wanted QIR support in MQT for a while. With #1091, we’re adding MLIR→QIR lowering; with #1099, we can translate from QuantumComputation to MLIR. Because we already import Qiskit/OpenQASM 3 into QuantumComputation, we can now transitively go Qiskit/OpenQASM 3 → QuantumComputation → MLIR → QIR (covering at least the QIR Base Profile).

In parallel, the first pieces of our integration with the Quantum Device Management Interface (QDMI) landed: the first (NA) device in #996 and the first MQT driver in #1010.

Also in parallel, we’ve been building a QIR backend/runtime based on the Decision Diagram (DD) package in MQT Core. This work currently lives in a private repository/branch: https://github.com/cda-tum/mqt-mlir/tree/feat-qir-backend
A pre-print describing the approach is available on arXiv: https://arxiv.org/abs/2411.18682v1

Bringing these strands together unlocks an end-to-end path: author a hybrid quantum-classical program, compile to QIR, and execute it against a QIR runtime via a QDMI device.

Problem

Right now the DD-based QIR runtime is private and not wired into the public MQT Core repo. There’s no QDMI device that consumes QIR payloads (text or binary) and no compiler-to-device hand-off. We need:

• A production-ready, open QIR runtime component (DD-based) in the repo.
• A QDMI device that accepts QIR programs (string and binary) and makes use of the runtime.
• A clean integration with the MLIR/QIR compiler pipeline so users can run compiled QIR via QDMI.
• A reference executable that links everything and can run hybrid programs (Base Profile first), paving the way for richer profiles.

Proposal:

Implement an end-to-end integration in three layers:

1. QIR runtime (DD-based) polishing and upstreaming

• Extract the runtime from the private repo into mqt-core/mlir or an appropriate src/qir/ subtree.
• Stabilize APIs for:
  • Loading QIR as LLVM IR text (.ll) and as LLVM bitcode (.bc); accept in-memory strings/byte buffers.
  • Configuring shots, seed, measurement return formats, and minimal device properties needed for Base Profile.
  • Executing entry points and retrieving classical results (mapping QIR Result* to a compact classical results buffer, e.g., std::vector<uint8_t> or bit-packed form).
• Document assumptions and supported QIR intrinsics (Base Profile focus); provide clear diagnostics for unsupported ops.

2. QDMI device for QIR

• Implement a QDMI device that:
  • Accepts payloads as either text (LLVM IR string) or binary (bitcode blob), plus run config (shots, seed, profile hints).
  • Internally loads the module into the DD-based runtime and executes the requested entry point.
  • Returns results via QDMI’s standard result container; include per-shot results and aggregate stats if available.
• Extend device properties to advertise QIR profile compatibility (Base Profile) and relevant limits (qubit count caps, precision modes, etc.).
• Include logging/trace hooks (optional) to assist debugging.

3. Compiler → QDMI integration

• Add a thin “submit-to-qir” path that:
  • Compiles a given circuit (Qiskit/OpenQASM 3/QuantumComputation/MLIR) to QIR (MLIR→QIR pipeline per ✨ Add MQTRef-QIR conversions #1091).
  • Produces both text (.ll) and bitcode (.bc) forms (configurable) and hands them to the QIR QDMI device.
• Ship a small C++ reference binary (and a Python binding if feasible) that:
  • Accepts input circuits or MLIR, compiles to QIR, invokes the QDMI device, and prints results.
  • Provides a seed option and potentially a --profile base selector.

4. Testing & CI

• Add lit/e2e tests that:
  • Compile small circuits (e.g., Bell, simple conditional) to QIR and run via the QDMI device.
  • Exercise both .ll and .bc paths.
  • Validate result equivalence vs the existing simulators for a tiny corpus.

Acceptance criteria

• DD-based QIR runtime is upstreamed into MQT Core with stable C++ API, documented assumptions, and Base Profile coverage.
• New QDMI device accepts both LLVM IR text and bitcode and returns results via standard QDMI containers.
• Compiler hand-off path exists: end-to-end tool can compile a Qiskit/OpenQASM 3 program to QIR and execute it via the QDMI device.
• E2E tests cover text and bitcode submission; results match existing simulators on a small test corpus; CI jobs added.
• A reference executable (C++) is provided; optional Python bindings expose a minimal compile_to_qir(...); device.run(...) flow.
• Documentation updated (QDMI devices, QIR runtime) with usage examples and known limitations; private repo code is deprecated/archived.