feat: support #pragma statements and preserve braket verbatim boxes - #341
feat: support #pragma statements and preserve braket verbatim boxes#341ryanhill1 wants to merge 4 commits into
Conversation
Pragmas were rejected outright (`Unsupported statement of type openqasm3.ast.Pragma`), which blocked verbatim execution on Braket QPUs since `#pragma braket verbatim` is the only way to pin physical qubits. Pragmas now pass through loads/validate/unroll/dumps unchanged, and a `braket verbatim` pragma marks the box that follows it so its gates are emitted as written instead of decomposed.
Argus reviewAuto-review is off for this repo. Tick the box below to run a review on this PR. Running Argus review... Estimated cost
Tip: you can also comment |
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![coderabbitai[bot]](https://avatars.github.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/pyqasm/modules/qasm3.py`:
- Around line 27-45: Complete the API documentation for
Qasm3Printer.visit_Pragma and dumps: add a concise docstring to visit_Pragma,
document dumps’ node and kwargs parameters and its return value in the project’s
required format, and annotate kwargs with the appropriate type while preserving
the existing behavior.
In `@src/pyqasm/visitor.py`:
- Around line 2943-2946: Update the _is_verbatim_pragma() docstring to document
the statement parameter and the boolean return value, while preserving its
existing behavior and type annotations.
- Around line 1586-1587: Update the verbatim custom-gate path in the visitor
branch using _in_verbatim_box and _visit_external_gate_operation so
_recording_ext_gate_depth is set while validating and emitting the original
custom gate, not its decomposed body. Preserve the prior depth-recording state
and restore it after the nested custom-gate operation, including nested verbatim
custom gates.
- Around line 3319-3321: Update the statement check in the visitor logic to
clear _verbatim_pragma_pending for every statement that is not a qasm3_ast.Box,
including intervening Pragma nodes. Add a regression test covering a verbatim
pragma followed by a non-verbatim pragma and then a box, ensuring the box is not
marked verbatim.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 7c7b5f8a-5695-4e1c-bd5c-252d9072bb5d
📒 Files selected for processing (6)
CHANGELOG.mdsrc/README.mdsrc/pyqasm/modules/qasm3.pysrc/pyqasm/printer.pysrc/pyqasm/visitor.pytests/qasm3/test_pragma.py
| class Qasm3Printer(Printer): | ||
| """OpenQASM 3 printer that writes pragmas in their '#pragma' form. | ||
|
|
||
| The upstream printer emits the bare 'pragma' keyword. Both forms parse, but tools | ||
| consuming the output (e.g. Amazon Braket for '#pragma braket verbatim') expect the | ||
| hashed form, which is also what they emit. | ||
| """ | ||
|
|
||
| def visit_Pragma(self, node: Pragma, context: PrinterState) -> None: | ||
| self._start_line(context) | ||
| self.stream.write(f"#pragma {node.command}") | ||
| self._end_line(context) | ||
|
|
||
|
|
||
| def dumps(node: QASMNode, **kwargs) -> str: | ||
| """Return the OpenQASM 3 string representation of ``node``.""" | ||
| out = io.StringIO() | ||
| Qasm3Printer(out, **kwargs).visit(node) | ||
| return out.getvalue() |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Complete the new API documentation and annotations.
Qasm3Printer.visit_Pragma() has no docstring. dumps() does not document node, kwargs, or its return value in the required format. Annotate kwargs as well.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pyqasm/modules/qasm3.py` around lines 27 - 45, Complete the API
documentation for Qasm3Printer.visit_Pragma and dumps: add a concise docstring
to visit_Pragma, document dumps’ node and kwargs parameters and its return value
in the project’s required format, and annotate kwargs with the appropriate type
while preserving the existing behavior.
Source: Coding guidelines
| elif self._in_verbatim_box or operation.name.name in self._external_gates: | ||
| result.extend(self._visit_external_gate_operation(operation, inverse_value, ctrls)) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Count a custom verbatim gate as one emitted gate.
When a custom gate is inside a verbatim box, _visit_external_gate_operation() validates it through _visit_custom_gate_operation(). That method sets _recording_ext_gate_depth only for configured external gates. It therefore records the decomposed gate body, although this path emits the original custom gate.
Set the depth-recording state for verbatim custom gates too. Preserve and restore the previous state for nested custom gates.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pyqasm/visitor.py` around lines 1586 - 1587, Update the verbatim
custom-gate path in the visitor branch using _in_verbatim_box and
_visit_external_gate_operation so _recording_ext_gate_depth is set while
validating and emitting the original custom gate, not its decomposed body.
Preserve the prior depth-recording state and restore it after the nested
custom-gate operation, including nested verbatim custom gates.
| @staticmethod | ||
| def _is_verbatim_pragma(statement: qasm3_ast.Pragma) -> bool: | ||
| """Check whether a pragma marks the following box as verbatim.""" | ||
| return statement.command.split() == ["braket", "verbatim"] |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add parameter and return documentation.
_is_verbatim_pragma() has type annotations, but its docstring does not describe statement or the boolean result.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pyqasm/visitor.py` around lines 2943 - 2946, Update the
_is_verbatim_pragma() docstring to document the statement parameter and the
boolean return value, while preserving its existing behavior and type
annotations.
Source: Coding guidelines
| if not isinstance(statement, (qasm3_ast.Pragma, qasm3_ast.Box)): | ||
| # a pending verbatim pragma only carries over to a box directly following it | ||
| self._verbatim_pragma_pending = False |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Clear the marker when any intervening pragma occurs.
The condition excludes every Pragma, so this sequence marks the box as verbatim even though #pragma braket verbatim does not immediately precede it:
`#pragma` braket verbatim
`#pragma` braket result probability
box { prx(0.1, 0.2) q[0]; }Clear _verbatim_pragma_pending for every non-Box statement. Add a regression test for an intervening non-verbatim pragma.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pyqasm/visitor.py` around lines 3319 - 3321, Update the statement check
in the visitor logic to clear _verbatim_pragma_pending for every statement that
is not a qasm3_ast.Box, including intervening Pragma nodes. Add a regression
test covering a verbatim pragma followed by a non-verbatim pragma and then a
box, ensuring the box is not marked verbatim.
- clear the pending verbatim marker on any non-box statement, so an intervening pragma drops it, matching the documented rule that the pragma must immediately precede the box - record a verbatim custom gate's depth once, as the external-gate path does, instead of counting the decomposed body it does not emit - document the new pragma printer and _is_verbatim_pragma
|
Reviewed all four findings; three were valid and are fixed in 993cd8b. Intervening pragma (major) — valid. The condition excluded every Verbatim custom gate depth — valid. Confirmed before the fix: a custom gate in a verbatim box was emitted as I did not add the preserve/restore of the previous state. The existing set-then-clear protocol already yields exactly one depth update for a nested custom gate (the inner call clears the flag, so the outer block skips); restoring the prior value would make both levels record, double-counting a single emitted gate. Verified: nested verbatim custom gate reports Both docstring findings — valid, added. One thing deliberately unchanged: a basic gate in a verbatim box still contributes its decomposition's depth ( |
![argus-eye[bot]](https://avatars.github.com/in/2969822?s=60&v=4){kind=small}
There was a problem hiding this comment.
🔎 Argus · 9/10 — Adds pragma and Braket verbatim-box support cleanly, with one validation edge case to address
🔍 PR intent vs diff (LLM analysis)
Argus read the diff against the stated intent. This is not an execution log — reviewer still needs to test behavior.
Goal: Support OpenQASM #pragma statements and preserve braket verbatim boxes through parsing, validation, unrolling, and serialization.
Not in scope:
- Fix remove_idle_qubits() recursion into box bodies.
- Fix unroll(consolidate_qubits=True) for physical qubits inside boxes.
Stated acceptance criteria (from PR/issue — not independently verified): - Pragmas pass unchanged through loads, validate, unroll, and dumps.
- #pragma braket verbatim marks the immediately following box as verbatim.
- Gates inside verbatim boxes are validated and counted but emitted without decomposition.
- Nested boxes inherit verbatim behavior, while each successive box requires its own pragma.
- Non-braket pragmas are preserved as opaque text.
- Qasm3Module prints pragmas with the #pragma form.
- Qasm2Module continues to reject pragmas.
- Circuit visualizations ignore pragmas when calculating timing and moments.
✅ Intent delivered
Verdict: This PR preserves pragmas through the QASM3 pipeline and correctly carries Braket verbatim behavior through nested boxes. It is close to merge-ready; resolving the remaining validation edge case would make the behavior more robust.
🟡 1 P1 · 6 files reviewed
Architecture: The parser-to-printer flow is well integrated; we should ensure validation semantics remain consistent for verbatim-box contents.
1 finding · 1 inline · 0 folded
🔢 354.5k tokens · $1.1995 total
| Stage | Tokens | Cost |
|---|---|---|
| Intent | 3.6k | $0.0021 |
| Triage | 3.7k | $0.0006 |
| Lead agent | 3.7k | $0.0094 |
| Review · bug_hunter | 82.2k | $0.3078 |
| Review · security | 81.0k | $0.2597 |
| Review · architecture | 80.6k | $0.2872 |
| Review · regression | 95.3k | $0.3220 |
| Acceptance | 1.9k | $0.0051 |
| Scoring | 1.5k | $0.0035 |
| Synthesis | 1.0k | $0.0020 |
Contract: production/full · checked: bug_hunter, security, architecture, regression · review took 2m32s
Dashboard → · React 👎 to dismiss · Reply to any inline comment or use @argus-eye help to chat
A pragma at the end of a box body left the marker armed, so the next box was emitted verbatim without one of its own. The text parser keeps pragmas global, but loads() also accepts a hand-built program, which reaches the same path.
|
Valid, and reachable — fixed in b3bf100. The text parser keeps pragmas global, but |
There was a problem hiding this comment.
Approved with comments — well-designed feature, and the hard part (positional scoping) is right. None of the findings block merge; the first two are inherited rather than introduced here.
Findings
All findings are posted inline on the relevant lines. Checklist:
- M1 — Verbatim gate with a decomposition rule reports decomposed depth (inherited)
- M2 — Custom gate in a verbatim box emits output that does not round-trip (inherited)
- M3 — Qubit-referencing pragmas silently desync from renumbering passes
- L1 —
mpl_drawpragma branch is load-bearing but untested - L2 — Docstring the honour-vs-forward asymmetry
How it was tested
- Pragma round-trip through
loads/unroll/dumps; barepragmanormalised to#pragma. - Verbatim box preserves
rx/czas written (depth=2,num_qubits=2); plainbox { crz(0.5) q[0], q[1]; }still decomposes to 12 statements, so no over-reach. - Scoping, all four positions: pragma → gate → box leaves the box non-verbatim; one pragma with two boxes marks only the first; a nested box inherits; two stacked pragmas count only the immediately preceding one.
#pragmainside a box is rejected by the parser itself (pragmas must be global), so the global-only assumption invisit_statementholds. - Validation is preserved inside a verbatim box: undefined gate, wrong arity, duplicate operand and out-of-range index all still raise. Verbatim is not an escape hatch.
- QASM 2 still rejects pragmas via the statement whitelist.
- Suite on branch: 647 passed, 4 skipped.
- Merged worktree of #341 + #344 + #345: 658 passing; all six open PRs merge cleanly (
CHANGELOG.mdonly) at 697 passing.
Next steps
Merge after #344 and #345 — both "Not fixed here" caveats are fixed by them, verified on a merged worktree, so that section can be deleted from the description rather than filed as follow-ups. Specifically: consolidate_qubits=True on a verbatim box with physical qubits raises AttributeError on this branch alone and works merged (#344); remove_idle_qubits()/reverse_qubit_order() correctly rewrite box bodies merged (#345). Then file the M1 follow-up and add the doc lines from M2/M3. L2 is attached as an applicable suggestion.
| self._recording_ext_gate_depth = gate_name in self._external_gates | ||
| # definition of a custom gate here - handle the depth separately afterwards. | ||
| # A verbatim gate is emitted as written, so it counts once, like an external gate. | ||
| self._recording_ext_gate_depth = self._in_verbatim_box or gate_name in self._external_gates |
There was a problem hiding this comment.
[M1] Verbatim gate with a decomposition rule reports decomposed depth — Implementation · Medium (pre-existing; follow-up, not a blocker)
Rationale: #pragma braket verbatim box { crz(0.5) q[0], q[1]; } emits exactly one instruction but reports depth == 12 — the depth of the decomposition that was deliberately not performed. (verbatim box { rx; cz } → 2 and verbatim box { ccx } → 1 are both correct, so this is specific to gates that have a decomposition rule.)
Root cause: _visit_external_gate_operation calls self._visit_basic_gate_operation(operation) "just for validation" at src/pyqasm/visitor.py:1351, and that call still runs _update_qubit_depth_for_gate. The _recording_ext_gate_depth suppression this line extends guards only the custom gate path, not the basic-gate path.
This is pre-existing — on main, unroll(external_gates=['crz']) also reports depth=12 while emitting one crz — so it is not a blocker here. It is worth flagging because this PR makes the defect reachable without the user opting in per gate name: any Braket verbatim program containing a decomposable gate now silently reports an inflated depth.
Change requested: file a follow-up against _visit_external_gate_operation (suppress depth recording around the validation-only call) and link it here. The "Not fixed here" section already sets the precedent.
There was a problem hiding this comment.
Follow-up filed as #352 and linked from the description. No code change here, per your call that it is not worth growing the diff.
Reproduced both halves first: verbatim box { crz(0.5) q[0], q[1]; } reports depth=12 while emitting one statement, and unroll(external_gates=['crz']) reports the same 12 on main. verbatim box { rx; cz } → 2 and verbatim box { ccx } → 1, so it is specific to gates with a decomposition rule as you said. #352 points at the validation-only _visit_basic_gate_operation call and the _recording_ext_gate_depth asymmetry.
The description now carries a "Known gap" section instead of leaving it unmentioned.
| if isinstance(operation, qasm3_ast.QuantumPhase): | ||
| result.extend(self._visit_phase_operation(operation, inverse_value, ctrls)) | ||
| elif operation.name.name in self._external_gates: | ||
| elif self._in_verbatim_box or operation.name.name in self._external_gates: |
There was a problem hiding this comment.
[M2] Custom gate in a verbatim box emits output that does not round-trip — Design / Maintenance · Medium (pre-existing in kind)
Rationale: this branch makes every gate take the external path when inside a verbatim box, user-defined ones included. Given gate mygate a { h a; } and a verbatim box containing mygate q[0];, the emitted program keeps the mygate q[0]; call while unrolling drops the gate mygate definition. Feeding that output back through pyqasm fails:
ValidationError: Unsupported / undeclared QASM operation: mygate
Pre-existing in kind — the same non-round-tripping output reproduces on main via unroll(external_gates=['mygate']). The difference that matters: external_gates is an explicit per-name opt-in, whereas _in_verbatim_box makes every gate external implicitly, including user-defined ones a device cannot accept as native instructions. Braket verbatim boxes exist specifically for native hardware gates, so this combination is meaningless in the first place.
Change requested: either reject a non-native, non-basis custom gate inside a verbatim box with a clear error, or document that verbatim bodies must contain only device-native gates. At minimum a line in the docs added by this PR.
There was a problem hiding this comment.
Resolved in 456e03b — took the documentation option.
Confirmed the round-trip failure first: gate mygate a { h a; } plus a verbatim box containing mygate q[0]; emits the call while unrolling drops the definition, and feeding that back gives ValidationError: Unsupported / undeclared QASM operation: mygate.
src/README.md now has a Pragmas section stating that a verbatim box should contain only device-native gates, that pyqasm does not enforce it, and what the output does if you ignore that. Went with documenting rather than rejecting since the combination is meaningless rather than dangerous, and rejecting would make pyqasm the arbiter of what a device considers native.
| """ | ||
| return statement.command.split() == ["braket", "verbatim"] | ||
|
|
||
| def _visit_pragma(self, statement: qasm3_ast.Pragma) -> list[qasm3_ast.Pragma]: |
There was a problem hiding this comment.
[M3] Qubit-referencing pragmas silently desync from renumbering passes — Implementation · Medium
Rationale: pass-through means no transform can rewrite pragma text, so a pragma that names qubits by index goes stale as soon as a renumbering pass runs. Two verified cases:
qubit[4] q;
#pragma braket noise bit_flip(0.1) q[3]
h q[3];
After unroll() + remove_idle_qubits() the register shrinks to qubit[1] q and the gate is rewritten to h q[0], but the pragma still reads q[3] — now pointing outside the declared register. Symmetrically, reverse_qubit_order() rewrites h q[0] → h q[3] while the pragma stays on q[0], so the noise channel lands on a different qubit than the gate it was written for. Relatedly, #pragma braket noise bit_flip(0.1) q[9] against qubit[1] q passes validate() cleanly.
This is inherent to the pass-through design, and parsing vendor pragma grammar is not the suggestion. It is newly reachable, though — before this PR such programs were rejected outright — and it fails silently, producing a program that is valid QASM and wrong. Note this is distinct from the box recursion gap that #345 fixes: no amount of body-walking fixes opaque text.
Change requested: document in the docs added here that pragma bodies are opaque and are not rewritten by qubit-renumbering passes (remove_idle_qubits, reverse_qubit_order, consolidate_qubits), so pragmas referencing qubits by index may go stale. A warning when a renumbering pass runs on a module carrying pragmas would be a reasonable follow-up, not required here.
There was a problem hiding this comment.
Resolved in 456e03b — documented in the same Pragmas section.
Verified both directions on this branch:
remove_idle_qubits() : qubit[4] q -> qubit[1] q, h q[3] -> h q[0], pragma still q[3]
reverse_qubit_order(): h q[3] -> h q[0], pragma still q[3]
The README now records that remove_idle_qubits(), reverse_qubit_order() and unroll(consolidate_qubits=True) renumber the program but not pragma text, that an index-referencing pragma can therefore land on the wrong qubit or outside the register, and that nothing raises because the output is still valid QASM. Left the warning-on-renumbering idea as a follow-up, per your note that it is not required here.
| if isinstance(s, ast.QuantumPhase): | ||
| global_phase += Qasm3ExprEvaluator.evaluate_expression(s.argument)[0] | ||
| elif isinstance(s, ast.Pragma): | ||
| continue # pragmas carry no timing information |
There was a problem hiding this comment.
[L1] This branch is load-bearing but untested — Implementation · Low
Rationale: without this continue, the pragma reaches the moment builder and hits raise ValueError(f"Unsupported statement: {statement}") — Pragma subclasses neither Statement nor QuantumStatement, so it is not filtered downstream. Correct fix, but there is no pragma case anywhere in tests/visualization/, so a regression here would surface as a hard error for anyone drawing a Braket verbatim program.
Change requested: add one mpl_draw test over a program containing a pragma.
There was a problem hiding this comment.
Resolved in 456e03b — test_draw_qasm3_pragma added to tests/visualization/test_mpl_draw.py.
Verified it is load-bearing: deleting the continue makes it fail with ValueError: Unsupported statement: Pragma(...), exactly as you described.
One thing worth knowing about the motivation: a Braket verbatim program cannot be drawn today regardless of this branch — Box has no moment-builder case either, so mpl_draw on any boxed program raises ValueError: Unsupported statement: Box(...), on main as well. So the test uses a bare pragma with plain gates to isolate the branch you flagged. Happy to file the Box drawing gap separately if you want it tracked.
| Pragmas carry vendor specific directives which pyqasm does not interpret, so they | ||
| are passed through unchanged. A 'braket verbatim' pragma additionally marks the box | ||
| that follows it, whose gates are then left as written instead of being decomposed. |
There was a problem hiding this comment.
[L2] Docstring the honour-vs-forward asymmetry — Maintenance · Low
Rationale: #pragma braket verbatim followed by something other than a box is a no-op for pyqasm, but it is still copied to the output, where Braket would apply it to whatever follows. That is defensible given "the marker is consumed by the next statement", but the split between what pyqasm honours and what it merely forwards is currently implicit.
Change requested:
| Pragmas carry vendor specific directives which pyqasm does not interpret, so they | |
| are passed through unchanged. A 'braket verbatim' pragma additionally marks the box | |
| that follows it, whose gates are then left as written instead of being decomposed. | |
| Pragmas carry vendor specific directives which pyqasm does not interpret, so they | |
| are passed through unchanged. A 'braket verbatim' pragma additionally marks the box | |
| that follows it, whose gates are then left as written instead of being decomposed. | |
| A verbatim pragma not followed by a box is honoured by nothing in pyqasm but is | |
| still copied to the output, where the consumer applies it to whatever comes next. |
Separately, in this file: the module-level dumps added in modules/qasm3.py shadows both openqasm3.printer.dumps and the public pyqasm.dumps (different signature). The shadowing is contained to that one file, so this is readability only — worth a glance, not a change request.
There was a problem hiding this comment.
Resolved in 456e03b — suggestion applied verbatim to the _visit_pragma docstring.
Left the dumps shadowing in modules/qasm3.py alone, per your note that it is readability only and not a change request.
- README gains a Pragmas section: pragma bodies are opaque and not rewritten by qubit-renumbering passes, and verbatim boxes should hold only device-native gates (M2, M3) - _visit_pragma docstring states the honour-vs-forward split for a verbatim pragma not followed by a box (L2) - test_draw_qasm3_pragma covers the Pragma branch in the moment builder; verified to fail when the branch is removed (L1)
3 participants
Summary of changes
Closes #340.
Problem
Any program containing a
#pragmawas rejected withValidationError: Unsupported statement of type <class 'openqasm3.ast.Pragma'>, becauseast.Pragmahad no entry in the visitor's dispatch map. That blocks verbatim execution on Braket QPUs through the qBraid stack:#pragma braket verbatimis the only remaining mechanism for fixed physical qubits, and pyqasm rejected the program client-side before it could be submitted.Pragmas now pass through
loads/validate/unroll/dumpsunchanged.Verbatim boxes are not decomposed
Pass-through alone is not enough: unrolling still rewrote the gates inside the box, so a verbatim
prx(...) $1came out as anrz/rx/rz/rx/rzchain the device cannot accept. Abraket verbatimpragma now marks theboxthat immediately follows it, and gates inside that box take the existing external-gate path — validated and counted for depth/qubits, but emitted as written. Nested boxes inherit it; the marker is consumed by the next statement, so each verbatim box needs its own pragma.The verbatim check is a literal match on the pragma command (
braket verbatim). Every other pragma is opaque text that pyqasm copies through.#pragmavspragmaopenqasm3's printer emits the barepragmakeyword. Both forms parse, but Braket emits and documents the hashed form, and the point of this change is round-tripping to Braket — soQasm3Modulenow prints via aPrintersubclass that writes#pragma. QASM 2 output is untouched (Qasm2Modulestill rejects pragmas via its statement whitelist).Limits of pass-through, documented
src/README.mdgains a Pragmas section recording two things the design does not give you:remove_idle_qubits(),reverse_qubit_order()andunroll(consolidate_qubits=True)renumber the program but not the opaque pragma body, so#pragma braket noise bit_flip(0.1) q[3]can end up on a different qubit than it was written for, or outside the register — silently, since the output is still valid QASM. Inherent to pass-through; parsing vendor pragma grammar is not on the table.gatedefinition, so that output does not load back into pyqasm.Known gap: depth of verbatim gates
#pragma braket verbatim box { crz(0.5) q[0], q[1]; }emits one instruction but reportsdepth == 12— the depth of the decomposition that was deliberately skipped. Pre-existing on theexternal_gatespath (unroll(external_gates=["crz"])reports the same onmain) and tracked in #352; this PR makes it reachable without opting in per gate name. Only gates with a decomposition rule are affected:verbatim box { rx; cz }reports 2 andverbatim box { ccx }reports 1, both correct.Merge order
Merge after #344 and #345. Two caveats that would otherwise apply here are fixed by them:
unroll(consolidate_qubits=True)on a verbatim box with physical qubits raisesAttributeErroron this branch alone and works merged (#344), andremove_idle_qubits()/reverse_qubit_order()correctly rewrite box bodies once merged (#345). Neither is on the path the issue needs (plainunroll()+dumps()).Tests
tests/qasm3/test_pragma.pycovers round-tripping,#pragmanormalisation, verbatim preservation, and the positional scoping in all four arrangements (pragma → gate → box, one pragma with two boxes, nested box inheritance, stacked pragmas). Validation inside a verbatim box is asserted to still reject undefined gates, wrong arity, duplicate operands and out-of-range indices — verbatim is not an escape hatch.tests/visualization/test_mpl_draw.py::test_draw_qasm3_pragmacovers thePragmabranch in the moment builder;Pragmasubclasses neitherStatementnorQuantumStatement, so without that branch a pragma reachesraise ValueError(f"Unsupported statement: ..."). Verified to fail when the branch is removed.