From 1eb0188ee78ba074c267795c5ae83c269d8839fb Mon Sep 17 00:00:00 2001
From: AlexanderIvrii <alexi@il.ibm.com>
Date: Fri, 29 Mar 2024 13:13:08 +0300
Subject: [PATCH 1/3] adding annotated argument to power methods

---
 qiskit/circuit/annotated_operation.py         | 18 ++++++++++
 qiskit/circuit/gate.py                        | 22 ++++++++----
 qiskit/circuit/library/standard_gates/i.py    |  2 +-
 .../circuit/library/standard_gates/iswap.py   |  2 +-
 qiskit/circuit/library/standard_gates/p.py    |  4 +--
 qiskit/circuit/library/standard_gates/r.py    |  2 +-
 qiskit/circuit/library/standard_gates/rx.py   |  2 +-
 qiskit/circuit/library/standard_gates/rxx.py  |  2 +-
 qiskit/circuit/library/standard_gates/ry.py   |  2 +-
 qiskit/circuit/library/standard_gates/ryy.py  |  2 +-
 qiskit/circuit/library/standard_gates/rz.py   |  2 +-
 qiskit/circuit/library/standard_gates/rzx.py  |  2 +-
 qiskit/circuit/library/standard_gates/rzz.py  |  2 +-
 qiskit/circuit/library/standard_gates/s.py    |  8 ++---
 qiskit/circuit/library/standard_gates/t.py    |  4 +--
 .../library/standard_gates/xx_minus_yy.py     |  2 +-
 .../library/standard_gates/xx_plus_yy.py      |  2 +-
 qiskit/circuit/library/standard_gates/z.py    |  2 +-
 qiskit/circuit/quantumcircuit.py              | 36 ++++++++++++-------
 .../circuit/test_annotated_operation.py       |  2 +-
 .../python/circuit/test_circuit_operations.py | 17 ++++++++-
 test/python/circuit/test_gate_power.py        | 26 +++++++++++++-
 22 files changed, 120 insertions(+), 43 deletions(-)

diff --git a/qiskit/circuit/annotated_operation.py b/qiskit/circuit/annotated_operation.py
index 2e7e4405e6be..bc6fbc05d1ce 100644
--- a/qiskit/circuit/annotated_operation.py
+++ b/qiskit/circuit/annotated_operation.py
@@ -198,6 +198,24 @@ def inverse(self, annotated: bool = True):
         extended_modifiers.append(InverseModifier())
         return AnnotatedOperation(self.base_op, extended_modifiers)
 
+    def power(self, exponent: float, annotated: bool = False):
+        """
+        Raise this gate to the power of ``exponent``.
+
+        Implemented as an annotated operation, see  :class:`.AnnotatedOperation`.
+
+        Args:
+            exponent: the power to raise the gate to
+            annotated: ignored (used for consistency with other power methods)
+
+        Returns:
+            An operation implementing ``gate^exponent``
+        """
+        # pylint: disable=unused-argument
+        extended_modifiers = self.modifiers.copy()
+        extended_modifiers.append(PowerModifier(exponent))
+        return AnnotatedOperation(self.base_op, extended_modifiers)
+
 
 def _canonicalize_modifiers(modifiers):
     """
diff --git a/qiskit/circuit/gate.py b/qiskit/circuit/gate.py
index af29f8033b44..82038b5327ac 100644
--- a/qiskit/circuit/gate.py
+++ b/qiskit/circuit/gate.py
@@ -18,7 +18,7 @@
 
 from qiskit.circuit.parameterexpression import ParameterExpression
 from qiskit.circuit.exceptions import CircuitError
-from .annotated_operation import AnnotatedOperation, ControlModifier
+from .annotated_operation import AnnotatedOperation, ControlModifier, PowerModifier
 from .instruction import Instruction
 
 
@@ -62,23 +62,31 @@ def to_matrix(self) -> np.ndarray:
             return self.__array__(dtype=complex)
         raise CircuitError(f"to_matrix not defined for this {type(self)}")
 
-    def power(self, exponent: float):
-        """Creates a unitary gate as `gate^exponent`.
+    def power(self, exponent: float, annotated: bool = False):
+        """Raise this gate to the power of ``exponent``.
+
+        Implemented either as a unitary gate (ref. :class:`~.library.UnitaryGate`)
+        or as an annotated operation (ref. :class:`.AnnotatedOperation`).
 
         Args:
-            exponent (float): Gate^exponent
+            exponent (float): the power to raise the gate to
+            annotated (bool): indicates whether the power gate can be implemented
+                as an annotated operation.
 
         Returns:
-            .library.UnitaryGate: To which `to_matrix` is self.to_matrix^exponent.
+            An operation implementing ``gate^exponent``
 
         Raises:
-            CircuitError: If Gate is not unitary
+            CircuitError: If gate is not unitary
         """
         # pylint: disable=cyclic-import
         from qiskit.quantum_info.operators import Operator
         from qiskit.circuit.library.generalized_gates.unitary import UnitaryGate
 
-        return UnitaryGate(Operator(self).power(exponent), label=f"{self.name}^{exponent}")
+        if not annotated:
+            return UnitaryGate(Operator(self).power(exponent), label=f"{self.name}^{exponent}")
+        else:
+            return AnnotatedOperation(self, PowerModifier(exponent))
 
     def __pow__(self, exponent: float) -> "Gate":
         return self.power(exponent)
diff --git a/qiskit/circuit/library/standard_gates/i.py b/qiskit/circuit/library/standard_gates/i.py
index 2468d9dcedf5..7af7a2bb93a4 100644
--- a/qiskit/circuit/library/standard_gates/i.py
+++ b/qiskit/circuit/library/standard_gates/i.py
@@ -65,7 +65,7 @@ def inverse(self, annotated: bool = False):
         ."""
         return IGate()  # self-inverse
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         return IGate()
 
diff --git a/qiskit/circuit/library/standard_gates/iswap.py b/qiskit/circuit/library/standard_gates/iswap.py
index d871f6b8c3de..fce9e8e53f89 100644
--- a/qiskit/circuit/library/standard_gates/iswap.py
+++ b/qiskit/circuit/library/standard_gates/iswap.py
@@ -124,7 +124,7 @@ def _define(self):
 
         self.definition = qc
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         return XXPlusYYGate(-np.pi * exponent)
 
diff --git a/qiskit/circuit/library/standard_gates/p.py b/qiskit/circuit/library/standard_gates/p.py
index d6e59a834e7c..24c118e471f5 100644
--- a/qiskit/circuit/library/standard_gates/p.py
+++ b/qiskit/circuit/library/standard_gates/p.py
@@ -145,7 +145,7 @@ def __array__(self, dtype=None):
         lam = float(self.params[0])
         return numpy.array([[1, 0], [0, exp(1j * lam)]], dtype=dtype)
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return PhaseGate(exponent * theta)
@@ -289,7 +289,7 @@ def __array__(self, dtype=None):
             )
         return numpy.array([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, eith, 0], [0, 0, 0, 1]], dtype=dtype)
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return CPhaseGate(exponent * theta)
diff --git a/qiskit/circuit/library/standard_gates/r.py b/qiskit/circuit/library/standard_gates/r.py
index a9b825a5484b..2d8027f9a68a 100644
--- a/qiskit/circuit/library/standard_gates/r.py
+++ b/qiskit/circuit/library/standard_gates/r.py
@@ -102,7 +102,7 @@ def __array__(self, dtype=None):
         exp_p = exp(1j * phi)
         return numpy.array([[cos, -1j * exp_m * sin], [-1j * exp_p * sin, cos]], dtype=dtype)
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         theta, phi = self.params
         return RGate(exponent * theta, phi)
diff --git a/qiskit/circuit/library/standard_gates/rx.py b/qiskit/circuit/library/standard_gates/rx.py
index 6ef963fa6bdf..6d5c003a4d06 100644
--- a/qiskit/circuit/library/standard_gates/rx.py
+++ b/qiskit/circuit/library/standard_gates/rx.py
@@ -126,7 +126,7 @@ def __array__(self, dtype=None):
         sin = math.sin(self.params[0] / 2)
         return numpy.array([[cos, -1j * sin], [-1j * sin, cos]], dtype=dtype)
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return RXGate(exponent * theta)
diff --git a/qiskit/circuit/library/standard_gates/rxx.py b/qiskit/circuit/library/standard_gates/rxx.py
index ddfe312291fd..825e4607c789 100644
--- a/qiskit/circuit/library/standard_gates/rxx.py
+++ b/qiskit/circuit/library/standard_gates/rxx.py
@@ -132,7 +132,7 @@ def __array__(self, dtype=None):
             dtype=dtype,
         )
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return RXXGate(exponent * theta)
diff --git a/qiskit/circuit/library/standard_gates/ry.py b/qiskit/circuit/library/standard_gates/ry.py
index 41e3b2598d15..57c46960f5c8 100644
--- a/qiskit/circuit/library/standard_gates/ry.py
+++ b/qiskit/circuit/library/standard_gates/ry.py
@@ -125,7 +125,7 @@ def __array__(self, dtype=None):
         sin = math.sin(self.params[0] / 2)
         return numpy.array([[cos, -sin], [sin, cos]], dtype=dtype)
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return RYGate(exponent * theta)
diff --git a/qiskit/circuit/library/standard_gates/ryy.py b/qiskit/circuit/library/standard_gates/ryy.py
index 059f5c117959..20a6bdadd218 100644
--- a/qiskit/circuit/library/standard_gates/ryy.py
+++ b/qiskit/circuit/library/standard_gates/ryy.py
@@ -132,7 +132,7 @@ def __array__(self, dtype=None):
             dtype=dtype,
         )
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return RYYGate(exponent * theta)
diff --git a/qiskit/circuit/library/standard_gates/rz.py b/qiskit/circuit/library/standard_gates/rz.py
index fcd16c8240c2..0a8d5fa25326 100644
--- a/qiskit/circuit/library/standard_gates/rz.py
+++ b/qiskit/circuit/library/standard_gates/rz.py
@@ -137,7 +137,7 @@ def __array__(self, dtype=None):
         ilam2 = 0.5j * float(self.params[0])
         return np.array([[exp(-ilam2), 0], [0, exp(ilam2)]], dtype=dtype)
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return RZGate(exponent * theta)
diff --git a/qiskit/circuit/library/standard_gates/rzx.py b/qiskit/circuit/library/standard_gates/rzx.py
index 42ba9158db0f..c3de703c350b 100644
--- a/qiskit/circuit/library/standard_gates/rzx.py
+++ b/qiskit/circuit/library/standard_gates/rzx.py
@@ -178,7 +178,7 @@ def __array__(self, dtype=None):
             dtype=dtype,
         )
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return RZXGate(exponent * theta)
diff --git a/qiskit/circuit/library/standard_gates/rzz.py b/qiskit/circuit/library/standard_gates/rzz.py
index 01cd1da199ea..419aae1d862e 100644
--- a/qiskit/circuit/library/standard_gates/rzz.py
+++ b/qiskit/circuit/library/standard_gates/rzz.py
@@ -145,7 +145,7 @@ def __array__(self, dtype=None):
             dtype=dtype,
         )
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         (theta,) = self.params
         return RZZGate(exponent * theta)
diff --git a/qiskit/circuit/library/standard_gates/s.py b/qiskit/circuit/library/standard_gates/s.py
index 5014e948f888..f17bea58ca49 100644
--- a/qiskit/circuit/library/standard_gates/s.py
+++ b/qiskit/circuit/library/standard_gates/s.py
@@ -94,7 +94,7 @@ def inverse(self, annotated: bool = False):
         """
         return SdgGate()
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         from .p import PhaseGate
 
