[Stretch] Support Duration type in classical expressions.

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, /):

qiskit/qasm3/printer.py

@@ -210,6 +210,12 @@ def _visit_FloatType(self, node: ast.FloatType) -> None:
     def _visit_BoolType(self, _node: ast.BoolType) -> None:
         self.stream.write("bool")
 
+    def _visit_DurationType(self, _node: ast.DurationType) -> None:
+        self.stream.write("duration")
+
+    def _visit_StretchType(self, _node: ast.StretchType) -> None:
+        self.stream.write("stretch")
+
     def _visit_IntType(self, node: ast.IntType) -> None:
         self.stream.write("int")
         if node.size is not None:

qiskit/qpy/__init__.py

@@ -382,31 +382,58 @@ def open(*args):
 Version 14
 ----------
 
-Version 14 adds support for additional :class:`~.types.Type` classes.
+Version 14 adds a new core DURATION type, as well as support for additional :class:`~.types.Type`
+classes.
+
+DURATION
+~~~~~~~~
+
+A :class:`~.circuit.Duration` is encoded by a single-byte ASCII ``char`` that encodes the kind of
+type, followed by a payload that varies depending on the type.  The defined codes are:
+
+==============================  =========  =========================================================
+Qiskit class                    Type code  Payload
+==============================  =========  =========================================================
+:class:`~.circuit.Duration.dt`   ``t``     One ``unsigned long long value``.
+
+:class:`~.circuit.Duration.ns`   ``n``     One ``double value``.
+
+:class:`~.circuit.Duration.us`   ``u``     One ``double value``.
+
+:class:`~.circuit.Duration.ms`   ``m``     One ``double value``.
+
+:class:`~.circuit.Duration.s`    ``s``     One ``double value``.
+
+==============================  =========  =========================================================
 
 Changes to EXPR_TYPE
 ~~~~~~~~~~~~~~~~~~~~
 
 The following table shows the new type classes added in the version:
 
-======================  =========  =================================================================
-Qiskit class            Type code  Payload
-======================  =========  =================================================================
-:class:`~.types.Float`  ``f``      None.
-======================  =========  =================================================================
+=========================  =========  ==============================================================
+Qiskit class               Type code  Payload
+=========================  =========  ==============================================================
+:class:`~.types.Float`     ``f``      None.
+
+:class:`~.types.Duration`  ``d``      None.
+
+=========================  =========  ==============================================================
 
 Changes to EXPR_VALUE
 ~~~~~~~~~~~~~~~~~~~~~
 
 The classical expression's type system now supports new encoding types for value literals, in
 addition to the existing encodings for int and bool. The new value type encodings are below:
 
-===========  =========  ============================================================================
-Python type  Type code  Payload
-===========  =========  ============================================================================
-``float``    ``f``      One ``double value``.
+===========================  =========  ============================================================
+Python type                  Type code  Payload
+===========================  =========  ============================================================
+``float``                    ``f``      One ``double value``.
 
-===========  =========  ============================================================================
+:class:`~.circuit.Duration`  ``t``      One ``DURATION``.
+
+===========================  =========  ============================================================
 
 .. _qpy_version_13: