[Stretch] Support Duration type in classical expressions. (#13844)

* 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.

* Add Float type to classical expressions.

* Allow DANGEROUS conversion from Float to Bool.

I wasn't going to have this, but since we have DANGEROUS
Float => Int, and we have Int => Bool, I think this makes the
most sense.

* Test Float ordering.

* Improve error messages for using Float with logical operators.

* Float tests for constructors.

* Add release note.

* Add Duration and Stretch classical types.

A Stretch can always represent a Duration (it's just an expression
without any unresolved stretch variables, in this case), so we
allow implicit conversion from Duration => Stretch.

The reason for a separate Duration type is to support things like
Duration / Duration => Float. This is not valid for stretches in
OpenQASM (to my knowledge).

* Add Duration type to qiskit.circuit.
Also adds support to expr.lift to create a value expression of
type types.Duration from an instance of qiskit.circuit.Duration.

* Block Stretch from use in binary relations.

* Add type ordering tests for Duration and Stretch.

Also improves testing for other types.

* Test expr constructors for Duration and Stretch.

* Fix lint.

* 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.

* QASM export for floats.

* QPY support for floats.

* Fix lint.

* Settle on Duration circuit core type.

* QPY serialization for durations and stretches.

* Add QPY testing.

I can't really test Stretch yet since we can't add them to circuits
until a later PR.

* QASM support for stretch and duration.

The best I can do to test these right now (before Delay
is made to accept timing expressions) is to use them in
comparison operations (will be in a follow up commit).

* Fix lint.

* Don't use match since we still support Python 3.9.

* Fix enum match.

* 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.

* Fix-up after merge.

* Fix-ups after merge.

* Fix lint.

* Fix comment and release note.

* Special-case Var const-ness for Stretch type.

This feels like a bit of a hack, but the idea is to override a
Var to report itself as a constant expression only in
the case that its type is Stretch. I would argue that it's not
quite as hack-y as it appears, since Stretch is probably the
only kind of constant we'll ever allow in Qiskit without an
in-line initializer. If ever we want to support declaring
other kinds of constants (e.g. Uint), we'll probably want to
introduce a `expr.Const` type whose constructor requires a
const initializer expression.

* Address review comments.

* Update release note.

* Update docs.

* Address review comments.

* Remove Stretch type.

* Remove a few more mentions of the binned stretch type.

* Add docstring for Duration.

* Address review comments.

* Remove unused import.

* Remove visitor short circuit.

Author: kevinhartman

crates/circuit/src/duration.rs

@@ -0,0 +1,89 @@
+// 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.
+
+use pyo3::prelude::*;
+use pyo3::IntoPyObjectExt;
+
+/// A length of time used to express circuit timing.
+///
+/// It defines a group of classes which are all subclasses of itself (functionally, an
+/// enumeration carrying data).
+///
+/// In Python 3.10+, you can use it in a match statement::
+///
+///   match duration:
+///      case Duration.dt(dt):
+///          return dt
+///      case Duration.s(seconds):
+///          return seconds / 5e-7
+///      case _:
+///          raise ValueError("expected dt or seconds")
+///
+/// And in Python 3.9, you can use :meth:`Duration.unit` to determine which variant
+/// is populated::
+///
+///   if duration.unit() == "dt":
+///       return duration.value()
+///   elif duration.unit() == "s":
+///       return duration.value() / 5e-7
+///   else:
+///       raise ValueError("expected dt or seconds")
+#[pyclass(eq, module = "qiskit._accelerate.circuit")]
+#[derive(PartialEq, Clone, Copy, Debug)]
+#[allow(non_camel_case_types)]
+pub enum Duration {
+    dt(i64),
+    ns(f64),
+    us(f64),
+    ms(f64),
+    s(f64),
+}
+
+#[pymethods]
+impl Duration {
+    /// The corresponding ``unit`` of the duration.
+    fn unit(&self) -> &'static str {
+        match self {
+            Duration::dt(_) => "dt",
+            Duration::us(_) => "us",
+            Duration::ns(_) => "ns",
+            Duration::ms(_) => "ms",
+            Duration::s(_) => "s",
+        }
+    }
+
+    /// The ``value`` of the duration.
+    ///
+    /// This will be a Python ``int`` if the :meth:`~Duration.unit` is ``"dt"``,
+    /// else a ``float``.
+    #[pyo3(name = "value")]
+    fn py_value(&self, py: Python) -> PyResult<PyObject> {
+        match self {
+            Duration::dt(v) => v.into_py_any(py),
+            Duration::us(v) | Duration::ns(v) | Duration::ms(v) | Duration::s(v) => {
+                v.into_py_any(py)
+            }
+        }
+    }
+}
+
+impl Duration {
+    fn __repr__(&self) -> String {
+        match self {
+            Duration::ns(t) => format!("Duration.ns({})", t),
+            Duration::us(t) => format!("Duration.us({})", t),
+            Duration::ms(t) => format!("Duration.ms({})", t),
+            Duration::s(t) => format!("Duration.s({})", t),
+            Duration::dt(t) => format!("Duration.dt({})", t),
+        }
+    }
+}

