qiskit 1.4.1__cp39-abi3-macosx_11_0_arm64.whl → 2.0.0__cp39-abi3-macosx_11_0_arm64.whl

qiskit/circuit/classical/types/__init__.py

@@ -33,16 +33,15 @@ data, and it's best to point to the same instance of the data where possible rat
 heap-allocating a new version of the same thing.  Where possible, the class constructors will return
 singleton instances to facilitate this.
 
-The two different types available are for Booleans (corresponding to :class:`.Clbit` and the
-literals ``True`` and ``False``), and unsigned integers (corresponding to
-:class:`.ClassicalRegister` and Python integers).
+The :class:`Bool` type represents :class:`.Clbit` and the literals ``True`` and ``False``, the
+:class:`Uint` type represents :class:`.ClassicalRegister` and Python integers, the :class:`Float`
+type represents Python floats, and the :class:`Duration` type represents a duration for use in
+timing-aware circuit operations.
 
 .. autoclass:: Bool
 .. autoclass:: Uint
-
-Note that :class:`Uint` defines a family of types parametrized by their width; it is not one single
-type, which may be slightly different to the 'classical' programming languages you are used to.
-
+.. autoclass:: Float
+.. autoclass:: Duration
 
 Working with types
 ==================
@@ -89,12 +88,17 @@ embedded into the :mod:`types` module.  You can query the casting kinds using :f
 The return values from this function are an enumeration explaining the types of cast that are
 allowed from the left type to the right type.
 
+Note that casts between :class:`Float` and :class:`Uint` are considered dangerous in either
+direction, and must be done explicitly.
+
 .. autoclass:: CastKind
 """
 
 __all__ = [
     "Type",
     "Bool",
+    "Duration",
+    "Float",
     "Uint",
     "Ordering",
     "order",
@@ -105,5 +109,5 @@ __all__ = [
     "cast_kind",
 ]
 
-from .types import Type, Bool, Uint
+from .types import Type, Bool, Duration, Float, Uint
 from .ordering import Ordering, order, is_subtype, is_supertype, greater, CastKind, cast_kind

qiskit/circuit/classical/types/ordering.py

@@ -26,7 +26,7 @@ __all__ = [
 
 import enum
 
-from .types import Type, Bool, Uint
+from .types import Type, Bool, Duration, Float, Uint
 
 
 # While the type system is simple, it's overkill to represent the complete partial ordering graph of
@@ -55,10 +55,6 @@ class Ordering(enum.Enum):
         return str(self)
 
 
-def _order_bool_bool(_a: Bool, _b: Bool, /) -> Ordering:
-    return Ordering.EQUAL
-
-
 def _order_uint_uint(left: Uint, right: Uint, /) -> Ordering:
     if left.width < right.width:
         return Ordering.LESS
@@ -68,8 +64,10 @@ def _order_uint_uint(left: Uint, right: Uint, /) -> Ordering:
 
 
 _ORDERERS = {
-    (Bool, Bool): _order_bool_bool,
+    (Bool, Bool): lambda _a, _b, /: Ordering.EQUAL,
     (Uint, Uint): _order_uint_uint,
+    (Float, Float): lambda _a, _b, /: Ordering.EQUAL,
+    (Duration, Duration): lambda _a, _b, /: Ordering.EQUAL,
 }
 
 
@@ -195,8 +193,14 @@ def _uint_cast(from_: Uint, to_: Uint, /) -> CastKind:
 _ALLOWED_CASTS = {
     (Bool, Bool): lambda _a, _b, /: CastKind.EQUAL,
     (Bool, Uint): lambda _a, _b, /: CastKind.LOSSLESS,
+    (Bool, Float): lambda _a, _b, /: CastKind.LOSSLESS,
     (Uint, Bool): lambda _a, _b, /: CastKind.IMPLICIT,
     (Uint, Uint): _uint_cast,
+    (Uint, Float): lambda _a, _b, /: CastKind.DANGEROUS,
+    (Float, Float): lambda _a, _b, /: CastKind.EQUAL,
+    (Float, Uint): lambda _a, _b, /: CastKind.DANGEROUS,
+    (Float, Bool): lambda _a, _b, /: CastKind.DANGEROUS,
+    (Duration, Duration): lambda _a, _b, /: CastKind.EQUAL,
 }
 
 
@@ -205,7 +209,10 @@ def cast_kind(from_: Type, to_: Type, /) -> CastKind:
 
     Examples:
 
-        .. code-block:: python
+        .. plot::
+           :include-source:
+           :nofigs:
+
 
             >>> from qiskit.circuit.classical import types
             >>> types.cast_kind(types.Bool(), types.Bool())

qiskit/circuit/classical/types/types.py

@@ -22,6 +22,8 @@ from __future__ import annotations
 __all__ = [
     "Type",
     "Bool",
+    "Duration",
+    "Float",
     "Uint",
 ]
 
@@ -115,3 +117,37 @@ class Uint(Type):
 
     def __eq__(self, other):
         return isinstance(other, Uint) and self.width == other.width
+
+
+@typing.final
+class Float(Type, metaclass=_Singleton):
+    """An IEEE-754 double-precision floating point number.
+    In the future, this may also be used to represent other fixed-width floats.
+    """
+
+    __slots__ = ()
+
+    def __repr__(self):
+        return "Float()"
+
+    def __hash__(self):
+        return hash(self.__class__)
+
+    def __eq__(self, other):
+        return isinstance(other, Float)
+
+
+@typing.final
+class Duration(Type, metaclass=_Singleton):
+    """A length of time, possibly negative."""
+
+    __slots__ = ()
+
+    def __repr__(self):
+        return "Duration()"
+
+    def __hash__(self):
+        return hash(self.__class__)
+
+    def __eq__(self, other):
+        return isinstance(other, Duration)

qiskit/circuit/commutation_checker.py

@@ -12,6 +12,7 @@
 
 """Code from commutative_analysis pass that checks commutation relations between DAG nodes."""
 
+from __future__ import annotations
 from typing import List, Union, Set, Optional
 
 from qiskit.circuit.operation import Operation
@@ -19,11 +20,31 @@ from qiskit._accelerate.commutation_checker import CommutationChecker as RustChe
 
 
 class CommutationChecker:
-    """This code is essentially copy-pasted from commutative_analysis.py.
-    This code cleverly hashes commutativity and non-commutativity results between DAG nodes and seems
-    quite efficient for large Clifford circuits.
-    They may be other possible efficiency improvements: using rule-based commutativity analysis,
-    evicting from the cache less useful entries, etc.
+    r"""Check commutations of two operations.
+
+    Two unitaries :math:`A` and :math:`B` on :math:`n` qubits commute if
+
+    .. math::
+
+        \frac{2^n F_{\text{process}}(AB, BA) + 1}{2^n + 1} > 1 - \varepsilon,
+
+    where
+
+    .. math::
+
+        F_{\text{process}}(U_1, U_2) = \left|\frac{\mathrm{Tr}(U_1 U_2^\dagger)}{2^n} \right|^2,
+
+    and we set :math:`\varepsilon` to :math:`10^{-12}` to account for round-off errors on
+    few-qubit systems. This metric is chosen for consistency with other closeness checks in
+    Qiskit.
+
+    When possible, commutation relations are queried from a lookup table. This is the case
+    for standard gates without parameters (such as :class:`.XGate` or :class:`.HGate`) or
+    gates with free parameters (such as :class:`.RXGate` with a :class:`.ParameterExpression` as
+    angle). Otherwise, a matrix-based check is performed, where two operations are said to
+    commute, if the average gate fidelity of performing the commutation is above a certain threshold
+    (see ``approximation_degree``). The result of this commutation is then added to the
+    cached lookup table.
     """
 
     def __init__(
@@ -40,9 +61,10 @@ class CommutationChecker:
         op1,
         op2,
         max_num_qubits: int = 3,
+        approximation_degree: float = 1.0,
     ) -> bool:
         """Checks if two DAGOpNodes commute."""
