[burgholzer]

🤖 AI text below 🤖

Description

Route Qiskit-to-OpenQASM 3 QDMI submissions through Core's Qiskit importer and OpenQASM exporter. Native import preserves physical sites, gate names, scalar parameters, operand order, and classical outputs. The backend validates device support before conversion. Advertised if/for/while/switch/break/continue operations and Store assignments map to Qiskit instructions; captured blocks use operand maps rather than top-level register-layout restrictions.

Opaque gates use private external functions without invented definitions. OpenQASM 2 input accepts opaque declarations; OpenQASM 3 output emits receiver-supplied calls, since that language has no opaque declaration. Unresolved execution, conflicting opaque signatures, and unlowered annotated operations reject explicitly. The Qiskit backend requires registers to partition the circuit bits in register order. DDSIM advertises Store support, using the compiler's existing assignment and local-variable lowering.

Use LLVM lookup containers in the importer, sorting variable identities only when constructing SSA tuples. Permutation-cache keys use owned SmallVectors with borrowed lookup; and opaque-cache hits compare argument types without rebuilding function types. Opaque-gate creation returns Expected errors, translated to Python exceptions by the binding-side caller. Share symbol naming, consolidate serializer tests, and integrate the contracts into existing documentation.

Emit OPENQASM 3; unless emitted syntax requires a newer minor version. Both native switches and switches generated for indexed tables require 3.1; the exporter tracks this while emitting, without a second traversal.

Provide compiler-backed IQM JSON and Base/Adaptive QIR serializers in text and bitcode. Physical import preserves qubit indices while lowering gate definitions. The consuming QIRProgram.to_iqm_json(target, copy=False) exposes the existing exporter and is shared with the compiler pipeline. IQM accepts placed PRX/CZ and complete, unique terminal readout; finite unconditional global phase is omitted from sampling payloads. Native placements remain validated.

Provider registrations override the new fallbacks. Prefer device-native/custom formats, then QPY, OpenQASM 3, Adaptive QIR, Base QIR, and OpenQASM 2. This retains opaque-gate submission and the effective previous DDSIM default. Devices with external QIR serializers that also advertise QPY/OpenQASM now follow this documented order. Conversion failure does not trigger a format retry.

Require qiskit>=2.5,<2.7 without the optional QASM importer. OpenQASM 2 submission and QPY 17 remain supported. Supported-minor nox tests use uv overlays. Git-Qiskit tests retain the exact-header build and use locked environments without backing up or replacing the lockfile. Users independently calling Qiskit's optional OpenQASM importer must install its extra themselves or use Core's converters.

Validation

Signed head: 532330d.

• 4,105 native tests passed; whole-file C++ lint and repository lint passed.
• Final installed wheel: 2,084 Python tests passed on Qiskit 2.6.1, one optional qirrunner test skipped; 596 focused tests passed on Qiskit 2.5.0.
• Fresh Python installation, device discovery, and all QIR encodings passed. The documented CMake consumer and bundled runtime/tool checks passed (three tests); C++ consumption requires the documented matching LLVM SDK.
• Regenerated stubs, executable documentation and internal links passed; rendered serializer guidance was inspected in Chrome. The final rendered page loaded successfully with an empty console.
• Raw QIR operands detect physical-site compaction even when counts agree. Previous-wheel failures prove the new serializer cases; the existing independent IQM matrix oracle also covers the direct physical-import/export API and ownership.
• The strengthened opaque-gate and format-order tests fail before the preference fix and pass afterward. One Ponytail review and a specialist challenge found no further justified changes.
• Paired public-entry-point probes on saved switch/for/continue and QFT12 programs (64 shots) measured 10-12 ms through QASM versus 19-28 ms through Adaptive bitcode. Serialization and result wait dominate; formatting is negligible. Shared-host measurements support preserving the existing path, not a general speed claim. No cache, second converter, routing pass, or format-retry mechanism was added.
• Current IQM provider source was checked at 06ff24ed8c396525111159df88d77a430093e78b for radians, site names, readout ordering and serializer precedence; no external provider job was submitted.
• Earlier validation of the unchanged nox workflow passed supported-minor and Git-Qiskit probes with matching C headers and unchanged uv.lock. Development probes do not extend the supported range.

Hosted CI is pending/unobserved. Other platforms and external hardware were not evaluated on this head.

AI assistance: Codex implemented and reviewed these changes under explicit user authorization.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[codecov]

Codecov Report

❌ Patch coverage is 57.50000% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...lir/lib/Target/OpenQASM/TranslateQCToOpenQASM3.cpp	21.4%	11 Missing ⚠️
mlir/lib/Target/OpenQASM/OpenQASMToQCEmitter.cpp	14.2%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!