Merge branch 'main' of github.com:Qiskit/qiskit into circuit-stretch

Author: kevinhartman

crates/circuit/src/dag_circuit.rs

@@ -2366,6 +2366,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)] => {
@@ -2422,6 +2423,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

@@ -52,6 +52,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
@@ -738,13 +739,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
@@ -770,6 +772,7 @@ class QuantumCircuit:
     ..
         TODO: expand the examples of the builder interface.
 
+    .. automethod:: box
     .. automethod:: break_loop
     .. automethod:: continue_loop
     .. automethod:: for_loop
@@ -6342,6 +6345,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"})