qiskit 2.0.3__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/circuit/classical/types/ordering.py

@@ -0,0 +1,229 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# 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.
+
+"""Tools for working with the partial ordering of the type system."""
+
+from __future__ import annotations
+
+__all__ = [
+    "Ordering",
+    "is_subtype",
+    "is_supertype",
+    "order",
+    "greater",
+    "CastKind",
+    "cast_kind",
+]
+
+import enum
+
+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
+# the set of types in an explicit graph form.  The strategy here is to assume that two types have no
+# ordering between them, and an ordering is defined by putting a function `Type * Type -> Ordering`
+# into the `_ORDERERS`.
+
+
+class Ordering(enum.Enum):
+    """Enumeration listing the possible relations between two types.  Types only have a partial
+    ordering, so it's possible for two types to have no sub-typing relationship.
+
+    Note that the sub-/supertyping relationship is not the same as whether a type can be explicitly
+    cast from one to another."""
+
+    LESS = enum.auto()
+    """The left type is a strict subtype of the right type."""
+    EQUAL = enum.auto()
+    """The two types are equal."""
+    GREATER = enum.auto()
+    """The left type is a strict supertype of the right type."""
+    NONE = enum.auto()
+    """There is no typing relationship between the two types."""
+
+    def __repr__(self):
+        return str(self)
+
+
+def _order_uint_uint(left: Uint, right: Uint, /) -> Ordering:
+    if left.width < right.width:
+        return Ordering.LESS
+    if left.width == right.width:
+        return Ordering.EQUAL
+    return Ordering.GREATER
+
+
+_ORDERERS = {
+    (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,
+}
+
+
+def order(left: Type, right: Type, /) -> Ordering:
+    """Get the ordering relationship between the two types as an enumeration value.
+
+    Examples:
+        Compare two :class:`Uint` types of different widths::
+
+            >>> from qiskit.circuit.classical import types
+            >>> types.order(types.Uint(8), types.Uint(16))
+            Ordering.LESS
+
+        Compare two types that have no ordering between them::
+
+            >>> types.order(types.Uint(8), types.Bool())
+            Ordering.NONE
+    """
+    if (orderer := _ORDERERS.get((left.kind, right.kind))) is None:
+        return Ordering.NONE
+    return orderer(left, right)
+
+
+def is_subtype(left: Type, right: Type, /, strict: bool = False) -> bool:
+    r"""Does the relation :math:`\text{left} \le \text{right}` hold?  If there is no ordering
+    relation between the two types, then this returns ``False``.  If ``strict``, then the equality
+    is also forbidden.
+
+    Examples:
+        Check if one type is a subclass of another::
+
+            >>> from qiskit.circuit.classical import types
+            >>> types.is_subtype(types.Uint(8), types.Uint(16))
+            True
+
+        Check if one type is a strict subclass of another::
+
+            >>> types.is_subtype(types.Bool(), types.Bool())
+            True
+            >>> types.is_subtype(types.Bool(), types.Bool(), strict=True)
+            False
+    """
+    order_ = order(left, right)
+    return order_ is Ordering.LESS or (not strict and order_ is Ordering.EQUAL)
+
+
+def is_supertype(left: Type, right: Type, /, strict: bool = False) -> bool:
+    r"""Does the relation :math:`\text{left} \ge \text{right}` hold?  If there is no ordering
+    relation between the two types, then this returns ``False``.  If ``strict``, then the equality
+    is also forbidden.
+
+    Examples:
+        Check if one type is a superclass of another::
+
+            >>> from qiskit.circuit.classical import types
+            >>> types.is_supertype(types.Uint(8), types.Uint(16))
+            False
+
+        Check if one type is a strict superclass of another::
+
+            >>> types.is_supertype(types.Bool(), types.Bool())
+            True
+            >>> types.is_supertype(types.Bool(), types.Bool(), strict=True)
+            False
+    """
+    order_ = order(left, right)
+    return order_ is Ordering.GREATER or (not strict and order_ is Ordering.EQUAL)
+
+
+def greater(left: Type, right: Type, /) -> Type:
+    """Get the greater of the two types, assuming that there is an ordering relation between them.
+    Technically, this is a slightly restricted version of the concept of the 'meet' of the two
+    types in that the return value must be one of the inputs. In practice in the type system there
+    is no concept of a 'sum' type, so the 'meet' exists if and only if there is an ordering between
+    the two types, and is equal to the greater of the two types.
+
+    Returns:
+        The greater of the two types.
+
+    Raises:
+        TypeError: if there is no ordering relation between the two types.
+
+    Examples:
+        Find the greater of two :class:`Uint` types::
+
+            >>> from qiskit.circuit.classical import types
+            >>> types.greater(types.Uint(8), types.Uint(16))
+            types.Uint(16)
+    """
+    order_ = order(left, right)
+    if order_ is Ordering.NONE:
+        raise TypeError(f"no ordering exists between '{left}' and '{right}'")
+    return left if order_ is Ordering.GREATER else right
+
+
+class CastKind(enum.Enum):
+    """A return value indicating the type of cast that can occur from one type to another."""
+
+    EQUAL = enum.auto()
+    """The two types are equal; no cast node is required at all."""
+    IMPLICIT = enum.auto()
+    """The 'from' type can be cast to the 'to' type implicitly.  A :class:`~.expr.Cast` node with
+    ``implicit==True`` is the minimum required to specify this."""
+    LOSSLESS = enum.auto()
+    """The 'from' type can be cast to the 'to' type explicitly, and the cast will be lossless.  This
+    requires a :class:`~.expr.Cast`` node with ``implicit=False``, but there's no danger from
+    inserting one."""
+    DANGEROUS = enum.auto()
+    """The 'from' type has a defined cast to the 'to' type, but depending on the value, it may lose
+    data.  A user would need to manually specify casts."""
+    NONE = enum.auto()
+    """There is no casting permitted from the 'from' type to the 'to' type."""
+
+
+def _uint_cast(from_: Uint, to_: Uint, /) -> CastKind:
+    if from_.width == to_.width:
+        return CastKind.EQUAL
+    if from_.width < to_.width:
+        return CastKind.LOSSLESS
+    return CastKind.DANGEROUS
+
+
+_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,
+}
+
+
+def cast_kind(from_: Type, to_: Type, /) -> CastKind:
+    """Determine the sort of cast that is required to move from the left type to the right type.
+
+    Examples:
+
+        .. plot::
+           :include-source:
+           :nofigs:
+
+
+            >>> from qiskit.circuit.classical import types
+            >>> types.cast_kind(types.Bool(), types.Bool())
+            <CastKind.EQUAL: 1>
+            >>> types.cast_kind(types.Uint(8), types.Bool())
+            <CastKind.IMPLICIT: 2>
+            >>> types.cast_kind(types.Bool(), types.Uint(8))
+            <CastKind.LOSSLESS: 3>
+            >>> types.cast_kind(types.Uint(16), types.Uint(8))
+            <CastKind.DANGEROUS: 4>
+    """
+    if (coercer := _ALLOWED_CASTS.get((from_.kind, to_.kind))) is None:
+        return CastKind.NONE
+    return coercer(from_, to_)

