Gate documentation overhaul

qiskit/extensions/__init__.py

@@ -45,6 +45,7 @@
    RYGate
    RZGate
    RZZGate
+   RZXGate
    SGate
    SdgGate
    SwapGate

qiskit/extensions/standard/__init__.py

@@ -27,6 +27,7 @@
 from .ryy import RYYGate
 from .rz import RZGate, CRZGate
 from .rzz import RZZGate
+from .rzx import RZXGate
 from .s import SGate, SdgGate
 from .swap import SwapGate, CSwapGate
 from .iswap import iSwapGate

qiskit/extensions/standard/dcx.py

@@ -40,7 +40,7 @@ class DCXGate(Gate):
 
     .. math::
 
-        DCX =
+        DCX\ q_0, q_1 =
             \begin{pmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 0 & 0 & 1 \\
@@ -50,6 +50,7 @@ class DCXGate(Gate):
     """
 
     def __init__(self):
+        """Create new DCX gate."""
         super().__init__('dcx', 2, [])
 
     def _define(self):
@@ -72,27 +73,7 @@ def to_matrix(self):
 
 
 def dcx(self, qubit1, qubit2):
-    """Apply DCX gate to a pair specified qubits (qubit1, qubit2).
-
-    Examples:
-
-        Circuit Representation:
-
-        .. jupyter-execute::
-
-            from qiskit import QuantumCircuit
-
-            circuit = QuantumCircuit(2)
-            circuit.dcx(0, 1)
-            print(circuit)
-            print(circuit.decompose())
-
-        Matrix Representation:
-
-        .. jupyter-execute::
-
-            from qiskit.extensions.standard.dcx import DCXGate
-            DCXGate().to_matrix()
+    """Apply :class:`~qiskit.extensions.standard.DCXGate`.
     """
     return self.append(DCXGate(), [qubit1, qubit2], [])
 

qiskit/extensions/standard/h.py

@@ -28,10 +28,33 @@
 
 # pylint: disable=cyclic-import
 class HGate(Gate):
-    """Hadamard gate."""
+    r"""Single-qubit Hadamard gate.
+
+    This gate is a \pi rotation about the X+Z axis, and has the effect of
+    changing computation basis from :math:`|0\rangle,|1\rangle` to
+    :math:`|+\rangle,|-\rangle` and vice-versa.
+
+    **Circuit symbol:**
+
+    .. parsed-literal::
+
+             ┌───┐
+        q_0: ┤ H ├
+             └───┘
+
+    **Matrix Representation:**
+
+    .. math::
+
+        H = \frac{1}{\sqrt{2}}
+            \begin{pmatrix}
+                1 & 1 \\
+                1 & -1
+            \end{pmatrix}
+    """
 
     def __init__(self, label=None):
-        """Create new Hadamard gate."""
+        """Create new H gate."""
         super().__init__('h', 1, [], label=label)
 
     def _define(self):
@@ -49,7 +72,9 @@ def _define(self):
         self.definition = definition
 
     def control(self, num_ctrl_qubits=1, label=None, ctrl_state=None):
-        """Controlled version of this gate.
+        """Return a (multi-)controlled-H gate.
+
+        One control qubit returns a CH gate.
 
         Args:
             num_ctrl_qubits (int): number of control qubits.
@@ -67,7 +92,7 @@ def control(self, num_ctrl_qubits=1, label=None, ctrl_state=None):
                                ctrl_state=ctrl_state)
 
     def inverse(self):
-        """Invert this gate."""
+        r"""Return inverted H gate (itself)."""
         return HGate()  # self-inverse
 
     def to_matrix(self):
@@ -78,43 +103,62 @@ def to_matrix(self):
 
 @deprecate_arguments({'q': 'qubit'})
 def h(self, qubit, *, q=None):  # pylint: disable=invalid-name,unused-argument
-    r"""Apply Hadamard (H) gate.
+    """Apply :class:`~qiskit.extensions.standard.HGate`."""
+    return self.append(HGate(), [qubit], [])
 
-    Applied to a specified qubit ``qubit``.
 
-    An H gate implements a rotation of :math:`\pi` about the axis
-    :math:`\frac{(x + z)}{\sqrt{2}}` on the Bloch sphere. This gate is
-    canonically used to rotate the qubit state from :math:`|0\rangle` to
-    :math:`|+\rangle` or :math:`|1\rangle` to :math:`|-\rangle`.
+QuantumCircuit.h = h
 
-    Examples:
 
-        Circuit Representation:
+class CHGate(ControlledGate):
+    r"""Controlled-Hadamard gate.
 
