qiskit 1.4.0__cp39-abi3-macosx_11_0_arm64.whl → 2.0.0rc1__cp39-abi3-macosx_11_0_arm64.whl

qiskit/circuit/classical/expr/constructors.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 __all__ = [
     "lift",
+    "cast",
     "bit_not",
     "logic_not",
     "bit_and",
@@ -32,6 +33,13 @@ __all__ = [
     "less_equal",
     "greater",
     "greater_equal",
+    "shift_left",
+    "shift_right",
+    "index",
+    "add",
+    "sub",
+    "mul",
+    "div",
     "lift_legacy_condition",
 ]
 
@@ -45,9 +53,9 @@ if typing.TYPE_CHECKING:
     import qiskit
 
 
-def _coerce_lossless(expr: Expr, type: types.Type) -> Expr:
+def _coerce_lossless(expr: Expr, type: types.Type) -> Expr | None:
     """Coerce ``expr`` to ``type`` by inserting a suitable :class:`Cast` node, if the cast is
-    lossless.  Otherwise, raise a ``TypeError``."""
+    lossless.  Otherwise, return ``None``."""
     kind = cast_kind(expr.type, type)
     if kind is CastKind.EQUAL:
         return expr
@@ -55,29 +63,13 @@ def _coerce_lossless(expr: Expr, type: types.Type) -> Expr:
         return Cast(expr, type, implicit=True)
     if kind is CastKind.LOSSLESS:
         return Cast(expr, type, implicit=False)
-    if kind is CastKind.DANGEROUS:
-        raise TypeError(f"cannot cast '{expr}' to '{type}' without loss of precision")
-    raise TypeError(f"no cast is defined to take '{expr}' to '{type}'")
+    return None
 
 
 def lift_legacy_condition(
     condition: tuple[qiskit.circuit.Clbit | qiskit.circuit.ClassicalRegister, int], /
 ) -> Expr:
-    """Lift a legacy two-tuple equality condition into a new-style :class:`Expr`.
-
-    Examples:
-        Taking an old-style conditional instruction and getting an :class:`Expr` from its
-        condition::
-
-            from qiskit.circuit import ClassicalRegister
-            from qiskit.circuit.library import HGate
-            from qiskit.circuit.classical import expr
-
-            cr = ClassicalRegister(2)
-            instr = HGate().c_if(cr, 3)
-
-            lifted = expr.lift_legacy_condition(instr.condition)
-    """
+    """Lift a legacy two-tuple equality condition into a new-style :class:`Expr`."""
     from qiskit.circuit import Clbit  # pylint: disable=cyclic-import
 
     target, value = condition
@@ -121,7 +113,7 @@ def lift(value: typing.Any, /, type: types.Type | None = None) -> Expr:
         if type is not None:
             raise ValueError("use 'cast' to cast existing expressions, not 'lift'")
         return value
-    from qiskit.circuit import Clbit, ClassicalRegister  # pylint: disable=cyclic-import
+    from qiskit.circuit import Clbit, ClassicalRegister, Duration  # pylint: disable=cyclic-import
 
     inferred: types.Type
     if value is True or value is False or isinstance(value, Clbit):
@@ -135,6 +127,12 @@ def lift(value: typing.Any, /, type: types.Type | None = None) -> Expr:
             raise ValueError("cannot represent a negative value")
         inferred = types.Uint(width=value.bit_length() or 1)
         constructor = Value
+    elif isinstance(value, float):
+        inferred = types.Float()
+        constructor = Value
+    elif isinstance(value, Duration):
+        inferred = types.Duration()
+        constructor = Value
     else:
         raise TypeError(f"failed to infer a type for '{value}'")
     if type is None:
@@ -195,11 +193,15 @@ def logic_not(operand: typing.Any, /) -> Expr:
             >>> expr.logic_not(ClassicalRegister(3, "c"))
             Unary(\
 Unary.Op.LOGIC_NOT, \
-Cast(Var(ClassicalRegister(3, 'c'), Uint(3)), Bool(), implicit=True), \
+Cast(Var(ClassicalRegister(3, 'c'), Uint(3)), \
+Bool(), implicit=True), \
 Bool())
     """
-    operand = _coerce_lossless(lift(operand), types.Bool())
-    return Unary(Unary.Op.LOGIC_NOT, operand, operand.type)
+    operand = lift(operand)
+    coerced_operand = _coerce_lossless(operand, types.Bool())
+    if coerced_operand is None:
+        raise TypeError(f"cannot apply '{Unary.Op.LOGIC_NOT}' to type '{operand.type}'")
+    return Unary(Unary.Op.LOGIC_NOT, coerced_operand, coerced_operand.type)
 
 
 def _lift_binary_operands(left: typing.Any, right: typing.Any) -> tuple[Expr, Expr]:
@@ -314,9 +316,13 @@ Uint(3))
 
 def _binary_logical(op: Binary.Op, left: typing.Any, right: typing.Any) -> Expr:
     bool_ = types.Bool()