qiskit/circuit/classical/types/types.py

@@ -0,0 +1,153 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# 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.
+
+"""Type-system definition for the expression tree."""
+
+# Given the nature of the tree representation and that there are helper functions associated with
+# many of the classes whose arguments naturally share names with themselves, it's inconvenient to
+# use synonyms everywhere.  This goes for the builtin 'type' as well.
+# pylint: disable=redefined-builtin,redefined-outer-name
+
+from __future__ import annotations
+
+__all__ = [
+    "Type",
+    "Bool",
+    "Duration",
+    "Float",
+    "Uint",
+]
+
+import typing
+
+
+class _Singleton(type):
+    """Metaclass to make the child, which should take zero initialization arguments, a singleton
+    object."""
+
+    def _get_singleton_instance(cls):
+        return cls._INSTANCE
+
+    @classmethod
+    def __prepare__(mcs, name, bases):  # pylint: disable=unused-argument
+        return {"__new__": mcs._get_singleton_instance}
+
+    @staticmethod
+    def __new__(cls, name, bases, namespace):
+        out = super().__new__(cls, name, bases, namespace)
+        out._INSTANCE = object.__new__(out)  # pylint: disable=invalid-name
+        return out
+
+
+class Type:
+    """Root base class of all nodes in the type tree.  The base case should never be instantiated
+    directly.
+
+    This must not be subclassed by users; subclasses form the internal data of the representation of
+    expressions, and it does not make sense to add more outside of Qiskit library code."""
+
+    __slots__ = ()
+
+    @property
+    def kind(self):
+        """Get the kind of this type.  This is exactly equal to the Python type object that defines
+        this type, that is ``t.kind is type(t)``, but is exposed like this to make it clear that
+        this a hashable enum-like discriminator you can rely on."""
+        return self.__class__
+
+    # Enforcement of immutability.  The constructor methods need to manually skip this.
+
+    def __setattr__(self, _key, _value):
+        raise AttributeError(f"'{self.kind.__name__}' instances are immutable")
+
+    def __copy__(self):
+        return self
+
+    def __deepcopy__(self, _memo):
+        return self
+
+    def __setstate__(self, state):
+        _dict, slots = state
+        for slot, value in slots.items():
+            # We need to overcome the type's enforcement of immutability post initialization.
+            super().__setattr__(slot, value)
+
+
+@typing.final
+class Bool(Type, metaclass=_Singleton):
+    """The Boolean type.  This has exactly two values: ``True`` and ``False``."""
+
+    __slots__ = ()
+
+    def __repr__(self):
+        return "Bool()"
+
+    def __hash__(self):
+        return hash(self.__class__)
+
+    def __eq__(self, other):
+        return isinstance(other, Bool)
+
+
+@typing.final
+class Uint(Type):
+    """An unsigned integer of fixed bit width."""
+
+    __slots__ = ("width",)
+
+    def __init__(self, width: int):
+        if isinstance(width, int) and width <= 0:
+            raise ValueError("uint width must be greater than zero")
+        super(Type, self).__setattr__("width", width)
+
+    def __repr__(self):
+        return f"Uint({self.width})"
+
+    def __hash__(self):
+        return hash((self.__class__, self.width))
+
+    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

