✨ Add examples/discover_backends.py for IQM QC discovery and selection

CHANGELOG.md

@@ -12,6 +12,9 @@ releases may include breaking changes.
 
 ### Added
 
+- ✨ Add `examples/discover_backends.py`, listing the quantum computers
+  available on an IQM Server and selecting one that satisfies a `--min-qubits`
+  constraint ([#146]) ([**@marcelwa**])
 - ✨ Validate IQM backend and target-QC availability once per node for each
   Slurm job step before launching tasks ([#136]) ([**@burgholzer**])
 - ✨ Add `iqm.qdmi.offloader` module exposing programmatic `sample` and
@@ -120,6 +123,7 @@ Compatible with QDMI `v1.3.0`.
 
 <!-- PR links -->
 
+[#146]: https://github.com/iqm-finland/QDMI-on-IQM/pull/146
 [#136]: https://github.com/iqm-finland/QDMI-on-IQM/pull/136
 [#134]: https://github.com/iqm-finland/QDMI-on-IQM/pull/134
 [#133]: https://github.com/iqm-finland/QDMI-on-IQM/pull/133

docs/examples.md

@@ -12,17 +12,20 @@ Welcome to the end-to-end tutorial. This guide walks you step by step through
 driving real quantum workloads on IQM systems using QDMI-on-IQM and the packaged
 {py:class}`~iqm.qdmi.qiskit.IQMBackend`.
 
-Whether you want to estimate molecular ground-state energies with [QSCI][qsci]
-or benchmark hardware with [MQT Bench][mqt-bench], the example scripts in this
-repository provide a practical starting point. This tutorial focuses on two
-application areas:
+Whether you want to estimate molecular ground-state energies with [QSCI][qsci],
+benchmark hardware with [MQT Bench][mqt-bench], or discover which IQM quantum
+computer to target in the first place, the example scripts in this repository
+provide a practical starting point. This tutorial focuses on three application
+areas:
 
 - **Quantum chemistry:** using [QSCI][qsci] and [Qiskit Nature][qiskit-nature]
   to estimate the ground-state energy of an H2 molecule.
 - **Benchmarking:** running [MQT Bench][mqt-bench] programs such as
   [GHZ states][ghz-state], [Deutsch-Jozsa][deutsch-jozsa],
   [QFT][quantum-fourier-transform], [graph states][graph-state],
   [W states][w-state], [Grover][grover], or [Quantum Phase Estimation][qpe].
+- **Backend discovery:** enumerating the quantum computers available on an IQM
+  Server and selecting one that satisfies a qubit-count constraint.
 
 :::{important}
 The example scripts live in the QDMI-on-IQM repository and are not shipped with
@@ -61,6 +64,7 @@ uvx nox -s examples
 # Run specific examples
 ./examples/qsci_h2.py --shots 256 --maxiter 5 --cutoff 4
 ./examples/mqt_bench.py --benchmark ghz --shots 128
+./examples/discover_backends.py --min-qubits 5
 ```
 
 ## Quantum Chemistry
@@ -153,6 +157,84 @@ Now try running the same script with `--backend iqm` to see how the distribution
 looks on real hardware. Remember to set the required environment variables for
 authentication before running the script.
 
+## Discovering and Selecting Backends
+
+Before running a workload, it can be useful to discover which quantum computers
+are actually available on an IQM Server and pick one programmatically, rather
+than hardcoding a single alias. The `examples/discover_backends.py` script
+demonstrates this: it lists the quantum computers exposed by the configured IQM
+Server endpoint, opens each one and queries its status, qubit count, per-site
+T1/T2, and (where exposed) two-qubit gate fidelity through the public
+`mqt.core.fomac` `Device`/`Site`/`Operation` API, and selects the largest one
+that satisfies a `--min-qubits` constraint.
+
+```{literalinclude} ../examples/discover_backends.py
+:language: python
+:caption: examples/discover_backends.py
+:start-after: "# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception"
+```
+
+Run it directly against an IQM Server (remember to set the required
+authentication environment variables first):
+
+```console
+./examples/discover_backends.py --min-qubits 5
+```
+
+Or exercise the simulator path, which reports the local DDSIM simulator's qubit
+count without contacting an IQM Server:
+
+```{code-cell} ipython3
+!../examples/discover_backends.py --backend sim --min-qubits 5
+```
+
+:::{note}
+QDMI-on-IQM does not currently expose a Python or C++ binding for listing every
+quantum computer on a server: each opened QDMI device session resolves to
+exactly one quantum computer, selected by ID, alias, or "first available" during
+session initialization (`IQM_QDMI_device_session_init` /
+`Process_static_quantum_architecture` in `src/iqm_device.cpp`). This example
+works around that by issuing the same `api/v1/quantum-computers` request the
+session already performs internally to learn the available aliases, then opens
+each candidate's device and queries it through the public
+`mqt.core.fomac.Device`/`Site`/`Operation` API for every other query.
+:::
+
+:::{note}
+True multi-QC enumeration without the `api/v1/quantum-computers` REST call above
+is not something any current or planned `mqt-core` release can fix on its own,
+because the root cause lives in this repo's own C++ device implementation, not
+in `mqt-core`: `mqt.core.fomac.Session.get_devices()` only ever returns one
+`Device` per registered `DeviceDefinition`, and each `DeviceDefinition` this
+library can hand `mqt-core` still resolves to exactly one IQM quantum computer,
+per the session-initialization behavior above. Registering one
+`DeviceDefinition` per alias would still require knowing every alias up front -
+the same requirement the REST call exists to satisfy. An open (unmerged)
+`mqt-core` pull request,
+[core#1912](https://github.com/munich-quantum-toolkit/core/pull/1912) ("Add
+configurable QDMI device discovery"), adds exactly that
+`DeviceRegistry`/`DeviceDefinition` mechanism (`qdmi.json` / `[tool.qdmi]` /
+env-var configuration), which would be the right way to *register* multiple
+already-known aliases as separate `Device`s - but it is relevant only as context
+here, not as a fix for the enumeration problem itself, which needs a change to
+this repo's own C++ session initialization to resolve. A related, larger,
+also-open PR,
+[core#1901](https://github.com/munich-quantum-toolkit/core/pull/1901),
+redesigns FoMaC and `qdmi::Driver` around that same registry and was reportedly
+exercised against IQM's own QDMI implementation branches during development.
+Neither PR has merged, and this note describes context, not a plan this repo
+currently depends on.
+
+Separately, and independent of that `mqt-core` discussion: the IQM Server API is
+also known to expose a queue-length / execution-availability-window signal,
+described for the "pay-as-you-go queue" and therefore apparently
+cloud/Resonance-oriented (unconfirmed for on-premise quantum computers).
+QDMI-on-IQM does not currently surface that signal through its Python or C++
+bindings, so this example does not use it. Once it is exposed through the
+library, ranking candidates by queue depth in addition to qubit count and
+fidelity would be a natural enhancement here.
+:::
+
 [deutsch-jozsa]: https://en.wikipedia.org/wiki/Deutsch%E2%80%93Jozsa_algorithm
 [ghz-state]: https://en.wikipedia.org/wiki/Greenberger%E2%80%93Horne%E2%80%93Zeilinger_state
 [graph-state]: https://en.wikipedia.org/wiki/Graph_state