[Stretch] Add +, -, *, / operators for 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/__init__.py

@@ -134,6 +134,10 @@
 .. autofunction:: greater_equal
 .. autofunction:: shift_left
 .. autofunction:: shift_right
+.. autofunction:: add
+.. autofunction:: sub
+.. autofunction:: mul
+.. autofunction:: div
 
 You can index into unsigned integers and bit-likes using another unsigned integer of any width.
 This includes in storing operations, if the target of the index is writeable.
@@ -214,6 +218,10 @@
     "greater",
     "greater_equal",
     "index",
+    "add",
+    "sub",
+    "mul",
+    "div",
     "lift_legacy_condition",
 ]
 
@@ -238,5 +246,9 @@
     shift_left,
     shift_right,
     index,
+    add,
+    sub,
+    mul,
+    div,
     lift_legacy_condition,
 )

qiskit/circuit/classical/expr/constructors.py

@@ -36,6 +36,10 @@
     "shift_left",
     "shift_right",
     "index",
+    "add",
+    "sub",
+    "mul",
+    "div",
     "lift_legacy_condition",
 ]
 
@@ -109,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):
@@ -126,6 +130,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:
@@ -561,3 +568,210 @@ 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 types.Bool
+        or right.type.kind is types.Bool
+        or left.type.kind is not right.type.kind
+        and types.order(left.type, right.type) is types.Ordering.NONE
+    ):
+        raise TypeError(f"invalid types for '{op}': '{left.type}' and '{right.type}'")
+    type = types.greater(left.type, right.type)
+    return Binary(
+        op,
+        _coerce_lossless(left, type),
+        _coerce_lossless(right, type),
+        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:
+        Subtration 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 :class:`~.types.Float`.
+
+    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 types.Duration and right.type.kind is types.Duration:
+        raise TypeError("cannot multiply two durations")
+    if left.type.kind is types.Duration and right.type.kind is 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 is 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
+    elif (
+        left.type.kind is right.type.kind
+        and left.type.kind is not types.Bool
+        and 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)
+    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 :class:`~.types.Float`, 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 is not types.Bool:
+        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 is 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,
+    )