crates/circuit/src/lib.rs

@@ -17,6 +17,7 @@ pub mod converters;
 pub mod dag_circuit;
 pub mod dag_node;
 mod dot_utils;
+pub mod duration;
 pub mod error;
 pub mod gate_matrix;
 pub mod imports;
@@ -157,6 +158,7 @@ macro_rules! impl_intopyobject_for_copy_pyclass {
 }
 
 pub fn circuit(m: &Bound<PyModule>) -> PyResult<()> {
+    m.add_class::<duration::Duration>()?;
     m.add_class::<circuit_data::CircuitData>()?;
     m.add_class::<circuit_instruction::CircuitInstruction>()?;
     m.add_class::<dag_circuit::DAGCircuit>()?;

qiskit/circuit/__init__.py

@@ -1282,6 +1282,8 @@ def __array__(self, dtype=None, copy=None):
         \end{pmatrix}
 """
 
+from qiskit._accelerate.circuit import Duration  # pylint: disable=unused-import
+
 from .exceptions import CircuitError
 from . import _utils
 from .quantumcircuit import QuantumCircuit

qiskit/circuit/classical/expr/constructors.py

@@ -109,7 +109,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):
@@ -126,6 +126,9 @@ def lift(value: typing.Any, /, type: types.Type | None = None) -> Expr:
     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:

qiskit/circuit/classical/expr/visitors.py

@@ -268,6 +268,8 @@ def is_lvalue(node: expr.Expr, /) -> bool:
     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``::

qiskit/circuit/classical/types/__init__.py

@@ -34,16 +34,14 @@
 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, and the
-:class:`Float` type represents Python floats.
+: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
-
-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:: Duration
 
 Working with types
 ==================
@@ -99,6 +97,7 @@
 __all__ = [
     "Type",
     "Bool",
+    "Duration",
     "Float",
     "Uint",
     "Ordering",
@@ -110,5 +109,5 @@
     "cast_kind",
 ]
 
-from .types import Type, Bool, Float, 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 @@
 
 import enum
 
-from .types import Type, Bool, Float, 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
@@ -67,6 +67,7 @@ def _order_uint_uint(left: Uint, right: Uint, /) -> Ordering:
     (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,
 }
 
 
@@ -199,6 +200,7 @@ def _uint_cast(from_: Uint, to_: Uint, /) -> CastKind:
     (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,
 }
 
 

qiskit/circuit/classical/types/types.py

@@ -22,6 +22,7 @@
 __all__ = [
     "Type",
     "Bool",
+    "Duration",
     "Float",
     "Uint",
 ]
@@ -134,3 +135,19 @@ def __hash__(self):
 
     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/qasm3/ast.py

@@ -173,6 +173,18 @@ class BitType(ClassicalType):
     __slots__ = ()
 
 
+class DurationType(ClassicalType):
+    """Type information for a duration."""
+
+    __slots__ = ()
+
+
+class StretchType(ClassicalType):
+    """Type information for a stretch."""
+
+    __slots__ = ()
+
+
 class BitArrayType(ClassicalType):
     """Type information for a sized number of classical bits."""
 

qiskit/qasm3/exporter.py

@@ -1255,6 +1255,8 @@ def _build_ast_type(type_: types.Type) -> ast.ClassicalType:
         return ast.UintType(type_.width)
     if type_.kind is types.Float:
         return ast.FloatType.DOUBLE
+    if type_.kind is types.Duration:
+        return ast.DurationType()
     raise RuntimeError(f"unhandled expr type '{type_}'")
 
 
@@ -1271,13 +1273,26 @@ def __init__(self, lookup):
     def visit_var(self, node, /):
         return self.lookup(node) if node.standalone else self.lookup(node.var)
 
+    # pylint: disable=too-many-return-statements
     def visit_value(self, node, /):
         if node.type.kind is types.Bool:
             return ast.BooleanLiteral(node.value)
         if node.type.kind is types.Uint:
             return ast.IntegerLiteral(node.value)
         if node.type.kind is types.Float:
             return ast.FloatLiteral(node.value)
+        if node.type.kind is types.Duration:
+            unit = node.value.unit()
+            if unit == "dt":
+                return ast.DurationLiteral(node.value.value(), ast.DurationUnit.SAMPLE)
+            if unit == "ns":
+                return ast.DurationLiteral(node.value.value(), ast.DurationUnit.NANOSECOND)
+            if unit == "us":
+                return ast.DurationLiteral(node.value.value(), ast.DurationUnit.MICROSECOND)
+            if unit == "ms":
+                return ast.DurationLiteral(node.value.value(), ast.DurationUnit.MILLISECOND)
+            if unit == "s":
+                return ast.DurationLiteral(node.value.value(), ast.DurationUnit.SECOND)
         raise RuntimeError(f"unhandled Value type '{node}'")
 
     def visit_cast(self, node, /):