[Stretch] Support const classical expressions. (Qiskit#13811)

* WIP

* Add try_const to lift.

* Try multiple singletons, new one for const.

* Revert "Try multiple singletons, new one for const."

This reverts commit e2b3221.

* Remove Bool singleton test.

* Add const handling for stores, fix test bugs.

* Fix formatting.

* Remove Duration and Stretch for now.

* Cleanup, fix const bug in index.

* Fix ordering issue for types with differing const-ness.

Types that have some natural order no longer have an ordering
when one of them is strictly greater but has an incompatible
const-ness (i.e. when the greater type is const but the other
type is not).

* Fix QPY serialization.

We need to reject types with const=True in QPY until it supports them.

For now, I've also made the Index and shift operator constructors
lift their RHS to the same const-ness as the target to make it
less likely that existing users of expr run into issues when
serializing to older QPY versions.

* Make expr.Lift default to non-const.

This is probably a better default in general, since we
don't really have much use for const except for timing
stuff.

* Revert to old test_expr_constructors.py.

* Make binary_logical lift independent again.

Since we're going for using a Cast node when const-ness
differs, this will be fine.

* Update tests, handle a few edge cases.

* Fix docstring.

* Remove now redundant arg from tests.

* Add const testing for ordering.

* Add const tests for shifts.

* Add release note.

* Add const store tests.

* Address lint, minor cleanup.

* Reject const vars in add_var and add_input.

Also removes the assumption that a const-type can never be an l-value
in favor of just restricting l-values with const types from being
added to circuits for now.

We will (in a separate PR) add support for adding stretch variables
to circuits, which are const. However, we may track those
differently, or at least not report them as variable when users
query the circuit for variables.

* Implement QPY support for const-typed expressions.

* Remove invalid test.

This one I'd added thinking I ought to block store from using
a const var target. But since I figured it's better to just
restrict adding vars to the circuit that are const (and leave
the decision of whether or not a const var can be an l-value
till later), this test no longer makes sense.

* Update QPY version 14 desc.

* Fix lint.

* Add serialization testing.

* Test pre-v14 QPY rejects const-typed exprs.

* Revert visitors.py.

* Address review comments.

* Improve type docs.

* Revert QPY, since the old format can support constexprs.

By making const-ness a property of expressions, we don't need
any special serialization in QPY. That's because we assume that
all `Var` expressions are non-const, and all `Value` expressions
are const. And the const-ness of any expression is defined by
the const-ness of its operands, e.g. when QPY reconstructs a
binary operand, the constructed expression's `const` attribute
gets set to `True` if both of the operands are `const`, which
ultimately flows bottom-up from the `Var` and `Value` leaf nodes.

* Move const-ness from Type to Expr.

* Revert QPY testing, no longer needed.

* Add explicit validation of const expr.

* Revert stuff I didn't need to touch.

* Update release note.

* A few finishing touches.

* Address review comments.

Author: kevinhartman

qiskit/circuit/classical/expr/__init__.py

@@ -39,14 +39,18 @@
 
 These objects are mutable and should not be reused in a different location without a copy.
 
+All :class`Expr` instances define a boolean :attr:`~Expr.const` attribute, which indicates
+whether the expression can be evaluated at compile time. Most expression classes infer this
+during construction based on the const-ness of their operands.
+
 The base for dynamic variables is the :class:`Var`, which can be either an arbitrarily typed
 real-time variable, or a wrapper around a :class:`.Clbit` or :class:`.ClassicalRegister`.
 
 .. autoclass:: Var
     :members: var, name, new
 
 Similarly, literals used in expressions (such as integers) should be lifted to :class:`Value` nodes
-with associated types.
+with associated types. A :class:`Value` is always considered a constant expression.
 
 .. autoclass:: Value
 

qiskit/circuit/classical/expr/expr.py

@@ -55,9 +55,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 +90,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 +101,7 @@ def __eq__(self, other):
         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 +144,7 @@ def __init__(
         name: str | None = None,
     ):
         super().__setattr__("type", type)
+        super().__setattr__("const", False)
         super().__setattr__("var", var)
         super().__setattr__("name", name)
 
@@ -151,8 +155,9 @@ def new(cls, name: str, type: types.Type) -> typing.Self:
 
     @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 +190,7 @@ def __getstate__(self):
     def __setstate__(self, state):
         var, type, name = state
         super().__setattr__("type", type)
+        super().__setattr__("const", False)
         super().__setattr__("var", var)
         super().__setattr__("name", name)
 
@@ -206,6 +212,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 +264,7 @@ def __init__(self, op: Unary.Op, operand: Expr, type: types.Type):
         self.op = op
         self.operand = operand
         self.type = type
+        self.const = operand.const
 
     def accept(self, visitor, /):
         return visitor.visit_unary(self)
@@ -265,6 +273,7 @@ def __eq__(self, other):
         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
         )
