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

[marcelwa]

🤖 AI text below 🤖

Summary

Adds examples/discover_backends.py, a third example alongside mqt_bench.py
and qsci_h2.py that demonstrates discovery rather than targeting a
single, already-known backend: it lists the quantum computers available on an
IQM Server, queries each one's qubit count and (where exposed) two-qubit gate
fidelity, and selects the largest QC that satisfies a --min-qubits
constraint, printing what was found and what was chosen.

Motivation

This mirrors the "list resources → filter by constraint → use the match"
pattern used in two 2026 arXiv papers on QRMI, a related IBM/Pasqal-led effort
to integrate quantum resources into HPC schedulers:

• arXiv:2506.10052's Python example calls service.resources(), picks one,
  and prints qrmi.metadata() before building a transpile target.
• arXiv:2607.19591's Grid Engine integration selects a resource via
  qsub -l qpu=PASQAL_FRESNEL,qpu_ready=1,qpu_slots=6 job.sh — select-by-name
  plus numeric constraints (readiness, capacity).

QDMI-on-IQM already exposes the underlying device-property API
(docs/usage.md: qubit count, coupling map, T1/T2, gate fidelities), but had
no example exercising discovery end-to-end.

What's actually discoverable today (and the resulting design)

Investigating the C++ session-init path (src/iqm_device.cpp,
Process_static_quantum_architecture) and the Python/FoMaC layer
(python/iqm/qdmi/qiskit.py, mqt.core.fomac) turned up:

• Each QDMI device session is scoped to a single quantum computer, chosen
  by ID, alias, or "first available" during
  IQM_QDMI_device_session_init. The full list of QCs is fetched
  once internally (GET api/v1/quantum-computers) purely to resolve that
  selection — it is not returned to the caller and there is no
  Python/C++ binding exposing it.
• mqt.core.fomac.Session.get_devices() looked promising but lists
  statically registered FoMaC devices (e.g. the DDSIM simulator), not
  dynamically loaded IQM QCs, so it doesn't help here either.
• Per-QC properties (qubit count, two-qubit gate fidelity) are fully
  reachable through the existing public API once a QC is selected:
  IQMBackend(qc_alias=...) plus the standard Qiskit Target (error on
  InstructionProperties). T1/T2 is only reachable via a private
  QDMIBackend._device attribute from mqt-core, so the example reports
  two-qubit gate fidelity as the "calibration quality" signal instead and
  documents that limitation rather than reaching into private internals.

Given that, this PR does not add or change any C++/Python binding. The
example issues the same api/v1/quantum-computers REST call the session
already performs internally (documented as a limitation directly in the
script's docstring and in docs/examples.md), then uses only the existing
public IQMBackend/Target API for everything else. A proper "list QCs"
binding would be a reasonable, separately-scoped follow-up if this pattern
turns out to be broadly useful, but felt out of scope for a single example
script.

Other changes

• noxfile.py: wire discover_backends.py into the examples nox session
  (--backend sim/--backend iqm), matching the existing two examples.
• pyproject.toml: add requests.** to tool.ty.analysis.allowed-unresolved-imports,
  following the existing pattern for example-only dependencies not required by
  the core library.
• docs/examples.md: new "Discovering and Selecting Backends" section with a
  literalinclude of the script and a sim-backend code-cell, matching the
  existing two examples' documentation style.
• CHANGELOG.md: [Unreleased] entry.

Update: Added a documented future-direction note (script docstring +
docs/examples.md) about the IQM Server API's queue-length /
availability-window signal (apparently cloud/Resonance-oriented, unconfirmed
for on-prem, not currently surfaced through QDMI-on-IQM's bindings) — no
speculative code calling it.

Update: Replaced the T1/T2/status workarounds with the public
mqt.core.fomac Device/Site/Operation API (Device.status(),
Site.t1()/t2(), Operation.fidelity() — all already available on the
existing mqt-core~=3.7.0 pin, no dependency change needed) instead of
reaching into the private QDMIBackend._device attribute. Also corrected the
future-direction note: verified against the actual installed mqt-core wheel
that upstream PR munich-quantum-toolkit/core#1912 does not fix multi-QC
enumeration — IQM's own C++ device implementation
(IQM_QDMI_device_session_init in src/iqm_device.cpp) resolves exactly one
QC per opened session regardless of mqt-core's device registry, so #1912 is
relevant only as the mechanism for registering already-known aliases, not as
a fix for the enumeration problem itself.

Test plan

• uvx nox -s lint passes (ruff, ty — including the new
  requests import — rumdl, license headers, etc.)
• uvx nox -s tests-3.14 passes (28 passed, 3 skipped live-IQM tests;
  unchanged — no Python source under python/iqm/qdmi/ was touched, so no
  new tests were needed)
• uvx nox -s examples -- --backend sim passes, including the new
  discover_backends.py --backend sim --min-qubits 3 invocation
• Not run: --backend iqm / live IQM discovery (would require real IQM
  Server credentials; intentionally not exercised in this session per
  task constraints)

🤖 Generated with Claude Code