Explanation and examples added for various QuantumCircuit methods Fixes #3400

qiskit/extensions/standard/h.py

@@ -72,7 +72,29 @@ def to_matrix(self):
 
 @deprecate_arguments({'q': 'qubit'})
 def h(self, qubit, *, q=None):  # pylint: disable=invalid-name,unused-argument
-    """Apply H to q."""
+    """Apply Hadamard (H) gate to a specified qubit (qubit).
+    An H gate implements a rotation of pi about the axis (x + z)/sqrt(2) on the Bloch sphere.
+    This gate is canonically used to rotate the qubit state from |0⟩ to |+⟩ or |1⟩ to |-⟩.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit import QuantumCircuit
+
+            circuit = QuantumCircuit(1)
+            circuit.h(0)
+            circuit.draw()
+
+        Matrix Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.extensions.standard.h import HGate
+            HGate().to_matrix()
+    """
     return self.append(HGate(), [qubit], [])
 
 
@@ -132,7 +154,29 @@ 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 from ctl to tgt."""
+    """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 |0⟩ to |+⟩ and and |1⟩ to |−⟩
+    when the control qubit is in state |1>.
+
+    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()
+    """
     return self.append(CHGate(), [control_qubit, target_qubit], [])
 
 

qiskit/extensions/standard/iden.py

@@ -44,10 +44,30 @@ def to_matrix(self):
 
 @deprecate_arguments({'q': 'qubit'})
 def iden(self, qubit, *, q=None):  # pylint: disable=unused-argument
-    """Apply Identity to qubit.
+    """Apply Identity to to a specified qubit (qubit).
 
-    Identity gate corresponds to a single-qubit gate wait cycle,
-    and should not be optimized or unrolled (it is an opaque gate).
+    The Identity gate ensures that nothing is applied to a qubit for one unit
+    of gate time. It leaves the quantum states |0> and |1> 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.iden(0)
+            circuit.draw()
+
+        Matrix Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.extensions.standard.iden import IdGate
+            IdGate().to_matrix()
     """
     return self.append(IdGate(), [qubit], [])
 

qiskit/extensions/standard/rx.py

@@ -77,7 +77,31 @@ def to_matrix(self):
 
 @deprecate_arguments({'q': 'qubit'})
 def rx(self, theta, qubit, *, q=None):  # pylint: disable=invalid-name,unused-argument
-    """Apply Rx to q."""
+    """Apply Rx gate with angle theta to a specified qubit (qubit).
+    An Rx gate implements a theta radian rotation of the qubit state vector about the
+    x axis of the Bloch sphere.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.circuit import QuantumCircuit, Parameter
+
+            theta = Parameter('θ')
+            circuit = QuantumCircuit(1)
+            circuit.rx(theta,0)
+            circuit.draw()
+
+        Matrix Representation:
+
+        .. jupyter-execute::
+
+            import numpy
+            from qiskit.extensions.standard.rx import RXGate
+            RXGate(numpy.pi/2).to_matrix()
+    """
     return self.append(RXGate(theta), [qubit], [])
 
 

qiskit/extensions/standard/ry.py

@@ -77,7 +77,31 @@ def to_matrix(self):
 
 @deprecate_arguments({'q': 'qubit'})
 def ry(self, theta, qubit, *, q=None):  # pylint: disable=invalid-name,unused-argument
-    """Apply Ry to qubit."""
+    """Apply Ry gate with angle theta to a specified qubit (qubit).
+    An Ry gate implements a theta radian rotation of the qubit state vector about the
+    y axis of the Bloch sphere.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.circuit import QuantumCircuit, Parameter
+
+            theta = Parameter('θ')
+            circuit = QuantumCircuit(1)
+            circuit.ry(theta,0)
+            circuit.draw()
+
+        Matrix Representation:
+
+        .. jupyter-execute::
+
+            import numpy
+            from qiskit.extensions.standard.ry import RYGate
+            RYGate(numpy.pi/2).to_matrix()
+    """
     return self.append(RYGate(theta), [qubit], [])
 
 

qiskit/extensions/standard/rz.py

@@ -67,7 +67,23 @@ def inverse(self):
 
 @deprecate_arguments({'q': 'qubit'})
 def rz(self, phi, qubit, *, q=None):  # pylint: disable=invalid-name,unused-argument
-    """Apply Rz to qubit."""
+    """Apply Rz gate with angle phi to a specified qubit (qubit).
+    An Rz gate implemements a phi radian rotation of the qubit state vector about the
+    z axis of the Bloch sphere.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.circuit import QuantumCircuit, Parameter
+
+            phi = Parameter('φ')
+            circuit = QuantumCircuit(1)
+            circuit.rz(phi,0)
+            circuit.draw()
+    """
     return self.append(RZGate(phi), [qubit], [])
 
 
