qiskit 2.0.3__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/circuit/controlflow/_builder_utils.py

@@ -0,0 +1,211 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# 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.
+
+"""Private utility functions that are used by the builder interfaces."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Iterable, Tuple, Set, Union, TypeVar, TYPE_CHECKING
+
+from qiskit.circuit import (  # pylint: disable=cyclic-import
+    ClassicalRegister,
+    Clbit,
+    QuantumRegister,
+)
+from qiskit.circuit.classical import expr, types
+from qiskit.circuit.exceptions import CircuitError
+
+if TYPE_CHECKING:
+    from qiskit.circuit import QuantumCircuit, Register
+
+_ConditionT = TypeVar(
+    "_ConditionT", bound=Union[Tuple[ClassicalRegister, int], Tuple[Clbit, int], expr.Expr]
+)
+
+
+def validate_condition(condition: _ConditionT) -> _ConditionT:
+    """Validate that a condition is in a valid format and return it, but raise if it is invalid.
+
+    Args:
+        condition: the condition to be tested for validity.  Must be either the legacy 2-tuple
+            format, or a :class:`~.expr.Expr` that has `Bool` type.
+
+    Raises:
+        CircuitError: if the condition is not in a valid format.
+
+    Returns:
+        The same condition as passed, if it was valid.
+    """
+    if isinstance(condition, expr.Expr):
+        if condition.type.kind is not types.Bool:
+            raise CircuitError(
+                "Classical conditions must be expressions with the type 'Bool()',"
+                f" not '{condition.type}'."
+            )
+        return condition
+    try:
+        bits, value = condition
+        if isinstance(bits, (ClassicalRegister, Clbit)) and isinstance(value, int):
+            return (bits, value)
+    except (TypeError, ValueError):
+        pass
+    raise CircuitError(
+        "A classical condition should be a 2-tuple of `(ClassicalRegister | Clbit, int)`,"
+        f" but received '{condition!r}'."
+    )
+
+
+@dataclasses.dataclass
+class LegacyResources:
+    """A pair of the :class:`.Clbit` and :class:`.ClassicalRegister` resources used by some other
+    object (such as a legacy condition or :class:`.expr.Expr` node)."""
+
+    clbits: tuple[Clbit, ...]
+    cregs: tuple[ClassicalRegister, ...]
+
+
+def node_resources(node: expr.Expr) -> LegacyResources:
+    """Get the legacy classical resources (:class:`.Clbit` and :class:`.ClassicalRegister`)
+    referenced by an :class:`~.expr.Expr`."""
+    # It's generally convenient for us to ensure that the resources are returned in some
+    # deterministic order.  This uses the ordering of 'dict' objects to fake out an ordered set.
+    clbits = {}
+    cregs = {}
+    for var in expr.iter_vars(node):
+        if isinstance(var.var, Clbit):
+            clbits[var.var] = None
+        elif isinstance(var.var, ClassicalRegister):
+            clbits.update((bit, None) for bit in var.var)
+            cregs[var.var] = None
+    return LegacyResources(tuple(clbits), tuple(cregs))
+
+
+def condition_resources(
+    condition: tuple[ClassicalRegister, int] | tuple[Clbit, int] | expr.Expr
+) -> LegacyResources:
+    """Get the legacy classical resources (:class:`.Clbit` and :class:`.ClassicalRegister`)
+    referenced by a legacy condition or an :class:`~.expr.Expr`."""
+    if isinstance(condition, expr.Expr):
+        return node_resources(condition)
+    target, _ = condition
+    if isinstance(target, ClassicalRegister):
+        return LegacyResources(tuple(target), (target,))
+    return LegacyResources((target,), ())
+
+
+def partition_registers(
+    registers: Iterable[Register],
+) -> Tuple[Set[QuantumRegister], Set[ClassicalRegister]]:
+    """Partition a sequence of registers into its quantum and classical registers."""
+    qregs = set()
+    cregs = set()
+    for register in registers:
+        if isinstance(register, QuantumRegister):
+            qregs.add(register)
+        elif isinstance(register, ClassicalRegister):
+            cregs.add(register)
+        else:
+            # Purely defensive against Terra expansion.
+            raise CircuitError(f"Unknown register: {register}.")
+    return qregs, cregs
+
+
+def unify_circuit_resources(circuits: Iterable[QuantumCircuit]) -> Iterable[QuantumCircuit]:
+    """
+    Ensure that all the given ``circuits`` have all the same qubits, clbits and registers, and
+    that they are defined in the same order.  The order is important for binding when the bodies are
+    used in the 3-tuple :obj:`.Instruction` context.
+
+    This function will preferentially try to mutate its inputs if they share an ordering, but if
+    not, it will rebuild two new circuits.  This is to avoid coupling too tightly to the inner
+    class; there is no real support for deleting or re-ordering bits within a :obj:`.QuantumCircuit`
+    context, and we don't want to rely on the *current* behavior of the private APIs, since they
+    are very liable to change.  No matter the method used, circuits with unified bits and registers
+    are returned.
+    """
+    circuits = tuple(circuits)
+    if len(circuits) < 2:
+        return circuits
+    qubits = []
+    clbits = []
+    for circuit in circuits:
+        if circuit.qubits[: len(qubits)] != qubits:
+            return _unify_circuit_resources_rebuild(circuits)
+        if circuit.clbits[: len(qubits)] != clbits:
+            return _unify_circuit_resources_rebuild(circuits)
+        if circuit.num_qubits > len(qubits):
+            qubits = list(circuit.qubits)
+        if circuit.num_clbits > len(clbits):
+            clbits = list(circuit.clbits)
+    for circuit in circuits:
+        circuit.add_bits(qubits[circuit.num_qubits :])
+        circuit.add_bits(clbits[circuit.num_clbits :])
+    return _unify_circuit_registers(circuits)
+
+
+def _unify_circuit_resources_rebuild(  # pylint: disable=invalid-name  # (it's too long?!)
+    circuits: Tuple[QuantumCircuit, ...]
+) -> Tuple[QuantumCircuit, QuantumCircuit]:
+    """
+    Ensure that all the given circuits have all the same qubits and clbits, and that they
+    are defined in the same order.  The order is important for binding when the bodies are used in
+    the 3-tuple :obj:`.Instruction` context.
+
+    This function will always rebuild the objects into new :class:`.QuantumCircuit` instances.
+    """
+    # pylint: disable=cyclic-import
+    from qiskit.circuit import QuantumCircuit
+
+    qubits, clbits = set(), set()
+    for circuit in circuits:
+        qubits.update(circuit.qubits)
+        clbits.update(circuit.clbits)
+    qubits, clbits = list(qubits), list(clbits)
+
+    # We use the inner `_append` method because everything is already resolved in the builders.
+    out_circuits = []
+    for circuit in circuits:
+        out = QuantumCircuit(
+            qubits,
+            clbits,
+            *circuit.qregs,
+            *circuit.cregs,
+            global_phase=circuit.global_phase,
+            inputs=circuit.iter_input_vars(),
+            captures=circuit.iter_captures(),
+        )
+        for var in circuit.iter_declared_vars():
+            out.add_uninitialized_var(var)
+        for stretch in circuit.iter_declared_stretches():
+            out.add_stretch(stretch)
+        for instruction in circuit.data:
+            out._append(instruction)
+        out_circuits.append(out)
+    return _unify_circuit_registers(out_circuits)
+
+
+def _unify_circuit_registers(circuits: Iterable[QuantumCircuit]) -> Iterable[QuantumCircuit]:
+    """
+    Ensure that ``true_body`` and ``false_body`` have the same registers defined within them.  These
+    do not need to be in the same order between circuits.  The two input circuits are returned,
+    mutated to have the same registers.
+    """
+    circuits = tuple(circuits)
+    total_registers = set()
+    for circuit in circuits:
+        total_registers.update(circuit.qregs)
+        total_registers.update(circuit.cregs)
+    for circuit in circuits:
+        for register in total_registers - set(circuit.qregs) - set(circuit.cregs):
+            circuit.add_register(register)
+    return circuits

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/controlflow/break_loop.py

@@ -0,0 +1,56 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2021.
+#
+# 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.
+
+"Circuit operation representing a ``break`` from a loop."
+
+from typing import Optional
+
+from qiskit.circuit.instruction import Instruction
+from .builder import InstructionPlaceholder, InstructionResources
+
+
+class BreakLoopOp(Instruction):
+    """A circuit operation which, when encountered, jumps to the end of the nearest enclosing loop.
+    Can only be used inside loops.
+    """
+
+    def __init__(self, num_qubits: int, num_clbits: int, label: Optional[str] = None):
+        """
+        Args:
+            num_qubits: the number of qubits this affects.
+            num_clbits: the number of qubits this affects.
+            label: an optional string label for the instruction.
+        """
+        super().__init__("break_loop", num_qubits, num_clbits, [], label=label)
+
+
+class BreakLoopPlaceholder(InstructionPlaceholder):
+    """A placeholder instruction for use in control-flow context managers, when the number of qubits
+    and clbits is not yet known.
+
+    .. warning::
+
+        This is an internal interface and no part of it should be relied upon outside of Qiskit
+        Terra.
+    """
+
+    def __init__(self, *, label: Optional[str] = None):
+        super().__init__("break_loop", 0, 0, [], label=label)
+
+    def concrete_instruction(self, qubits, clbits):
+        return (
+            BreakLoopOp(len(qubits), len(clbits), label=self.label),
+            InstructionResources(qubits=tuple(qubits), clbits=tuple(clbits)),
+        )
+
+    def placeholder_resources(self):
+        return InstructionResources()