-    left = _coerce_lossless(lift(left), bool_)
-    right = _coerce_lossless(lift(right), bool_)
-    return Binary(op, left, right, bool_)
+    left = lift(left)
+    right = lift(right)
+    coerced_left = _coerce_lossless(left, bool_)
+    coerced_right = _coerce_lossless(right, bool_)
+    if coerced_left is None or coerced_right is None:
+        raise TypeError(f"invalid types for '{op}': '{left.type}' and '{right.type}'")
+    return Binary(op, coerced_left, coerced_right, bool_)
 
 
 def logic_and(left: typing.Any, right: typing.Any, /) -> Expr:
@@ -354,6 +360,8 @@ def _equal_like(op: Binary.Op, left: typing.Any, right: typing.Any) -> Expr:
     if left.type.kind is not right.type.kind:
         raise TypeError(f"invalid types for '{op}': '{left.type}' and '{right.type}'")
     type = types.greater(left.type, right.type)
+    # Note that we don't check the return value of _coerce_lossless for these
+    # since 'left' and 'right' are guaranteed to be the same kind here.
     return Binary(op, _coerce_lossless(left, type), _coerce_lossless(right, type), types.Bool())
 
 
@@ -398,6 +406,8 @@ def _binary_relation(op: Binary.Op, left: typing.Any, right: typing.Any) -> Expr
     if left.type.kind is not right.type.kind or left.type.kind is types.Bool:
         raise TypeError(f"invalid types for '{op}': '{left.type}' and '{right.type}'")
     type = types.greater(left.type, right.type)
+    # Note that we don't check the return value of _coerce_lossless for these
+    # since 'left' and 'right' are guaranteed to be the same kind here.
     return Binary(op, _coerce_lossless(left, type), _coerce_lossless(right, type), types.Bool())
 
 
