From 0485562077c83eec9c2780f78c8ec44995d6d684 Mon Sep 17 00:00:00 2001 From: ykharkov <112575584+ykharkov@users.noreply.github.com> Date: Thu, 16 Nov 2023 11:02:29 -0500 Subject: [PATCH] doc: Add matrix expressions to docstrings (#756) * Add matrix expressions to docstrings * linter * fix r-strings * Capitalize H gate * Rename theta->phi * Address comments * Update src/braket/circuits/gates.py Co-authored-by: Ryan Shaffer <3620100+rmshaffer@users.noreply.github.com> * add matrices to subrountines * Remove [Registers this function into the circuit class] line from docstrings --------- Co-authored-by: Abe Coull <85974725+math411@users.noreply.github.com> Co-authored-by: Cody Wang Co-authored-by: Ryan Shaffer <3620100+rmshaffer@users.noreply.github.com> Co-authored-by: Abe Coull Co-authored-by: Aaron Berdy --- src/braket/circuits/gates.py | 719 +++++++++++++++++++++++++++++++---- 1 file changed, 639 insertions(+), 80 deletions(-) diff --git a/src/braket/circuits/gates.py b/src/braket/circuits/gates.py index dbc2e1a0b..9a4214c37 100644 --- a/src/braket/circuits/gates.py +++ b/src/braket/circuits/gates.py @@ -60,7 +60,14 @@ 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 +98,13 @@ def h( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Hadamard gate. + + Unitary matrix: + + .. math:: \mathtt{H} = \frac{1}{\sqrt{2}} \begin{bmatrix} + 1 & 1 \\ + 1 & -1 \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -125,7 +138,14 @@ 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"]) @@ -156,7 +176,13 @@ def i( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Identity gate. + + Unitary matrix: + + .. math:: \mathtt{I} = \begin{bmatrix} + 1 & 0 \\ + 0 & 1 \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -190,7 +216,15 @@ 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"]) @@ -221,7 +255,14 @@ def x( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Pauli-X gate. + + Unitary matrix: + + .. math:: \mathtt{X} = \begin{bmatrix} + 0 & 1 \\ + 1 & 0 + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -255,7 +296,15 @@ 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"]) @@ -286,7 +335,14 @@ def y( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Pauli-Y gate. + + Unitary matrix: + + .. math:: \mathtt{Y} = \begin{bmatrix} + 0 & -i \\ + i & 0 + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -320,7 +376,15 @@ 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"]) @@ -351,7 +415,12 @@ def z( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Pauli-Z gate. + + .. math:: \mathtt{Z} = \begin{bmatrix} + 1 & 0 \\ + 0 & -1 + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -385,7 +454,15 @@ 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"]) @@ -416,7 +493,12 @@ def s( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""S gate. + + .. math:: \mathtt{S} = \begin{bmatrix} + 1 & 0 \\ + 0 & i + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -450,7 +532,15 @@ 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"]) @@ -481,7 +571,12 @@ def si( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Conjugate transpose of S gate. + + .. math:: \mathtt{S}^\dagger = \begin{bmatrix} + 1 & 0 \\ + 0 & -i + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -515,7 +610,15 @@ 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"]) @@ -546,7 +649,12 @@ def t( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""T gate. + + .. math:: \mathtt{T} = \begin{bmatrix} + 1 & 0 \\ + 0 & e^{i \pi/4} + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -580,7 +688,15 @@ 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"]) @@ -611,7 +727,12 @@ def ti( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Conjugate transpose of T gate. + + .. math:: \mathtt{T}^\dagger = \begin{bmatrix} + 1 & 0 \\ + 0 & e^{-i \pi/4} + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -645,7 +766,15 @@ def ti( class V(Gate): - """Square root of not gate.""" + r"""Square root of X gate (V 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"]) @@ -676,7 +805,12 @@ def v( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Square root of X gate (V gate). + + .. math:: \mathtt{V} = \frac{1}{2}\begin{bmatrix} + 1+i & 1-i \\ + 1-i & 1+i + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s) @@ -710,7 +844,15 @@ def v( class Vi(Gate): - """Conjugate transpose of square root of not gate.""" + r"""Conjugate transpose of square root of X gate (conjugate transpose of V). + + 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"]) @@ -741,7 +883,12 @@ def vi( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Conjugate transpose of square root of X gate (conjugate transpose of V). + + .. 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) @@ -778,7 +925,14 @@ def vi( class Rx(AngledGate): - """X-axis rotation gate. + 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)} + \end{bmatrix}. Args: angle (Union[FreeParameterExpression, float]): angle in radians. @@ -799,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. """ @@ -824,7 +978,12 @@ def rx( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""X-axis rotation gate. + + .. 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). @@ -858,7 +1017,14 @@ def rx( class Ry(AngledGate): - """Y-axis rotation gate. + 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)} + \end{bmatrix}. Args: angle (Union[FreeParameterExpression, float]): angle in radians. @@ -879,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. """ @@ -904,7 +1070,12 @@ def ry( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Y-axis rotation gate. + + .. 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). @@ -923,6 +1094,7 @@ def ry( Returns: Iterable[Instruction]: Rx instruction. + Examples: >>> circ = Circuit().ry(0, 0.15) """ @@ -938,7 +1110,14 @@ 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. @@ -980,7 +1159,12 @@ def rz( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Z-axis rotation gate. + + .. 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). @@ -1014,7 +1198,14 @@ 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. @@ -1054,7 +1245,12 @@ def phaseshift( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""Phase shift gate. + + .. math:: \mathtt{PhaseShift}(\phi) = \begin{bmatrix} + 1 & 0 \\ + 0 & e^{i \phi} + \end{bmatrix} Args: target (QubitSetInput): Target qubit(s). @@ -1095,7 +1291,17 @@ 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"]) @@ -1128,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"""Controlled NOT gate. + + .. 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 @@ -1155,7 +1368,17 @@ 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"]) @@ -1195,7 +1418,14 @@ def swap( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Swap gate. + + .. 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. @@ -1230,7 +1460,17 @@ 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"]) @@ -1270,7 +1510,14 @@ def iswap( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""ISwap gate. + + .. 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. @@ -1305,7 +1552,16 @@ 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. @@ -1357,7 +1613,14 @@ def pswap( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""PSwap gate. + + .. 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. @@ -1393,10 +1656,20 @@ 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. """ @@ -1419,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. """ @@ -1453,7 +1726,14 @@ def xy( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""XY gate. + + .. 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. @@ -1489,7 +1769,16 @@ def xy( class CPhaseShift(AngledGate): - """Controlled phase shift gate. + r"""Controlled phase shift gate. + + Unitary matrix: + + .. 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: angle (Union[FreeParameterExpression, float]): angle in radians. @@ -1527,7 +1816,14 @@ def cphaseshift( angle: Union[FreeParameterExpression, float], power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Controlled phase shift gate. + + .. 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 @@ -1558,7 +1854,16 @@ 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. @@ -1596,7 +1901,14 @@ def cphaseshift00( angle: Union[FreeParameterExpression, float], power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Controlled phase shift gate for phasing the \|00> state. + + .. 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 @@ -1627,7 +1939,16 @@ 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} + 1 & 0 & 0 & 0 \\ + 0 & e^{i \phi} & 0 & 0 \\ + 0 & 0 & 1 & 0 \\ + 0 & 0 & 0 & 1 + \end{bmatrix}. Args: angle (Union[FreeParameterExpression, float]): angle in radians. @@ -1665,7 +1986,14 @@ def cphaseshift01( angle: Union[FreeParameterExpression, float], power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Controlled phase shift gate for phasing the \|01> state. + + .. 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 @@ -1696,7 +2024,16 @@ 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. @@ -1734,7 +2071,14 @@ def cphaseshift10( angle: Union[FreeParameterExpression, float], power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Controlled phase shift gate for phasing the \\|10> state. + + .. 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 @@ -1765,7 +2109,17 @@ def cphaseshift10( class CV(Gate): - """Controlled Sqrt of NOT gate.""" + r"""Controlled Sqrt of X 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"]) @@ -1798,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"""Controlled Sqrt of X gate. + + .. 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 @@ -1825,7 +2186,17 @@ 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"]) @@ -1858,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"""Controlled Pauli-Y gate. + + .. 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 @@ -1885,7 +2263,17 @@ 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"]) @@ -1910,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"""Controlled Pauli-Z gate. + + .. 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 @@ -1937,7 +2332,17 @@ 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"]) @@ -1976,7 +2381,14 @@ def ecr( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""An echoed RZX(pi/2) gate (ECR gate). + + .. 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. @@ -2011,7 +2423,16 @@ 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 @@ -2037,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. """ @@ -2071,7 +2492,14 @@ def xx( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Ising XX coupling gate. + + .. 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. @@ -2107,7 +2535,16 @@ 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 @@ -2133,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. """ @@ -2167,7 +2604,14 @@ def yy( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Ising YY coupling gate. + + .. 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. @@ -2203,7 +2647,16 @@ 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 @@ -2257,7 +2710,14 @@ def zz( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Ising ZZ coupling gate. + + .. 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. @@ -2296,7 +2756,21 @@ 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"]) @@ -2341,7 +2815,18 @@ def ccnot( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""CCNOT gate or Toffoli gate. + + .. 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. @@ -2379,7 +2864,21 @@ 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"]) @@ -2421,7 +2920,18 @@ def cswap( target2: QubitInput, power: float = 1, ) -> Instruction: - """Registers this function into the circuit class. + r"""Controlled Swap gate. + + .. 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 @@ -2452,7 +2962,14 @@ 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. @@ -2497,7 +3014,12 @@ def gpi( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""IonQ GPi gate. + + .. math:: \mathtt{GPi}(\phi) = \begin{bmatrix} + 0 & e^{-i \phi} \\ + e^{i \phi} & 0 + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s). @@ -2531,7 +3053,14 @@ 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. @@ -2576,7 +3105,12 @@ def gpi2( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""IonQ GPi2 gate. + + .. math:: \mathtt{GPi2}(\phi) = \begin{bmatrix} + 1 & -i e^{-i \phi} \\ + -i e^{i \phi} & 1 + \end{bmatrix}. Args: target (QubitSetInput): Target qubit(s). @@ -2610,12 +3144,26 @@ def gpi2( class MS(TripleAngledGate): - """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}} \\ + 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__( @@ -2689,7 +3237,18 @@ def ms( control_state: Optional[BasisStateInput] = None, power: float = 1, ) -> Iterable[Instruction]: - """Registers this function into the circuit class. + r"""IonQ Mølmer-Sørensen gate. + + .. 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. @@ -2729,7 +3288,7 @@ def ms( class Unitary(Gate): - """Arbitrary unitary gate + """Arbitrary unitary gate. Args: matrix (numpy.ndarray): Unitary matrix which defines the gate. @@ -2792,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"""Arbitrary unitary gate. Args: targets (QubitSet): Target qubits. @@ -2849,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: