diff --git a/qiskit/extensions/standard/h.py b/qiskit/extensions/standard/h.py index 49a11c5798ea..002bca37b813 100644 --- a/qiskit/extensions/standard/h.py +++ b/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], []) diff --git a/qiskit/extensions/standard/iden.py b/qiskit/extensions/standard/iden.py index affe473db801..bfcafe17d473 100644 --- a/qiskit/extensions/standard/iden.py +++ b/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], []) diff --git a/qiskit/extensions/standard/rx.py b/qiskit/extensions/standard/rx.py index acdbd6f3e782..c14335e654a8 100644 --- a/qiskit/extensions/standard/rx.py +++ b/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], []) diff --git a/qiskit/extensions/standard/ry.py b/qiskit/extensions/standard/ry.py index 5f9ed296fa8e..f9d86892e47c 100644 --- a/qiskit/extensions/standard/ry.py +++ b/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], []) diff --git a/qiskit/extensions/standard/rz.py b/qiskit/extensions/standard/rz.py index 57a639d296f1..f215c276a9a5 100644 --- a/qiskit/extensions/standard/rz.py +++ b/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], []) diff --git a/qiskit/extensions/standard/s.py b/qiskit/extensions/standard/s.py index 8ecf3dbc187e..cea199c41a22 100644 --- a/qiskit/extensions/standard/s.py +++ b/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], []) diff --git a/qiskit/extensions/standard/swap.py b/qiskit/extensions/standard/swap.py index 2fdabfc2225f..1cfce87a4840 100644 --- a/qiskit/extensions/standard/swap.py +++ b/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], []) diff --git a/qiskit/extensions/standard/t.py b/qiskit/extensions/standard/t.py index 5aa0745fdf14..dd05b7ca5d92 100644 --- a/qiskit/extensions/standard/t.py +++ b/qiskit/extensions/standard/t.py @@ -87,13 +87,57 @@ def to_matrix(self): @deprecate_arguments({'q': 'qubit'}) def t(self, qubit, *, q=None): # pylint: disable=invalid-name,unused-argument - """Apply T to qubit.""" + """Apply T gate to a specified qubit (qubit). + A T gate implements a pi/4 rotation of a qubit state vector about the + z axis of the Bloch sphere. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + + circuit = QuantumCircuit(1) + circuit.t(0) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + from qiskit.extensions.standard.t import TGate + TGate().to_matrix() + """ return self.append(TGate(), [qubit], []) @deprecate_arguments({'q': 'qubit'}) def tdg(self, qubit, *, q=None): # pylint: disable=unused-argument - """Apply Tdg to q.""" + """Apply Tdg gate to a specified qubit (qubit). + A Tdg gate implements a -pi/4 rotation of a qubit state vector about the + z axis of the Bloch sphere. It is the inverse of T-gate. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + + circuit = QuantumCircuit(1) + circuit.tdg(0) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + from qiskit.extensions.standard.t import TdgGate + TdgGate().to_matrix() + """ return self.append(TdgGate(), [qubit], []) diff --git a/qiskit/extensions/standard/u1.py b/qiskit/extensions/standard/u1.py index a8f0dad1e11f..014d24d90718 100644 --- a/qiskit/extensions/standard/u1.py +++ b/qiskit/extensions/standard/u1.py @@ -61,7 +61,7 @@ def inverse(self): return U1Gate(-self.params[0]) def to_matrix(self): - """Return a Numpy.array for the U3 gate.""" + """Return a Numpy.array for the U1 gate.""" lam = self.params[0] lam = float(lam) return numpy.array([[1, 0], [0, numpy.exp(1j * lam)]], dtype=complex) @@ -69,7 +69,30 @@ def to_matrix(self): @deprecate_arguments({'q': 'qubit'}) def u1(self, theta, qubit, *, q=None): # pylint: disable=invalid-name,unused-argument - """Apply u1 with angle theta to qubit.""" + """Apply U1 gate with angle theta to a specified qubit (qubit). + u1(λ) := diag(1, eiλ) ∼ U(0, 0, λ) = Rz(λ) where ~ is equivalence up to a global phase. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit.circuit import QuantumCircuit, Parameter + + theta = Parameter('θ') + circuit = QuantumCircuit(1) + circuit.u1(theta,0) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + import numpy + from qiskit.extensions.standard.u1 import U1Gate + U1Gate(numpy.pi/2).to_matrix() + """ return self.append(U1Gate(theta), [qubit], []) @@ -115,7 +138,23 @@ def inverse(self): 'tgt': 'target_qubit'}) def cu1(self, theta, control_qubit, target_qubit, *, ctl=None, tgt=None): # pylint: disable=unused-argument - """Apply cu1 from ctl to tgt with angle theta.""" + """Apply cU1 gate from a specified control (control_qubit) to target (target_qubit) qubit + with angle theta. A cU1 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.cu1(theta,0,1) + circuit.draw() + """ return self.append(Cu1Gate(theta), [control_qubit, target_qubit], []) diff --git a/qiskit/extensions/standard/u2.py b/qiskit/extensions/standard/u2.py index 20881b070910..50fcf4b35c13 100644 --- a/qiskit/extensions/standard/u2.py +++ b/qiskit/extensions/standard/u2.py @@ -47,7 +47,7 @@ def inverse(self): return U2Gate(-self.params[1] - pi, -self.params[0] + pi) def to_matrix(self): - """Return a Numpy.array for the U3 gate.""" + """Return a Numpy.array for the U2 gate.""" isqrt2 = 1 / numpy.sqrt(2) phi, lam = self.params phi, lam = float(phi), float(lam) @@ -61,7 +61,31 @@ def to_matrix(self): @deprecate_arguments({'q': 'qubit'}) def u2(self, phi, lam, qubit, *, q=None): # pylint: disable=invalid-name,unused-argument - """Apply u2 to qubit.""" + """Apply U2 gate with angle phi and lam to a specified qubit (qubit). + u2(φ,λ) := U(π/2,φ,λ) = Rz(φ + π/2)Rx(π/2)Rz(λ − π/2) + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit.circuit import QuantumCircuit, Parameter + + phi = Parameter('φ') + lam = Parameter('λ') + circuit = QuantumCircuit(1) + circuit.u2(phi,lam,0) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + import numpy + from qiskit.extensions.standard.u2 import U2Gate + U2Gate(numpy.pi/2,numpy.pi/2).to_matrix() + """ return self.append(U2Gate(phi, lam), [qubit], []) diff --git a/qiskit/extensions/standard/u3.py b/qiskit/extensions/standard/u3.py index 526d9aaefa2e..3a4449a69b28 100644 --- a/qiskit/extensions/standard/u3.py +++ b/qiskit/extensions/standard/u3.py @@ -71,7 +71,32 @@ def to_matrix(self): @deprecate_arguments({'q': 'qubit'}) def u3(self, theta, phi, lam, qubit, *, q=None): # pylint: disable=invalid-name,unused-argument - """Apply u3 to qubit.""" + """Apply U3 gate with angle theta, phi, and lam to a specified qubit (qubit). + u3(θ, φ, λ) := U(θ, φ, λ) = Rz(φ + 3π)Rx(π/2)Rz(θ + π)Rx(π/2)Rz(λ) + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit.circuit import QuantumCircuit, Parameter + + theta = Parameter('theta') + phi = Parameter('φ') + lam = Parameter('λ') + circuit = QuantumCircuit(1) + circuit.u3(theta,phi,lam,0) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + import numpy + from qiskit.extensions.standard.u3 import U3Gate + U3Gate(numpy.pi/2,numpy.pi/2,numpy.pi/2).to_matrix() + """ return self.append(U3Gate(theta, phi, lam), [qubit], []) @@ -122,7 +147,26 @@ def inverse(self): 'tgt': 'target_qubit'}) def cu3(self, theta, phi, lam, control_qubit, target_qubit, *, ctl=None, tgt=None): # pylint: disable=unused-argument - """Apply cu3 from ctl to tgt with angle theta, phi, lam.""" + """Apply cU3 gate from a specified control (control_qubit) to target (target_qubit) qubit + with angle theta, phi, and lam. + A cU3 gate implements a U3(theta,phi,lam) on the target qubit when the + control qubit is in state |1>. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit.circuit import QuantumCircuit, Parameter + + theta = Parameter('θ') + phi = Parameter('φ') + lam = Parameter('λ') + circuit = QuantumCircuit(2) + circuit.cu3(theta,phi,lam,0,1) + circuit.draw() + """ return self.append(Cu3Gate(theta, phi, lam), [control_qubit, target_qubit], []) diff --git a/qiskit/extensions/standard/x.py b/qiskit/extensions/standard/x.py index 1bcd8d5ab2fe..93457b083fb3 100644 --- a/qiskit/extensions/standard/x.py +++ b/qiskit/extensions/standard/x.py @@ -75,7 +75,31 @@ def to_matrix(self): @deprecate_arguments({'q': 'qubit'}) def x(self, qubit, *, q=None): # pylint: disable=unused-argument - """Apply X to qubit.""" + """Apply X gate to a specified qubit (qubit). + An X gate implements a pi rotation of the qubit state vector about the + x axis of the Bloch sphere. + This gate is canonically used to implement a bit flip on the qubit state from |0⟩ to |1⟩, + or vice versa. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + + circuit = QuantumCircuit(1) + circuit.x(0) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + from qiskit.extensions.standard.x import XGate + XGate().to_matrix() + """ return self.append(XGate(), [qubit], []) @@ -120,7 +144,31 @@ def to_matrix(self): 'tgt': 'target_qubit'}) def cx(self, control_qubit, target_qubit, # pylint: disable=invalid-name *, ctl=None, tgt=None): # pylint: disable=unused-argument - """Apply CX from ctl to tgt.""" + """Apply CX gate from a specified control (control_qubit) to target (target_qubit) qubit. + A CX gate implements a pi rotation of the qubit state vector about the x axis + of the Bloch sphere when the control qubit is in state |1>. + This gate is canonically used to implement a bit flip on the qubit state from |0⟩ to |1⟩, + or vice versa when the control qubit is in state |1>. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + + circuit = QuantumCircuit(2) + circuit.cx(0,1) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + from qiskit.extensions.standard.cx import CnotGate + CnotGate().to_matrix() + """ return self.append(CnotGate(), [control_qubit, target_qubit], []) @@ -192,7 +240,29 @@ def to_matrix(self): 'tgt': 'target_qubit'}) def ccx(self, control_qubit1, control_qubit2, target_qubit, *, ctl1=None, ctl2=None, tgt=None): # pylint: disable=unused-argument - """Apply Toffoli to ctl1 and ctl2 to tgt.""" + """Apply Toffoli (ccX) gate from two specified controls (control_qubit1 and control_qubit2) + to target (target_qubit) qubit. This gate is canonically used to rotate the qubit state from + |0⟩ to |1⟩, or vice versa when both the control qubits are in state |1>. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + + circuit = QuantumCircuit(3) + circuit.ccx(0,1,2) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + from qiskit.extensions.standard.x import ToffoliGate + ToffoliGate().to_matrix() + """ return self.append(ToffoliGate(), [control_qubit1, control_qubit2, target_qubit], []) diff --git a/qiskit/extensions/standard/y.py b/qiskit/extensions/standard/y.py index a65013c1079a..25f85bd34586 100644 --- a/qiskit/extensions/standard/y.py +++ b/qiskit/extensions/standard/y.py @@ -68,7 +68,31 @@ def to_matrix(self): @deprecate_arguments({'q': 'qubit'}) def y(self, qubit, *, q=None): # pylint: disable=unused-argument - """Apply Y to qubit.""" + """Apply Y gate to a specified qubit (qubit). + A Y gate implements a pi rotation of the qubit state vector about the + y axis of the Bloch sphere. + This gate is canonically used to implement a bit flip and phase flip on the qubit state + from |0⟩ to i|1⟩, or from |1> to -i|0>. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + + circuit = QuantumCircuit(1) + circuit.y(0) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + from qiskit.extensions.standard.y import YGate + YGate().to_matrix() + """ return self.append(YGate(), [qubit], []) @@ -110,7 +134,24 @@ def inverse(self): 'tgt': 'target_qubit'}) def cy(self, control_qubit, target_qubit, # pylint: disable=invalid-name *, ctl=None, tgt=None): # pylint: disable=unused-argument - """Apply CY to circuit.""" + """Apply cY gate from a specified control (control_qubit) to target (target_qubit) qubit. + A cY gate implements a pi rotation of the qubit state vector about the y axis + of the Bloch sphere when the control qubit is in state |1>. + This gate is canonically used to implement a bit flip and phase flip on the qubit state + from |0⟩ to i|1⟩, or from |1> to -i|0> when the control qubit is in state |1>. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + + circuit = QuantumCircuit(2) + circuit.cy(0,1) + circuit.draw() + """ return self.append(CyGate(), [control_qubit, target_qubit], []) diff --git a/qiskit/extensions/standard/z.py b/qiskit/extensions/standard/z.py index 338d6eae6b8c..2c970b8781f5 100644 --- a/qiskit/extensions/standard/z.py +++ b/qiskit/extensions/standard/z.py @@ -68,7 +68,31 @@ def to_matrix(self): @deprecate_arguments({'q': 'qubit'}) def z(self, qubit, *, q=None): # pylint: disable=unused-argument - """Apply Z to qubit.""" + """Apply Z gate to a specified qubit (qubit). + A Z gate implements a pi rotation of the qubit state vector about the + z axis of the Bloch sphere. + This gate is canonically used to implement a phase flip on the qubit state from |+⟩ to |-⟩, + or vice versa. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + + circuit = QuantumCircuit(1) + circuit.z(0) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + from qiskit.extensions.standard.z import ZGate + ZGate().to_matrix() + """ return self.append(ZGate(), [qubit], []) @@ -111,11 +135,37 @@ def to_matrix(self): [0, 0, 1, 0], [0, 0, 0, -1]], dtype=complex) + @deprecate_arguments({'ctl': 'control_qubit', 'tgt': 'target_qubit'}) def cz(self, control_qubit, target_qubit, # pylint: disable=invalid-name *, ctl=None, tgt=None): # pylint: disable=unused-argument - """Apply CZ to circuit.""" + """Apply cZ gate from a specified control (control_qubit) to target (target_qubit) qubit. + A cZ gate implements a pi rotation of the qubit state vector about the z axis + of the Bloch sphere when the control qubit is in state |1>. + This gate is canonically used to implement a phase flip on the qubit state from |+⟩ to |-⟩, + or vice versa when the control qubit is in state |1>. + + Examples: + + Circuit Representation: + + .. jupyter-execute:: + + from qiskit import QuantumCircuit + import numpy + + circuit = QuantumCircuit(2) + circuit.cz(0,1) + circuit.draw() + + Matrix Representation: + + .. jupyter-execute:: + + from qiskit.extensions.standard.cz import CzGate + CzGate().to_matrix() + """ return self.append(CzGate(), [control_qubit, target_qubit], []) diff --git a/releasenotes/notes/fix3400_quantum_methods-e822a1247329f927.yaml b/releasenotes/notes/fix3400_quantum_methods-e822a1247329f927.yaml new file mode 100644 index 000000000000..519db8b485a3 --- /dev/null +++ b/releasenotes/notes/fix3400_quantum_methods-e822a1247329f927.yaml @@ -0,0 +1,6 @@ +--- +fixes: + - | + Explanation and examples have been added to QuantumCircuit methods for these gates (ccx, ch, crz, cswap, cu1, cu3, cx, cy, cz, h, iden, rx, ry, rz, s, sdg, swap, t, tdg, u1, u2, u3, x, y, z). + Fixes `issue #3400 ` +