@@ -479,7 +489,11 @@ def _shift_like(
     if type is not None and type.kind is not types.Uint:
         raise TypeError(f"type '{type}' is not a valid bitshift operand type")
     if isinstance(left, Expr):
-        left = _coerce_lossless(left, type) if type is not None else left
+        if type is not None:
+            coerced_left = _coerce_lossless(left, type)
+            if coerced_left is None:
+                raise TypeError(f"type '{type}' cannot losslessly represent '{left.type}'")
+            left = coerced_left
     else:
         left = lift(left, type)
     right = lift(right)
@@ -554,3 +568,209 @@ def index(target: typing.Any, index: typing.Any, /) -> Expr:
     if target.type.kind is not types.Uint or index.type.kind is not types.Uint:
         raise TypeError(f"invalid types for indexing: '{target.type}' and '{index.type}'")
     return Index(target, index, types.Bool())
+
+
+def _binary_sum(op: Binary.Op, left: typing.Any, right: typing.Any) -> Expr:
+    left, right = _lift_binary_operands(left, right)
+    if left.type.kind is right.type.kind and left.type.kind in {
+        types.Uint,
+        types.Float,
+        types.Duration,
+    }:
+        type = types.greater(left.type, right.type)
+        return Binary(
+            op,
+            _coerce_lossless(left, type),
+            _coerce_lossless(right, type),
+            type,
+        )
+    raise TypeError(f"invalid types for '{op}': '{left.type}' and '{right.type}'")
+
+
+def add(left: typing.Any, right: typing.Any, /) -> Expr:
+    """Create an addition expression node from the given values, resolving any implicit casts and
+    lifting the values into :class:`Value` nodes if required.
+
+    Examples:
+        Addition of two floating point numbers::
+
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.add(5.0, 2.0)
+            Binary(\
+Binary.Op.ADD, \
+Value(5.0, Float()), \
+Value(2.0, Float()), \
+Float())
+
+        Addition of two durations::
+
+            >>> from qiskit.circuit import Duration
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.add(Duration.dt(1000), Duration.dt(1000))
+            Binary(\
+Binary.Op.ADD, \
+Value(Duration.dt(1000), Duration()), \
+Value(Duration.dt(1000), Duration()), \
+Duration())
+        """
+    return _binary_sum(Binary.Op.ADD, left, right)
+
+
+def sub(left: typing.Any, right: typing.Any, /) -> Expr:
+    """Create a subtraction expression node from the given values, resolving any implicit casts and
+    lifting the values into :class:`Value` nodes if required.
+
+    Examples:
+        Subtraction of two floating point numbers::
+
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.sub(5.0, 2.0)
+            Binary(\
+Binary.Op.SUB, \
+Value(5.0, Float()), \
+Value(2.0, Float()), \
+Float())
+
+        Subtraction of two durations::
+
+            >>> from qiskit.circuit import Duration
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.add(Duration.dt(1000), Duration.dt(1000))
+            Binary(\
+Binary.Op.SUB, \
+Value(Duration.dt(1000), Duration()), \
+Value(Duration.dt(1000), Duration()), \
+Duration())
+        """
+    return _binary_sum(Binary.Op.SUB, left, right)
+
+
+def mul(left: typing.Any, right: typing.Any) -> Expr:
+    """Create a multiplication expression node from the given values, resolving any implicit casts and
+    lifting the values into :class:`Value` nodes if required.
+
+    This can be used to multiply numeric operands of the same type kind, or to multiply a duration
+    operand by a numeric operand.
+
+    Examples:
+        Multiplication of two floating point numbers::
+
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.mul(5.0, 2.0)
+            Binary(\
+Binary.Op.MUL, \
+Value(5.0, Float()), \
+Value(2.0, Float()), \
+Float())
+
+        Multiplication of a duration by a float::
+
+            >>> from qiskit.circuit import Duration
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.mul(Duration.dt(1000), 0.5)
+            Binary(\
+Binary.Op.MUL, \
+Value(Duration.dt(1000), Duration()), \
+Value(0.5, Float()), \
+Duration())
+    """
+    left, right = _lift_binary_operands(left, right)
+    type: types.Type
+    if left.type.kind is right.type.kind is types.Duration:
+        raise TypeError("cannot multiply two durations")
+    if left.type.kind is right.type.kind and left.type.kind in {types.Uint, types.Float}:
+        type = types.greater(left.type, right.type)
+        left = _coerce_lossless(left, type)
+        right = _coerce_lossless(right, type)
+    elif left.type.kind is types.Duration and right.type.kind in {types.Uint, types.Float}:
+        if not right.const:
+            raise ValueError(
+                f"multiplying operands '{left}' and '{right}' would result in a non-const '{left.type}'"
+            )
+        type = left.type
+    elif right.type.kind is types.Duration and left.type.kind in {types.Uint, types.Float}:
+        if not left.const:
+            raise ValueError(
+                f"multiplying operands '{left}' and '{right}' would result in a non-const '{right.type}'"
+            )
+        type = right.type
+    else:
+        raise TypeError(f"invalid types for '{Binary.Op.MUL}': '{left.type}' and '{right.type}'")
+    return Binary(
+        Binary.Op.MUL,
+        left,
+        right,
+        type,
+    )
+
+
+def div(left: typing.Any, right: typing.Any) -> Expr:
+    """Create a division expression node from the given values, resolving any implicit casts and
+    lifting the values into :class:`Value` nodes if required.
+
+    This can be used to divide numeric operands of the same type kind, to divide a
+    :class`~.types.Duration` operand by a numeric operand, or to divide two
+    :class`~.types.Duration` operands which yields an expression of type
+    :class:`~.types.Float`.
+
+    Examples:
+        Division of two floating point numbers::
+
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.div(5.0, 2.0)
+            Binary(\
+Binary.Op.DIV, \
+Value(5.0, Float()), \
+Value(2.0, Float()), \
+Float())
+
+        Division of two durations::
+
+            >>> from qiskit.circuit import Duration
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.div(Duration.dt(10000), Duration.dt(1000))
+            Binary(\
+Binary.Op.DIV, \
+Value(Duration.dt(10000), Duration()), \
+Value(Duration.dt(1000), Duration()), \
+Float())
+
+
+        Division of a duration by a float::
+
+            >>> from qiskit.circuit import Duration
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.div(Duration.dt(10000), 12.0)
+            Binary(\
+Binary.Op.DIV, \
+Value(Duration.dt(10000), Duration()), \
+Value(12.0, types.Float()), \
+Duration())
+    """
+    left, right = _lift_binary_operands(left, right)
+    type: types.Type
+    if left.type.kind is right.type.kind and left.type.kind in {
+        types.Duration,
+        types.Uint,
+        types.Float,
+    }:
+        if left.type.kind is types.Duration:
+            type = types.Float()
+        elif types.order(left.type, right.type) is not types.Ordering.NONE:
+            type = types.greater(left.type, right.type)
+            left = _coerce_lossless(left, type)
+            right = _coerce_lossless(right, type)
+    elif left.type.kind is types.Duration and right.type.kind in {types.Uint, types.Float}:
+        if not right.const:
+            raise ValueError(
+                f"division of '{left}' and '{right}' would result in a non-const '{left.type}'"
+            )
+        type = left.type
+    else:
+        raise TypeError(f"invalid types for '{Binary.Op.DIV}': '{left.type}' and '{right.type}'")
+    return Binary(
+        Binary.Op.DIV,
+        left,
+        right,
+        type,
+    )

qiskit/circuit/classical/expr/expr.py

@@ -22,10 +22,12 @@ from __future__ import annotations
 __all__ = [
     "Expr",
     "Var",
+    "Stretch",
     "Value",
     "Cast",
     "Unary",
     "Binary",
+    "Index",
 ]
 
 import abc
@@ -55,9 +57,10 @@ class Expr(abc.ABC):
     All subclasses are responsible for setting their ``type`` attribute in their ``__init__``, and
     should not call the parent initializer."""
 
-    __slots__ = ("type",)
+    __slots__ = ("type", "const")
 
     type: types.Type
+    const: bool
 
     # Sentinel to prevent instantiation of the base class.
     @abc.abstractmethod
@@ -89,6 +92,7 @@ class Cast(Expr):
 
     def __init__(self, operand: Expr, type: types.Type, implicit: bool = False):
         self.type = type
+        self.const = operand.const
         self.operand = operand
         self.implicit = implicit
 
@@ -99,6 +103,7 @@ class Cast(Expr):
         return (
             isinstance(other, Cast)
             and self.type == other.type
+            and self.const == other.const
             and self.operand == other.operand
             and self.implicit == other.implicit
         )
@@ -141,6 +146,7 @@ class Var(Expr):
         name: str | None = None,
     ):
         super().__setattr__("type", type)
+        super().__setattr__("const", False)
         super().__setattr__("var", var)
         super().__setattr__("name", name)
 
@@ -151,8 +157,9 @@ class Var(Expr):
 
     @property
     def standalone(self) -> bool:
-        """Whether this :class:`Var` is a standalone variable that owns its storage location.  If
-        false, this is a wrapper :class:`Var` around a pre-existing circuit object."""
+        """Whether this :class:`Var` is a standalone variable that owns its storage
+        location, if applicable. If false, this is a wrapper :class:`Var` around a
+        pre-existing circuit object."""
         return isinstance(self.var, uuid.UUID)
 
     def accept(self, visitor, /):
@@ -185,6 +192,76 @@ class Var(Expr):
     def __setstate__(self, state):
         var, type, name = state
         super().__setattr__("type", type)
+        super().__setattr__("const", False)
+        super().__setattr__("var", var)
+        super().__setattr__("name", name)
+
+    def __copy__(self):
+        # I am immutable...
+        return self
+
+    def __deepcopy__(self, memo):
+        # ... as are all my constituent parts.
+        return self
+
+
+@typing.final
+class Stretch(Expr):
+    """A stretch variable.
+
+    In general, construction of stretch variables for use in programs should use :meth:`Stretch.new`
+    or :meth:`.QuantumCircuit.add_stretch`.
+    """
+
+    __slots__ = (
+        "var",
+        "name",
+    )
+
+    var: uuid.UUID
+    """A :class:`~uuid.UUID` to uniquely identify this stretch."""
+    name: str
+    """The name of the stretch variable."""
+
+    def __init__(
+        self,
+        var: uuid.UUID,
+        name: str,
+    ):
+        super().__setattr__("type", types.Duration())
+        super().__setattr__("const", True)
+        super().__setattr__("var", var)
+        super().__setattr__("name", name)
+
+    @classmethod
+    def new(cls, name: str) -> typing.Self:
+        """Generate a new named stretch variable."""
+        return cls(uuid.uuid4(), name)
+
+    def accept(self, visitor, /):
+        return visitor.visit_stretch(self)
+
+    def __setattr__(self, key, value):
+        if hasattr(self, key):
+            raise AttributeError(f"'Stretch' object attribute '{key}' is read-only")
+        raise AttributeError(f"'Stretch' object has no attribute '{key}'")
+
+    def __hash__(self):
+        return hash((self.var, self.name))
+
+    def __eq__(self, other):
+        return isinstance(other, Stretch) and self.var == other.var and self.name == other.name
+
+    def __repr__(self):
+        return f"Stretch({self.var}, {self.name})"
+
+    def __getstate__(self):
+        return (self.var, self.name)
+
+    def __setstate__(self, state):
+        var, name = state
+        super().__setattr__("type", types.Duration())
+        super().__setattr__("const", True)
         super().__setattr__("var", var)
         super().__setattr__("name", name)
 
@@ -206,6 +283,7 @@ class Value(Expr):
     def __init__(self, value: typing.Any, type: types.Type):
         self.type = type
         self.value = value
+        self.const = True
 
     def accept(self, visitor, /):
         return visitor.visit_value(self)
@@ -257,6 +335,7 @@ class Unary(Expr):
         self.op = op
         self.operand = operand
         self.type = type
+        self.const = operand.const
 
     def accept(self, visitor, /):
         return visitor.visit_unary(self)
@@ -265,6 +344,7 @@ class Unary(Expr):
         return (
             isinstance(other, Unary)
             and self.type == other.type
+            and self.const == other.const
             and self.op is other.op
             and self.operand == other.operand
         )
@@ -305,6 +385,15 @@ class Binary(Expr):
         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`
@@ -336,6 +425,14 @@ class Binary(Expr):
         """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__()}"
@@ -348,6 +445,7 @@ class Binary(Expr):
         self.left = left
         self.right = right
         self.type = type
+        self.const = left.const and right.const
 
     def accept(self, visitor, /):
         return visitor.visit_binary(self)
@@ -356,6 +454,7 @@ class Binary(Expr):
         return (
             isinstance(other, Binary)
             and self.type == other.type
+            and self.const == other.const
             and self.op is other.op
             and self.left == other.left
             and self.right == other.right
@@ -381,6 +480,7 @@ class Index(Expr):
         self.target = target
         self.index = index
         self.type = type
+        self.const = target.const and index.const
 
     def accept(self, visitor, /):
         return visitor.visit_index(self)
@@ -389,6 +489,7 @@ class Index(Expr):
         return (
             isinstance(other, Index)
             and self.type == other.type
+            and self.const == other.const
             and self.target == other.target
             and self.index == other.index
         )