@@ -348,6 +357,7 @@ def __init__(self, op: Binary.Op, left: Expr, right: Expr, type: types.Type):
         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 +366,7 @@ def __eq__(self, other):
         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 +392,7 @@ def __init__(self, target: Expr, index: Expr, type: types.Type):
         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 +401,7 @@ def __eq__(self, other):
         return (
             isinstance(other, Index)
             and self.type == other.type
+            and self.const == other.const
             and self.target == other.target
             and self.index == other.index
         )

releasenotes/notes/const-expr-397ff09042942b81.yaml

@@ -0,0 +1,22 @@
+---
+features_circuits:
+  - |
+    The classical realtime-expressions module :mod:`qiskit.circuit.classical` can now represent
+    constant expressions. The :class:`~.expr.Expr` class now has a bool
+    :attr:`~.expr.Expr.const` attribute which indicates the expression's const-ness. This allows
+    us to enforce that expressions in certain contexts must be possible to evaluate at compile time.
+
+    All :class:`~.expr.Var` expressions are considered to be non-const, while all :class:`~.expr.Value`
+    expressions are const.
+
+    An expression comprised only of other const expressions is also const::
+
+      from qiskit.circuit.classical import expr
+
+      assert expr.bit_and(5, 6).const
+
+    An expression that contains any non-const expression is non-const::
+
+      from qiskit.circuit.classical import expr, types
+
+      assert not expr.bit_and(5, expr.Var.new("a", types.Uint(5)).const

test/python/circuit/classical/test_expr_constructors.py

@@ -182,12 +182,15 @@ def test_binary_bitwise_explicit(self, function, opcode):
                 opcode, expr.Var(cr, types.Uint(8)), expr.Value(255, types.Uint(8)), types.Uint(8)
             ),
         )
+        self.assertFalse(function(cr, 255).const)
+
         self.assertEqual(
             function(255, cr),
             expr.Binary(
                 opcode, expr.Value(255, types.Uint(8)), expr.Var(cr, types.Uint(8)), types.Uint(8)
             ),
         )
+        self.assertFalse(function(255, cr).const)
 
         clbit = Clbit()
         self.assertEqual(
@@ -199,6 +202,8 @@ def test_binary_bitwise_explicit(self, function, opcode):
                 types.Bool(),
             ),
         )
+        self.assertFalse(function(True, clbit).const)
+
         self.assertEqual(
             function(clbit, False),
             expr.Binary(
@@ -208,6 +213,18 @@ def test_binary_bitwise_explicit(self, function, opcode):
                 types.Bool(),
             ),
         )
+        self.assertFalse(function(clbit, True).const)
+
+        self.assertEqual(
+            function(255, 255),
+            expr.Binary(
+                opcode,
+                expr.Value(255, types.Uint(8)),
+                expr.Value(255, types.Uint(8)),
+                types.Uint(8),
+            ),
+        )
+        self.assertTrue(function(255, 255).const)
 
     @ddt.data(
         (expr.bit_and, expr.Binary.Op.BIT_AND),
@@ -278,6 +295,7 @@ def test_binary_logical_explicit(self, function, opcode):
                 types.Bool(),
             ),
         )
