Qiskit interop: warning hygiene, 3.0-proofing, honest dependency floors

[rileyjmurray]

This makes pyGSTi's qiskit interop clean under error::pygsti.tools.exceptions.QiskitInteropWarning, which this PR promotes from a defined-but-inert exception class to a pytest.ini error. Getting there required fixing several real bugs that were hiding behind warnings nobody could see (or that were misclassified so they wouldn't fire at all), removing qiskit APIs slated for removal in 3.0, and correcting the ibmq extra's dependency floors, which were stale enough to break on qiskit versions we claim to support.

Five commits, one per phase, each leaving the suite green under the strict filter: 7e39339dc → 73a4f54bc → f4178a8c3 → 962c67a1e → 1bb2ae93f.

What changed

Warning hygiene (pygsti/tools/_qiskit_interop.py, new)

• Eleven copy-pasted exact-version checks against qiskit==2.1.1, scattered across circuit.py, internalgates.py, subcircuit_selection.py, mirror_edesign.py, and scarab.py, are replaced by one helper, check_qiskit_version(context, required=True), checked against a tested range (TESTED_QISKIT_RANGE = ((1, 4), (3,))) instead of a single pin.
• That consolidation incidentally fixed real bugs the old pattern was causing: a warn-inside-try/bare-except that turned the promoted warning into a false "qiskit does not appear to be installed" RuntimeError; a MissingDependencyWarning misclassification in subcircuit_selection.py where a genuine version mismatch was reported as a missing dependency and execution silently continued; and a NameError fall-through in internalgates.py when qiskit is truly absent.
• from_qiskit now warns about discarded classical data only when the circuit actually has clbits — previously it fired on len(circuit.cregs), so a pure pygsti→qiskit→pygsti round trip warned about discarding the empty cr register that convert_to_qiskit always attaches, even when nothing was measured.
• The plain-UserWarning 'skipping measure' is now a QiskitInteropWarning with an actual message.
• from_qiskit gains lossy={'warn', 'ignore', 'raise'}; the mirror-edesign pipeline passes lossy='ignore' at call sites where the loss is intentional.
• mirror_edesign's fullstack path no longer forwards coupling_map to transpile() alongside a backend — the warning claimed it was ignored, but an explicit coupling_map actually overrides the backend's map, so the old behavior silently used the wrong topology.
• New test/unit/tools/test_qiskit_interop.py exercises the warning paths directly.

Qiskit 3.0-proofing

• Removed the last uses of APIs slated for removal in qiskit 3.0: iterating a CircuitInstruction as a tuple (→ .operation/.qubits), qubit._index and layout.initial_layout[idx]._register.name == 'ancilla' (→ circuit.find_bit(qubit).index and isinstance(..., AncillaQubit)), and circuit._qbit_argument_conversion(i)[0] (→ the public, stable-since-1.0 circuit.qubits[i]).
• Test files: the deprecated QFT class (built on the also-removed BlueprintCircuit) is replaced with QFTGate.
• Considered and rejected: a global pytest filter promoting qiskit DeprecationWarnings to errors. Warning attribution follows stacklevel, so such a filter would promote all pygsti-attributed DeprecationWarnings, not just qiskit-related ones — too much blast radius on the full suite. Documented in the phase-2 commit message.

extras/ibmq guard split + honest floors

• ibmqexperiment.py imported ConvertToMidCircuitMeasure (added in qiskit-ibm-runtime 0.44) in the same try/except as the core runtime names. On any older runtime the whole import failed and _Sampler was set to None, disabling all IBMQ submission — even though nothing else needed the new pass. It's now guarded separately, with the assertion only in the code path that actually converts mid-circuit measurements (message names the real fix: upgrade runtime, or pass use_ibm_mcm=False).
• pyproject.toml's ibmq extra goes from the stale, unbounded qiskit>1, qiskit-ibm-runtime>=0.17.1 to qiskit>=1.4,<3, qiskit-ibm-runtime>=0.40, matching TESTED_QISKIT_RANGE.
• Validated: all 11 ibmq tests now pass on both qiskit 2.5.0/runtime 0.47 and qiskit 2.1.1/runtime 0.41.1 — the latter previously failed solely because of the coupled import.

Coverage

• test/unit/protocols/test_scarab.py (new): smoke tests for all three scarab benchmark wrappers (lowlevel/fullstack/subcircuit_mirror_benchmark), which are public API in pygsti.protocols.scarab but previously had zero coverage — these would have caught the phase-1 bare-except bug.
• test_circuit.py: a convert_to_qiskit argument matrix (qubits_to_measure in None/'all'/'active'/list form, oversized num_qubits, ordered_data_indices metadata, the invalid-option error path).
• test_subcirc_selection.py: greedy_growth_subcirc_selection coverage (direct call and via sample_subcircuits(strategy='greedy')), plus a stochastic_2q_drops test — see below. subcircuit_selection.py coverage goes from 42% to 80%.
• extras/devices gets no new tests, per plan: its calibration formats predate the current runtime API, and deprecation is proposed to maintainers instead of investing in coverage.

CI

• New .github/workflows/qiskit-interop.yml, weekly: a bare qiskit-1.4-floor matrix leg (runtime uninstalled), a runtime-0.40-floor leg, and a latest leg. Keeps TESTED_QISKIT_RANGE honest and should flag qiskit 3.0 breakage the week it ships rather than at user-report time.

Reviewer attention

1. New bug found, not fixed: stochastic_2q_drops=True is broken. Writing the greedy/stochastic coverage in phase 4 (previously 0% covered) surfaced that simple_weighted_subcirc_selection(..., stochastic_2q_drops=True) re-adds dangling two-qubit gates whose support, by definition, includes at least one qubit outside the selected subset — and the subcircuit is then built with line_labels=sorted(qubit_subset), so Circuit.__init__ raises ValueError on essentially any connected circuit. The new test documents the intended behavior and is marked @unittest.expectedFailure. Fixing it needs a maintainer call: should retained dangling gates expand the subcircuit's line labels (changing its effective width), or should they be truncated to their in-subset qubits? Whoever picks a direction should also remove the expectedFailure marker.
2. ibmq extra's dependency floor moved from qiskit>1 to qiskit>=1.4,<3 and from qiskit-ibm-runtime>=0.17.1 to >=0.40. This is a correction, not a new restriction — anything outside the old, unbounded range was already broken (that's how finding 5 was found), but it's technically a tightening of the declared floor that downstream pins might notice.
3. No global DeprecationWarning promotion. See the qiskit-3.0-proofing section above — flagging so it isn't independently proposed and then hit the same blast-radius problem.

Testing

Cross-version validation, all with the strict error::QiskitInteropWarning filter, 141 passed + 2 xfailed on each:

• qiskit 2.5.0 + qiskit-ibm-runtime 0.47 (py313 conda env)
• qiskit 2.1.1 + qiskit-ibm-runtime 0.41.1
• qiskit 1.4.6 + qiskit-ibm-runtime 0.37.0

[sserita]

+1 on Nick's suggestion for the subseq for easier selection of tests, but not blocking. Other than that, looks great, merge as you will. I'll make an issue for the 2q_drops problem, which will be on my plate most likely.