Add representation of box (#13869)

* Add representation of `box`

This adds in the base `box` control-flow construction, with support for
containing instructions and having a literal delay, like the `Delay`
instruction.

This supports basic output to OpenQASM 3, QPY and some rudimentary
support in the text and mpl drawers.  The transpiler largely handles
things already, since control flow is handled generically in most
places.

Known issues:

- We expect this to be able to accept stretches in its duration, just as
  `Delay` can, which will need a follow-up.
- We expect `Box` to support "annotations" in a future release of
  Qiskit.
- There is currently no way in OpenQASM 3 to represent a qubit that is
  idle during a `box` without inserting a magic instruction on it.
- IBM backends don't claim support for `box` yet, so `transpile` against
  a backend will fail, though you can modify the `Target` to add the
  instruction manually.

Add tests of box

* Add QPY backwards-compatibility test

* Add `BoxOp.body` getter and tests

Author: jakelishman

crates/circuit/src/dag_circuit.rs

@@ -2317,6 +2317,7 @@ impl DAGCircuit {
         let condition_op_check = imports::CONDITION_OP_CHECK.get_bound(py);
         let switch_case_op_check = imports::SWITCH_CASE_OP_CHECK.get_bound(py);
         let for_loop_op_check = imports::FOR_LOOP_OP_CHECK.get_bound(py);
+        let box_op_check = imports::BOX_OP_CHECK.get_bound(py);
         let node_match = |n1: &NodeType, n2: &NodeType| -> PyResult<bool> {
             match [n1, n2] {
                 [NodeType::Operation(inst1), NodeType::Operation(inst2)] => {
@@ -2373,6 +2374,10 @@ impl DAGCircuit {
                                     for_loop_op_check
                                         .call1((n1, n2, &self_bit_indices, &other_bit_indices))?
                                         .extract()
+                                } else if name == "box" {
+                                    box_op_check
+                                        .call1((n1, n2, &self_bit_indices, &other_bit_indices))?
+                                        .extract()
                                 } else {
                                     Err(PyRuntimeError::new_err(format!(
                                         "unhandled control-flow operation: {}",

crates/circuit/src/imports.rs

@@ -110,6 +110,8 @@ pub static SWITCH_CASE_OP_CHECK: ImportOnceCell =
     ImportOnceCell::new("qiskit.dagcircuit.dagnode", "_switch_case_eq");
 pub static FOR_LOOP_OP_CHECK: ImportOnceCell =
     ImportOnceCell::new("qiskit.dagcircuit.dagnode", "_for_loop_eq");
+pub static BOX_OP_CHECK: ImportOnceCell =
+    ImportOnceCell::new("qiskit.dagcircuit.dagnode", "_box_eq");
 pub static UUID: ImportOnceCell = ImportOnceCell::new("uuid", "UUID");
 pub static BARRIER: ImportOnceCell = ImportOnceCell::new("qiskit.circuit", "Barrier");
 pub static DELAY: ImportOnceCell = ImportOnceCell::new("qiskit.circuit", "Delay");

qiskit/circuit/__init__.py

@@ -1315,6 +1315,7 @@ def __array__(self, dtype=None, copy=None):
 
 from .controlflow import (
     ControlFlowOp,
+    BoxOp,
     WhileLoopOp,
     ForLoopOp,
     IfElseOp,

qiskit/circuit/controlflow/__init__.py

@@ -18,13 +18,14 @@
 from .continue_loop import ContinueLoopOp
 from .break_loop import BreakLoopOp
 
+from .box import BoxOp
 from .if_else import IfElseOp
 from .while_loop import WhileLoopOp
 from .for_loop import ForLoopOp
 from .switch_case import SwitchCaseOp, CASE_DEFAULT
 
 
-CONTROL_FLOW_OP_NAMES = frozenset(("for_loop", "while_loop", "if_else", "switch_case"))
+CONTROL_FLOW_OP_NAMES = frozenset(("for_loop", "while_loop", "if_else", "switch_case", "box"))
 """Set of the instruction names of Qiskit's known control-flow operations."""
 
 
@@ -53,5 +54,6 @@ def get_control_flow_name_mapping():
         "while_loop": WhileLoopOp,
         "for_loop": ForLoopOp,
         "switch_case": SwitchCaseOp,
+        "box": BoxOp,
     }
     return name_mapping

qiskit/circuit/controlflow/box.py

@@ -0,0 +1,163 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2025.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Simple box basic block."""
+
+from __future__ import annotations
+
+import typing
+
+from qiskit.circuit.exceptions import CircuitError
+from .control_flow import ControlFlowOp
+
+if typing.TYPE_CHECKING:
+    from qiskit.circuit import QuantumCircuit
+
+
+class BoxOp(ControlFlowOp):
+    """A scoped "box" of operations on a circuit that are treated atomically in the greater context.
+
+    A "box" is a control-flow construct that is entered unconditionally.  The contents of the box
+    behave somewhat as if the start and end of the box were barriers, except it is permissible to
+    commute operations "all the way" through the box.  The box is also an explicit scope for the
+    purposes of variables, stretches and compiler passes.
+
+    Typically you create this by using the builder-interface form of :meth:`.QuantumCircuit.box`.
+    """
+
+    def __init__(
+        self,
+        body: QuantumCircuit,
+        duration: None = None,
+        unit: typing.Literal["dt", "s", "ms", "us", "ns", "ps"] = "dt",
+        label: str | None = None,
+    ):
+        """
+        Default constructor of :class:`BoxOp`.
+
+        Args:
+            body: the circuit to use as the body of the box.  This should explicit close over any
+                :class:`.expr.Var` variables that must be incident from the outer circuit.  The
+                expected number of qubit and clbits for the resulting instruction are inferred from
+                the number in the circuit, even if they are idle.
+            duration: an optional duration for the box as a whole.
+            unit: the unit of the ``duration``.
+            label: an optional string label for the instruction.
+        """
+        super().__init__("box", body.num_qubits, body.num_clbits, [body], label=label)
+        self.duration = duration
+        self.unit = unit
+
+    @property
+    def params(self):
+        return self._params
+
+    @params.setter
+    def params(self, parameters):
+        # pylint: disable=cyclic-import
+        from qiskit.circuit import QuantumCircuit
+
+        (body,) = parameters
+
+        if not isinstance(body, QuantumCircuit):
+            raise CircuitError(
+                "BoxOp expects a body parameter of type "
+                f"QuantumCircuit, but received {type(body)}."
+            )
+
+        if body.num_qubits != self.num_qubits or body.num_clbits != self.num_clbits:
+            raise CircuitError(
+                "Attempted to assign a body parameter with a num_qubits or "
+                "num_clbits different than that of the BoxOp. "
+                f"BoxOp num_qubits/clbits: {self.num_qubits}/{self.num_clbits} "
+                f"Supplied body num_qubits/clbits: {body.num_qubits}/{body.num_clbits}."
+            )
+
+        self._params = [body]
+
+    @property
+    def body(self):
+        """The ``body`` :class:`.QuantumCircuit` of the operation.
+
+        This is the same as object returned as the sole entry in :meth:`params` and :meth:`blocks`.
+        """
+        # Not settable via this property; the only meaningful way to replace a body is via
+        # larger `QuantumCircuit` methods, or using `replace_blocks`.
+        return self.params[0]
+
+    @property
+    def blocks(self):
+        return (self._params[0],)
+
+    def replace_blocks(self, blocks):
+        (body,) = blocks
+        return BoxOp(body, duration=self.duration, unit=self.unit, label=self.label)
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, BoxOp)
+            and self.duration == other.duration
+            and self.unit == other.unit
+            and super().__eq__(other)
+        )
+
+
+class BoxContext:
+    """Context-manager that powers :meth:`.QuantumCircuit.box`.
+
+    This is not part of the public interface, and should not be instantiated by users.
+    """
+
+    __slots__ = ("_circuit", "_duration", "_unit", "_label")
+
+    def __init__(
+        self,
+        circuit: QuantumCircuit,
+        *,
+        duration: None = None,
+        unit: typing.Literal["dt", "s", "ms", "us", "ns", "ps"] = "dt",
+        label: str | None = None,
+    ):
+        """
+        Args:
+            circuit: the outermost scope of the circuit under construction.
+            duration: the final duration of the box.
+            unit: the unit of ``duration``.
+            label: an optional label for the box.
+        """
+        self._circuit = circuit
+        self._duration = duration
+        self._unit = unit
+        self._label = label
+
+    def __enter__(self):
+        # For a box to have the semantics of internal qubit alignment with a resolvable duration, we
+        # can't allow conditional jumps to exit it.  Technically an unconditional `break` or
+        # `continue` could work, but we're not getting into that.
+        self._circuit._push_scope(allow_jumps=False)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is not None:
+            # If we're leaving the context manager because an exception was raised, there's nothing
+            # to do except restore the circuit state.
+            self._circuit._pop_scope()
+            return False
+        scope = self._circuit._pop_scope()
+        # Boxes do not need to pass any further resources in, because there's no jumps out of a
+        # `box` permitted.
+        body = scope.build(scope.qubits(), scope.clbits())
+        self._circuit.append(
+            BoxOp(body, duration=self._duration, unit=self._unit, label=self._label),
+            body.qubits,
+            body.clbits,
+        )
+        return False

qiskit/circuit/quantumcircuit.py

@@ -51,6 +51,7 @@
 from .controlflow import ControlFlowOp, _builder_utils
 from .controlflow.builder import CircuitScopeInterface, ControlFlowBuilderBlock
 from .controlflow.break_loop import BreakLoopOp, BreakLoopPlaceholder
+from .controlflow.box import BoxOp, BoxContext
 from .controlflow.continue_loop import ContinueLoopOp, ContinueLoopPlaceholder
 from .controlflow.for_loop import ForLoopOp, ForLoopContext
 from .controlflow.if_else import IfElseOp, IfContext
@@ -737,13 +738,14 @@ class QuantumCircuit:
     ==============================  ================================================================
     :class:`QuantumCircuit` method  Control-flow instruction
     ==============================  ================================================================
-    :meth:`if_test`                 :class:`.IfElseOp` with only a ``True`` body.
-    :meth:`if_else`                 :class:`.IfElseOp` with both ``True`` and ``False`` bodies.
-    :meth:`while_loop`              :class:`.WhileLoopOp`.
-    :meth:`switch`                  :class:`.SwitchCaseOp`.
-    :meth:`for_loop`                :class:`.ForLoopOp`.
-    :meth:`break_loop`              :class:`.BreakLoopOp`.
-    :meth:`continue_loop`           :class:`.ContinueLoopOp`.
+    :meth:`if_test`                 :class:`.IfElseOp` with only a ``True`` body
+    :meth:`if_else`                 :class:`.IfElseOp` with both ``True`` and ``False`` bodies
+    :meth:`while_loop`              :class:`.WhileLoopOp`
+    :meth:`switch`                  :class:`.SwitchCaseOp`
+    :meth:`for_loop`                :class:`.ForLoopOp`
+    :meth:`box`                     :class:`.BoxOp`
+    :meth:`break_loop`              :class:`.BreakLoopOp`
+    :meth:`continue_loop`           :class:`.ContinueLoopOp`
     ==============================  ================================================================
 
     :class:`QuantumCircuit` has corresponding methods for all of the control-flow operations that
@@ -769,6 +771,7 @@ class QuantumCircuit:
     ..
         TODO: expand the examples of the builder interface.
 
+    .. automethod:: box
     .. automethod:: break_loop
     .. automethod:: continue_loop
     .. automethod:: for_loop
@@ -6040,6 +6043,107 @@ def _pop_previous_instruction_in_scope(self) -> CircuitInstruction:
         instruction = self._data.pop()
         return instruction
 
+    def box(
+        self,
+        # Forbidding passing `body` by keyword is in anticipation of the constructor expanding to
+        # allow `annotations` to be passed as the positional argument in the context-manager form.
+        body: QuantumCircuit | None = None,
+        /,
+        qubits: Sequence[QubitSpecifier] | None = None,
+        clbits: Sequence[ClbitSpecifier] | None = None,
+        *,
+        label: str | None = None,
+        duration: None = None,
+        unit: Literal["dt", "s", "ms", "us", "ns", "ps"] = "dt",
+    ):
+        """Create a ``box`` of operations on this circuit that are treated atomically in the greater
+        context.
+
+        A "box" is a control-flow construct that is entered unconditionally.  The contents of the
+        box behave somewhat as if the start and end of the box were barriers (see :meth:`barrier`),
+        except it is permissible to commute operations "all the way" through the box.  The box is
+        also an explicit scope for the purposes of variables, stretches and compiler passes.
+
+        There are two forms for calling this function:
+
+        * Pass a :class:`QuantumCircuit` positionally, and the ``qubits`` and ``clbits`` it acts
+          on.  In this form, a :class:`.BoxOp` is immediately created and appended using the circuit
+          as the body.
+
+        * Use in a ``with`` statement with no ``body``, ``qubits`` or ``clbits``.  This is the
+          "builder-interface form", where you then use other :class:`QuantumCircuit` methods within
+          the Python ``with`` scope to add instructions to the ``box``.  This is the preferred form,
+          and much less error prone.
+
+        Examples:
+
+            Using the builder interface to add two boxes in sequence.  The two boxes in this circuit
+            can execute concurrently, and the second explicitly inserts a data-flow dependency on
+            qubit 8 for the duration of the box, even though the qubit is idle.
+
+            .. code-block:: python
+
+                from qiskit.circuit import QuantumCircuit
+
+                qc = QuantumCircuit(9)
+                with qc.box():
+                    qc.cz(0, 1)
+                    qc.cz(2, 3)
+                with qc.box():
+                    qc.cz(4, 5)
+                    qc.cz(6, 7)
+                    qc.noop(8)
+
+            Using the explicit construction of box.  This creates the same circuit as above, and
+            should give an indication why the previous form is preferred for interactive use.
+
+            .. code-block:: python
+
+                from qiskit.circuit import QuantumCircuit, BoxOp
+
+                body_0 = QuantumCircuit(4)
+                body_0.cz(0, 1)
+                body_0.cz(2, 3)
+
+                # Note that the qubit indices inside a body related only to the body.  The
+                # association with qubits in the containing circuit is made by the ``qubits``
+                # argument to `QuantumCircuit.box`.
+                body_1 = QuantumCircuit(5)
+                body_1.cz(0, 1)
+                body_1.cz(2, 3)
+
+                qc = QuantumCircuit(9)
+                qc.box(body_0, [0, 1, 2, 3], [])
+                qc.box(body_1, [4, 5, 6, 7, 8], [])
+
+        Args:
+            body: if given, the :class:`QuantumCircuit` to use as the box's body in the explicit
+                construction.  Not given in the context-manager form.
+            qubits: the qubits to apply the :class:`.BoxOp` to, in the explicit form.
+            clbits: the qubits to apply the :class:`.BoxOp` to, in the explicit form.
+            label: an optional string label for the instruction.
+            duration: an optional explicit duration for the :class:`.BoxOp`.  Scheduling passes are
+                constrained to schedule the contained scope to match a given duration, including
+                delay insertion if required.
+            unit: the unit of the ``duration``.
+        """
+        if isinstance(body, QuantumCircuit):
+            # Explicit-body form.
+            if qubits is None or clbits is None:
+                raise CircuitError("When using 'box' with a body, you must pass qubits and clbits.")
+            return self.append(
+                BoxOp(body, duration=duration, unit=unit, label=label),
+                qubits,
+                clbits,
+                copy=False,
+            )
+        # Context-manager form.
+        if qubits is not None or clbits is not None:
+            raise CircuitError(
+                "When using 'box' as a context manager, you cannot pass qubits or clbits."
+            )
+        return BoxContext(self, duration=duration, unit=unit, label=label)
+
     @typing.overload
     def while_loop(
         self,

qiskit/dagcircuit/dagnode.py

@@ -19,6 +19,7 @@
 
 import qiskit._accelerate.circuit
 from qiskit.circuit import (
+    BoxOp,
     Clbit,
     ClassicalRegister,
     IfElseOp,
@@ -170,11 +171,18 @@ def _for_loop_eq(node1, node2, bit_indices1, bit_indices2):
     )
 
 
+def _box_eq(node1, node2, bit_indices1, bit_indices2):
+    return node1.op.duration == node2.op.duration and _circuit_to_dag(
+        node1.op.blocks[0], node1.qargs, node1.cargs, bit_indices1
+    ) == _circuit_to_dag(node2.op.blocks[0], node2.qargs, node2.cargs, bit_indices2)
+
+
 _SEMANTIC_EQ_CONTROL_FLOW = {
     IfElseOp: _condition_op_eq,
     WhileLoopOp: _condition_op_eq,
     SwitchCaseOp: _switch_case_eq,
     ForLoopOp: _for_loop_eq,
+    BoxOp: _box_eq,
 }
 
 _SEMANTIC_EQ_SYMMETRIC = frozenset({"barrier", "swap", "break_loop", "continue_loop"})