docs: add quantum and qsystem gate definitions

guppylang/std/qsystem/__init__.py

@@ -17,6 +17,19 @@
 @guppy
 @no_type_check
 def phased_x(q: qubit, angle1: angle, angle2: angle) -> None:
+    r"""phased_x gate command.
+
+    .. math::
+
+        \mathrm{phased\_x}(q, \theta_1, \theta_2)=
+          \mathrm{Rz(\theta_2)Rx(\theta_1)Rz(\theta_2)}&=
+          \begin{pmatrix}
+          \cos(\frac{\pi \theta_1}{2}) &
+            -i e^{-i \pi \theta_2}\sin(\frac{\pi\theta_1}{2})\\
+          -i e^{i \pi \theta_2}\sin(\frac{\pi\theta_1}{2}) &
+            \cos(\frac{\pi \theta_1}{2})
+           \end{pmatrix}
+    """
     f1 = float(angle1)
     f2 = float(angle2)
     _phased_x(q, f1, f2)
@@ -25,30 +38,72 @@ def phased_x(q: qubit, angle1: angle, angle2: angle) -> None:
 @guppy
 @no_type_check
 def zz_max(q1: qubit, q2: qubit) -> None:
-    """Maximally entangling ZZPhase.
-
-    Equivalent to `zz_phase(q1, q2, pi / 2)`.
+    r"""zz_max gate command. A maximally entangling zz_phase gate.
+
+    This is a special case of the ZZPhase operation with angle = pi/2
+
+    .. math::
+        \mathrm{zz\_max}(q_1,q_2)=\mathrm{zz\_phase}(q_2,q_1,\pi/2)=
+        \exp(\frac{- i \pi}{4}\big(Z \otimes Z \big))=
+          \begin{pmatrix}
+            e^{\frac{-i \pi}{4}} & 0 & 0 & 0 \\
+            0 & e^{\frac{i \pi}{4}} & 0 & 0 \\
+            0 & 0 & e^{\frac{i \pi}{4}} & 0 \\
+            0 & 0 & 0 & e^{\frac{-i \pi}{4}}
+        \end{pmatrix}
     """
     zz_phase(q1, q2, pi / 2)
 
 
 @guppy
 @no_type_check
 def zz_phase(q1: qubit, q2: qubit, angle: angle) -> None:
+    r"""zz_phase gate command.
+
+    .. math::
+        \mathrm{zz\_phase}(q_1,q_2,\theta)=
+        \exp(\frac{- i \pi \theta}{2}\big(Z \otimes Z \big))=
+          \begin{pmatrix}
+            e^{\frac{-i \pi \theta}{2}} & 0 & 0 & 0 \\
+            0 & e^{\frac{i \pi \theta}{2}} & 0 & 0 \\
+            0 & 0 & e^{\frac{i \pi \theta}{2}} & 0 \\
+            0 & 0 & 0 & e^{\frac{-i \pi \theta}{2}}
+        \end{pmatrix}
+    >>> @guppy
+    ... def qsystem_cx(q1: qubit, q2: qubit) -> None:
+    ...     phased_x(angle(3/2), angle(-1/2), q2)
+    ...     zz_phase(q1, q2, angle(1/2))
+    ...     rz(angle(5/2), q1)
+    ...     phasedx(angle(-3/2), q1)
+    ...     rz(angle(3/2), q2)
+    >>> guppy.compile(qsystem_cx)
+    """
     f = float(angle)
     _zz_phase(q1, q2, f)
 
 
 @guppy
 @no_type_check
 def rz(q: qubit, angle: angle) -> None:
+    r"""rz gate command.
+
+    .. math::
+        \mathrm{rz}(q,\theta)=
+        \exp(\frac{- i \pi \theta}{2}\big(Z \big))=
+          \begin{pmatrix}
+            e^{\frac{-i \pi \theta}{2}} & 0  \\
+            0 & e^{\frac{i \pi \theta}{2}}
+        \end{pmatrix}
+    """
+
     f1 = float(angle)
     _rz(q, f1)
 
 
 @guppy.hugr_op(quantum_op("Measure", ext=QSYSTEM_EXTENSION))
 @no_type_check
-def measure(q: qubit @ owned) -> bool: ...
+def measure(q: qubit @ owned) -> bool:
+    """Measure a qubit destructively."""
 
 
 @guppy.custom(InoutMeasureResetCompiler("MeasureReset", QSYSTEM_EXTENSION))
@@ -59,7 +114,8 @@ def measure_and_reset(q: qubit) -> bool:
 
 @guppy.hugr_op(quantum_op("Reset", ext=QSYSTEM_EXTENSION))
 @no_type_check
-def reset(q: qubit) -> None: ...
+def reset(q: qubit) -> None:
+    """Reset a qubit to the |0> state."""
 
 
 # TODO
@@ -94,7 +150,7 @@ def _phased_x(q: qubit, angle1: float, angle2: float) -> None:
 def _zz_phase(q1: qubit, q2: qubit, angle: float) -> None:
     """ZZPhase operation from the qsystem extension.
 
-    See `guppylang.std.qsystem.phased_x` for a public definition that
+    See `guppylang.std.qsystem.zz_phase` for a public definition that
     accepts angle parameters.
     """
 

guppylang/std/qsystem/functional.py

@@ -1,3 +1,9 @@
+"""Guppy standard module for functional qsystem native operations. For the mathematical
+definitions of these gates, see the guppylang.std.qsystem documentation.
+
+These gates are the same as those in the std.qsystem but use functional syntax.
+"""
+
 from typing import no_type_check
 
 from guppylang.decorator import guppy
@@ -10,53 +16,61 @@
 @guppy
 @no_type_check
 def phased_x(q: qubit @ owned, angle1: angle, angle2: angle) -> qubit:
+    """Functional PhasedX gate command."""
     qsystem.phased_x(q, angle1, angle2)
     return q
 
 
 @guppy
 @no_type_check
 def zz_phase(q1: qubit @ owned, q2: qubit @ owned, angle: angle) -> tuple[qubit, qubit]:
+    """Functional ZZPhase gate command."""
     qsystem.zz_phase(q1, q2, angle)
     return q1, q2
 
 
 @guppy
 @no_type_check
 def measure_and_reset(q: qubit @ owned) -> tuple[qubit, bool]:
+    """Functional measure_and_reset command."""
     b = qsystem.measure_and_reset(q)
     return q, b
 
 
 @guppy
 @no_type_check
 def zz_max(q1: qubit @ owned, q2: qubit @ owned) -> tuple[qubit, qubit]:
+    """Functional ZZMax gate command."""
     qsystem.zz_max(q1, q2)
     return q1, q2
 
 
 @guppy
 @no_type_check
 def rz(q: qubit @ owned, angle: angle) -> qubit:
+    """Functional Rz gate command."""
     qsystem.rz(q, angle)
     return q
 
 
 @guppy
 @no_type_check
 def measure(q: qubit @ owned) -> bool:
+    """Functional destructive measurement command."""
     result = qsystem.measure(q)
     return result
 
 
 @guppy
 @no_type_check
 def qfree(q: qubit @ owned) -> None:
+    """Functional qfree command."""
     qsystem.qfree(q)
 
 
 @guppy
 @no_type_check
 def reset(q: qubit @ owned) -> qubit:
+    """Functional Reset command."""
     qsystem.reset(q)
     return q