qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/circuit/classical/expr/expr.py

@@ -0,0 +1,156 @@
+# 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.
+
+"""Expression-tree nodes."""
+
+
+__all__ = [
+    "Expr",
+    "Var",
+    "Stretch",
+    "Value",
+    "Cast",
+    "Unary",
+    "Binary",
+    "Index",
+]
+
+import enum
+
+from qiskit._accelerate.circuit.classical.expr import (
+    Expr,
+    Var,
+    Stretch,
+    Value,
+    Cast,
+    Unary,
+    Binary,
+    Index,
+)  # pylint: disable=unused-import
+
+
+class _UnaryOp(enum.Enum):
+    """Enumeration of the opcodes for unary operations.
+
+    The bitwise negation :data:`BIT_NOT` takes a single bit or an unsigned integer of known
+    width, and returns a value of the same type.
+
+    The logical negation :data:`LOGIC_NOT` takes an input that is implicitly coerced to a
+    Boolean, and returns a Boolean.
+    """
+
+    # If adding opcodes, remember to add helper constructor functions in `constructors.py`.
+    # The opcode integers should be considered a public interface; they are used by
+    # serialization formats that may transfer data between different versions of Qiskit.
+    #
+    # !!! YOU MUST ALSO UPDATE the underlying Rust enum if you touch this.
+    BIT_NOT = 1
+    """Bitwise negation. ``~operand``."""
+    LOGIC_NOT = 2
+    """Logical negation. ``!operand``."""
+
+    def __str__(self):
+        return f"Unary.{super().__str__()}"
+
+    def __repr__(self):
+        return f"Unary.{super().__repr__()}"
+
+
+# Setting these tricks Sphinx into thinking that this enum is actually
+# defined as an inner class of the Rust pyclass.
+_UnaryOp.__module__ = "qiskit._accelerate.circuit.classical.expr"
+_UnaryOp.__name__ = "Op"
+_UnaryOp.__qualname__ = "Unary.Op"
+
+
+class _BinaryOp(enum.Enum):
+    """Enumeration of the opcodes for binary operations.
+
+    The bitwise operations :data:`BIT_AND`, :data:`BIT_OR` and :data:`BIT_XOR` apply to two
+    operands of the same type, which must be a single bit or an unsigned integer of fixed width.
+    The resultant type is the same as the two input types.
+
+    The logical operations :data:`LOGIC_AND` and :data:`LOGIC_OR` first implicitly coerce their
+    arguments to Booleans, and then apply the logical operation.  The resultant type is always
+    Boolean.
+
+    The binary mathematical relations :data:`EQUAL`, :data:`NOT_EQUAL`, :data:`LESS`,
+    :data:`LESS_EQUAL`, :data:`GREATER` and :data:`GREATER_EQUAL` take unsigned integers
+    (with an implicit cast to make them the same width), and return a Boolean.
+
+    The bitshift operations :data:`SHIFT_LEFT` and :data:`SHIFT_RIGHT` can take bit-like
+    container types (e.g. unsigned integers) as the left operand, and any integer type as the
+    right-hand operand.  In all cases, the output bit width is the same as the input, and zeros
+    fill in the "exposed" spaces.
+
+    The binary arithmetic operators :data:`ADD`, :data:`SUB:, :data:`MUL`, and :data:`DIV`
+    can be applied to two floats or two unsigned integers, which should be made to be of
+    the same width during construction via a cast.
+    The :data:`ADD`, :data:`SUB`, and :data:`DIV` operators can be applied on two durations
+    yielding another duration, or a float in the case of :data:`DIV`. The :data:`MUL` operator
+    can also be applied to a duration and a numeric type, yielding another duration. Finally,
+    the :data:`DIV` operator can be used to divide a duration by a numeric type, yielding a
+    duration.
+    """
+
+    # If adding opcodes, remember to add helper constructor functions in `constructors.py`
+    # The opcode integers should be considered a public interface; they are used by
+    # serialization formats that may transfer data between different versions of Qiskit.
+    #
+    # !!! YOU MUST ALSO UPDATE the underlying Rust enum if you touch this.
+    BIT_AND = 1
+    """Bitwise "and". ``lhs & rhs``."""
+    BIT_OR = 2
+    """Bitwise "or". ``lhs | rhs``."""
+    BIT_XOR = 3
+    """Bitwise "exclusive or". ``lhs ^ rhs``."""
+    LOGIC_AND = 4
+    """Logical "and". ``lhs && rhs``."""
+    LOGIC_OR = 5
+    """Logical "or". ``lhs || rhs``."""
+    EQUAL = 6
+    """Numeric equality. ``lhs == rhs``."""
+    NOT_EQUAL = 7
+    """Numeric inequality. ``lhs != rhs``."""
+    LESS = 8
+    """Numeric less than. ``lhs < rhs``."""
+    LESS_EQUAL = 9
+    """Numeric less than or equal to. ``lhs <= rhs``"""
+    GREATER = 10
+    """Numeric greater than. ``lhs > rhs``."""
+    GREATER_EQUAL = 11
+    """Numeric greater than or equal to. ``lhs >= rhs``."""
+    SHIFT_LEFT = 12
+    """Zero-padding bitshift to the left.  ``lhs << rhs``."""
+    SHIFT_RIGHT = 13
+    """Zero-padding bitshift to the right.  ``lhs >> rhs``."""
+    ADD = 14
+    """Addition. ``lhs + rhs``."""
+    SUB = 15
+    """Subtraction. ``lhs - rhs``."""
+    MUL = 16
+    """Multiplication. ``lhs * rhs``."""
+    DIV = 17
+    """Division. ``lhs / rhs``."""
+
+    def __str__(self):
+        return f"Binary.{super().__str__()}"
+
+    def __repr__(self):
+        return f"Binary.{super().__repr__()}"
+
+
+# Setting these tricks Sphinx into thinking that this enum is actually
+# defined as an inner class of the Rust pyclass.
+_BinaryOp.__module__ = "qiskit._accelerate.circuit.classical.expr"
+_BinaryOp.__name__ = "Op"
+_BinaryOp.__qualname__ = "Binary.Op"