@@ -172,7 +172,7 @@ def inverse(self, annotated: bool = False):
         """
         return SGate()
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         from .p import PhaseGate
 
@@ -259,7 +259,7 @@ def inverse(self, annotated: bool = False):
         """
         return CSdgGate(ctrl_state=self.ctrl_state)
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         from .p import CPhaseGate
 
@@ -345,7 +345,7 @@ def inverse(self, annotated: bool = False):
         """
         return CSGate(ctrl_state=self.ctrl_state)
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         from .p import CPhaseGate
 
diff --git a/qiskit/circuit/library/standard_gates/t.py b/qiskit/circuit/library/standard_gates/t.py
index 3ae47035e7b0..cf294ac58942 100644
--- a/qiskit/circuit/library/standard_gates/t.py
+++ b/qiskit/circuit/library/standard_gates/t.py
@@ -92,7 +92,7 @@ def inverse(self, annotated: bool = False):
         """
         return TdgGate()
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         return PhaseGate(0.25 * numpy.pi * exponent)
 
@@ -168,7 +168,7 @@ def inverse(self, annotated: bool = False):
         """
         return TGate()
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         return PhaseGate(-0.25 * numpy.pi * exponent)
 
diff --git a/qiskit/circuit/library/standard_gates/xx_minus_yy.py b/qiskit/circuit/library/standard_gates/xx_minus_yy.py
index 2bdb32ad3c2b..44fcf2a9988c 100644
--- a/qiskit/circuit/library/standard_gates/xx_minus_yy.py
+++ b/qiskit/circuit/library/standard_gates/xx_minus_yy.py
@@ -184,7 +184,7 @@ def __array__(self, dtype=complex):
             dtype=dtype,
         )
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         theta, beta = self.params
         return XXMinusYYGate(exponent * theta, beta)
diff --git a/qiskit/circuit/library/standard_gates/xx_plus_yy.py b/qiskit/circuit/library/standard_gates/xx_plus_yy.py
index 5b53d9861ebb..ea5ee31587fe 100644
--- a/qiskit/circuit/library/standard_gates/xx_plus_yy.py
+++ b/qiskit/circuit/library/standard_gates/xx_plus_yy.py
@@ -185,7 +185,7 @@ def __array__(self, dtype=complex):
             dtype=dtype,
         )
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         theta, beta = self.params
         return XXPlusYYGate(exponent * theta, beta)
diff --git a/qiskit/circuit/library/standard_gates/z.py b/qiskit/circuit/library/standard_gates/z.py
index ef078ddb1aa7..8009a8264e48 100644
--- a/qiskit/circuit/library/standard_gates/z.py
+++ b/qiskit/circuit/library/standard_gates/z.py
@@ -140,7 +140,7 @@ def inverse(self, annotated: bool = False):
         """
         return ZGate()  # self-inverse
 
-    def power(self, exponent: float):
+    def power(self, exponent: float, annotated: bool = False):
         """Raise gate to a power."""
         return PhaseGate(numpy.pi * exponent)
 
diff --git a/qiskit/circuit/quantumcircuit.py b/qiskit/circuit/quantumcircuit.py
index 1e83baa8f1b8..cdbcfdda5c22 100644
--- a/qiskit/circuit/quantumcircuit.py
+++ b/qiskit/circuit/quantumcircuit.py
@@ -777,26 +777,38 @@ def repeat(self, reps: int) -> "QuantumCircuit":
 
         return repeated_circ
 
-    def power(self, power: float, matrix_power: bool = False) -> "QuantumCircuit":
+    def power(
+        self, power: float, matrix_power: bool = False, annotated: bool = False
+    ) -> "QuantumCircuit":
         """Raise this circuit to the power of ``power``.
 
-        If ``power`` is a positive integer and ``matrix_power`` is ``False``, this implementation
-        defaults to calling ``repeat``. Otherwise, if the circuit is unitary, the matrix is
-        computed to calculate the matrix power.
+        If ``power`` is a positive integer and both ``matrix_power`` and ``annotated``
+        are ``False``, this implementation defaults to calling ``repeat``. Otherwise,
+        the circuit is converted into a gate, and a new circuit, containing this gate
+        raised to the given power, is returned. The gate raised to the given power is
+        implemented either as a unitary gate if ``annotated`` is ``False`` or as an
+        annotated operation if ``annotated`` is ``True``.
 
         Args:
             power (float): The power to raise this circuit to.
-            matrix_power (bool): If True, the circuit is converted to a matrix and then the
-                matrix power is computed. If False, and ``power`` is a positive integer,
-                the implementation defaults to ``repeat``.
+            matrix_power (bool): indicates whether the inner power gate can be implemented
+                as a unitary gate.
+            annotated (bool): indicates whether the inner power gate can be implemented
+                as an annotated operation.
 
         Raises:
-            CircuitError: If the circuit needs to be converted to a gate but it is not unitary.
+            CircuitError: If the circuit needs to be converted to a unitary gate, but is
+                not unitary.
 
         Returns:
             QuantumCircuit: A circuit implementing this circuit raised to the power of ``power``.
         """
-        if power >= 0 and isinstance(power, (int, np.integer)) and not matrix_power:
+        if (
+            power >= 0
+            and isinstance(power, (int, np.integer))
+            and not matrix_power
+            and not annotated
+        ):
             return self.repeat(power)
 
         # attempt conversion to gate
@@ -812,12 +824,12 @@ def power(self, power: float, matrix_power: bool = False) -> "QuantumCircuit":
         except QiskitError as ex:
             raise CircuitError(
                 "The circuit contains non-unitary operations and cannot be "
-                "controlled. Note that no qiskit.circuit.Instruction objects may "
-                "be in the circuit for this operation."
+                "raised to a power. Note that no qiskit.circuit.Instruction "
+                "objects may be in the circuit for this operation."
             ) from ex
 
         power_circuit = QuantumCircuit(self.qubits, self.clbits, *self.qregs, *self.cregs)
