🤝 Design discussion: client interface, interoperability, and “stack-as-device” composition

[burgholzer]

This is a kick-off discussion to settle several architectural decisions around QDMI, interoperability, and how we expose an entire software stack to other stacks.

Context recap

• QDMI today is two C interfaces:
  • Device interface (C header/ABI): implemented by providers and third parties; each implementation is nameshifted via a unique prefix to avoid symbol collisions in-process. This interface contains device/property queries and job submission/management (plus authentication via sessions).
  • Client interface (C header/ABI): a neutral, non-nameshifted mirror of the device interface that adds a device handle as first argument to most methods. A QDMI “driver” loads one or more provider device libraries (nameshifted), exposes enumeration and returns opaque handles to use devices via the client interface.
• Above QDMI we’re building:
  • A compiler infrastructure (MLIR-based) that uses QDMI queries to tailor compilation and QDMI job APIs to submit programs and retrieve results; sessions handle auth.
  • A scheduler and other orchestration components.
  • Frontend adapters (e.g., Qiskit, PennyLane) that drive the stack.

Big question 1 — Do we need the client interface? Should we standardize the compiler↔QDMI boundary?

• Observation: While working on a QDMI driver implementation for the MQT (see ✨ MQT QDMI Driver munich-quantum-toolkit/core#1010) we noticed that our C++ driver already has an object-oriented abstraction. Writing a FoMaC C++ wrapper over the C client interface risks duplicating many of the same concepts, feeling redundant.
• Tension:
  • If we let the driver expose a FoMaC API directly (skipping the client interface), the compiler stack becomes tightly coupled to the specific driver. That improves ergonomics short-term but loses plug-and-play interoperability with other drivers/stacks.
  • If we keep the client interface as the canonical boundary, we preserve the ability to mix-and-match compilers, drivers, and devices across organizations (e.g., MQV collaborations), at the cost of boilerplate and a stricter ABI.
• Options (not mutually exclusive):
  1. Keep and evolve the client interface (recommended for interoperability):
     • Formalize versioning and capability negotiation (feature bits/extensions, error codes, profiles).
     • Reference FoMaC bindings (C++/Rust/Python) that wrap the client interface in ergonomic types while remaining driver-agnostic.
     • Provide conformance tests for drivers and bindings.
  2. Driver-native high-level API (ergonomics first):
     • A driver may additionally expose a C++ API tailored to a specific stack.
     • The compiler can talk to this API directly where interop isn’t required.
     • We keep the client interface for interop scenarios and upstream collaborations.
• Proposed stance:
  • Prioritize interoperability as a core goal. Keep the client interface and invest in it (versioning, capability discovery, conformance tests). Build reference C++ FoMaC libraries layered over the client interface to remove boilerplate for users.
  • Document this decision and avoid re-litigating unless we plan a v2 with a different approach.

Big question 2 — How do we expose an entire software stack to other stacks (stack-as-device), without bypassing schedulers?

• Constraints we established in prior discussions:
  • We do not share individual provider device libraries with external stacks. That would create contention outside our scheduler’s control.
  • Sharing direct access to a driver’s client interface also bypasses scheduling and policies.
• Desire: Wrap the whole software stack (scheduler + compiler + drivers + devices) behind a QDMI-compatible façade, so another stack can consume it via the same primitives. This enables A to consume B’s stack and vice versa.
• Challenges:
  • A stack may manage multiple devices. A naïve “stack looks like one device” wrapper either hides multiplicity or requires duplicating N exposed devices.
  • We lack a notion of composite/hierarchical devices and device graphs in QDMI v1.
  • Properties and capabilities across multiple child devices: how to surface them (union/intersection/selection)? How to identify and select a child at job submission time?
  • For stack-as-device composition, should device selection be explicit (client chooses) or delegated (provider/driver schedules), or both?

Proposed next steps:

• Reaffirm the client interface as the portability boundary for compilers and drivers, with FoMaC bindings layered on top. Or decide that this should be handled differently
• Outline a concept for interoperability between two stacks relying on QDMI and start the development of a small proof-of-concept.

---

Explicitly tagging some people here because I think this is a pretty fundamental discussion: @ystade @echavarria-lrz @mnfarooqi
Your input on this would be highly appreciated.

[hiq-lab]

Interesting discussion — we've been dealing with both questions from the other side (as a consumer/implementor rather than the QDMI core team), so here's our perspective from building Arvak, a Rust-native quantum compilation and orchestration platform with 13 backend adapters (IBM, IQM, AQT, Quantinuum, Braket, IonQ, Quandela, Pasqal/Pulser, QDMI, etc.).

On Big Question 1 — Keep the client interface

We strongly agree with the proposed stance. We implemented both sides of QDMI in Rust (client-side FFI in our adapter, device-side FFI for exposing Arvak as a QDMI device), and the client interface is what makes this possible without tight coupling.

The boilerplate concern is real — the buffer-query two-call pattern (NULL for size, allocate, query again) is verbose in every language. But the fix is reference bindings (C++, Rust, Python), not removing the boundary. We opened #351 to propose contributing Rust bindings that abstract this away while preserving the client interface as the portability layer.

The key insight: the client interface is an ABI contract. It's what lets us swap drivers without recompiling. FoMaC bindings are ergonomics on top, not a replacement.

On Big Question 2 — Stack-as-device composition

This is exactly what we do with Arvak's HAL Contract. Our architecture:

External consumer (QDMI client, gRPC, Python)
    ↓
HAL facade (validate → compile → route → submit)
    ↓
Backend registry (13 adapters, each behind the same trait)
    ↓
Physical devices (IBM QPUs, IQM Garnet, AQT ions, simulators, ...)

The HAL facade looks like "one device" to the outside but internally manages multiple backends. Some concrete design choices we made that may be relevant:

Device multiplicity: We expose individual backends and a routing layer. The client can either target a specific backend (submit(circuit, backend="ibm_torino")) or let the orchestrator choose based on circuit requirements (qubit count, gate set, queue depth). Both paths go through the same validate() → submit() → status() → result() lifecycle.

Capability aggregation: We don't union/intersect capabilities across child devices. Each backend exposes its own Capabilities struct (qubit count, gate set, topology, noise profile). The orchestrator uses these for routing decisions, but the client can query them individually. A "composite capabilities" endpoint that says "this stack can handle up to 156 qubits" would be misleading — it depends on which backend gets selected.

Scheduler integration: Jobs go through the HAL facade, which enforces scheduling policies before delegating to the backend adapter. External consumers never get direct access to a provider device library — they see the stack as a single QDMI device. This is exactly the constraint you described.

What QDMI would need for this pattern:

1. QDMI_DEVICE_PROPERTY_CHILDDEVICES (from PR ✨ Enabling Multi-Core Architectures #230) is the right primitive. A stack-as-device exposes child devices, each with their own properties.

2. A QDMI_DEVICE_PROPERTY_ROUTINGPOLICY or similar — does the stack select the device, or does the client? We support both: explicit (job_parameter: target_device) and delegated (orchestrator picks based on circuit analysis).

3. Job submission should allow an optional device hint without requiring it. The QDMI job parameter enum could add QDMI_DEVICE_JOB_PARAMETER_TARGETDEVICE for explicit selection.

We'd be happy to contribute a proof-of-concept: Arvak exposed as a QDMI composite device, where submitting a circuit via the QDMI client interface triggers Arvak's compilation + routing + backend submission pipeline internally.

[burgholzer]

Thanks for the input @hiq-lab.
Since the original creation of this issue over half a year ago, a lot of discussions have happened that are not properly reflected online as part of this issue.
It is very likely that the Client Interface will not exist in v2 of QDMI and will be replaced by a more modular extension infrastructure to facilitate all the different scenarios.

One quick note: Please be mindful of the maintainers' time when posting. Your messages are very clearly AI-assisted and overflow with content that is only tangent to the issue at hand.
We value external contributions, but only if they are not of the extractive kind. See https://llvm.org/docs/AIToolPolicy.html#extractive-contributions for what I mean with that.
We hope you understand.

[hiq-lab]

I do understand and I apologize. I will refrain in the future and thank you for taking the time to comment on this.