@@ -0,0 +1,133 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 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.
+
+"""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
+from qiskit._accelerate.commutation_checker import CommutationChecker as RustChecker
+
+
+class CommutationChecker:
+    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__(
+        self,
+        standard_gate_commutations: dict = None,
+        cache_max_entries: int = 10**6,
+        *,
+        gates: Optional[Set[str]] = None,
+    ):
+        self.cc = RustChecker(standard_gate_commutations, cache_max_entries, gates)
+
+    def commute_nodes(
+        self,
+        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, approximation_degree)
+
+    def commute(
+        self,
+        op1: Operation,
+        qargs1: List,
+        cargs1: List,
+        op2: Operation,
+        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
+        truly commute, and the return value of `False` means that either the operations do not
+        commute or that the commutation check was skipped (for example, when the operations
+        have conditions or have too many qubits).
+
+        Args:
+            op1: first operation.
+            qargs1: first operation's qubits.
+            cargs1: first operation's clbits.
+            op2: second operation.
+            qargs2: second operation's qubits.
+            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, approximation_degree
+        )
+
+    def num_cached_entries(self):
+        """Returns number of cached entries"""
+        return self.cc.num_cached_entries()
+
+    def clear_cached_commutations(self):
+        """Clears the dictionary holding cached commutations"""
+        self.cc.clear_cached_commutations()
+
+    def check_commutation_entries(
+        self,
+        first_op: Operation,
+        first_qargs: List,
+        second_op: Operation,
+        second_qargs: List,
+    ) -> Union[bool, None]:
+        """Returns stored commutation relation if any
+
+        Args:
+            first_op: first operation.
+            first_qargs: first operation's qubits.
+            second_op: second operation.
+            second_qargs: second operation's qubits.
+
+        Return:
+            bool: True if the gates commute and false if it is not the case.
+        """
+        return self.cc.library.check_commutation_entries(
+            first_op, first_qargs, second_op, second_qargs
+        )

qiskit/circuit/commutation_library.py

@@ -0,0 +1,20 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2023.
+#
+# 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.
+
+"""Provides a commutation checker that caches the determined commutation results during this session """
+
+from qiskit.circuit import CommutationChecker
+
+from qiskit.circuit._standard_gates_commutations import standard_gates_commutations
+
+StandardGateCommutations = standard_gates_commutations
+SessionCommutationChecker = CommutationChecker(StandardGateCommutations)

qiskit/circuit/controlflow/__init__.py

@@ -0,0 +1,59 @@
+# 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.
+
+"""Instruction sub-classes for dynamic circuits."""
+
+
+from ._builder_utils import condition_resources, node_resources, LegacyResources
+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", "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