@@ -111,7 +127,23 @@ def inverse(self):
 @deprecate_arguments({'ctl': 'control_qubit', 'tgt': 'target_qubit'})
 def crz(self, theta, control_qubit, target_qubit,
         *, ctl=None, tgt=None):  # pylint: disable=unused-argument
-    """Apply crz from ctl to tgt with angle theta."""
+    """Apply cRz gate from a specified control (control_qubit) to target (target_qubit) qubit
+    with angle theta. A cRz gate implements a theta radian rotation of the qubit state vector
+    about the z axis of the Bloch sphere when the control qubit is in state |1>.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.circuit import QuantumCircuit, Parameter
+
+            theta = Parameter('θ')
+            circuit = QuantumCircuit(2)
+            circuit.crz(theta,0,1)
+            circuit.draw()
+    """
     return self.append(CrzGate(theta), [control_qubit, target_qubit], [])
 
 

qiskit/extensions/standard/s.py

@@ -87,13 +87,57 @@ def to_matrix(self):
 
 @deprecate_arguments({'q': 'qubit'})
 def s(self, qubit, *, q=None):  # pylint: disable=invalid-name,unused-argument
-    """Apply S to qubit."""
+    """Apply S gate to a specified qubit (qubit).
+    An S gate implements a pi/2 rotation of the qubit state vector about the
+    z axis of the Bloch sphere.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit import QuantumCircuit
+
+            circuit = QuantumCircuit(1)
+            circuit.s(0)
+            circuit.draw()
+
+        Matrix Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.extensions.standard.s import SGate
+            SGate().to_matrix()
+    """
     return self.append(SGate(), [qubit], [])
 
 
 @deprecate_arguments({'q': 'qubit'})
 def sdg(self, qubit, *, q=None):  # pylint: disable=unused-argument
-    """Apply Sdg to qubit."""
+    """Apply Sdg gate to a specified qubit (qubit).
+    An Sdg gate implements a -pi/2 rotation of the qubit state vector about the
+    z axis of the Bloch sphere. It is the inverse of S gate.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit import QuantumCircuit
+
+            circuit = QuantumCircuit(1)
+            circuit.sdg(0)
+            circuit.draw()
+
+        Matrix Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.extensions.standard.s import SdgGate
+            SdgGate().to_matrix()
+    """
     return self.append(SdgGate(), [qubit], [])
 
 

qiskit/extensions/standard/swap.py

@@ -73,7 +73,28 @@ def to_matrix(self):
 
 
 def swap(self, qubit1, qubit2):
-    """Apply SWAP from qubit1 to qubit2."""
+    """Apply SWAP gate to a pair specified qubits (qubit1, qubit2).
+    The SWAP gate canonically swaps the states of two qubits.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit import QuantumCircuit
+
+            circuit = QuantumCircuit(2)
+            circuit.swap(0,1)
+            circuit.draw()
+
+        Matrix Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.extensions.standard.swap import SwapGate
+            SwapGate().to_matrix()
+    """
     return self.append(SwapGate(), [qubit1, qubit2], [])
 
 
@@ -112,13 +133,47 @@ def inverse(self):
         """Invert this gate."""
         return FredkinGate()  # self-inverse
 
+    def to_matrix(self):
+        """Return a Numpy.array for the Fredkin (CSWAP) gate."""
+        return numpy.array([[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, 0, 1, 0, 0],
+                            [0, 0, 0, 0, 1, 0, 0, 0],
+                            [0, 0, 0, 1, 0, 0, 0, 0],
+                            [0, 0, 0, 0, 0, 0, 1, 0],
+                            [0, 0, 0, 0, 0, 0, 0, 1]], dtype=complex)
+
 
 @deprecate_arguments({'ctl': 'control_qubit',
                       'tgt1': 'target_qubit1',
                       'tgt2': 'target_qubit2'})
 def cswap(self, control_qubit, target_qubit1, target_qubit2,
           *, ctl=None, tgt1=None, tgt2=None):  # pylint: disable=unused-argument
-    """Apply Fredkin to circuit."""
+    """Apply Fredkin (CSWAP) gate from a specified control (control_qubit) to target1
+    (target_qubit1) and target2 (target_qubit2) qubits. The CSWAP gate is canonically
+    used to swap the qubit states of target1 and target2 when the control qubit is in
+    state |1>.
+
+    Examples:
+
+        Circuit Representation:
+
+        .. jupyter-execute::
+
+            from qiskit import QuantumCircuit
+
+            circuit = QuantumCircuit(3)
+            circuit.cswap(0,1,2)
+            circuit.draw()
+
+        Matrix Representation:
+
+        .. jupyter-execute::
+
+            from qiskit.extensions.standard.swap import FredkinGate
+            FredkinGate().to_matrix()
+    """
     return self.append(FredkinGate(),
                        [control_qubit, target_qubit1, target_qubit2],
                        [])