From 0d9f0559a1a2713e054189ff64901ab5d7422db4 Mon Sep 17 00:00:00 2001
From: Yaroslav Kharkov <ykharkov@amazon.com>
Date: Mon, 23 Oct 2023 11:31:53 -0400
Subject: [PATCH 01/11] Add matrix expressions to docstrings

---
 src/braket/circuits/gates.py | 262 +++++++++++++++++++++++++++++++++++
 1 file changed, 262 insertions(+)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index dbc2e1a0b..28cdd203f 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -109,6 +109,12 @@ def h(
         Returns:
             Iterable[Instruction]: `Iterable` of H instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{h} = \frac{1}{\sqrt{2}}\begin{bmatrix}
+                1 & 1 \\
+                1 & -1
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().h(0)
             >>> circ = Circuit().h([0, 1, 2])
@@ -174,6 +180,12 @@ def i(
         Returns:
             Iterable[Instruction]: `Iterable` of I instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{I} = \begin{bmatrix}
+                1 & 0 \\
+                0 & 1
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().i(0)
             >>> circ = Circuit().i([0, 1, 2])
@@ -239,6 +251,12 @@ def x(
         Returns:
             Iterable[Instruction]: `Iterable` of X instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{X} = \begin{bmatrix}
+                0 & 1 \\
+                1 & 0
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().x(0)
             >>> circ = Circuit().x([0, 1, 2])
@@ -304,6 +322,12 @@ def y(
         Returns:
             Iterable[Instruction]: `Iterable` of Y instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{Y} = \begin{bmatrix}
+                0 & -i \\
+                i & 0
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().y(0)
             >>> circ = Circuit().y([0, 1, 2])
@@ -369,6 +393,12 @@ def z(
         Returns:
             Iterable[Instruction]: `Iterable` of Z instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{X} = \begin{bmatrix}
+                1 & 0 \\
+                0 & -1
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().z(0)
             >>> circ = Circuit().z([0, 1, 2])
@@ -434,6 +464,12 @@ def s(
         Returns:
             Iterable[Instruction]: `Iterable` of S instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{S} = \begin{bmatrix}
+                1 & 0 \\
+                0 & i
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().s(0)
             >>> circ = Circuit().s([0, 1, 2])
@@ -499,6 +535,12 @@ def si(
         Returns:
             Iterable[Instruction]: Iterable of Si instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{S}^\dag = \begin{bmatrix}
+                1 & 0 \\
+                0 & -i
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().si(0)
             >>> circ = Circuit().si([0, 1, 2])
@@ -564,6 +606,12 @@ def t(
         Returns:
             Iterable[Instruction]: `Iterable` of T instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{T} = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{i \pi/4}
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().t(0)
             >>> circ = Circuit().t([0, 1, 2])
@@ -629,6 +677,12 @@ def ti(
         Returns:
             Iterable[Instruction]: `Iterable` of Ti instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{T}^\dag = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{-i \pi/4}
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().ti(0)
             >>> circ = Circuit().ti([0, 1, 2])
@@ -694,6 +748,12 @@ def v(
         Returns:
             Iterable[Instruction]: `Iterable` of V instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{V} = \frac{1}{2}\begin{bmatrix}
+                1+i & 1-i \\
+                1-i & 1+i
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().v(0)
             >>> circ = Circuit().v([0, 1, 2])
@@ -759,6 +819,12 @@ def vi(
         Returns:
             Iterable[Instruction]: `Iterable` of Vi instructions.
 
+        Unitary matrix:
+        .. math:: \mathtt{V}^\dag = \frac{1}{2}\begin{bmatrix}
+                1-i & 1+i \\
+                1+i & 1-i
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().vi(0)
             >>> circ = Circuit().vi([0, 1, 2])
@@ -843,6 +909,12 @@ def rx(
         Returns:
             Iterable[Instruction]: Rx instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{R_x}(\theta) = \begin{bmatrix}
+                \cos{\theta/2} & -i \sin{\theta/2} \\
+                -i \sin{\theta/2} & \cos{\theta/2}
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().rx(0, 0.15)
         """
@@ -923,6 +995,12 @@ def ry(
         Returns:
             Iterable[Instruction]: Rx instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{R_y}(\theta) = \begin{bmatrix}
+                \cos{\theta/2} & -\sin{\theta/2} \\
+                \sin{\theta/2} & \cos{\theta/2}
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().ry(0, 0.15)
         """
@@ -999,6 +1077,12 @@ def rz(
         Returns:
             Iterable[Instruction]: Rx instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{R_z}(\phi) = \begin{bmatrix}
+                e^{-i \phi/2} & 0 \\
+                0 & e^{i \phi/2}
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().rz(0, 0.15)
         """
@@ -1073,6 +1157,12 @@ def phaseshift(
         Returns:
             Iterable[Instruction]: PhaseShift instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{phaseshift}(\phi) = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{i \phi}
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().phaseshift(0, 0.15)
         """
@@ -1141,6 +1231,14 @@ def cnot(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instru
         Returns:
             Instruction: CNot instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CNOT} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                0 & 0 & 1 & 0 \\
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().cnot(0, 1)
         """
@@ -1214,6 +1312,14 @@ def swap(
         Returns:
             Instruction: Swap instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{SWAP} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().swap(0, 1)
         """
@@ -1289,6 +1395,14 @@ def iswap(
         Returns:
             Instruction: ISwap instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{iSWAP} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & i & 0 \\
+                0 & i & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().iswap(0, 1)
         """
@@ -1377,6 +1491,14 @@ def pswap(
         Returns:
             Instruction: PSwap instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{PSWAP}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & e^{i \phi} & 0 \\
+                0 & e^{i \phi} & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().pswap(0, 1, 0.15)
         """
@@ -1473,6 +1595,14 @@ def xy(
         Returns:
             Instruction: XY instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{XY}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & \cos{\phi/2} & i\sin{\phi/2} & 0 \\
+                0 & i\sin{\phi/2} & \cos{\phi/2} & 0 \\
+                0 & 0 & 0 & 1 \\
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().xy(0, 1, 0.15)
         """
@@ -1541,6 +1671,14 @@ def cphaseshift(
         Returns:
             Instruction: CPhaseShift instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CPhaseShift00}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & e^{i \phi}
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().cphaseshift(0, 1, 0.15)
         """
@@ -1610,6 +1748,14 @@ def cphaseshift00(
         Returns:
             Instruction: CPhaseShift00 instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CPhaseShift01}(\phi) = \begin{bmatrix}
+                e^{i \phi} & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 1
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().cphaseshift00(0, 1, 0.15)
         """
@@ -1679,6 +1825,14 @@ def cphaseshift01(
         Returns:
             Instruction: CPhaseShift01 instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CPhaseShift01}(\phi) = \begin{bmatrix}
+                e^{i \phi} & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 1
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().cphaseshift01(0, 1, 0.15)
         """
@@ -1748,6 +1902,14 @@ def cphaseshift10(
         Returns:
             Instruction: CPhaseShift10 instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CPhaseShift10}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & e^{i \phi} & 0 \\
+                0 & 0 & 0 & 1
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().cphaseshift10(0, 1, 0.15)
         """
@@ -1811,6 +1973,14 @@ def cv(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
         Returns:
             Instruction: CV instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CV}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0.5+0.5i & 0.5-0.5i \\
+                0 & 0 & 0.5-0.5i & 0.5+0.5i
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().cv(0, 1)
         """
@@ -1871,6 +2041,14 @@ def cy(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
         Returns:
             Instruction: CY instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CY} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & -i \\
+                0 & 0 & i & 0
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().cy(0, 1)
         """
@@ -1923,6 +2101,14 @@ def cz(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
         Returns:
             Instruction: CZ instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CY} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & -1
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().cz(0, 1)
         """
@@ -1995,6 +2181,14 @@ def ecr(
         Returns:
             Instruction: ECR instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{ECR} = \begin{bmatrix}
+                0 & 0 & 1 & i \\
+                0 & 0 & i & 1 \\
+                1 & -i & 0 & 0 \\
+                -i & 1 & 0 & 0
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().ecr(0, 1)
         """
@@ -2091,6 +2285,14 @@ def xx(
         Returns:
             Instruction: XX instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{XX}(\phi) = \begin{bmatrix}
+                \cos{\phi/2} & 0 & 0 & -i \sin{\phi/2} \\
+                0 & \cos{\phi/2} & -i \sin{\phi/2} & 0 \\
+                0 & -i \sin{\phi/2} & \cos{\phi/2} & 0 \\
+                -i \sin{\phi/2} & 0 & 0 & \cos{\phi/2}
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().xx(0, 1, 0.15)
         """
@@ -2187,6 +2389,14 @@ def yy(
         Returns:
             Instruction: YY instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{YY}(\phi) = \begin{bmatrix}
+                \cos{\phi/2} & 0 & 0 & i \sin{\phi/2} \\
+                0 & \cos{\phi/2} & -i \sin{\phi/2} & 0 \\
+                0 & -i \sin{\phi/2} & \cos{\phi/2} & 0 \\
+                i \sin{\phi/2} & 0 & 0 & \cos{\phi/2}
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().yy(0, 1, 0.15)
         """
@@ -2277,6 +2487,14 @@ def zz(
         Returns:
             Instruction: ZZ instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{ZZ}(\phi) = \begin{bmatrix}
+                e^{-i\phi/2} & 0 & 0 & 0 \\
+                0 & e^{i\phi/2} & 0 & 0 \\
+                0 & 0 & e^{i\phi/2} & 0 \\
+                0 & 0 & 0 & e^{-i\phi/2}
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().zz(0, 1, 0.15)
         """
@@ -2363,6 +2581,18 @@ def ccnot(
         Returns:
             Instruction: CCNot instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CCNOT} = \begin{bmatrix}
+                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
+                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().ccnot(0, 1, 2)
         """
@@ -2435,6 +2665,18 @@ def cswap(
         Returns:
             Instruction: CSwap instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{CCNOT} = \begin{bmatrix}
+                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
+                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().cswap(0, 1, 2)
         """
@@ -2516,6 +2758,12 @@ def gpi(
         Returns:
             Iterable[Instruction]: GPi instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{GPi}(\phi) = \begin{bmatrix}
+                0 & e^{-i \phi} \\
+                e^{i \phi} & 0
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().gpi(0, 0.15)
         """
@@ -2595,6 +2843,12 @@ def gpi2(
         Returns:
             Iterable[Instruction]: GPi2 instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{GPi2}(\phi) = \begin{bmatrix}
+                1 & -i e^{-i \phi} \\
+                -i e^{i \phi} & 1
+            \end{bmatrix}.
+            
         Examples:
             >>> circ = Circuit().gpi2(0, 0.15)
         """
@@ -2711,6 +2965,14 @@ def ms(
         Returns:
             Iterable[Instruction]: MS instruction.
 
+        Unitary matrix:
+        .. math:: \mathtt{MS}(\phi_0, \phi_1) = \frac{1}{\sqrt{2}}\begin{bmatrix}
+                1 & 0 & 0 & -ie^{-i (\phi_0 + \phi_1)} \\
+                0 & 1 & -ie^{-i (\phi_0 - \phi_1)} & 0 \\
+                0 & -ie^{i (\phi_0 - \phi_1)} & 1 & 0 \\
+                -ie^{i (\phi_0 + \phi_1)} & 0 & 0 & 1
+            \end{bmatrix}.
+
         Examples:
             >>> circ = Circuit().ms(0, 1, 0.15, 0.34)
         """

From 1a02a30785dc3c1246641e7a15396b09a19c68fa Mon Sep 17 00:00:00 2001
From: Yaroslav Kharkov <ykharkov@amazon.com>
Date: Mon, 23 Oct 2023 13:08:24 -0400
Subject: [PATCH 02/11] linter

---
 src/braket/circuits/gates.py | 623 ++++++++++++++++++-----------------
 1 file changed, 324 insertions(+), 299 deletions(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index 28cdd203f..1ea905c35 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -60,7 +60,13 @@
 
 
 class H(Gate):
-    """Hadamard gate."""
+    r"""Hadamard gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{h} = \frac{1}{\sqrt{2}} \begin{bmatrix}
+                1 & 1 \\
+                1 & -1 \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["H"])
@@ -91,7 +97,7 @@ def h(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -109,12 +115,6 @@ def h(
         Returns:
             Iterable[Instruction]: `Iterable` of H instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{h} = \frac{1}{\sqrt{2}}\begin{bmatrix}
-                1 & 1 \\
-                1 & -1
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().h(0)
             >>> circ = Circuit().h([0, 1, 2])
@@ -131,7 +131,13 @@ def h(
 
 
 class I(Gate):  # noqa: E742, E261
-    """Identity gate."""
+    r"""Identity gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{I} = \begin{bmatrix}
+                1 & 0 \\
+                0 & 1 \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["I"])
@@ -162,7 +168,7 @@ def i(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -180,12 +186,6 @@ def i(
         Returns:
             Iterable[Instruction]: `Iterable` of I instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{I} = \begin{bmatrix}
-                1 & 0 \\
-                0 & 1
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().i(0)
             >>> circ = Circuit().i([0, 1, 2])
@@ -202,7 +202,14 @@ def i(
 
 
 class X(Gate):
-    """Pauli-X gate."""
+    r"""Pauli-X gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{X} = \begin{bmatrix}
+                0 & 1 \\
+                1 & 0
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["X"])
@@ -251,12 +258,6 @@ def x(
         Returns:
             Iterable[Instruction]: `Iterable` of X instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{X} = \begin{bmatrix}
-                0 & 1 \\
-                1 & 0
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().x(0)
             >>> circ = Circuit().x([0, 1, 2])
@@ -273,7 +274,14 @@ def x(
 
 
 class Y(Gate):
-    """Pauli-Y gate."""
+    r"""Pauli-Y gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{Y} = \begin{bmatrix}
+                0 & -i \\
+                i & 0
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["Y"])
@@ -322,12 +330,6 @@ def y(
         Returns:
             Iterable[Instruction]: `Iterable` of Y instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{Y} = \begin{bmatrix}
-                0 & -i \\
-                i & 0
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().y(0)
             >>> circ = Circuit().y([0, 1, 2])
@@ -344,7 +346,14 @@ def y(
 
 
 class Z(Gate):
-    """Pauli-Z gate."""
+    r"""Pauli-Z gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{Z} = \begin{bmatrix}
+                1 & 0 \\
+                0 & -1
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["Z"])
@@ -393,12 +402,6 @@ def z(
         Returns:
             Iterable[Instruction]: `Iterable` of Z instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{X} = \begin{bmatrix}
-                1 & 0 \\
-                0 & -1
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().z(0)
             >>> circ = Circuit().z([0, 1, 2])
@@ -415,7 +418,14 @@ def z(
 
 
 class S(Gate):
-    """S gate."""
+    r"""S gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{S} = \begin{bmatrix}
+                1 & 0 \\
+                0 & i
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["S"])
@@ -464,12 +474,6 @@ def s(
         Returns:
             Iterable[Instruction]: `Iterable` of S instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{S} = \begin{bmatrix}
-                1 & 0 \\
-                0 & i
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().s(0)
             >>> circ = Circuit().s([0, 1, 2])
@@ -486,7 +490,14 @@ def s(
 
 
 class Si(Gate):
-    """Conjugate transpose of S gate."""
+    r"""Conjugate transpose of S gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{S}^\dagger = \begin{bmatrix}
+                1 & 0 \\
+                0 & -i
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["Si"])
@@ -535,12 +546,6 @@ def si(
         Returns:
             Iterable[Instruction]: Iterable of Si instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{S}^\dag = \begin{bmatrix}
-                1 & 0 \\
-                0 & -i
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().si(0)
             >>> circ = Circuit().si([0, 1, 2])
@@ -557,7 +562,14 @@ def si(
 
 
 class T(Gate):
-    """T gate."""
+    r"""T gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{T} = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{i \pi/4}
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["T"])
@@ -606,12 +618,6 @@ def t(
         Returns:
             Iterable[Instruction]: `Iterable` of T instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{T} = \begin{bmatrix}
-                1 & 0 \\
-                0 & e^{i \pi/4}
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().t(0)
             >>> circ = Circuit().t([0, 1, 2])
@@ -628,7 +634,14 @@ def t(
 
 
 class Ti(Gate):
-    """Conjugate transpose of T gate."""
+    r"""Conjugate transpose of T gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{T}^\dagger = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{-i \pi/4}
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["Ti"])
@@ -677,12 +690,6 @@ def ti(
         Returns:
             Iterable[Instruction]: `Iterable` of Ti instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{T}^\dag = \begin{bmatrix}
-                1 & 0 \\
-                0 & e^{-i \pi/4}
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().ti(0)
             >>> circ = Circuit().ti([0, 1, 2])
@@ -699,7 +706,14 @@ def ti(
 
 
 class V(Gate):
-    """Square root of not gate."""
+    r"""Square root of not gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{V} = \frac{1}{2}\begin{bmatrix}
+                1+i & 1-i \\
+                1-i & 1+i
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["V"])
@@ -748,12 +762,6 @@ def v(
         Returns:
             Iterable[Instruction]: `Iterable` of V instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{V} = \frac{1}{2}\begin{bmatrix}
-                1+i & 1-i \\
-                1-i & 1+i
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().v(0)
             >>> circ = Circuit().v([0, 1, 2])
@@ -770,7 +778,14 @@ def v(
 
 
 class Vi(Gate):
-    """Conjugate transpose of square root of not gate."""
+    r"""Conjugate transpose of square root of not gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{V}^\dagger = \frac{1}{2}\begin{bmatrix}
+                1-i & 1+i \\
+                1+i & 1-i
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["Vi"])
@@ -819,12 +834,6 @@ def vi(
         Returns:
             Iterable[Instruction]: `Iterable` of Vi instructions.
 
-        Unitary matrix:
-        .. math:: \mathtt{V}^\dag = \frac{1}{2}\begin{bmatrix}
-                1-i & 1+i \\
-                1+i & 1-i
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().vi(0)
             >>> circ = Circuit().vi([0, 1, 2])
@@ -844,7 +853,13 @@ def vi(
 
 
 class Rx(AngledGate):
-    """X-axis rotation gate.
+    r"""X-axis rotation gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{R_x}(\theta) = \begin{bmatrix}
+                \cos{(\theta/2)} & -i \sin{(\theta/2)} \\
+                -i \sin{(\theta/2)} & \cos{(\theta/2)}
+                \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -909,12 +924,6 @@ def rx(
         Returns:
             Iterable[Instruction]: Rx instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{R_x}(\theta) = \begin{bmatrix}
-                \cos{\theta/2} & -i \sin{\theta/2} \\
-                -i \sin{\theta/2} & \cos{\theta/2}
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().rx(0, 0.15)
         """
@@ -930,7 +939,13 @@ def rx(
 
 
 class Ry(AngledGate):
-    """Y-axis rotation gate.
+    r"""Y-axis rotation gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{R_y}(\theta) = \begin{bmatrix}
+                \cos{(\theta/2)} & -\sin{(\theta/2)} \\
+                \sin{(\theta/2)} & \cos{(\theta/2)}
+                \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -995,11 +1010,6 @@ def ry(
         Returns:
             Iterable[Instruction]: Rx instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{R_y}(\theta) = \begin{bmatrix}
-                \cos{\theta/2} & -\sin{\theta/2} \\
-                \sin{\theta/2} & \cos{\theta/2}
-            \end{bmatrix}.
 
         Examples:
             >>> circ = Circuit().ry(0, 0.15)
@@ -1016,7 +1026,13 @@ def ry(
 
 
 class Rz(AngledGate):
-    """Z-axis rotation gate.
+    r"""Z-axis rotation gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{R_z}(\phi) = \begin{bmatrix}
+                e^{-i \phi/2} & 0 \\
+                0 & e^{i \phi/2}
+                \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -1077,12 +1093,6 @@ def rz(
         Returns:
             Iterable[Instruction]: Rx instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{R_z}(\phi) = \begin{bmatrix}
-                e^{-i \phi/2} & 0 \\
-                0 & e^{i \phi/2}
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().rz(0, 0.15)
         """
@@ -1098,7 +1108,13 @@ def rz(
 
 
 class PhaseShift(AngledGate):
-    """Phase shift gate.
+    r"""Phase shift gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{PhaseShift}(\phi) = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{i \phi}
+                \end{bmatrix}
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -1157,12 +1173,6 @@ def phaseshift(
         Returns:
             Iterable[Instruction]: PhaseShift instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{phaseshift}(\phi) = \begin{bmatrix}
-                1 & 0 \\
-                0 & e^{i \phi}
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().phaseshift(0, 0.15)
         """
@@ -1185,7 +1195,16 @@ def phaseshift(
 
 
 class CNot(Gate):
-    """Controlled NOT gate."""
+    r"""Controlled NOT gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{CNOT} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                0 & 0 & 1 & 0 \\
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["C", "X"])
@@ -1231,14 +1250,6 @@ def cnot(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instru
         Returns:
             Instruction: CNot instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CNOT} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & 1 \\
-                0 & 0 & 1 & 0 \\
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().cnot(0, 1)
         """
@@ -1253,7 +1264,16 @@ def cnot(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instru
 
 
 class Swap(Gate):
-    """Swap gate."""
+    r"""Swap gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{SWAP} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["SWAP", "SWAP"])
@@ -1312,14 +1332,6 @@ def swap(
         Returns:
             Instruction: Swap instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{SWAP} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & 1 \\
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().swap(0, 1)
         """
@@ -1336,7 +1348,16 @@ def swap(
 
 
 class ISwap(Gate):
-    """ISwap gate."""
+    r"""ISwap gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{iSWAP} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & i & 0 \\
+                0 & i & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["ISWAP", "ISWAP"])
@@ -1395,14 +1416,6 @@ def iswap(
         Returns:
             Instruction: ISwap instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{iSWAP} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 0 & i & 0 \\
-                0 & i & 0 & 0 \\
-                0 & 0 & 0 & 1 \\
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().iswap(0, 1)
         """
@@ -1419,7 +1432,15 @@ def iswap(
 
 
 class PSwap(AngledGate):
-    """PSwap gate.
+    r"""PSwap gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{PSWAP}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & e^{i \phi} & 0 \\
+                0 & e^{i \phi} & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -1491,14 +1512,6 @@ def pswap(
         Returns:
             Instruction: PSwap instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{PSWAP}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 0 & e^{i \phi} & 0 \\
-                0 & e^{i \phi} & 0 & 0 \\
-                0 & 0 & 0 & 1 \\
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().pswap(0, 1, 0.15)
         """
@@ -1515,10 +1528,19 @@ def pswap(
 
 
 class XY(AngledGate):
-    """XY gate.
+    r"""XY gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{XY}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & \cos{(\phi/2)} & i\sin{(\phi/2)} & 0 \\
+                0 & i\sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
+                0 & 0 & 0 & 1 \\
+            \end{bmatrix}.
 
     Reference: https://arxiv.org/abs/1912.04424v1
 
+
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
     """
@@ -1595,14 +1617,6 @@ def xy(
         Returns:
             Instruction: XY instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{XY}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & \cos{\phi/2} & i\sin{\phi/2} & 0 \\
-                0 & i\sin{\phi/2} & \cos{\phi/2} & 0 \\
-                0 & 0 & 0 & 1 \\
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().xy(0, 1, 0.15)
         """
@@ -1619,7 +1633,15 @@ def xy(
 
 
 class CPhaseShift(AngledGate):
-    """Controlled phase shift gate.
+    r"""Controlled phase shift gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{CPhaseShift00}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & e^{i \phi}
+            \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -1671,14 +1693,6 @@ def cphaseshift(
         Returns:
             Instruction: CPhaseShift instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CPhaseShift00}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & e^{i \phi}
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().cphaseshift(0, 1, 0.15)
         """
@@ -1696,7 +1710,15 @@ def cphaseshift(
 
 
 class CPhaseShift00(AngledGate):
-    """Controlled phase shift gate for phasing the \\|00> state.
+    r"""Controlled phase shift gate for phasing the \|00> state.
+
+    Unitary matrix:
+        .. math:: \mathtt{CPhaseShift00}(\phi) = \begin{bmatrix}
+                e^{i \phi} & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 1
+                \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -1748,14 +1770,6 @@ def cphaseshift00(
         Returns:
             Instruction: CPhaseShift00 instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CPhaseShift01}(\phi) = \begin{bmatrix}
-                e^{i \phi} & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & 1
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().cphaseshift00(0, 1, 0.15)
         """
@@ -1773,7 +1787,15 @@ def cphaseshift00(
 
 
 class CPhaseShift01(AngledGate):
-    """Controlled phase shift gate for phasing the \\|01> state.
+    r"""Controlled phase shift gate for phasing the \|01> state.
+
+    Unitary matrix:
+        .. math:: \mathtt{CPhaseShift01}(\phi) = \begin{bmatrix}
+                e^{i \phi} & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 1
+            \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -1825,14 +1847,6 @@ def cphaseshift01(
         Returns:
             Instruction: CPhaseShift01 instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CPhaseShift01}(\phi) = \begin{bmatrix}
-                e^{i \phi} & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & 1
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().cphaseshift01(0, 1, 0.15)
         """
@@ -1850,7 +1864,15 @@ def cphaseshift01(
 
 
 class CPhaseShift10(AngledGate):
-    """Controlled phase shift gate for phasing the \\|10> state.
+    r"""Controlled phase shift gate for phasing the \\|10> state.
+
+    Unitary matrix:
+        .. math:: \mathtt{CPhaseShift10}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & e^{i \phi} & 0 \\
+                0 & 0 & 0 & 1
+                \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -1902,14 +1924,6 @@ def cphaseshift10(
         Returns:
             Instruction: CPhaseShift10 instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CPhaseShift10}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & e^{i \phi} & 0 \\
-                0 & 0 & 0 & 1
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().cphaseshift10(0, 1, 0.15)
         """
@@ -1927,7 +1941,16 @@ def cphaseshift10(
 
 
 class CV(Gate):
-    """Controlled Sqrt of NOT gate."""
+    r"""Controlled Sqrt of NOT gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{CV} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0.5+0.5i & 0.5-0.5i \\
+                0 & 0 & 0.5-0.5i & 0.5+0.5i
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["C", "V"])
@@ -1973,14 +1996,6 @@ def cv(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
         Returns:
             Instruction: CV instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CV}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 0.5+0.5i & 0.5-0.5i \\
-                0 & 0 & 0.5-0.5i & 0.5+0.5i
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().cv(0, 1)
         """
@@ -1995,7 +2010,16 @@ def cv(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
 
 
 class CY(Gate):
-    """Controlled Pauli-Y gate."""
+    r"""Controlled Pauli-Y gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{CY} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & -i \\
+                0 & 0 & i & 0
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["C", "Y"])
@@ -2041,14 +2065,6 @@ def cy(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
         Returns:
             Instruction: CY instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CY} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & -i \\
-                0 & 0 & i & 0
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().cy(0, 1)
         """
@@ -2063,7 +2079,16 @@ def cy(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
 
 
 class CZ(Gate):
-    """Controlled Pauli-Z gate."""
+    r"""Controlled Pauli-Z gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{CZ} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & -1
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["C", "Z"])
@@ -2101,14 +2126,6 @@ def cz(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
         Returns:
             Instruction: CZ instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CY} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & -1
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().cz(0, 1)
         """
@@ -2123,7 +2140,16 @@ def cz(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruct
 
 
 class ECR(Gate):
-    """An echoed RZX(pi/2) gate."""
+    r"""An echoed RZX(pi/2) gate (ECR gate).
+
+    Unitary matrix:
+        .. math:: \mathtt{ECR} = \begin{bmatrix}
+                0 & 0 & 1 & i \\
+                0 & 0 & i & 1 \\
+                1 & -i & 0 & 0 \\
+                -i & 1 & 0 & 0
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["ECR", "ECR"])
@@ -2181,14 +2207,6 @@ def ecr(
         Returns:
             Instruction: ECR instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{ECR} = \begin{bmatrix}
-                0 & 0 & 1 & i \\
-                0 & 0 & i & 1 \\
-                1 & -i & 0 & 0 \\
-                -i & 1 & 0 & 0
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().ecr(0, 1)
         """
@@ -2205,7 +2223,15 @@ def ecr(
 
 
 class XX(AngledGate):
-    """Ising XX coupling gate.
+    r"""Ising XX coupling gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{XX}(\phi) = \begin{bmatrix}
+                \cos{(\phi/2)} & 0 & 0 & -i \sin{(\phi/2)} \\
+                0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\
+                0 & -i \sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
+                -i \sin{(\phi/2)} & 0 & 0 & \cos{(\phi/2)}
+                \end{bmatrix}.
 
     Reference: https://arxiv.org/abs/1707.06356
 
@@ -2285,14 +2311,6 @@ def xx(
         Returns:
             Instruction: XX instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{XX}(\phi) = \begin{bmatrix}
-                \cos{\phi/2} & 0 & 0 & -i \sin{\phi/2} \\
-                0 & \cos{\phi/2} & -i \sin{\phi/2} & 0 \\
-                0 & -i \sin{\phi/2} & \cos{\phi/2} & 0 \\
-                -i \sin{\phi/2} & 0 & 0 & \cos{\phi/2}
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().xx(0, 1, 0.15)
         """
@@ -2309,7 +2327,15 @@ def xx(
 
 
 class YY(AngledGate):
-    """Ising YY coupling gate.
+    r"""Ising YY coupling gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{YY}(\phi) = \begin{bmatrix}
+                \cos{(\phi/2)} & 0 & 0 & i \sin{(\phi/2)} \\
+                0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\
+                0 & -i \sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
+                i \sin{(\phi/2)} & 0 & 0 & \cos{(\phi/2)}
+                \end{bmatrix}.
 
     Reference: https://arxiv.org/abs/1707.06356
 
@@ -2389,14 +2415,6 @@ def yy(
         Returns:
             Instruction: YY instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{YY}(\phi) = \begin{bmatrix}
-                \cos{\phi/2} & 0 & 0 & i \sin{\phi/2} \\
-                0 & \cos{\phi/2} & -i \sin{\phi/2} & 0 \\
-                0 & -i \sin{\phi/2} & \cos{\phi/2} & 0 \\
-                i \sin{\phi/2} & 0 & 0 & \cos{\phi/2}
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().yy(0, 1, 0.15)
         """
@@ -2413,7 +2431,15 @@ def yy(
 
 
 class ZZ(AngledGate):
-    """Ising ZZ coupling gate.
+    r"""Ising ZZ coupling gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{ZZ}(\phi) = \begin{bmatrix}
+                e^{-i\phi/2} & 0 & 0 & 0 \\
+                0 & e^{i\phi/2} & 0 & 0 \\
+                0 & 0 & e^{i\phi/2} & 0 \\
+                0 & 0 & 0 & e^{-i\phi/2}
+            \end{bmatrix}.
 
     Reference: https://arxiv.org/abs/1707.06356
 
@@ -2487,14 +2513,6 @@ def zz(
         Returns:
             Instruction: ZZ instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{ZZ}(\phi) = \begin{bmatrix}
-                e^{-i\phi/2} & 0 & 0 & 0 \\
-                0 & e^{i\phi/2} & 0 & 0 \\
-                0 & 0 & e^{i\phi/2} & 0 \\
-                0 & 0 & 0 & e^{-i\phi/2}
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().zz(0, 1, 0.15)
         """
@@ -2514,7 +2532,20 @@ def zz(
 
 
 class CCNot(Gate):
-    """CCNOT gate or Toffoli gate."""
+    r"""CCNOT gate or Toffoli gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{CCNOT} = \begin{bmatrix}
+                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
+                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["C", "C", "X"])
@@ -2581,18 +2612,6 @@ def ccnot(
         Returns:
             Instruction: CCNot instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CCNOT} = \begin{bmatrix}
-                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
-                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
-                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().ccnot(0, 1, 2)
         """
@@ -2609,7 +2628,20 @@ def ccnot(
 
 
 class CSwap(Gate):
-    """Controlled Swap gate."""
+    r"""Controlled Swap gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{CSWAP} = \begin{bmatrix}
+                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
+                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
+                \end{bmatrix}.
+    """
 
     def __init__(self):
         super().__init__(qubit_count=None, ascii_symbols=["C", "SWAP", "SWAP"])
@@ -2665,18 +2697,6 @@ def cswap(
         Returns:
             Instruction: CSwap instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{CCNOT} = \begin{bmatrix}
-                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
-                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().cswap(0, 1, 2)
         """
@@ -2694,7 +2714,13 @@ def cswap(
 
 
 class GPi(AngledGate):
-    """IonQ GPi gate.
+    r"""IonQ GPi gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{GPi}(\phi) = \begin{bmatrix}
+                0 & e^{-i \phi} \\
+                e^{i \phi} & 0
+                \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -2758,12 +2784,6 @@ def gpi(
         Returns:
             Iterable[Instruction]: GPi instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{GPi}(\phi) = \begin{bmatrix}
-                0 & e^{-i \phi} \\
-                e^{i \phi} & 0
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().gpi(0, 0.15)
         """
@@ -2779,7 +2799,13 @@ def gpi(
 
 
 class GPi2(AngledGate):
-    """IonQ GPi2 gate.
+    r"""IonQ GPi2 gate.
+
+    Unitary matrix:
+        .. math:: \mathtt{GPi2}(\phi) = \begin{bmatrix}
+                1 & -i e^{-i \phi} \\
+                -i e^{i \phi} & 1
+            \end{bmatrix}.
 
     Args:
         angle (Union[FreeParameterExpression, float]): angle in radians.
@@ -2843,12 +2869,6 @@ def gpi2(
         Returns:
             Iterable[Instruction]: GPi2 instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{GPi2}(\phi) = \begin{bmatrix}
-                1 & -i e^{-i \phi} \\
-                -i e^{i \phi} & 1
-            \end{bmatrix}.
-            
         Examples:
             >>> circ = Circuit().gpi2(0, 0.15)
         """
@@ -2864,12 +2884,25 @@ def gpi2(
 
 
 class MS(TripleAngledGate):
-    """IonQ Mølmer-Sørenson gate.
+    r"""IonQ Mølmer-Sørenson gate.
+
+        Unitary matrix:
+            .. math:: &\mathtt{MS}(\phi_0, \phi_1, \theta) =\\ &\begin{bmatrix}
+                    \cos{\frac{\theta}{2}} & 0 &
+                    0 & -ie^{-i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} \\
+                    0 & \cos{\frac{\theta}{2}} &
+                    -ie^{-i (\phi_0 - \phi_1)}\sin{\frac{\theta}{2}} & 0 \\
+                    0 & -ie^{i (\phi_0 - \phi_1)}\sin{\frac{\theta}{2}} &
+                    \cos{\frac{\theta}{2}} & 0 \\
+                    -ie^{i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} & 0
+                    & 0 & \cos{\frac{\theta}{2}}
+                    \end{bmatrix}.
 
     Args:
         angle_1 (Union[FreeParameterExpression, float]): angle in radians.
         angle_2 (Union[FreeParameterExpression, float]): angle in radians.
         angle_3 (Union[FreeParameterExpression, float]): angle in radians.
+        Default value is angle_3=pi/2.
     """
 
     def __init__(
@@ -2965,14 +2998,6 @@ def ms(
         Returns:
             Iterable[Instruction]: MS instruction.
 
-        Unitary matrix:
-        .. math:: \mathtt{MS}(\phi_0, \phi_1) = \frac{1}{\sqrt{2}}\begin{bmatrix}
-                1 & 0 & 0 & -ie^{-i (\phi_0 + \phi_1)} \\
-                0 & 1 & -ie^{-i (\phi_0 - \phi_1)} & 0 \\
-                0 & -ie^{i (\phi_0 - \phi_1)} & 1 & 0 \\
-                -ie^{i (\phi_0 + \phi_1)} & 0 & 0 & 1
-            \end{bmatrix}.
-
         Examples:
             >>> circ = Circuit().ms(0, 1, 0.15, 0.34)
         """

From 3b1a47a623a9504fee352615c5fef0bcbea286cf Mon Sep 17 00:00:00 2001
From: Yaroslav Kharkov <ykharkov@amazon.com>
Date: Mon, 23 Oct 2023 13:19:24 -0400
Subject: [PATCH 03/11] fix r-strings

---
 src/braket/circuits/gates.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index 1ea905c35..efc6104ac 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -97,7 +97,7 @@ def h(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -168,7 +168,7 @@ def i(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)

From a25331ef1344c25fd18cf22560000466c99bd52b Mon Sep 17 00:00:00 2001
From: Yaroslav Kharkov <ykharkov@amazon.com>
Date: Mon, 23 Oct 2023 14:22:58 -0400
Subject: [PATCH 04/11] Capitalize H gate

---
 src/braket/circuits/gates.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index efc6104ac..0ef2050a1 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -63,7 +63,7 @@ class H(Gate):
     r"""Hadamard gate.
 
     Unitary matrix:
-        .. math:: \mathtt{h} = \frac{1}{\sqrt{2}} \begin{bmatrix}
+        .. math:: \mathtt{H} = \frac{1}{\sqrt{2}} \begin{bmatrix}
                 1 & 1 \\
                 1 & -1 \end{bmatrix}.
     """

From 79ce29dbced8448bba5f3e3c847bbd4d5e781c1b Mon Sep 17 00:00:00 2001
From: Yaroslav Kharkov <ykharkov@amazon.com>
Date: Mon, 23 Oct 2023 16:43:09 -0400
Subject: [PATCH 05/11] Rename theta->phi

---
 src/braket/circuits/gates.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index 0ef2050a1..b810d6ba9 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -856,9 +856,9 @@ class Rx(AngledGate):
     r"""X-axis rotation gate.
 
     Unitary matrix:
-        .. math:: \mathtt{R_x}(\theta) = \begin{bmatrix}
-                \cos{(\theta/2)} & -i \sin{(\theta/2)} \\
-                -i \sin{(\theta/2)} & \cos{(\theta/2)}
+        .. math:: \mathtt{R_x}(\phi) = \begin{bmatrix}
+                \cos{(\phi/2)} & -i \sin{(\phi/2)} \\
+                -i \sin{(\phi/2)} & \cos{(\phi/2)}
                 \end{bmatrix}.
 
     Args:
@@ -942,9 +942,9 @@ class Ry(AngledGate):
     r"""Y-axis rotation gate.
 
     Unitary matrix:
-        .. math:: \mathtt{R_y}(\theta) = \begin{bmatrix}
-                \cos{(\theta/2)} & -\sin{(\theta/2)} \\
-                \sin{(\theta/2)} & \cos{(\theta/2)}
+        .. math:: \mathtt{R_y}(\phi) = \begin{bmatrix}
+                \cos{(\phi/2)} & -\sin{(\phi/2)} \\
+                \sin{(\phi/2)} & \cos{(\phi/2)}
                 \end{bmatrix}.
 
     Args:

From 707173af2722754ea0082ce89167e6055e6477a7 Mon Sep 17 00:00:00 2001
From: Yaroslav Kharkov <ykharkov@amazon.com>
Date: Sat, 28 Oct 2023 14:44:44 -0400
Subject: [PATCH 06/11] Address comments

---
 src/braket/circuits/gates.py | 44 ++++++++++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 4 deletions(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index b810d6ba9..640695d50 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -63,6 +63,7 @@ class H(Gate):
     r"""Hadamard gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{H} = \frac{1}{\sqrt{2}} \begin{bmatrix}
                 1 & 1 \\
                 1 & -1 \end{bmatrix}.
@@ -134,6 +135,7 @@ class I(Gate):  # noqa: E742, E261
     r"""Identity gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{I} = \begin{bmatrix}
                 1 & 0 \\
                 0 & 1 \end{bmatrix}.
@@ -205,6 +207,7 @@ class X(Gate):
     r"""Pauli-X gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{X} = \begin{bmatrix}
                 0 & 1 \\
                 1 & 0
@@ -277,6 +280,7 @@ class Y(Gate):
     r"""Pauli-Y gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{Y} = \begin{bmatrix}
                 0 & -i \\
                 i & 0
@@ -349,6 +353,7 @@ class Z(Gate):
     r"""Pauli-Z gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{Z} = \begin{bmatrix}
                 1 & 0 \\
                 0 & -1
@@ -421,6 +426,7 @@ class S(Gate):
     r"""S gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{S} = \begin{bmatrix}
                 1 & 0 \\
                 0 & i
@@ -493,6 +499,7 @@ class Si(Gate):
     r"""Conjugate transpose of S gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{S}^\dagger = \begin{bmatrix}
                 1 & 0 \\
                 0 & -i
@@ -565,6 +572,7 @@ class T(Gate):
     r"""T gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{T} = \begin{bmatrix}
                 1 & 0 \\
                 0 & e^{i \pi/4}
@@ -637,6 +645,7 @@ class Ti(Gate):
     r"""Conjugate transpose of T gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{T}^\dagger = \begin{bmatrix}
                 1 & 0 \\
                 0 & e^{-i \pi/4}
@@ -709,6 +718,7 @@ class V(Gate):
     r"""Square root of not gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{V} = \frac{1}{2}\begin{bmatrix}
                 1+i & 1-i \\
                 1-i & 1+i
@@ -781,6 +791,7 @@ class Vi(Gate):
     r"""Conjugate transpose of square root of not gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{V}^\dagger = \frac{1}{2}\begin{bmatrix}
                 1-i & 1+i \\
                 1+i & 1-i
@@ -856,6 +867,7 @@ class Rx(AngledGate):
     r"""X-axis rotation gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{R_x}(\phi) = \begin{bmatrix}
                 \cos{(\phi/2)} & -i \sin{(\phi/2)} \\
                 -i \sin{(\phi/2)} & \cos{(\phi/2)}
@@ -942,6 +954,7 @@ class Ry(AngledGate):
     r"""Y-axis rotation gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{R_y}(\phi) = \begin{bmatrix}
                 \cos{(\phi/2)} & -\sin{(\phi/2)} \\
                 \sin{(\phi/2)} & \cos{(\phi/2)}
@@ -1029,6 +1042,7 @@ class Rz(AngledGate):
     r"""Z-axis rotation gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{R_z}(\phi) = \begin{bmatrix}
                 e^{-i \phi/2} & 0 \\
                 0 & e^{i \phi/2}
@@ -1111,6 +1125,7 @@ class PhaseShift(AngledGate):
     r"""Phase shift gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{PhaseShift}(\phi) = \begin{bmatrix}
                 1 & 0 \\
                 0 & e^{i \phi}
@@ -1198,6 +1213,7 @@ class CNot(Gate):
     r"""Controlled NOT gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{CNOT} = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 \\
@@ -1267,6 +1283,7 @@ class Swap(Gate):
     r"""Swap gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{SWAP} = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 0 & 1 & 0 \\
@@ -1351,6 +1368,7 @@ class ISwap(Gate):
     r"""ISwap gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{iSWAP} = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 0 & i & 0 \\
@@ -1435,6 +1453,7 @@ class PSwap(AngledGate):
     r"""PSwap gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{PSWAP}(\phi) = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 0 & e^{i \phi} & 0 \\
@@ -1531,6 +1550,7 @@ class XY(AngledGate):
     r"""XY gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{XY}(\phi) = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & \cos{(\phi/2)} & i\sin{(\phi/2)} & 0 \\
@@ -1636,7 +1656,8 @@ class CPhaseShift(AngledGate):
     r"""Controlled phase shift gate.
 
     Unitary matrix:
-        .. math:: \mathtt{CPhaseShift00}(\phi) = \begin{bmatrix}
+
+        .. math:: \mathtt{CPhaseShift}(\phi) = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 \\
                 0 & 0 & 1 & 0 \\
@@ -1713,6 +1734,7 @@ class CPhaseShift00(AngledGate):
     r"""Controlled phase shift gate for phasing the \|00> state.
 
     Unitary matrix:
+
         .. math:: \mathtt{CPhaseShift00}(\phi) = \begin{bmatrix}
                 e^{i \phi} & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 \\
@@ -1790,9 +1812,10 @@ class CPhaseShift01(AngledGate):
     r"""Controlled phase shift gate for phasing the \|01> state.
 
     Unitary matrix:
+
         .. math:: \mathtt{CPhaseShift01}(\phi) = \begin{bmatrix}
-                e^{i \phi} & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
+                1 & 0 & 0 & 0 \\
+                0 & e^{i \phi} & 0 & 0 \\
                 0 & 0 & 1 & 0 \\
                 0 & 0 & 0 & 1
             \end{bmatrix}.
@@ -1867,6 +1890,7 @@ class CPhaseShift10(AngledGate):
     r"""Controlled phase shift gate for phasing the \\|10> state.
 
     Unitary matrix:
+
         .. math:: \mathtt{CPhaseShift10}(\phi) = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 \\
@@ -1944,6 +1968,7 @@ class CV(Gate):
     r"""Controlled Sqrt of NOT gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{CV} = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 \\
@@ -2013,6 +2038,7 @@ class CY(Gate):
     r"""Controlled Pauli-Y gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{CY} = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 \\
@@ -2082,6 +2108,7 @@ class CZ(Gate):
     r"""Controlled Pauli-Z gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{CZ} = \begin{bmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 \\
@@ -2143,6 +2170,7 @@ class ECR(Gate):
     r"""An echoed RZX(pi/2) gate (ECR gate).
 
     Unitary matrix:
+
         .. math:: \mathtt{ECR} = \begin{bmatrix}
                 0 & 0 & 1 & i \\
                 0 & 0 & i & 1 \\
@@ -2226,6 +2254,7 @@ class XX(AngledGate):
     r"""Ising XX coupling gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{XX}(\phi) = \begin{bmatrix}
                 \cos{(\phi/2)} & 0 & 0 & -i \sin{(\phi/2)} \\
                 0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\
@@ -2330,6 +2359,7 @@ class YY(AngledGate):
     r"""Ising YY coupling gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{YY}(\phi) = \begin{bmatrix}
                 \cos{(\phi/2)} & 0 & 0 & i \sin{(\phi/2)} \\
                 0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\
@@ -2434,6 +2464,7 @@ class ZZ(AngledGate):
     r"""Ising ZZ coupling gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{ZZ}(\phi) = \begin{bmatrix}
                 e^{-i\phi/2} & 0 & 0 & 0 \\
                 0 & e^{i\phi/2} & 0 & 0 \\
@@ -2535,6 +2566,7 @@ class CCNot(Gate):
     r"""CCNOT gate or Toffoli gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{CCNOT} = \begin{bmatrix}
                 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
@@ -2631,6 +2663,7 @@ class CSwap(Gate):
     r"""Controlled Swap gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{CSWAP} = \begin{bmatrix}
                 1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
                 0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
@@ -2717,6 +2750,7 @@ class GPi(AngledGate):
     r"""IonQ GPi gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{GPi}(\phi) = \begin{bmatrix}
                 0 & e^{-i \phi} \\
                 e^{i \phi} & 0
@@ -2802,6 +2836,7 @@ class GPi2(AngledGate):
     r"""IonQ GPi2 gate.
 
     Unitary matrix:
+
         .. math:: \mathtt{GPi2}(\phi) = \begin{bmatrix}
                 1 & -i e^{-i \phi} \\
                 -i e^{i \phi} & 1
@@ -2884,9 +2919,10 @@ def gpi2(
 
 
 class MS(TripleAngledGate):
-    r"""IonQ Mølmer-Sørenson gate.
+    r"""IonQ Mølmer-Sørensen gate.
 
         Unitary matrix:
+
             .. math:: &\mathtt{MS}(\phi_0, \phi_1, \theta) =\\ &\begin{bmatrix}
                     \cos{\frac{\theta}{2}} & 0 &
                     0 & -ie^{-i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} \\

From 47b1674ca88091796e5b7c0ec1014d7102314a1c Mon Sep 17 00:00:00 2001
From: ykharkov <112575584+ykharkov@users.noreply.github.com>
Date: Wed, 1 Nov 2023 10:44:40 -0400
Subject: [PATCH 07/11] Update src/braket/circuits/gates.py

Co-authored-by: Ryan Shaffer <3620100+rmshaffer@users.noreply.github.com>
---
 src/braket/circuits/gates.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index 640695d50..a9c68d339 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -2921,7 +2921,7 @@ def gpi2(
 class MS(TripleAngledGate):
     r"""IonQ Mølmer-Sørensen gate.
 
-        Unitary matrix:
+    Unitary matrix:
 
             .. math:: &\mathtt{MS}(\phi_0, \phi_1, \theta) =\\ &\begin{bmatrix}
                     \cos{\frac{\theta}{2}} & 0 &

From 759f745c56a208f03c938972553a8d668a428f78 Mon Sep 17 00:00:00 2001
From: Abe Coull <accoull@amazon.com>
Date: Wed, 1 Nov 2023 12:26:25 -0700
Subject: [PATCH 08/11] add matrices to subrountines

---
 src/braket/circuits/gates.py | 322 ++++++++++++++++++++++++++++++-----
 1 file changed, 279 insertions(+), 43 deletions(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index a9c68d339..9c8164985 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -98,7 +98,13 @@ def h(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        Unitary matrix:
+
+            .. math:: \mathtt{H} = \frac{1}{\sqrt{2}} \begin{bmatrix}
+                    1 & 1 \\
+                    1 & -1 \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -170,7 +176,13 @@ def i(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        Unitary matrix:
+
+            .. math:: \mathtt{I} = \begin{bmatrix}
+                    1 & 0 \\
+                    0 & 1 \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -243,7 +255,14 @@ def x(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        Unitary matrix:
+
+            .. math:: \mathtt{X} = \begin{bmatrix}
+                    0 & 1 \\
+                    1 & 0
+                    \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -316,7 +335,14 @@ def y(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        Unitary matrix:
+
+            .. math:: \mathtt{Y} = \begin{bmatrix}
+                    0 & -i \\
+                    i & 0
+                    \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -389,7 +415,12 @@ def z(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{Z} = \begin{bmatrix}
+                1 & 0 \\
+                0 & -1
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -462,7 +493,12 @@ def s(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{S} = \begin{bmatrix}
+                1 & 0 \\
+                0 & i
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -535,7 +571,12 @@ def si(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{S}^\dagger = \begin{bmatrix}
+                1 & 0 \\
+                0 & -i
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -608,7 +649,12 @@ def t(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{T} = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{i \pi/4}
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -681,7 +727,12 @@ def ti(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{T}^\dagger = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{-i \pi/4}
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -754,7 +805,12 @@ def v(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{V} = \frac{1}{2}\begin{bmatrix}
+                1+i & 1-i \\
+                1-i & 1+i
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -827,7 +883,12 @@ def vi(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{V}^\dagger = \frac{1}{2}\begin{bmatrix}
+                1-i & 1+i \\
+                1+i & 1-i
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -892,7 +953,7 @@ def _to_jaqcd(self, target: QubitSet, **kwargs) -> Any:
         return ir.Rx.construct(target=target[0], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        """Returns a matrix representation of this gate.
+        r"""Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -917,7 +978,12 @@ def rx(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{R_x}(\phi) = \begin{bmatrix}
+                \cos{(\phi/2)} & -i \sin{(\phi/2)} \\
+                -i \sin{(\phi/2)} & \cos{(\phi/2)}
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -979,7 +1045,7 @@ def _to_jaqcd(self, target: QubitSet) -> Any:
         return ir.Ry.construct(target=target[0], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        """Returns a matrix representation of this gate.
+        r"""Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -1004,7 +1070,12 @@ def ry(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{R_y}(\phi) = \begin{bmatrix}
+                \cos{(\phi/2)} & -\sin{(\phi/2)} \\
+                \sin{(\phi/2)} & \cos{(\phi/2)}
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1088,7 +1159,12 @@ def rz(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{R_z}(\phi) = \begin{bmatrix}
+                e^{-i \phi/2} & 0 \\
+                0 & e^{i \phi/2}
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1169,7 +1245,12 @@ def phaseshift(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{PhaseShift}(\phi) = \begin{bmatrix}
+                1 & 0 \\
+                0 & e^{i \phi}
+                \end{bmatrix}
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1253,7 +1334,14 @@ def fixed_qubit_count() -> int:
     @staticmethod
     @circuit.subroutine(register=True)
     def cnot(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CNOT} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                0 & 0 & 1 & 0 \\
+                \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1330,7 +1418,14 @@ def swap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{SWAP} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1415,7 +1510,14 @@ def iswap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{iSWAP} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & i & 0 \\
+                0 & i & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1511,7 +1613,14 @@ def pswap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{PSWAP}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 0 & e^{i \phi} & 0 \\
+                0 & e^{i \phi} & 0 & 0 \\
+                0 & 0 & 0 & 1 \\
+                \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1583,7 +1692,7 @@ def _to_jaqcd(self, target: QubitSet) -> Any:
         return ir.XY.construct(targets=[target[0], target[1]], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        """Returns a matrix representation of this gate.
+        r"""Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -1617,7 +1726,14 @@ def xy(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{XY}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & \cos{(\phi/2)} & i\sin{(\phi/2)} & 0 \\
+                0 & i\sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
+                0 & 0 & 0 & 1 \\
+            \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1700,7 +1816,14 @@ def cphaseshift(
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CPhaseShift}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & e^{i \phi}
+            \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1778,7 +1901,14 @@ def cphaseshift00(
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CPhaseShift00}(\phi) = \begin{bmatrix}
+                e^{i \phi} & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 1
+                \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1856,7 +1986,14 @@ def cphaseshift01(
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CPhaseShift01}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & e^{i \phi} & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 1
+            \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1934,7 +2071,14 @@ def cphaseshift10(
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CPhaseShift10}(\phi) = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & e^{i \phi} & 0 \\
+                0 & 0 & 0 & 1
+                \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2008,7 +2152,14 @@ def fixed_qubit_count() -> int:
     @staticmethod
     @circuit.subroutine(register=True)
     def cv(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CV} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0.5+0.5i & 0.5-0.5i \\
+                0 & 0 & 0.5-0.5i & 0.5+0.5i
+                \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2078,7 +2229,14 @@ def fixed_qubit_count() -> int:
     @staticmethod
     @circuit.subroutine(register=True)
     def cy(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CY} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & -i \\
+                0 & 0 & i & 0
+                \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2140,7 +2298,14 @@ def fixed_qubit_count() -> int:
     @staticmethod
     @circuit.subroutine(register=True)
     def cz(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CZ} = \begin{bmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & -1
+                \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2216,7 +2381,14 @@ def ecr(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{ECR} = \begin{bmatrix}
+                0 & 0 & 1 & i \\
+                0 & 0 & i & 1 \\
+                1 & -i & 0 & 0 \\
+                -i & 1 & 0 & 0
+                \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2286,7 +2458,7 @@ def _to_jaqcd(self, target: QubitSet) -> Any:
         return ir.XX.construct(targets=[target[0], target[1]], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        """Returns a matrix representation of this gate.
+        r"""Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -2320,7 +2492,14 @@ def xx(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{XX}(\phi) = \begin{bmatrix}
+                \cos{(\phi/2)} & 0 & 0 & -i \sin{(\phi/2)} \\
+                0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\
+                0 & -i \sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
+                -i \sin{(\phi/2)} & 0 & 0 & \cos{(\phi/2)}
+                \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2391,7 +2570,7 @@ def _to_jaqcd(self, target: QubitSet) -> Any:
         return ir.YY.construct(targets=[target[0], target[1]], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        """Returns a matrix representation of this gate.
+        r"""Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -2425,7 +2604,14 @@ def yy(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{YY}(\phi) = \begin{bmatrix}
+                \cos{(\phi/2)} & 0 & 0 & i \sin{(\phi/2)} \\
+                0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\
+                0 & -i \sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
+                i \sin{(\phi/2)} & 0 & 0 & \cos{(\phi/2)}
+                \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2524,7 +2710,14 @@ def zz(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{ZZ}(\phi) = \begin{bmatrix}
+                e^{-i\phi/2} & 0 & 0 & 0 \\
+                0 & e^{i\phi/2} & 0 & 0 \\
+                0 & 0 & e^{i\phi/2} & 0 \\
+                0 & 0 & 0 & e^{-i\phi/2}
+            \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2622,7 +2815,18 @@ def ccnot(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CCNOT} = \begin{bmatrix}
+                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
+                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
+                \end{bmatrix}.
 
         Args:
             control1 (QubitInput): Control qubit 1 index.
@@ -2716,7 +2920,18 @@ def cswap(
         target2: QubitInput,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{CSWAP} = \begin{bmatrix}
+                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
+                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
+                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
+                \end{bmatrix}.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2799,7 +3014,12 @@ def gpi(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{GPi}(\phi) = \begin{bmatrix}
+                0 & e^{-i \phi} \\
+                e^{i \phi} & 0
+                \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -2885,7 +3105,12 @@ def gpi2(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: \mathtt{GPi2}(\phi) = \begin{bmatrix}
+                1 & -i e^{-i \phi} \\
+                -i e^{i \phi} & 1
+            \end{bmatrix}.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -3012,7 +3237,18 @@ def ms(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
+
+        .. math:: &\mathtt{MS}(\phi_0, \phi_1, \theta) =\\ &\begin{bmatrix}
+                    \cos{\frac{\theta}{2}} & 0 &
+                    0 & -ie^{-i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} \\
+                    0 & \cos{\frac{\theta}{2}} &
+                    -ie^{-i (\phi_0 - \phi_1)}\sin{\frac{\theta}{2}} & 0 \\
+                    0 & -ie^{i (\phi_0 - \phi_1)}\sin{\frac{\theta}{2}} &
+                    \cos{\frac{\theta}{2}} & 0 \\
+                    -ie^{i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} & 0
+                    & 0 & \cos{\frac{\theta}{2}}
+                    \end{bmatrix}.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -3115,7 +3351,7 @@ def _transform_matrix_to_ir(matrix: np.ndarray) -> list:
     @staticmethod
     @circuit.subroutine(register=True)
     def unitary(targets: QubitSet, matrix: np.ndarray, display_name: str = "U") -> Instruction:
-        """Registers this function into the circuit class.
+        r"""Registers this function into the circuit class.
 
         Args:
             targets (QubitSet): Target qubits.
@@ -3172,7 +3408,7 @@ def pulse_sequence(self) -> PulseSequence:
 
     @property
     def parameters(self) -> list[FreeParameter]:
-        """Returns the list of `FreeParameter` s associated with the gate."""
+        r"""Returns the list of `FreeParameter` s associated with the gate."""
         return list(self._pulse_sequence.parameters)
 
     def bind_values(self, **kwargs) -> PulseGate:

From 1d84dee9eb0de331bb44a0a56d32ff2b1ecde1c1 Mon Sep 17 00:00:00 2001
From: Aaron Berdy <berdy@amazon.com>
Date: Tue, 14 Nov 2023 15:58:06 -0800
Subject: [PATCH 09/11] Revert "add matrices to subrountines"

This reverts commit 759f745c56a208f03c938972553a8d668a428f78.
---
 src/braket/circuits/gates.py | 322 +++++------------------------------
 1 file changed, 43 insertions(+), 279 deletions(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index 9c8164985..a9c68d339 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -98,13 +98,7 @@ def h(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        Unitary matrix:
-
-            .. math:: \mathtt{H} = \frac{1}{\sqrt{2}} \begin{bmatrix}
-                    1 & 1 \\
-                    1 & -1 \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -176,13 +170,7 @@ def i(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        Unitary matrix:
-
-            .. math:: \mathtt{I} = \begin{bmatrix}
-                    1 & 0 \\
-                    0 & 1 \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -255,14 +243,7 @@ def x(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        Unitary matrix:
-
-            .. math:: \mathtt{X} = \begin{bmatrix}
-                    0 & 1 \\
-                    1 & 0
-                    \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -335,14 +316,7 @@ def y(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        Unitary matrix:
-
-            .. math:: \mathtt{Y} = \begin{bmatrix}
-                    0 & -i \\
-                    i & 0
-                    \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -415,12 +389,7 @@ def z(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{Z} = \begin{bmatrix}
-                1 & 0 \\
-                0 & -1
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -493,12 +462,7 @@ def s(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{S} = \begin{bmatrix}
-                1 & 0 \\
-                0 & i
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -571,12 +535,7 @@ def si(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{S}^\dagger = \begin{bmatrix}
-                1 & 0 \\
-                0 & -i
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -649,12 +608,7 @@ def t(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{T} = \begin{bmatrix}
-                1 & 0 \\
-                0 & e^{i \pi/4}
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -727,12 +681,7 @@ def ti(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{T}^\dagger = \begin{bmatrix}
-                1 & 0 \\
-                0 & e^{-i \pi/4}
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -805,12 +754,7 @@ def v(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{V} = \frac{1}{2}\begin{bmatrix}
-                1+i & 1-i \\
-                1-i & 1+i
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -883,12 +827,7 @@ def vi(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{V}^\dagger = \frac{1}{2}\begin{bmatrix}
-                1-i & 1+i \\
-                1+i & 1-i
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -953,7 +892,7 @@ def _to_jaqcd(self, target: QubitSet, **kwargs) -> Any:
         return ir.Rx.construct(target=target[0], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        r"""Returns a matrix representation of this gate.
+        """Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -978,12 +917,7 @@ def rx(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{R_x}(\phi) = \begin{bmatrix}
-                \cos{(\phi/2)} & -i \sin{(\phi/2)} \\
-                -i \sin{(\phi/2)} & \cos{(\phi/2)}
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1045,7 +979,7 @@ def _to_jaqcd(self, target: QubitSet) -> Any:
         return ir.Ry.construct(target=target[0], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        r"""Returns a matrix representation of this gate.
+        """Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -1070,12 +1004,7 @@ def ry(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{R_y}(\phi) = \begin{bmatrix}
-                \cos{(\phi/2)} & -\sin{(\phi/2)} \\
-                \sin{(\phi/2)} & \cos{(\phi/2)}
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1159,12 +1088,7 @@ def rz(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{R_z}(\phi) = \begin{bmatrix}
-                e^{-i \phi/2} & 0 \\
-                0 & e^{i \phi/2}
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1245,12 +1169,7 @@ def phaseshift(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{PhaseShift}(\phi) = \begin{bmatrix}
-                1 & 0 \\
-                0 & e^{i \phi}
-                \end{bmatrix}
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1334,14 +1253,7 @@ def fixed_qubit_count() -> int:
     @staticmethod
     @circuit.subroutine(register=True)
     def cnot(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CNOT} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & 1 \\
-                0 & 0 & 1 & 0 \\
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1418,14 +1330,7 @@ def swap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{SWAP} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & 1 \\
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1510,14 +1415,7 @@ def iswap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{iSWAP} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 0 & i & 0 \\
-                0 & i & 0 & 0 \\
-                0 & 0 & 0 & 1 \\
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1613,14 +1511,7 @@ def pswap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{PSWAP}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 0 & e^{i \phi} & 0 \\
-                0 & e^{i \phi} & 0 & 0 \\
-                0 & 0 & 0 & 1 \\
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1692,7 +1583,7 @@ def _to_jaqcd(self, target: QubitSet) -> Any:
         return ir.XY.construct(targets=[target[0], target[1]], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        r"""Returns a matrix representation of this gate.
+        """Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -1726,14 +1617,7 @@ def xy(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{XY}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & \cos{(\phi/2)} & i\sin{(\phi/2)} & 0 \\
-                0 & i\sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
-                0 & 0 & 0 & 1 \\
-            \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1816,14 +1700,7 @@ def cphaseshift(
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CPhaseShift}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & e^{i \phi}
-            \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1901,14 +1778,7 @@ def cphaseshift00(
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CPhaseShift00}(\phi) = \begin{bmatrix}
-                e^{i \phi} & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & 1
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1986,14 +1856,7 @@ def cphaseshift01(
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CPhaseShift01}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & e^{i \phi} & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & 1
-            \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2071,14 +1934,7 @@ def cphaseshift10(
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CPhaseShift10}(\phi) = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & e^{i \phi} & 0 \\
-                0 & 0 & 0 & 1
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2152,14 +2008,7 @@ def fixed_qubit_count() -> int:
     @staticmethod
     @circuit.subroutine(register=True)
     def cv(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CV} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 0.5+0.5i & 0.5-0.5i \\
-                0 & 0 & 0.5-0.5i & 0.5+0.5i
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2229,14 +2078,7 @@ def fixed_qubit_count() -> int:
     @staticmethod
     @circuit.subroutine(register=True)
     def cy(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CY} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & -i \\
-                0 & 0 & i & 0
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2298,14 +2140,7 @@ def fixed_qubit_count() -> int:
     @staticmethod
     @circuit.subroutine(register=True)
     def cz(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CZ} = \begin{bmatrix}
-                1 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 \\
-                0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & -1
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2381,14 +2216,7 @@ def ecr(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{ECR} = \begin{bmatrix}
-                0 & 0 & 1 & i \\
-                0 & 0 & i & 1 \\
-                1 & -i & 0 & 0 \\
-                -i & 1 & 0 & 0
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2458,7 +2286,7 @@ def _to_jaqcd(self, target: QubitSet) -> Any:
         return ir.XX.construct(targets=[target[0], target[1]], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        r"""Returns a matrix representation of this gate.
+        """Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -2492,14 +2320,7 @@ def xx(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{XX}(\phi) = \begin{bmatrix}
-                \cos{(\phi/2)} & 0 & 0 & -i \sin{(\phi/2)} \\
-                0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\
-                0 & -i \sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
-                -i \sin{(\phi/2)} & 0 & 0 & \cos{(\phi/2)}
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2570,7 +2391,7 @@ def _to_jaqcd(self, target: QubitSet) -> Any:
         return ir.YY.construct(targets=[target[0], target[1]], angle=self.angle)
 
     def to_matrix(self) -> np.ndarray:
-        r"""Returns a matrix representation of this gate.
+        """Returns a matrix representation of this gate.
         Returns:
             ndarray: The matrix representation of this gate.
         """
@@ -2604,14 +2425,7 @@ def yy(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{YY}(\phi) = \begin{bmatrix}
-                \cos{(\phi/2)} & 0 & 0 & i \sin{(\phi/2)} \\
-                0 & \cos{(\phi/2)} & -i \sin{(\phi/2)} & 0 \\
-                0 & -i \sin{(\phi/2)} & \cos{(\phi/2)} & 0 \\
-                i \sin{(\phi/2)} & 0 & 0 & \cos{(\phi/2)}
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2710,14 +2524,7 @@ def zz(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{ZZ}(\phi) = \begin{bmatrix}
-                e^{-i\phi/2} & 0 & 0 & 0 \\
-                0 & e^{i\phi/2} & 0 & 0 \\
-                0 & 0 & e^{i\phi/2} & 0 \\
-                0 & 0 & 0 & e^{-i\phi/2}
-            \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2815,18 +2622,7 @@ def ccnot(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CCNOT} = \begin{bmatrix}
-                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
-                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
-                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control1 (QubitInput): Control qubit 1 index.
@@ -2920,18 +2716,7 @@ def cswap(
         target2: QubitInput,
         power: float = 1,
     ) -> Instruction:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{CSWAP} = \begin{bmatrix}
-                1 & 0 & 0 & 0 & 0 & 0 & 0 & 0 \\
-                0 & 1 & 0 & 0 & 0 & 0 & 0 & 0  \\
-                0 & 0 & 1 & 0 & 0 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 1 & 0 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 1 & 0 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 0 & 1 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 1 & 0 & 0 \\
-                0 & 0 & 0 & 0 & 0 & 0 & 0 & 1 \\
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -3014,12 +2799,7 @@ def gpi(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{GPi}(\phi) = \begin{bmatrix}
-                0 & e^{-i \phi} \\
-                e^{i \phi} & 0
-                \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -3105,12 +2885,7 @@ def gpi2(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: \mathtt{GPi2}(\phi) = \begin{bmatrix}
-                1 & -i e^{-i \phi} \\
-                -i e^{i \phi} & 1
-            \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -3237,18 +3012,7 @@ def ms(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        r"""Registers this function into the circuit class.
-
-        .. math:: &\mathtt{MS}(\phi_0, \phi_1, \theta) =\\ &\begin{bmatrix}
-                    \cos{\frac{\theta}{2}} & 0 &
-                    0 & -ie^{-i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} \\
-                    0 & \cos{\frac{\theta}{2}} &
-                    -ie^{-i (\phi_0 - \phi_1)}\sin{\frac{\theta}{2}} & 0 \\
-                    0 & -ie^{i (\phi_0 - \phi_1)}\sin{\frac{\theta}{2}} &
-                    \cos{\frac{\theta}{2}} & 0 \\
-                    -ie^{i (\phi_0 + \phi_1)}\sin{\frac{\theta}{2}} & 0
-                    & 0 & \cos{\frac{\theta}{2}}
-                    \end{bmatrix}.
+        """Registers this function into the circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -3351,7 +3115,7 @@ def _transform_matrix_to_ir(matrix: np.ndarray) -> list:
     @staticmethod
     @circuit.subroutine(register=True)
     def unitary(targets: QubitSet, matrix: np.ndarray, display_name: str = "U") -> Instruction:
-        r"""Registers this function into the circuit class.
+        """Registers this function into the circuit class.
 
         Args:
             targets (QubitSet): Target qubits.
@@ -3408,7 +3172,7 @@ def pulse_sequence(self) -> PulseSequence:
 
     @property
     def parameters(self) -> list[FreeParameter]:
-        r"""Returns the list of `FreeParameter` s associated with the gate."""
+        """Returns the list of `FreeParameter` s associated with the gate."""
         return list(self._pulse_sequence.parameters)
 
     def bind_values(self, **kwargs) -> PulseGate:

From cb6d54ca236e50b10bf5fc887a626e4a3922d076 Mon Sep 17 00:00:00 2001
From: Aaron Berdy <berdy@amazon.com>
Date: Tue, 14 Nov 2023 16:08:49 -0800
Subject: [PATCH 10/11] feat: insert class documentation into circuit
 subroutine

---
 src/braket/circuits/gates.py | 133 ++++++++++++++++++++++++-----------
 1 file changed, 93 insertions(+), 40 deletions(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index a9c68d339..c0fe42bed 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -13,7 +13,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from copy import deepcopy
 from typing import Any, Optional, Union
 
@@ -49,13 +49,25 @@
 """
 To add a new gate:
     1. Implement the class and extend `Gate`
-    2. Add a method with the `@circuit.subroutine(register=True)` decorator. Method name
+    2. Add a method with the `@circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)` decorator. Method name
        will be added into the `Circuit` class. This method is the default way
        clients add this gate to a circuit.
     3. Register the class with the `Gate` class via `Gate.register_gate()`.
 """
 
 
+def _prepend_docstring(source: str) -> Callable:
+    def _update_docstring(func: Callable) -> Callable:
+        doc_string = source
+        if arg_loc := source.find("\n    Args:"):
+            doc_string = source[:arg_loc]
+        func.__doc__ = "\n".join([doc_string, func.__doc__])
+        return func
+
+    return _update_docstring
+
+
 # Single qubit gates #
 
 
@@ -91,6 +103,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def h(
         target: QubitSetInput,
         *,
@@ -98,7 +111,7 @@ def h(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -163,6 +176,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def i(
         target: QubitSetInput,
         *,
@@ -170,7 +184,7 @@ def i(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -236,6 +250,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def x(
         target: QubitSetInput,
         *,
@@ -243,7 +258,7 @@ def x(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -309,6 +324,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def y(
         target: QubitSetInput,
         *,
@@ -316,7 +332,7 @@ def y(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -382,6 +398,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def z(
         target: QubitSetInput,
         *,
@@ -389,7 +406,7 @@ def z(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -455,6 +472,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def s(
         target: QubitSetInput,
         *,
@@ -462,7 +480,7 @@ def s(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -528,6 +546,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def si(
         target: QubitSetInput,
         *,
@@ -535,7 +554,7 @@ def si(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -601,6 +620,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def t(
         target: QubitSetInput,
         *,
@@ -608,7 +628,7 @@ def t(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -674,6 +694,8 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+
+    @_prepend_docstring(__doc__)
     def ti(
         target: QubitSetInput,
         *,
@@ -681,7 +703,7 @@ def ti(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -747,6 +769,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def v(
         target: QubitSetInput,
         *,
@@ -754,7 +777,7 @@ def v(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -820,6 +843,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def vi(
         target: QubitSetInput,
         *,
@@ -827,7 +851,7 @@ def vi(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s)
@@ -909,6 +933,7 @@ def bind_values(self, **kwargs) -> AngledGate:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def rx(
         target: QubitSetInput,
         angle: Union[FreeParameterExpression, float],
@@ -917,7 +942,7 @@ def rx(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -996,6 +1021,7 @@ def bind_values(self, **kwargs) -> AngledGate:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def ry(
         target: QubitSetInput,
         angle: Union[FreeParameterExpression, float],
@@ -1004,7 +1030,7 @@ def ry(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1080,6 +1106,8 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+
+    @_prepend_docstring(__doc__)
     def rz(
         target: QubitSetInput,
         angle: Union[FreeParameterExpression, float],
@@ -1088,7 +1116,7 @@ def rz(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1161,6 +1189,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def phaseshift(
         target: QubitSetInput,
         angle: Union[FreeParameterExpression, float],
@@ -1169,7 +1198,7 @@ def phaseshift(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -1252,8 +1281,9 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cnot(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1322,6 +1352,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def swap(
         target1: QubitInput,
         target2: QubitInput,
@@ -1330,7 +1361,7 @@ def swap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1407,6 +1438,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def iswap(
         target1: QubitInput,
         target2: QubitInput,
@@ -1415,7 +1447,7 @@ def iswap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1502,6 +1534,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def pswap(
         target1: QubitInput,
         target2: QubitInput,
@@ -1511,7 +1544,7 @@ def pswap(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1608,6 +1641,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def xy(
         target1: QubitInput,
         target2: QubitInput,
@@ -1617,7 +1651,7 @@ def xy(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -1694,13 +1728,14 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cphaseshift(
         control: QubitSetInput,
         target: QubitInput,
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1772,13 +1807,14 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cphaseshift00(
         control: QubitSetInput,
         target: QubitInput,
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1850,13 +1886,14 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cphaseshift01(
         control: QubitSetInput,
         target: QubitInput,
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -1928,13 +1965,14 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cphaseshift10(
         control: QubitSetInput,
         target: QubitInput,
         angle: Union[FreeParameterExpression, float],
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2007,8 +2045,9 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cv(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2077,8 +2116,9 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cy(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2139,8 +2179,9 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cz(control: QubitSetInput, target: QubitInput, power: float = 1) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2208,6 +2249,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def ecr(
         target1: QubitInput,
         target2: QubitInput,
@@ -2216,7 +2258,7 @@ def ecr(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2311,6 +2353,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def xx(
         target1: QubitInput,
         target2: QubitInput,
@@ -2320,7 +2363,7 @@ def xx(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2416,6 +2459,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def yy(
         target1: QubitInput,
         target2: QubitInput,
@@ -2425,7 +2469,7 @@ def yy(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2515,6 +2559,8 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+
+    @_prepend_docstring(__doc__)
     def zz(
         target1: QubitInput,
         target2: QubitInput,
@@ -2524,7 +2570,7 @@ def zz(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -2613,6 +2659,7 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def ccnot(
         control1: QubitInput,
         control2: QubitInput,
@@ -2622,7 +2669,7 @@ def ccnot(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control1 (QubitInput): Control qubit 1 index.
@@ -2710,13 +2757,14 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def cswap(
         control: QubitSetInput,
         target1: QubitInput,
         target2: QubitInput,
         power: float = 1,
     ) -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             control (QubitSetInput): Control qubit(s). The last control qubit
@@ -2791,6 +2839,7 @@ def bind_values(self, **kwargs) -> GPi:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def gpi(
         target: QubitSetInput,
         angle: Union[FreeParameterExpression, float],
@@ -2799,7 +2848,7 @@ def gpi(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -2877,6 +2926,7 @@ def bind_values(self, **kwargs) -> GPi2:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def gpi2(
         target: QubitSetInput,
         angle: Union[FreeParameterExpression, float],
@@ -2885,7 +2935,7 @@ def gpi2(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target (QubitSetInput): Target qubit(s).
@@ -3001,6 +3051,7 @@ def bind_values(self, **kwargs) -> MS:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def ms(
         target1: QubitInput,
         target2: QubitInput,
@@ -3012,7 +3063,7 @@ def ms(
         control_state: Optional[BasisStateInput] = None,
         power: float = 1,
     ) -> Iterable[Instruction]:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             target1 (QubitInput): Target qubit 1 index.
@@ -3114,8 +3165,9 @@ def _transform_matrix_to_ir(matrix: np.ndarray) -> list:
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def unitary(targets: QubitSet, matrix: np.ndarray, display_name: str = "U") -> Instruction:
-        """Registers this function into the circuit class.
+        """This method allows adding this gate within the Circuit class.
 
         Args:
             targets (QubitSet): Target qubits.
@@ -3172,7 +3224,7 @@ def pulse_sequence(self) -> PulseSequence:
 
     @property
     def parameters(self) -> list[FreeParameter]:
-        """Returns the list of `FreeParameter` s associated with the gate."""
+        r"""Returns the list of `FreeParameter` s associated with the gate."""
         return list(self._pulse_sequence.parameters)
 
     def bind_values(self, **kwargs) -> PulseGate:
@@ -3201,6 +3253,7 @@ def _to_openqasm(
 
     @staticmethod
     @circuit.subroutine(register=True)
+    @_prepend_docstring(__doc__)
     def pulse_gate(
         targets: QubitSet,
         pulse_sequence: PulseSequence,

From 1539c8fba820452b2036cf16ab157de098c28878 Mon Sep 17 00:00:00 2001
From: Aaron Berdy <berdy@amazon.com>
Date: Tue, 14 Nov 2023 16:18:14 -0800
Subject: [PATCH 11/11] lint

---
 src/braket/circuits/gates.py | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py
index c0fe42bed..c43d72ea2 100644
--- a/src/braket/circuits/gates.py
+++ b/src/braket/circuits/gates.py
@@ -694,7 +694,6 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
-
     @_prepend_docstring(__doc__)
     def ti(
         target: QubitSetInput,
@@ -1106,7 +1105,6 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
-
     @_prepend_docstring(__doc__)
     def rz(
         target: QubitSetInput,
@@ -2559,7 +2557,6 @@ def fixed_qubit_count() -> int:
 
     @staticmethod
     @circuit.subroutine(register=True)
-
     @_prepend_docstring(__doc__)
     def zz(
         target1: QubitInput,