-        return self.cc.commute_nodes(op1, op2, max_num_qubits)
+        return self.cc.commute_nodes(op1, op2, max_num_qubits, approximation_degree)
 
     def commute(
         self,
@@ -53,6 +75,7 @@ class CommutationChecker:
         qargs2: List,
         cargs2: List,
         max_num_qubits: int = 3,
+        approximation_degree: float = 1.0,
     ) -> bool:
         """
         Checks if two Operations commute. The return value of `True` means that the operations
@@ -69,11 +92,15 @@ class CommutationChecker:
             cargs2: second operation's clbits.
             max_num_qubits: the maximum number of qubits to consider, the check may be skipped if
                 the number of qubits for either operation exceeds this amount.
+            approximation_degree: If the average gate fidelity in between the two operations
+                is above this number (up to ``1e-12``) they are assumed to commute.
 
         Returns:
             bool: whether two operations commute.
         """
-        return self.cc.commute(op1, qargs1, cargs1, op2, qargs2, cargs2, max_num_qubits)
+        return self.cc.commute(
+            op1, qargs1, cargs1, op2, qargs2, cargs2, max_num_qubits, approximation_degree
+        )
 
     def num_cached_entries(self):
         """Returns number of cached entries"""

qiskit/circuit/controlflow/__init__.py

@@ -18,11 +18,42 @@ from .control_flow import ControlFlowOp
 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."""
+
+
+def get_control_flow_name_mapping():
+    """Return a dictionary mapping the names of control-flow operations
+    to their corresponding classes."
+
+    Examples:
+
+        .. code-block:: python
+
+            from qiskit.circuit import get_control_flow_name_mapping
+
+            ctrl_flow_name_map = get_control_flow_name_mapping()
+            if_else_object = ctrl_flow_name_map["if_else"]
+
+            print(if_else_object)
+
+        .. code-block:: text
+
+            <class 'qiskit.circuit.controlflow.if_else.IfElseOp'>
+    """
+
+    name_mapping = {
+        "if_else": IfElseOp,
+        "while_loop": WhileLoopOp,
+        "for_loop": ForLoopOp,
+        "switch_case": SwitchCaseOp,
+        "box": BoxOp,
+    }
+    return name_mapping

qiskit/circuit/controlflow/_builder_utils.py

@@ -17,14 +17,16 @@ 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
-from qiskit.circuit.register import Register
-from qiskit.circuit.classicalregister import ClassicalRegister, Clbit
-from qiskit.circuit.quantumregister import QuantumRegister
 
 if TYPE_CHECKING:
-    from qiskit.circuit import QuantumCircuit
+    from qiskit.circuit import QuantumCircuit, Register
 
 _ConditionT = TypeVar(
     "_ConditionT", bound=Union[Tuple[ClassicalRegister, int], Tuple[Clbit, int], expr.Expr]
@@ -180,10 +182,12 @@ def _unify_circuit_resources_rebuild(  # pylint: disable=invalid-name  # (it's t
             *circuit.cregs,
             global_phase=circuit.global_phase,
             inputs=circuit.iter_input_vars(),
-            captures=circuit.iter_captured_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)

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

@@ -48,7 +48,7 @@ class BreakLoopPlaceholder(InstructionPlaceholder):
 
     def concrete_instruction(self, qubits, clbits):
         return (
-            self._copy_mutable_properties(BreakLoopOp(len(qubits), len(clbits), label=self.label)),
+            BreakLoopOp(len(qubits), len(clbits), label=self.label),
             InstructionResources(qubits=tuple(qubits), clbits=tuple(clbits)),
         )