feat: support #pragma statements and preserve braket verbatim boxes

CHANGELOG.md

@@ -15,6 +15,7 @@ Types of changes:
 ## Unreleased
 
 ### Added
+- Added support for `#pragma` statements, which previously raised `ValidationError: Unsupported statement of type <class 'openqasm3.ast.Pragma'>` and blocked any program carrying one. Pragmas are now passed through `loads`/`validate`/`unroll`/`dumps` unchanged, and are printed in their `#pragma` form (the upstream printer emits the bare `pragma` keyword). A `#pragma braket verbatim` additionally marks the `box` that immediately follows it: gates inside a verbatim box are emitted as written instead of being decomposed, so verbatim submissions to Braket QPUs keep the native gates they were built with. ([#341](https://github.com/qBraid/pyqasm/pull/341))
 - Added support for the `c3x` (3-controlled X) and `rc3x`/`rcccx` (relative-phase 3-controlled X) gates, decomposed into basis gates following qiskit's `C3XGate`/`RC3XGate` definitions. Also extended the `ctrl @` modifier chain so that 3- and 4-control stacks on `x` (e.g. `ctrl @ ctrl @ ctrl @ x`, `ctrl(4) @ x`) resolve to `c3x`/`c4x`. ([#320](https://github.com/qBraid/pyqasm/pull/320))
 
 ### Improved / Modified

src/README.md

@@ -30,7 +30,7 @@ Source code for OpenQASM 3 program validator and semantic analyzer
 | QuantumGateModifier (ctrl)     | ✅          | Completed              |
 | WhileLoop                      | ✅          | Completed              |
 | IODeclaration                  | 📋          | Planned                |
-| Pragma                         | 📋          | Planned                |
+| Pragma                         | ✅          | Preserved as-is        |
 | Annotation                     | 📋          | Planned                |
 | DurationType                   | ✅          | Completed              |
 | StretchType                    | ✅          | Completed              |
@@ -41,3 +41,22 @@ Source code for OpenQASM 3 program validator and semantic analyzer
 | ComplexType                    | ✅          | Completed              |
 | AngleType                      | ✅          | Completed              |
 | ExternDeclaration              | ✅          | Completed              |
+
+## Pragmas
+
+A pragma body is opaque text. pyqasm copies it to the output unchanged and never parses
+it, with one exception: `#pragma braket verbatim` marks the `box` that immediately
+follows it, and gates inside that box are emitted as written rather than decomposed.
+
+Two consequences worth knowing before relying on them:
+
+- **Qubit-renumbering passes do not rewrite pragmas.** `remove_idle_qubits()`,
+  `reverse_qubit_order()` and `unroll(consolidate_qubits=True)` renumber qubits in the
+  program but not inside pragma text, so a pragma naming qubits by index — say
+  `#pragma braket noise bit_flip(0.1) q[3]` — can end up on a different qubit than the
+  one it was written for, or outside the declared register. The output is still valid
+  QASM, so nothing raises.
+- **A verbatim box should contain only device-native gates.** That is what Braket
+  verbatim boxes are for, and pyqasm does not enforce it: a user-defined gate inside a
+  verbatim box is emitted as a call while unrolling drops its `gate` definition, so the
+  output does not load back into pyqasm.

src/pyqasm/modules/qasm3.py

@@ -16,12 +16,50 @@
 Defines a module for handling OpenQASM 3.0 programs.
 """
 
-from openqasm3.ast import Program
-from openqasm3.printer import dumps
+import io
+from typing import Any
+
+from openqasm3.ast import Pragma, Program, QASMNode
+from openqasm3.printer import Printer, PrinterState
 
 from pyqasm.modules.base import QasmModule
 
 
+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:
+        """Write a pragma node, keeping the '#' that the upstream printer drops.
+
+        Args:
+            node (Pragma): The pragma to write.
+            context (PrinterState): The printer state, carrying the current indent.
+        """
+        self._start_line(context)
+        self.stream.write(f"#pragma {node.command}")
+        self._end_line(context)
+
+
+def dumps(node: QASMNode, **kwargs: Any) -> str:
+    """Return the OpenQASM 3 string representation of ``node``.
+
+    Args:
+        node (QASMNode): The node to print, usually a Program.
+        **kwargs (Any): Printer options, forwarded to `openqasm3.printer.Printer`.
+
+    Returns:
+        str: The printed program.
+    """
+    out = io.StringIO()
+    Qasm3Printer(out, **kwargs).visit(node)
+    return out.getvalue()
+
+
 class Qasm3Module(QasmModule):
     """
     A module representing an openqasm3 quantum program.

src/pyqasm/printer.py

@@ -134,6 +134,8 @@ def mpl_draw(  # pylint: disable=too-many-locals
     for s in program._statements:
         if isinstance(s, ast.QuantumPhase):
             global_phase += Qasm3ExprEvaluator.evaluate_expression(s.argument)[0]
+        elif isinstance(s, ast.Pragma):
+            continue  # pragmas carry no timing information
         else:
             statements.append(s)
 

src/pyqasm/visitor.py

@@ -143,6 +143,11 @@ def __init__(  # pylint: disable=too-many-arguments
         # timeline within the box. Delays on disjoint qubits run in parallel,
         # so box durations are validated against the per-qubit maximum.
         self._box_delay_frames: list[dict[tuple[str, int], float]] = []
+        # A 'braket verbatim' pragma applies to the box that immediately follows it.
+        # Gates inside such a box are emitted as written so that the device receives
+        # the exact native instructions the user asked for.
+        self._verbatim_pragma_pending: bool = False
+        self._in_verbatim_box: bool = False
         self._in_extern_function: bool = False
         self._openpulse_qubit_map: dict[str, set[str]] = {}
         self._total_pulse_qubits: int = 0
@@ -188,6 +193,7 @@ def _construct_visit_map(self):
             qasm3_ast.ContinueStatement: self._visit_continue,
             qasm3_ast.DelayInstruction: self._visit_delay_statement,
             qasm3_ast.Box: self._visit_box_statement,
+            qasm3_ast.Pragma: self._visit_pragma,
             qasm3_ast.CalibrationDefinition: self._visit_calibration_definition,
             qasm3_ast.CalibrationStatement: self._visit_calibration_statement,
             qasm3_ast.CalibrationGrammarDeclaration: self._visit_calibration_grammar_declaration,
@@ -1257,8 +1263,9 @@ def _visit_custom_gate_operation(
         self._scope_manager.push_context(Context.GATE)
 
         # Pause recording the depth of new gates because we are processing the
-        # definition of a custom gate here - handle the depth separately afterwards
-        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
 
         result = []
         for gate_op in gate_definition_ops:
@@ -1577,7 +1584,7 @@ def _visit_generic_gate_operation(  # pylint: disable=too-many-branches, too-man
         for _ in range(power_value):
             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:
                 result.extend(self._visit_external_gate_operation(operation, inverse_value, ctrls))
             elif operation.name.name in self._custom_gates:
                 result.extend(self._visit_custom_gate_operation(operation, inverse_value, ctrls))
@@ -2934,6 +2941,42 @@ def _visit_delay_statement(
 
         return [statement]
 
+    @staticmethod
+    def _is_verbatim_pragma(statement: qasm3_ast.Pragma) -> bool:
+        """Check whether a pragma marks the following box as verbatim.
+
+        Args:
+            statement (qasm3_ast.Pragma): The pragma to inspect.
+
+        Returns:
+            bool: True for a 'braket verbatim' pragma, False for any other.
+        """
+        return statement.command.split() == ["braket", "verbatim"]
+
+    def _visit_pragma(self, statement: qasm3_ast.Pragma) -> list[qasm3_ast.Pragma]:
+        """
+        Visit a Pragma statement.
+
+        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.
+
+        Args:
+            statement (qasm3_ast.Pragma): The Pragma node to visit.
+        Returns:
+            list[qasm3_ast.Pragma]: The pragma, unmodified.
+        """
+        logger.debug("Visiting pragma '%s'", statement.command)
+        if self._is_verbatim_pragma(statement):
+            self._verbatim_pragma_pending = True
+
+        if self._check_only:
+            return []
+
+        return [statement]
+
     def _visit_box_statement(self, statement: qasm3_ast.Box) -> list[qasm3_ast.Statement]:
         """
         Visit a Box statement.
@@ -2943,6 +2986,9 @@ def _visit_box_statement(self, statement: qasm3_ast.Box) -> list[qasm3_ast.State
             list[qasm3_ast.Statement]: The list of statements generated by the Box statement.
         """
         statements = []
+        outer_verbatim = self._in_verbatim_box
+        self._in_verbatim_box = outer_verbatim or self._verbatim_pragma_pending
+        self._verbatim_pragma_pending = False
         _box_time_var = statement.duration
         box_duration_val = 0
         if _box_time_var is not None:
@@ -2976,6 +3022,9 @@ def _visit_box_statement(self, statement: qasm3_ast.Box) -> list[qasm3_ast.State
         self._scope_manager.restore_context()
         self._scope_manager.decrement_scope_level()
         self._scope_manager.pop_scope()
+        self._in_verbatim_box = outer_verbatim
+        # a marker left behind by the body must not reach the next box
+        self._verbatim_pragma_pending = False
 
         delay_frame = self._box_delay_frames.pop()
         if _box_time_var and box_duration_val and delay_frame:
@@ -3265,18 +3314,26 @@ def _visit_include(self, include: qasm3_ast.Include) -> list[qasm3_ast.Statement
 
         return [include]
 
-    def visit_statement(self, statement: qasm3_ast.Statement) -> list[qasm3_ast.Statement]:
+    def visit_statement(
+        self, statement: qasm3_ast.Statement | qasm3_ast.Pragma
+    ) -> list[qasm3_ast.Statement]:
         """Visit a statement element.
 
         Args:
-            statement (qasm3_ast.Statement): The statement to visit.
+            statement (qasm3_ast.Statement | qasm3_ast.Pragma): The statement to visit.
 
         Returns:
             None
         """
         logger.debug("Visiting statement '%s'", str(statement))
         result = []
 
+        if not isinstance(statement, qasm3_ast.Box):
+            # a pending verbatim pragma only carries over to a box directly following it.
+            # Clearing before dispatch lets a verbatim pragma re-arm the flag for itself,
+            # while any other statement - another pragma included - drops it.
+            self._verbatim_pragma_pending = False
+
         visitor_function = self._visit_map.get(type(statement))
         if visitor_function:
             if isinstance(statement, qasm3_ast.ExpressionStatement):
@@ -3293,11 +3350,13 @@ def visit_statement(self, statement: qasm3_ast.Statement) -> list[qasm3_ast.Stat
             )
         return result
 
-    def visit_basic_block(self, stmt_list: list[qasm3_ast.Statement]) -> list[qasm3_ast.Statement]:
+    def visit_basic_block(
+        self, stmt_list: Sequence[qasm3_ast.Statement | qasm3_ast.Pragma]
+    ) -> list[qasm3_ast.Statement]:
         """Visit a basic block of statements.
 
         Args:
-            stmt_list (list[qasm3_ast.Statement]): The list of statements to visit.
+            stmt_list (Sequence[qasm3_ast.Statement | qasm3_ast.Pragma]): The statements to visit.
 
         Returns:
             list[qasm3_ast.Statement]: The list of unrolled statements.