qiskit/circuit/classical/expr/visitors.py

@@ -0,0 +1,381 @@
+# 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.
+
+"""Expression visitors."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ExprVisitor",
+    "iter_vars",
+    "iter_identifiers",
+    "structurally_equivalent",
+    "is_lvalue",
+]
+
+import typing
+
+from . import expr
+
+_T_co = typing.TypeVar("_T_co", covariant=True)
+
+
+class ExprVisitor(typing.Generic[_T_co]):
+    """Base class for visitors to the :class:`Expr` tree.  Subclasses should override whichever of
+    the ``visit_*`` methods that they are able to handle, and should be organized such that
+    non-existent methods will never be called."""
+
+    # The method names are self-explanatory and docstrings would just be noise.
+    # pylint: disable=missing-function-docstring
+
+    __slots__ = ()
+
+    def visit_generic(self, node: expr.Expr, /) -> _T_co:  # pragma: no cover
+        raise RuntimeError(f"expression visitor {self} has no method to handle expr {node}")
+
+    def visit_var(self, node: expr.Var, /) -> _T_co:  # pragma: no cover
+        return self.visit_generic(node)
+
+    def visit_stretch(self, node: expr.Stretch, /) -> _T_co:  # pragma: no cover
+        return self.visit_generic(node)
+
+    def visit_value(self, node: expr.Value, /) -> _T_co:  # pragma: no cover
+        return self.visit_generic(node)
+
+    def visit_unary(self, node: expr.Unary, /) -> _T_co:  # pragma: no cover
+        return self.visit_generic(node)
+
+    def visit_binary(self, node: expr.Binary, /) -> _T_co:  # pragma: no cover
+        return self.visit_generic(node)
+
+    def visit_cast(self, node: expr.Cast, /) -> _T_co:  # pragma: no cover
+        return self.visit_generic(node)
+
+    def visit_index(self, node: expr.Index, /) -> _T_co:  # pragma: no cover
+        return self.visit_generic(node)
+
+
+class _VarWalkerImpl(ExprVisitor[typing.Iterable[expr.Var]]):
+    # We don't want docstrings for the inherited visitor methods, which are self-explanatory and
+    # would just be noise.
+    # pylint: disable=missing-function-docstring
+
+    __slots__ = ()
+
+    def visit_var(self, node, /):
+        yield node
+
+    def visit_stretch(self, node, /):
+        # pylint: disable=unused-argument
+        yield from ()
+
+    def visit_value(self, node, /):
+        # pylint: disable=unused-argument
+        yield from ()
+
+    def visit_unary(self, node, /):
+        yield from node.operand.accept(self)
+
+    def visit_binary(self, node, /):
+        yield from node.left.accept(self)
+        yield from node.right.accept(self)
+
+    def visit_cast(self, node, /):
+        yield from node.operand.accept(self)
+
+    def visit_index(self, node, /):
+        yield from node.target.accept(self)
+        yield from node.index.accept(self)
+
+
+class _IdentWalkerImpl(ExprVisitor[typing.Iterable[typing.Union[expr.Var, expr.Stretch]]]):
+    __slots__ = ()
+
+    def visit_var(self, node, /):
+        yield node
+
+    def visit_stretch(self, node, /):
+        yield node
+
+    def visit_value(self, node, /):
+        yield from ()
+
+    def visit_unary(self, node, /):
+        yield from node.operand.accept(self)
+
+    def visit_binary(self, node, /):
+        yield from node.left.accept(self)
+        yield from node.right.accept(self)
+
+    def visit_cast(self, node, /):
+        yield from node.operand.accept(self)
+
+    def visit_index(self, node, /):
+        yield from node.target.accept(self)
+        yield from node.index.accept(self)
+
+
+_VAR_WALKER = _VarWalkerImpl()
+_IDENT_WALKER = _IdentWalkerImpl()
+
+
+def iter_vars(node: expr.Expr) -> typing.Iterator[expr.Var]:
+    """Get an iterator over the :class:`~.expr.Var` nodes referenced at any level in the given
+    :class:`~.expr.Expr`.
+
+    Examples:
+        Print out the name of each :class:`.ClassicalRegister` encountered::
+
+            from qiskit.circuit import ClassicalRegister
+            from qiskit.circuit.classical import expr
+
+            cr1 = ClassicalRegister(3, "a")
+            cr2 = ClassicalRegister(3, "b")
+
+            for node in expr.iter_vars(expr.bit_and(expr.bit_not(cr1), cr2)):
+                if isinstance(node.var, ClassicalRegister):
+                    print(node.var.name)
+
+    .. seealso::
+        :func:`iter_identifiers`
+            Get an iterator over all identifier nodes in the expression, including
+            both :class:`~.expr.Var` and :class:`~.expr.Stretch` nodes.
+    """
+    yield from node.accept(_VAR_WALKER)
+
+
+def iter_identifiers(node: expr.Expr) -> typing.Iterator[typing.Union[expr.Var, expr.Stretch]]:
+    """Get an iterator over the :class:`~.expr.Var` and :class:`~.expr.Stretch`
+    nodes referenced at any level in the given :class:`~.expr.Expr`.
+
+    Examples:
+        Print out the name of each :class:`.ClassicalRegister` encountered::
+
+            from qiskit.circuit import ClassicalRegister
+            from qiskit.circuit.classical import expr
+
+            cr1 = ClassicalRegister(3, "a")
+            cr2 = ClassicalRegister(3, "b")
+
+            for node in expr.iter_vars(expr.bit_and(expr.bit_not(cr1), cr2)):
+                if isinstance(node.var, ClassicalRegister):
+                    print(node.var.name)
+
+    .. seealso::
+        :func:`iter_vars`
+            Get an iterator over just the :class:`~.expr.Var` nodes in the expression.
+    """
+    yield from node.accept(_IDENT_WALKER)
+
+
+class _StructuralEquivalenceImpl(ExprVisitor[bool]):
+    # The strategy here is to continue to do regular double dispatch through the visitor format,
+    # since we simply exit out with a ``False`` as soon as the structure of the two trees isn't the
+    # same; we never need to do any sort of "triple" dispatch.  To recurse through both trees
+    # simultaneously, we hold a pointer to the "full" expression of the other (at the given depth)
+    # in the stack variables of each visit function, and pass the next "deeper" pointer via the
+    # `other` state in the class instance.
+
+    __slots__ = (
+        "self_key",
+        "other_key",
+        "other",
+    )
+
+    def __init__(self, other: expr.Expr, self_key, other_key):
+        self.self_key = self_key
+        self.other_key = other_key
+        self.other = other
+
+    def visit_var(self, node, /):
+        if self.other.__class__ is not node.__class__ or self.other.type != node.type:
+            return False
+        if self.self_key is None or (self_var := self.self_key(node.var)) is None:
+            self_var = node.var
+        if self.other_key is None or (other_var := self.other_key(self.other.var)) is None:
+            other_var = self.other.var
+        return self_var == other_var
+
+    def visit_stretch(self, node, /):
+        if self.other.__class__ is not node.__class__:
+            return False
+        return node.var == self.other.var
+
+    def visit_value(self, node, /):
+        return (
+            node.__class__ is self.other.__class__
+            and node.type == self.other.type
+            and node.value == self.other.value
+        )
+
+    def visit_unary(self, node, /):
+        if (
+            self.other.__class__ is not node.__class__
+            or self.other.op is not node.op
+            or self.other.type != node.type
+        ):
+            return False
+        self.other = self.other.operand
+        return node.operand.accept(self)
+
+    def visit_binary(self, node, /):
+        if (
+            self.other.__class__ is not node.__class__
+            or self.other.op is not node.op
+            or self.other.type != node.type
+        ):
+            return False
+        other = self.other
+        self.other = other.left
+        if not node.left.accept(self):
+            return False
+        self.other = other.right
+        return node.right.accept(self)
+
+    def visit_cast(self, node, /):
+        if self.other.__class__ is not node.__class__ or self.other.type != node.type:
+            return False
+        self.other = self.other.operand
+        return node.operand.accept(self)
+
+    def visit_index(self, node, /):
+        if self.other.__class__ is not node.__class__ or self.other.type != node.type:
+            return False
+        other = self.other
+        self.other = other.target
+        if not node.target.accept(self):
+            return False
+        self.other = other.index
+        return node.index.accept(self)
+
+
+def structurally_equivalent(
+    left: expr.Expr,
+    right: expr.Expr,
+    left_var_key: typing.Callable[[typing.Any], typing.Any] | None = None,
+    right_var_key: typing.Callable[[typing.Any], typing.Any] | None = None,
+) -> bool:
+    """Do these two expressions have exactly the same tree structure, up to some key function for
+    the :class:`~.expr.Var` objects?
+
+    In other words, are these two expressions the exact same trees, except we compare the
+    :attr:`.Var.var` fields by calling the appropriate ``*_var_key`` function on them, and comparing
+    that output for equality.  This function does not allow any semantic "equivalences" such as
+    asserting that ``a == b`` is equivalent to ``b == a``; the evaluation order of the operands
+    could, in general, cause such a statement to be false (consider hypothetical ``extern``
+    functions that access global state).
+
+    There's no requirements on the key functions, except that their outputs should have general
+    ``__eq__`` methods.  If a key function returns ``None``, the variable will be used verbatim
+    instead.
+
+    Args:
+        left: one of the :class:`~.expr.Expr` nodes.
+        right: the other :class:`~.expr.Expr` node.
+        left_var_key: a callable whose output should be used when comparing :attr:`.Var.var`
+            attributes.  If this argument is ``None`` or its output is ``None`` for a given
+            variable in ``left``, the variable will be used verbatim.
+        right_var_key: same as ``left_var_key``, but used on the variables in ``right`` instead.
+
+    Examples:
+        Comparing two expressions for structural equivalence, with no remapping of the variables.
+        These are different because the different :class:`.Clbit` instances compare differently::
+
+            >>> from qiskit.circuit import Clbit
+            >>> from qiskit.circuit.classical import expr
+            >>> left_bits = [Clbit(), Clbit()]
+            >>> right_bits = [Clbit(), Clbit()]
+            >>> left = expr.logic_and(expr.logic_not(left_bits[0]), left_bits[1])
+            >>> right = expr.logic_and(expr.logic_not(right_bits[0]), right_bits[1])
+            >>> expr.structurally_equivalent(left, right)
+            False
+
+        Comparing the same two expressions, but this time using mapping functions that associate
+        the bits with simple indices::
+
+            >>> left_key = {var: i for i, var in enumerate(left_bits)}.get
+            >>> right_key = {var: i for i, var in enumerate(right_bits)}.get
+            >>> expr.structurally_equivalent(left, right, left_key, right_key)
+            True
+    """
+    return left.accept(_StructuralEquivalenceImpl(right, left_var_key, right_var_key))
+
+
+class _IsLValueImpl(ExprVisitor[bool]):
+    __slots__ = ()
+
+    def visit_var(self, node, /):
+        return True
+
+    def visit_stretch(self, node, /):
+        return False
+
+    def visit_value(self, node, /):
+        return False
+
+    def visit_unary(self, node, /):
+        return False
+
+    def visit_binary(self, node, /):
+        return False
+
+    def visit_cast(self, node, /):
+        return False
+
+    def visit_index(self, node, /):
+        return node.target.accept(self)
+
+
+_IS_LVALUE = _IsLValueImpl()
+
+
+def is_lvalue(node: expr.Expr, /) -> bool:
+    """Return whether this expression can be used in l-value positions, that is, whether it has a
+    well-defined location in memory, such as one that might be writeable.
+
+    Being an l-value is a necessary but not sufficient for this location to be writeable; it is
+    permissible that a larger object containing this memory location may not allow writing from
+    the scope that attempts to write to it.  This would be an access property of the containing
+    program, however, and not an inherent property of the expression system.
+
+    A constant expression is never an lvalue.
+
+    Examples:
+        Literal values are never l-values; there's no memory location associated with (for example)
+        the constant ``1``::
+
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.is_lvalue(expr.lift(2))
+            False
+
+        :class:`~.expr.Var` nodes are always l-values, because they always have some associated
+        memory location::
+
+            >>> from qiskit.circuit.classical import types
+            >>> from qiskit.circuit import Clbit
+            >>> expr.is_lvalue(expr.Var.new("a", types.Bool()))
+            True
+            >>> expr.is_lvalue(expr.lift(Clbit()))
+            True
+
+        Currently there are no unary or binary operations on variables that can produce an l-value
+        expression, but it is likely in the future that some sort of "indexing" operation will be
+        added, which could produce l-values::
+
+            >>> a = expr.Var.new("a", types.Uint(8))
+            >>> b = expr.Var.new("b", types.Uint(8))
+            >>> expr.is_lvalue(a) and expr.is_lvalue(b)
+            True
+            >>> expr.is_lvalue(expr.bit_and(a, b))
+            False
+    """
+    return node.accept(_IS_LVALUE)

qiskit/circuit/classical/types/__init__.py

@@ -0,0 +1,113 @@
+# 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.
+
+"""
+==============================================
+Typing (:mod:`qiskit.circuit.classical.types`)
+==============================================
+
+Representation
+==============
+
+The type system of the expression tree is exposed through this module.  This is inherently linked to
+the expression system in the :mod:`~.classical.expr` module, as most expressions can only be
+understood with the context of the types that they act on.
+
+All types inherit from an abstract base class:
+
+.. autoclass:: Type
+
+Types should be considered immutable objects, and you must not mutate them.  It is permissible to
+reuse a :class:`Type` that you take from another object without copying it, and generally this will
+be the best approach for performance.  :class:`Type` objects are designed to be small amounts of
+data, and it's best to point to the same instance of the data where possible rather than
+heap-allocating a new version of the same thing.  Where possible, the class constructors will return
+singleton instances to facilitate this.
+
+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
+.. autoclass:: Float
+.. autoclass:: Duration
+
+Working with types
+==================
+
+There are some additional functions on these types documented in the subsequent sections. 
+These are mostly expected to be used only in manipulations of the expression tree;
+users who are building expressions using the
+:ref:`user-facing construction interface <circuit-classical-expressions-expr-construction>` should
+not need to use these.
+
+Partial ordering of types
+=========================
+
+The type system is equipped with a partial ordering, where :math:`a < b` is interpreted as
+":math:`a` is a strict subtype of :math:`b`".  Note that the partial ordering is a subset of the
+directed graph that describes the allowed explicit casting operations between types.  The partial
+ordering defines when one type may be lossless directly interpreted as another.
+
+The low-level interface to querying the subtyping relationship is the :func:`order` function.
+
+.. autofunction:: order
+
+The return value is an enumeration :class:`Ordering` that describes what, if any, subtyping
+relationship exists between the two types.
+
+.. autoclass:: Ordering
+    :member-order: bysource
+
+Some helper methods are then defined in terms of this low-level :func:`order` primitive:
+
+.. autofunction:: is_subtype
+.. autofunction:: is_supertype
+.. autofunction:: greater
+
+
+Casting between types
+=====================
+
+It is common to need to cast values of one type to another type.  The casting rules for this are
+embedded into the :mod:`types` module.  You can query the casting kinds using :func:`cast_kind`:
+
+.. autofunction:: cast_kind
+
+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",
+    "is_subtype",
+    "is_supertype",
+    "greater",
+    "CastKind",
+    "cast_kind",
+]
+
+from .types import Type, Bool, Duration, Float, Uint
+from .ordering import Ordering, order, is_subtype, is_supertype, greater, CastKind, cast_kind