-        .. jupyter-execute::
+    Applies a Hadamard on the target qubit if the control is
+    in the :math:`|1\rangle` state.
 
-            from qiskit import QuantumCircuit
+    **Circuit symbol:**
 
-            circuit = QuantumCircuit(1)
-            circuit.h(0)
-            circuit.draw()
+    .. parsed-literal::
 
-        Matrix Representation:
+             ┌───┐
+        q_0: ┤ H ├
+             └─┬─┘
+        q_1: ──■──
 
-        .. jupyter-execute::
+    **Matrix Representation:**
 
-            from qiskit.extensions.standard.h import HGate
-            HGate().to_matrix()
+    .. math::
 
-    """
-    return self.append(HGate(), [qubit], [])
+        CH\ q_1, q_0 =
+            |0\rangle\langle 0| \otimes I + |1\rangle\langle 1| \otimes H =
+            \frac{1}{\sqrt{2}}
+            \begin{pmatrix}
+                1 & 0 & 0 & 0 \\
+                0 & 1 & 0 & 0 \\
+                0 & 0 & 1 & 1 \\
+                0 & 0 & 1 & -1
+            \end{pmatrix}
 
+    .. note::
 
-QuantumCircuit.h = h
+        In Qiskit's convention, higher qubit indices are more significant
+        (little endian convention). In many textbooks, controlled gates are
+        presented with the assumption of more significant qubits as control,
+        which is how we present the gate above as well, resulting in textbook
+        matrices. Instead, if we use q_0 as control, the matrix will be:
 
+        .. math::
 
-class CHGate(ControlledGate):
-    """The controlled-H gate."""
+            CH\ q_0, q_1 =
+                I \otimes |0\rangle\langle 0| + H \otimes |1\rangle\langle 1| =
+                \frac{1}{\sqrt{2}}
+                \begin{pmatrix}
+                    1 & 0 & 0 & 0 \\
+                    0 & 1 & 0 & 1 \\
+                    0 & 0 & 1 & 0 \\
+                    0 & 1 & 0 & -1
+                \end{pmatrix}
+    """
 
     def __init__(self):
         """Create new CH gate."""
@@ -150,7 +194,7 @@ def _define(self):
         self.definition = definition
 
     def inverse(self):
-        """Invert this gate."""
+        """Return inverted CH gate (itself)."""
         return CHGate()  # self-inverse
 
     def to_matrix(self):
@@ -165,32 +209,7 @@ def to_matrix(self):
 @deprecate_arguments({'ctl': 'control_qubit', 'tgt': 'target_qubit'})
 def ch(self, control_qubit, target_qubit,  # pylint: disable=invalid-name
        *, ctl=None, tgt=None):  # pylint: disable=unused-argument
-    """Apply cH gate
-
-    From a specified control ``control_qubit`` to target ``target_qubit`` qubit.
-    This gate is canonically used to rotate the qubit state from :math:`|0\\rangle` to
-    :math:`|+\\rangle` and :math:`|1\\rangle to :math:`|−\\rangle` when the control qubit is
-    in state :math:`|1\\rangle`.
-
-    Examples:
-
-        Circuit Representation:
-
-        .. jupyter-execute::
-
-            from qiskit import QuantumCircuit
-
-            circuit = QuantumCircuit(2)
-            circuit.ch(0,1)
-            circuit.draw()
-
-        Matrix Representation:
-
-        .. jupyter-execute::
-
-            from qiskit.extensions.standard.h import CHGate
-            CHGate().to_matrix()
-    """
+    """Apply :class:`~qiskit.extensions.standard.CHGate`."""
     return self.append(CHGate(), [control_qubit, target_qubit], [])
 
 

qiskit/extensions/standard/i.py

@@ -33,10 +33,26 @@ def __instancecheck__(mcs, inst):
 
 
 class IGate(Gate, metaclass=IMeta):
-    """Identity gate.
+    r"""Identity gate.
 
     Identity gate corresponds to a single-qubit gate wait cycle,
     and should not be optimized or unrolled (it is an opaque gate).
