New function to negate expressions (#15447)

* added negation unary operator and implemented negation constructor for floats, int and delays

* added documentation and tests

* function and enum name changed, added release notes

* linting and testing done, test fixed

* added function name to the docstring

* Uint no longer negatable, fixed the relevant tests and release notes

* added negate to serialization stress-tests

* added documentation, better example, fixed test_cases

* linting and testing

* added a more self contained example and updated release notes

* added negate operation to necessary qasm3 files to fix printing issues

* Fix a ruff issue

* Fix docs failure in CI

---------

Co-authored-by: Eli Arbel <arbel@il.ibm.com>

Author: Shobhit21287

crates/circuit/src/classical/expr/unary.rs

@@ -40,13 +40,14 @@ pub struct Unary {
 pub enum UnaryOp {
     BitNot = 1,
     LogicNot = 2,
+    Negate = 3,
 }
 
 unsafe impl ::bytemuck::CheckedBitPattern for UnaryOp {
     type Bits = u8;
 
     fn is_valid_bit_pattern(bits: &Self::Bits) -> bool {
-        *bits > 0 && *bits < 3
+        *bits > 0 && *bits < 4
     }
 }
 

qiskit/circuit/classical/expr/__init__.py

@@ -123,6 +123,7 @@
 
 .. autofunction:: bit_not
 .. autofunction:: logic_not
+.. autofunction:: negate
 
 Similarly, the binary operations and relations have helper functions defined.
 
@@ -230,6 +231,7 @@
     "logic_not",
     "logic_or",
     "mul",
+    "negate",
     "not_equal",
     "shift_left",
     "shift_right",
@@ -263,4 +265,5 @@
     mul,
     div,
     lift_legacy_condition,
+    negate,
 )

qiskit/circuit/classical/expr/constructors.py

@@ -761,3 +761,33 @@ def div(left: typing.Any, right: typing.Any) -> Expr:
         right,
         type,
     )
+
+
+def negate(operand: typing.Any, /) -> Expr:
+    """Negate an expression node from the given value, resolving any implicit casts and
+    lifting the value into a :class:`Value` node if required.
+    
+    Examples:
+        Negation of a floating point number::
+
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.negate(5.0)
+            Unary(\
+Unary.Op.NEGATE, \
+Value(5.0, Float()), \
+Float())
+
+        Negation of a duration::
+
+            >>> from qiskit.circuit import Duration
+            >>> from qiskit.circuit.classical import expr
+            >>> expr.negate(Duration.dt(1000))
+            Unary(\
+Unary.Op.NEGATE, \
+Value(Duration.dt(1000), Duration()), \
+Duration())
+    """
+    operand = lift(operand)
+    if operand.type.kind not in (types.Float, types.Duration):
+        raise TypeError(f"cannot apply '{Unary.Op.NEGATE}' to type '{operand.type}'")
+    return Unary(Unary.Op.NEGATE, operand, operand.type)

qiskit/circuit/classical/expr/expr.py

@@ -46,6 +46,9 @@ class _UnaryOp(enum.Enum):
 
     The logical negation :data:`LOGIC_NOT` takes an input that is implicitly coerced to a
     Boolean, and returns a Boolean.
+
+    The arithmetic negation :data:`NEGATE` takes an input that is either float or duration and
+    returns a value of the same type.
     """
 
     # If adding opcodes, remember to add helper constructor functions in `constructors.py`.
@@ -57,6 +60,8 @@ class _UnaryOp(enum.Enum):
     """Bitwise negation. ``~operand``."""
     LOGIC_NOT = 2
     """Logical negation. ``!operand``."""
+    NEGATE = 3
+    """Arithmetic negation. ``-operand``."""
 
     def __str__(self):
         return f"Unary.{super().__str__()}"

qiskit/qasm3/ast.py

@@ -306,6 +306,7 @@ class Unary(Expression):
     class Op(enum.Enum):
         LOGIC_NOT = "!"
         BIT_NOT = "~"
+        NEGATE = "-"
 
     def __init__(self, op: Op, operand: Expression):
         self.op = op

qiskit/qasm3/printer.py

@@ -38,6 +38,7 @@
     #
     ast.Unary.Op.LOGIC_NOT: _BindingPower(right=22),
     ast.Unary.Op.BIT_NOT: _BindingPower(right=22),
+    ast.Unary.Op.NEGATE: _BindingPower(right=22),
     #
     # Modulo: (19, 20)
     ast.Binary.Op.MUL: _BindingPower(19, 20),

releasenotes/notes/unary-negation-for-expressions-14ebd75289718472.yaml

@@ -0,0 +1,19 @@
+features_circuits:
+  - |
+    Introduced a new unary negation operation :func:`~.expr.negate`, allowing users to negate 
+    float and duration expressions. In-case a scalar is passed, it is automatically lifted to 
+    the correct type.
+
+    Example usage::
+    
+        from qiskit.circuit import ClassicalRegister
+        from qiskit.circuit.classical import expr, types
+
+        qc = QuantumCircuit(2, 2)
+        in_var1 = qc.add_input("in1", types.Float())
+        
+        with qc.if_test(expr.greater(in_var1, 0.2)) as else_:
+            qc.rz(0.3, 0)
+        with else_:
+            with qc.if_test(expr.greater(expr.negate(in_var1), 0.2)): 
+                qc.rz(-0.3, 0)

test/python/circuit/classical/test_expr_constructors.py

@@ -122,6 +122,8 @@ def test_cast_allows_lossy_downcasting(self):
         (expr.logic_not, ClassicalRegister(3)),
         (expr.logic_not, False),
         (expr.logic_not, Clbit()),
+        (expr.negate, 7.0),
+        (expr.negate, Duration.dt(1000)),
     )
     @ddt.unpack
     def test_unary_functions_lift_scalars(self, function, scalar):
@@ -916,3 +918,34 @@ def test_div_forbidden(self):
             expr.div(255.0, 1)
         with self.assertRaisesRegex(TypeError, "invalid types"):
             expr.div(255.0, Duration.dt(1000))
+
+    def test_unary_negate_forbidden(self):
+        with self.assertRaisesRegex(TypeError, "cannot apply"):
+            expr.negate(True)
+        with self.assertRaisesRegex(TypeError, "cannot apply"):
+            expr.negate(Clbit())
+        with self.assertRaisesRegex(TypeError, "cannot apply"):
+            cr = ClassicalRegister(3)
+            expr.negate(cr)
+        with self.assertRaisesRegex(TypeError, "cannot apply"):
+            expr.negate(expr.Value(5, types.Uint(3)))
+
+    def test_unary_negate_explicit(self):
+
+        self.assertEqual(
+            expr.negate(7.0),
+            expr.Unary(
+                expr.Unary.Op.NEGATE,
+                expr.Value(7.0, types.Float()),
+                types.Float(),
+            ),
+        )
+
+        self.assertEqual(
+            expr.negate(Duration.dt(1000)),
+            expr.Unary(
+                expr.Unary.Op.NEGATE,
+                expr.Value(Duration.dt(1000), types.Duration()),
+                types.Duration(),
+            ),
+        )

test/python/circuit/test_circuit_load_from_qpy.py

@@ -1774,7 +1774,7 @@ def test_if_else_expr_stress(self):
                         ),
                     ),
                 ),
-                expr.logic_not(loose),
+                expr.greater(expr.negate(expr.cast(loose, types.Float())), 1.5),
             ),
             outer.copy(),
             [1],
@@ -1864,7 +1864,7 @@ def test_switch_expr_stress(self):
                         ),
                     ),
                 ),
-                expr.logic_not(loose),
+                expr.greater(expr.negate(expr.cast(loose, types.Float())), 1.5),
             ),
             [(False, outer.copy())],
             [1],