✨ Preserve quantum-register subroutines in OpenQASM 3

🤖 AI text below 🤖

Problem Statement

OpenQASM 3 supports subroutines such as def f(qubit[4] q), but MQT Core currently models only custom gate definitions. Import lowers gate formals to scalar QC qubits, and export accepts only leading f64 parameters followed by scalar-qubit arguments.

Using gate or flattening a register loses the source-level function boundary and cannot represent indexed register logic faithfully.

Proposed Solution

Import and export one coherent, useful subset of OpenQASM 3 subroutines after the shared QC/QCO register-call contract is available.

Supported subset

• Global, defined, non-recursive, void def subroutines.
• One or more scalar qubit or fixed positive qubit[N] parameters.
• Existing supported statements in the body, including calls to previously defined supported gates and subroutines.
• No local qubit declarations.
• Register actuals are whole register identifiers. Scalar actuals use existing scalar references.
• All quantum actuals at a call must be provably pairwise disjoint.

Import each supported subroutine as a private QC func.func with borrowed scalar/memref arguments and ordinary func.call. Export reachable ordinary functions with at least one fixed register argument as def. Continue to export scalar mqt.unitary functions as gate.

Keep the parser, semantic model, QC emitter, and exporter in one pull request. A syntax-only intermediate state is not independently useful.

Likely implementation areas:

• OpenQASM lexer tokens and syntax nodes
• OpenQASMParser.h and semantic analysis
• OpenQASMToQCEmitter.cpp
• TranslateQCToOpenQASM3.cpp
• Frontend documentation and focused parser, semantics, emitter, and round-trip tests

Acceptance criteria

• Import and export support a subroutine with mixed scalar-qubit and multiple fixed-register parameters.
• Nested supported subroutine calls work when definitions precede use.
• QC→OpenQASM 3→QC preserves register count, order, and static sizes.
• Duplicate and overlapping quantum actuals are rejected before emission.
• Dynamic registers, slices, concatenations, unresolved calls, recursion, and non-void subroutines receive targeted diagnostics.
• Existing custom-gate import and export behavior remains unchanged.
• Tests include negative parser/semantic cases and an end-to-end round trip.

Dependencies and related work

• Parent feature: #2427
• Depends on: #2428
• Related broader backlog: #1733
• General classical arrays remain in #2109.
• Register slices remain in #2110.
• Coordinate naming and unitary recognition with #2414 and #2413, but do not make either issue a prerequisite.
• Language contract: https://openqasm.com/versions/3.0/language/subroutines.html

Non-goals

Classical by-value parameters; classical register parameters; bit[N] references; classical return values; extern; early return; recursion; local qubit declarations; dynamic or sliced quantum arrays; modifiers on subroutine calls.

Start with the OpenQASM lexer and syntax nodes, OpenQASMParser.h, and semantic analysis to trace how definitions and calls are represented. Then inspect OpenQASMToQCEmitter.cpp and TranslateQCToOpenQASM3.cpp; add focused parser, semantics, emitter, and round-trip tests covering the acceptance criteria, including diagnostics and unchanged custom-gate behavior.