+
+    **Matrix Representation:**
+
+    .. math::
+
+        I = \begin{pmatrix}
+                1 & 0 \\
+                0 & 1
+            \end{pmatrix}
+
+    **Circuit symbol:**
+
+    .. parsed-literal::
+             ┌───┐
+        q_0: ┤ I ├
+             └───┘
     """
 
     def __init__(self, label=None):
@@ -66,32 +82,7 @@ def __init__(self):
 
 @deprecate_arguments({'q': 'qubit'})
 def i(self, qubit, *, q=None):  # pylint: disable=unused-argument
-    """Apply Identity to to a specified qubit ``qubit``.
-
-    The Identity gate ensures that nothing is applied to a qubit for one unit
-    of gate time. It leaves the quantum states :math:`|0\\rangle` and
-    :math:`|1\\rangle` unchanged. The Identity gate should not be optimized or
-    unrolled (it is an opaque gate).
-
-    Examples:
-
-        Circuit Representation:
-
-        .. jupyter-execute::
-
-            from qiskit import QuantumCircuit
-
-            circuit = QuantumCircuit(1)
-            circuit.id(0)  # or circuit.i(0)
-            circuit.draw()
-
-        Matrix Representation:
-
-        .. jupyter-execute::
-
-            from qiskit.extensions.standard.i import IGate
-            IGate().to_matrix()
-    """
+    """Apply :class:`~qiskit.extensions.standard.IGate`."""
     return self.append(IGate(), [qubit], [])
 
 

qiskit/extensions/standard/iswap.py

@@ -25,11 +25,21 @@
 class iSwapGate(Gate):
     r"""iSWAP gate.
 
-    A 2-qubit XY interaction that is equivalent to a SWAP up to a diagonal.
+    A 2-qubit XX+YY interaction.
     This is a Clifford and symmetric gate. Its action is to swap two qubit
     states and phase the :math:`|01\rangle` and :math:`|10\rangle`
     amplitudes by i.
 
+    **Circuit Symbol:**
+
+    .. parsed-literal::
+
+        q_0: ─⨂─
+              │
+        q_1: ─⨂─
+
+    **Reference Implementation:**
+
     .. parsed-literal::
 
              ┌───┐┌───┐     ┌───┐
@@ -38,16 +48,25 @@ class iSwapGate(Gate):
         q_1: ┤ S ├─────┤ X ├──■──┤ H ├
              └───┘     └───┘     └───┘
 
+    **Matrix Representation:**
+
     .. math::
 
-        iSWAP =
+        iSWAP = R_{XX+YY}(-\frac{\pi}{2})
+          = exp(i \frac{\pi}{4} (X{\otimes}X+Y{\otimes}Y)) =
             \begin{pmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 0 & i & 0 \\
                 0 & i & 0 & 0 \\
                 0 & 0 & 0 & 1
             \end{pmatrix}
-          = \begin{pmatrix}
+
+    This gate is equivalent to a SWAP up to a diagonal.
+
+    .. math::
+
+         iSWAP =
+            \begin{pmatrix}
                 1 & 0 & 0 & 0 \\
                 0 & 0 & 1 & 0 \\
                 0 & 1 & 0 & 0 \\
@@ -62,6 +81,7 @@ class iSwapGate(Gate):
     """
 
     def __init__(self):
+        """Create new iSwap gate."""
         super().__init__('iswap', 2, [])
 
     def _define(self):
@@ -97,25 +117,7 @@ def to_matrix(self):
 
 
 def iswap(self, qubit1, qubit2):
-    """Apply iSWAP gate to a pair specified qubits (qubit1, qubit2).
-
-    Examples:
-
-        Circuit Representation:
-
-        .. jupyter-execute::
-
-            from qiskit import QuantumCircuit
-
-            circuit = QuantumCircuit(2)
-            circuit.iswap(0,1)
-            circuit.draw()
-
-        .. jupyter-execute::
-
-            from qiskit.extensions.standard.iswap import iSwapGate
-            from qiskit.quantum_info import Operator
-            Operator(iSwapGate()).data
+    """Apply :class:`~qiskit.extensions.standard.iSwapGate`.
     """
     return self.append(iSwapGate(), [qubit1, qubit2], [])