-        power_circuit.append(gate.power(power), list(range(gate.num_qubits)))
+        power_circuit.append(gate.power(power, annotated=annotated), list(range(gate.num_qubits)))
         return power_circuit
 
     def control(
diff --git a/test/python/circuit/test_annotated_operation.py b/test/python/circuit/test_annotated_operation.py
index e26d3f845e79..f4228fc0485f 100644
--- a/test/python/circuit/test_annotated_operation.py
+++ b/test/python/circuit/test_annotated_operation.py
@@ -27,7 +27,7 @@
 from test import QiskitTestCase  # pylint: disable=wrong-import-order
 
 
-class TestAnnotatedOperationlass(QiskitTestCase):
+class TestAnnotatedOperationClass(QiskitTestCase):
     """Testing qiskit.circuit.AnnotatedOperation"""
 
     def test_create_gate_with_modifier(self):
diff --git a/test/python/circuit/test_circuit_operations.py b/test/python/circuit/test_circuit_operations.py
index 61108ed03b2e..483224196798 100644
--- a/test/python/circuit/test_circuit_operations.py
+++ b/test/python/circuit/test_circuit_operations.py
@@ -19,7 +19,7 @@
 from ddt import data, ddt
 
 from qiskit import ClassicalRegister, QuantumCircuit, QuantumRegister
-from qiskit.circuit import Gate, Instruction, Measure, Parameter, Barrier
+from qiskit.circuit import Gate, Instruction, Measure, Parameter, Barrier, AnnotatedOperation
 from qiskit.circuit.bit import Bit
 from qiskit.circuit.classical import expr, types
 from qiskit.circuit.classicalregister import Clbit
@@ -1013,6 +1013,21 @@ def test_power(self):
         with self.subTest("negative power"):
             self.assertEqual(qc.power(-2).data[0].operation, gate.power(-2))
 
+        with self.subTest("integer circuit power via annotation"):
+            power_qc = qc.power(4, annotated=True)
+            self.assertIsInstance(power_qc[0].operation, AnnotatedOperation)
+            self.assertEqual(Operator(power_qc), Operator(qc).power(4))
+
+        with self.subTest("float circuit power via annotation"):
+            power_qc = qc.power(1.5, annotated=True)
+            self.assertIsInstance(power_qc[0].operation, AnnotatedOperation)
+            self.assertEqual(Operator(power_qc), Operator(qc).power(1.5))
+
+        with self.subTest("negative circuit power via annotation"):
+            power_qc = qc.power(-2, annotated=True)
+            self.assertIsInstance(power_qc[0].operation, AnnotatedOperation)
+            self.assertEqual(Operator(power_qc), Operator(qc).power(-2))
+
     def test_power_parameterized_circuit(self):
         """Test taking a parameterized circuit to a power."""
         theta = Parameter("th")
diff --git a/test/python/circuit/test_gate_power.py b/test/python/circuit/test_gate_power.py
index 2dea1242ecaf..918a736c415d 100644
--- a/test/python/circuit/test_gate_power.py
+++ b/test/python/circuit/test_gate_power.py
@@ -20,7 +20,7 @@
 import scipy.linalg
 from ddt import data, ddt, unpack
 
-from qiskit.circuit import Gate, QuantumCircuit
+from qiskit.circuit import Gate, QuantumCircuit, AnnotatedOperation
 from qiskit.circuit.library import (
     CPhaseGate,
     CSdgGate,
@@ -45,6 +45,7 @@
     XXPlusYYGate,
     ZGate,
     iSwapGate,
+    SwapGate,
 )
 from qiskit.quantum_info.operators import Operator
 from test import QiskitTestCase  # pylint: disable=wrong-import-order
@@ -260,5 +261,28 @@ def test_efficient_gate_powering(self, gate: Gate, output_gate_type: Type[Gate])
             np.testing.assert_allclose(np.array(result), expected, atol=1e-8)
 
 
+@ddt
+class TestPowerAnnotatedGate(QiskitTestCase):
+    """Test raising gates to power using ``annotated`` argument."""
+
+    def test_s_gate(self):
+        """Test raising SGate to a power. Since SGate has an efficient ``power``
+        method, the result should not be an annotated operation.
+        """
+        result = SGate().power(1.5, annotated=True)
+        self.assertNotIsInstance(result, AnnotatedOperation)
+
+    def test_swap_gate(self):
+        """Test raising SwapGate to a power using different methods."""
+        # SwapGate has no native power method.
+        result1 = SwapGate().power(1.5, annotated=True)
+        self.assertIsInstance(result1, AnnotatedOperation)
+
+        result2 = SwapGate().power(1.5, annotated=False)
+        self.assertIsInstance(result2, UnitaryGate)
+
+        self.assertEqual(Operator(result1), Operator(result2))
+
+
 if __name__ == "__main__":
     unittest.main()

From b1679d023399f6d2b002b595a81bef3257de56e7 Mon Sep 17 00:00:00 2001
From: AlexanderIvrii <alexi@il.ibm.com>
Date: Fri, 29 Mar 2024 13:48:31 +0300
Subject: [PATCH 2/3] release notes

---
 ...nnotated-arg-to-power-4afe90e89fa50f5a.yaml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 releasenotes/notes/add-annotated-arg-to-power-4afe90e89fa50f5a.yaml

diff --git a/releasenotes/notes/add-annotated-arg-to-power-4afe90e89fa50f5a.yaml b/releasenotes/notes/add-annotated-arg-to-power-4afe90e89fa50f5a.yaml
new file mode 100644
index 000000000000..95537833b6d4
--- /dev/null
+++ b/releasenotes/notes/add-annotated-arg-to-power-4afe90e89fa50f5a.yaml
@@ -0,0 +1,18 @@
+---
+features:
+  - |
+    The methods :meth:`~qiskit.circuit.QuantumCircuit.power`,
+    :meth:`~qiskit.circuit.Gate.power`, as well as the similar methods
+    of subclasses of :class:`~qiskit.circuit.Gate`
+    (such as of :class:`~qiskit.circuit.library.SGate`) all have an additional
+    argument ``annotated``.
+    The default value of ``False`` corresponds to the existing behavior.
+    Furthermore, for standard gates with an explicitly defined ``power`` method,
+    the argument ``annotated`` has no effect, for example both
+    ``SGate().power(1.5, annotated=False)`` and ``SGate().power(1.5, annotated=True)``
+    return a ``PhaseGate``.
+    The difference manifests for gates without an explicitly defined
+    power method. The value of ``False`` returns a
+    :class:`~.library.UnitaryGate`, just as before, while the value of ``True``
+    returns an :class:`~.AnnotatedOperation` that represents the instruction
+    modified with the "power modifier".

From 735e986d95da3ec785345206619a24944b304ef3 Mon Sep 17 00:00:00 2001
From: Matthew Treinish <mtreinish@kortar.org>
Date: Tue, 23 Apr 2024 13:46:00 -0400
Subject: [PATCH 3/3] Apply suggestions from code review

---
 qiskit/circuit/gate.py                               | 9 +++++++--
 qiskit/circuit/library/standard_gates/i.py           | 1 -
 qiskit/circuit/library/standard_gates/iswap.py       | 1 -
 qiskit/circuit/library/standard_gates/p.py           | 2 --
 qiskit/circuit/library/standard_gates/r.py           | 1 -
 qiskit/circuit/library/standard_gates/rx.py          | 1 -
 qiskit/circuit/library/standard_gates/rxx.py         | 1 -
 qiskit/circuit/library/standard_gates/ry.py          | 1 -
 qiskit/circuit/library/standard_gates/ryy.py         | 1 -
 qiskit/circuit/library/standard_gates/rz.py          | 1 -
 qiskit/circuit/library/standard_gates/rzx.py         | 1 -
 qiskit/circuit/library/standard_gates/rzz.py         | 1 -
 qiskit/circuit/library/standard_gates/s.py           | 4 ----
 qiskit/circuit/library/standard_gates/t.py           | 2 --
 qiskit/circuit/library/standard_gates/xx_minus_yy.py | 1 -
 qiskit/circuit/library/standard_gates/xx_plus_yy.py  | 1 -
 qiskit/circuit/library/standard_gates/z.py           | 1 -
 17 files changed, 7 insertions(+), 23 deletions(-)

diff --git a/qiskit/circuit/gate.py b/qiskit/circuit/gate.py
index 82038b5327ac..132526775860 100644
--- a/qiskit/circuit/gate.py
+++ b/qiskit/circuit/gate.py
@@ -66,12 +66,17 @@ def power(self, exponent: float, annotated: bool = False):
         """Raise this gate to the power of ``exponent``.
 
         Implemented either as a unitary gate (ref. :class:`~.library.UnitaryGate`)
-        or as an annotated operation (ref. :class:`.AnnotatedOperation`).
+        or as an annotated operation (ref. :class:`.AnnotatedOperation`). In the case of several standard
+        gates, such as :class:`.RXGate`, when the power of a gate can be expressed in terms of another
+        standard gate that is returned directly.
 
         Args:
             exponent (float): the power to raise the gate to
             annotated (bool): indicates whether the power gate can be implemented
-                as an annotated operation.
+                as an annotated operation. In the case of several standard
+                gates, such as :class:`.RXGate`, this argument is ignored when
+                the power of a gate can be expressed in terms of another
+                standard gate.
 
         Returns:
             An operation implementing ``gate^exponent``
diff --git a/qiskit/circuit/library/standard_gates/i.py b/qiskit/circuit/library/standard_gates/i.py
index 7af7a2bb93a4..93523215d6f0 100644
--- a/qiskit/circuit/library/standard_gates/i.py
+++ b/qiskit/circuit/library/standard_gates/i.py
@@ -66,7 +66,6 @@ def inverse(self, annotated: bool = False):
         return IGate()  # self-inverse
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         return IGate()
 
     def __eq__(self, other):
diff --git a/qiskit/circuit/library/standard_gates/iswap.py b/qiskit/circuit/library/standard_gates/iswap.py
index fce9e8e53f89..50d3a6bb3473 100644
--- a/qiskit/circuit/library/standard_gates/iswap.py
+++ b/qiskit/circuit/library/standard_gates/iswap.py
@@ -125,7 +125,6 @@ def _define(self):
         self.definition = qc
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         return XXPlusYYGate(-np.pi * exponent)
 
     def __eq__(self, other):
diff --git a/qiskit/circuit/library/standard_gates/p.py b/qiskit/circuit/library/standard_gates/p.py
index 54143b63f42f..94d5d3e347d2 100644
--- a/qiskit/circuit/library/standard_gates/p.py
+++ b/qiskit/circuit/library/standard_gates/p.py
@@ -146,7 +146,6 @@ def __array__(self, dtype=None):
         return numpy.array([[1, 0], [0, exp(1j * lam)]], dtype=dtype)
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return PhaseGate(exponent * theta)
 
@@ -290,7 +289,6 @@ def __array__(self, dtype=None):
         return numpy.array([[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, eith, 0], [0, 0, 0, 1]], dtype=dtype)
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return CPhaseGate(exponent * theta)
 
diff --git a/qiskit/circuit/library/standard_gates/r.py b/qiskit/circuit/library/standard_gates/r.py
index 2d8027f9a68a..3fc537baef90 100644
--- a/qiskit/circuit/library/standard_gates/r.py
+++ b/qiskit/circuit/library/standard_gates/r.py
@@ -103,7 +103,6 @@ def __array__(self, dtype=None):
         return numpy.array([[cos, -1j * exp_m * sin], [-1j * exp_p * sin, cos]], dtype=dtype)
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         theta, phi = self.params
         return RGate(exponent * theta, phi)
 
diff --git a/qiskit/circuit/library/standard_gates/rx.py b/qiskit/circuit/library/standard_gates/rx.py
index 6d5c003a4d06..3483d5ebc956 100644
--- a/qiskit/circuit/library/standard_gates/rx.py
+++ b/qiskit/circuit/library/standard_gates/rx.py
@@ -127,7 +127,6 @@ def __array__(self, dtype=None):
         return numpy.array([[cos, -1j * sin], [-1j * sin, cos]], dtype=dtype)
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return RXGate(exponent * theta)
 
diff --git a/qiskit/circuit/library/standard_gates/rxx.py b/qiskit/circuit/library/standard_gates/rxx.py
index 825e4607c789..03e9d22dcc24 100644
--- a/qiskit/circuit/library/standard_gates/rxx.py
+++ b/qiskit/circuit/library/standard_gates/rxx.py
@@ -133,7 +133,6 @@ def __array__(self, dtype=None):
         )
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return RXXGate(exponent * theta)
 
diff --git a/qiskit/circuit/library/standard_gates/ry.py b/qiskit/circuit/library/standard_gates/ry.py
index 57c46960f5c8..b902887ee0e0 100644
--- a/qiskit/circuit/library/standard_gates/ry.py
+++ b/qiskit/circuit/library/standard_gates/ry.py
@@ -126,7 +126,6 @@ def __array__(self, dtype=None):
         return numpy.array([[cos, -sin], [sin, cos]], dtype=dtype)
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return RYGate(exponent * theta)
 
diff --git a/qiskit/circuit/library/standard_gates/ryy.py b/qiskit/circuit/library/standard_gates/ryy.py
index 20a6bdadd218..50ce9b0c4f73 100644
--- a/qiskit/circuit/library/standard_gates/ryy.py
+++ b/qiskit/circuit/library/standard_gates/ryy.py
@@ -133,7 +133,6 @@ def __array__(self, dtype=None):
         )
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return RYYGate(exponent * theta)
 
diff --git a/qiskit/circuit/library/standard_gates/rz.py b/qiskit/circuit/library/standard_gates/rz.py
index 0a8d5fa25326..c7311b4a6e59 100644
--- a/qiskit/circuit/library/standard_gates/rz.py
+++ b/qiskit/circuit/library/standard_gates/rz.py
@@ -138,7 +138,6 @@ def __array__(self, dtype=None):
         return np.array([[exp(-ilam2), 0], [0, exp(ilam2)]], dtype=dtype)
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return RZGate(exponent * theta)
 
diff --git a/qiskit/circuit/library/standard_gates/rzx.py b/qiskit/circuit/library/standard_gates/rzx.py
index c3de703c350b..d59676663da1 100644
--- a/qiskit/circuit/library/standard_gates/rzx.py
+++ b/qiskit/circuit/library/standard_gates/rzx.py
@@ -179,7 +179,6 @@ def __array__(self, dtype=None):
         )
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return RZXGate(exponent * theta)
 
diff --git a/qiskit/circuit/library/standard_gates/rzz.py b/qiskit/circuit/library/standard_gates/rzz.py
index 419aae1d862e..3a00fb7b7395 100644
--- a/qiskit/circuit/library/standard_gates/rzz.py
+++ b/qiskit/circuit/library/standard_gates/rzz.py
@@ -146,7 +146,6 @@ def __array__(self, dtype=None):
         )
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         (theta,) = self.params
         return RZZGate(exponent * theta)
 
diff --git a/qiskit/circuit/library/standard_gates/s.py b/qiskit/circuit/library/standard_gates/s.py
index f17bea58ca49..6fde1c6544e5 100644
--- a/qiskit/circuit/library/standard_gates/s.py
+++ b/qiskit/circuit/library/standard_gates/s.py
@@ -95,7 +95,6 @@ def inverse(self, annotated: bool = False):
         return SdgGate()
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         from .p import PhaseGate
 
         return PhaseGate(0.5 * numpy.pi * exponent)
@@ -173,7 +172,6 @@ def inverse(self, annotated: bool = False):
         return SGate()
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         from .p import PhaseGate
 
         return PhaseGate(-0.5 * numpy.pi * exponent)
@@ -260,7 +258,6 @@ def inverse(self, annotated: bool = False):
         return CSdgGate(ctrl_state=self.ctrl_state)
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         from .p import CPhaseGate
 
         return CPhaseGate(0.5 * numpy.pi * exponent)
@@ -346,7 +343,6 @@ def inverse(self, annotated: bool = False):
         return CSGate(ctrl_state=self.ctrl_state)
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         from .p import CPhaseGate
 
         return CPhaseGate(-0.5 * numpy.pi * exponent)
diff --git a/qiskit/circuit/library/standard_gates/t.py b/qiskit/circuit/library/standard_gates/t.py
index cf294ac58942..87a38d9d44c1 100644
--- a/qiskit/circuit/library/standard_gates/t.py
+++ b/qiskit/circuit/library/standard_gates/t.py
@@ -93,7 +93,6 @@ def inverse(self, annotated: bool = False):
         return TdgGate()
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         return PhaseGate(0.25 * numpy.pi * exponent)
 
     def __eq__(self, other):
@@ -169,7 +168,6 @@ def inverse(self, annotated: bool = False):
         return TGate()
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         return PhaseGate(-0.25 * numpy.pi * exponent)
 
     def __eq__(self, other):
diff --git a/qiskit/circuit/library/standard_gates/xx_minus_yy.py b/qiskit/circuit/library/standard_gates/xx_minus_yy.py
index 44fcf2a9988c..387a23ad058a 100644
--- a/qiskit/circuit/library/standard_gates/xx_minus_yy.py
+++ b/qiskit/circuit/library/standard_gates/xx_minus_yy.py
@@ -185,7 +185,6 @@ def __array__(self, dtype=complex):
         )
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         theta, beta = self.params
         return XXMinusYYGate(exponent * theta, beta)
 
diff --git a/qiskit/circuit/library/standard_gates/xx_plus_yy.py b/qiskit/circuit/library/standard_gates/xx_plus_yy.py
index ea5ee31587fe..b69ba49de30d 100644
--- a/qiskit/circuit/library/standard_gates/xx_plus_yy.py
+++ b/qiskit/circuit/library/standard_gates/xx_plus_yy.py
@@ -186,7 +186,6 @@ def __array__(self, dtype=complex):
         )
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         theta, beta = self.params
         return XXPlusYYGate(exponent * theta, beta)
 
diff --git a/qiskit/circuit/library/standard_gates/z.py b/qiskit/circuit/library/standard_gates/z.py
index 8009a8264e48..2b69595936d8 100644
--- a/qiskit/circuit/library/standard_gates/z.py
+++ b/qiskit/circuit/library/standard_gates/z.py
@@ -141,7 +141,6 @@ def inverse(self, annotated: bool = False):
         return ZGate()  # self-inverse
 
     def power(self, exponent: float, annotated: bool = False):
-        """Raise gate to a power."""
         return PhaseGate(numpy.pi * exponent)
 
     def __eq__(self, other):