+        self.assertFalse(function(cr, clbit).const)
 
         self.assertEqual(
             function(cr, 3),
@@ -288,6 +306,7 @@ def test_binary_logical_explicit(self, function, opcode):
                 types.Bool(),
             ),
         )
+        self.assertFalse(function(cr, 3).const)
 
         self.assertEqual(
             function(False, clbit),
@@ -298,6 +317,7 @@ def test_binary_logical_explicit(self, function, opcode):
                 types.Bool(),
             ),
         )
+        self.assertFalse(function(False, clbit).const)
 
     @ddt.data(
         (expr.equal, expr.Binary.Op.EQUAL),
@@ -314,6 +334,7 @@ def test_binary_equal_explicit(self, function, opcode):
                 opcode, expr.Var(cr, types.Uint(8)), expr.Value(255, types.Uint(8)), types.Bool()
             ),
         )
+        self.assertFalse(function(cr, 255).const)
 
         self.assertEqual(
             function(7, cr),
@@ -324,6 +345,7 @@ def test_binary_equal_explicit(self, function, opcode):
                 types.Bool(),
             ),
         )
+        self.assertFalse(function(7, cr).const)
 
         self.assertEqual(
             function(clbit, True),
@@ -334,6 +356,7 @@ def test_binary_equal_explicit(self, function, opcode):
                 types.Bool(),
             ),
         )
+        self.assertFalse(function(clbit, True).const)
 
     @ddt.data(expr.equal, expr.not_equal)
     def test_binary_equal_forbidden(self, function):
@@ -360,6 +383,7 @@ def test_binary_relation_explicit(self, function, opcode):
                 opcode, expr.Var(cr, types.Uint(8)), expr.Value(200, types.Uint(8)), types.Bool()
             ),
         )
+        self.assertFalse(function(cr, 200).const)
 
         self.assertEqual(
             function(12, cr),
@@ -370,6 +394,7 @@ def test_binary_relation_explicit(self, function, opcode):
                 types.Bool(),
             ),
         )
+        self.assertFalse(function(12, cr).const)
 
     @ddt.data(expr.less, expr.less_equal, expr.greater, expr.greater_equal)
     def test_binary_relation_forbidden(self, function):
@@ -388,10 +413,19 @@ def test_index_explicit(self):
             expr.index(cr, 3),
             expr.Index(expr.Var(cr, types.Uint(4)), expr.Value(3, types.Uint(2)), types.Bool()),
         )
+        self.assertFalse(expr.index(cr, 3).const)
+
         self.assertEqual(
             expr.index(a, cr),
             expr.Index(a, expr.Var(cr, types.Uint(4)), types.Bool()),
         )
+        self.assertFalse(expr.index(a, cr).const)
+
+        self.assertEqual(
+            expr.index(255, 1),
+            expr.Index(expr.Value(255, types.Uint(8)), expr.Value(1, types.Uint(1)), types.Bool()),
+        )
+        self.assertTrue(expr.index(255, 1).const)
 
     def test_index_forbidden(self):
         with self.assertRaisesRegex(TypeError, "invalid types"):
@@ -414,16 +448,21 @@ def test_shift_explicit(self, function, opcode):
                 opcode, expr.Var(cr, types.Uint(8)), expr.Value(5, types.Uint(3)), types.Uint(8)
             ),
         )
+        self.assertFalse(function(cr, 5).const)
+
         self.assertEqual(
             function(a, cr),
             expr.Binary(opcode, a, expr.Var(cr, types.Uint(8)), types.Uint(4)),
         )
+        self.assertFalse(function(a, cr).const)
+
         self.assertEqual(
             function(3, 5, types.Uint(8)),
             expr.Binary(
                 opcode, expr.Value(3, types.Uint(8)), expr.Value(5, types.Uint(3)), types.Uint(8)
             ),
         )
+        self.assertTrue(function(3, 5, types.Uint(8)).const)
 
     @ddt.data(expr.shift_left, expr.shift_right)
     def test_shift_forbidden(self, function):