Improve qiskit.circuit.QuantumCircuit page

qiskit/circuit/quantumcircuit.py

@@ -127,6 +127,34 @@ class QuantumCircuit:
         different regimes of quantum-circuit descriptions in Qiskit, see the module-level
         documentation of :mod:`qiskit.circuit`.
 
+    Example:
+
+    .. plot::
+       :include-source:
+       :nofigs:
+
+       from qiskit import QuantumCircuit
+
+       # Create a new circuit with two qubits
+       qc = QuantumCircuit(2)
+
+       # Add a Hadamard gate to qubit 0
+       qc.h(0)
+
+       # Perform a controlled-X gate on qubit 1, controlled by qubit 0
+       qc.cx(0, 1)
+
+       # Return a text drawing of the circuit.
+       qc.draw()
+
+    .. code-block:: text
+
+            ┌───┐
+       q_0: ┤ H ├──■──
+            └───┘┌─┴─┐
+       q_1: ─────┤ X ├
+                 └───┘
+
     Circuit attributes
     ==================
 
@@ -1079,7 +1107,32 @@ def __init__(
             regs = tuple(int(reg) for reg in regs)  # cast to int
         self._base_name = None
         self.name: str
-        """A human-readable name for the circuit."""
+        """A human-readable name for the circuit.
+
+        Example:
+
+            .. plot::
+                :include-source:
+                :nofigs:
+                :context: reset
+
+                from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+
+                qr = QuantumRegister(2)
+                cr = ClassicalRegister(2)
+                qc = QuantumCircuit(qr, cr)
+
+                qc.h(qr[0])
+                qc.cx(qr[0], qr[1])
+                qc.measure(qr, cr)
+                qc.name = "my_circuit"
+
+                print(qc.name)
+
+            .. code-block:: text
+
+                my_circuit
+        """
         if name is None:
             self._base_name = self._cls_prefix()
             self._name_update()
@@ -1150,10 +1203,31 @@ def __init__(
         self._duration = None
         self._unit = "dt"
         self.metadata = {} if metadata is None else metadata
-        """Arbitrary user-defined metadata for the circuit.
+        """Arbitrary user-defined dictionary of metadata for the circuit.
 
         Qiskit will not examine the content of this mapping, but it will pass it through the
-        transpiler and reattach it to the output, so you can track your own metadata."""
+        transpiler and reattach it to the output, so you can track your own metadata.
+
+        Example:
+
+            .. plot::
+                :include-source:
+                :nofigs:
+
+                from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+
+                q = QuantumRegister(2)
+                c = ClassicalRegister(2)
+                qc = QuantumCircuit(q, c)
+
+                qc.metadata = {'experiment_type': 'Bell state experiment'}
+
+                print(qc.metadata)
+
+            .. code-block:: text
+
+                {'experiment_type': 'Bell state experiment'}
+        """
 
     @property
     @deprecate_func(since="1.3.0", removal_timeline="in Qiskit 2.0.0", is_property=True)
@@ -1285,9 +1359,27 @@ def layout(self) -> Optional[TranspileLayout]:
     def data(self) -> QuantumCircuitData:
         """The circuit data (instructions and context).
 
-        Returns:
-            QuantumCircuitData: a list-like object containing the :class:`.CircuitInstruction`\\ s
-            for each instruction.
+        Example:
+
+            .. plot::
+                :include-source:
+                :nofigs:
+
+                from qiskit import QuantumCircuit
+
+                qc = QuantumCircuit(2, 2)
+                qc.measure([0], [1])
+                print(qc.data)
+
+            .. code-block:: text
+
+                [CircuitInstruction(operation=Instruction(name='measure', num_qubits=1,
+                num_clbits=1, params=[]), qubits=(Qubit(QuantumRegister(2, 'q'), 0),),
+                clbits=(Clbit(ClassicalRegister(2, 'c'), 1),))]
+
+            Returns:
+                QuantumCircuitData: a list-like object containing the :class:`.CircuitInstruction`\\ s
+                for each instruction.
         """
         return QuantumCircuitData(self)
 
@@ -1405,14 +1497,34 @@ def _has_calibration_for(self, instruction: CircuitInstruction | tuple):
 
     @property
     def metadata(self) -> dict:
-        """The user provided metadata associated with the circuit.
+        """The user-provided metadata associated with the circuit.
 
-        The metadata for the circuit is a user provided ``dict`` of metadata
+        The metadata for the circuit is a user-provided ``dict`` of metadata
         for the circuit. It will not be used to influence the execution or
         operation of the circuit, but it is expected to be passed between
-        all transforms of the circuit (ie transpilation) and that providers will
+        all transforms of the circuit (i.e., transpilation) and that providers will
         associate any circuit metadata with the results it returns from
         execution of that circuit.
+
+        Example:
+
+            .. plot::
+                :include-source:
+                :nofigs:
+
+                from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+
+                q = QuantumRegister(2)
+                c = ClassicalRegister(2)
+                qc = QuantumCircuit(q, c)
+
+                qc.metadata = {'experiment_type': 'Bell state experiment'}
+
+                print(qc.metadata)
+
+            .. code-block:: text
+
+               {'experiment_type': 'Bell state experiment'}
         """
         return self._metadata
 
@@ -2245,7 +2357,43 @@ def qubits(self) -> list[Qubit]:
     @property
     def clbits(self) -> list[Clbit]:
         """A list of :class:`Clbit`\\ s in the order that they were added.  You should not mutate
-        this."""
+        this.
+
+        Example:
+
+            .. plot::
+                :include-source:
+                :nofigs:
+                :context: reset
+
+                from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+
+                qr1 = QuantumRegister(2)
+                qr2 = QuantumRegister(1)
+                cr1 = ClassicalRegister(2)
+                cr2 = ClassicalRegister(1)
+                qc = QuantumCircuit(qr1, qr2, cr1, cr2)
+
+                print("List the quantum registers:", qc.qregs)
+                print("List the classical registers:", qc.cregs)
+                print("List the qubits in this circuit:", qc.qubits)
+                print("List the ancilla qubits:", qc.ancillas)
+                print("List the classical bits in this circuit:", qc.clbits)
+
+            .. code-block:: text
+
+                List the quantum registers: [QuantumRegister(2, 'q0'),
+                QuantumRegister(1, 'q1')]
+                List the classical registers: [ClassicalRegister(2, 'c0'),
+                ClassicalRegister(1, 'c1')]
+                List the qubits in this circuit: [Qubit(QuantumRegister(2,
+                'q0'), 0), Qubit(QuantumRegister(2, 'q0'), 1), Qubit
+                (QuantumRegister(1, 'q1'), 0)]
+                List the ancilla qubits: []
+                List the classical bits in this circuit: [Clbit
+                (ClassicalRegister(2, 'c0'), 0), Clbit(ClassicalRegister(2,
+                'c0'), 1), Clbit(ClassicalRegister(1, 'c1'), 0)]
+        """
         return self._data.clbits
 
     @property
@@ -4131,7 +4279,45 @@ def from_qasm_str(qasm_str: str) -> "QuantumCircuit":
 
     @property
     def global_phase(self) -> ParameterValueType:
-        """The global phase of the current circuit scope in radians."""
+        """The global phase of the current circuit scope in radians.
+
+        Example:
+
+            .. plot::
+                :include-source:
+                :nofigs:
+                :context: reset
+
+                from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
+
+                qreg_q = QuantumRegister(2, 'q')
+                creg_c = ClassicalRegister(2, 'c')
+                circuit = QuantumCircuit(qreg_q, creg_c)
+
+                circuit.h(qreg_q[0])
+                circuit.cx(qreg_q[0], qreg_q[1])
+
+                print(circuit.global_phase) # find the global phase of the current circuit
+
+            .. code-block:: text
+
+                0.0
+
+            .. plot::
+                :include-source:
+                :nofigs:
+                :context:
+
+                from numpy import pi
+
+                circuit.global_phase = pi/4 # set the global phase of the circuit to pi/4
+                print(circuit.global_phase)
+
+            .. code-block:: text
+
+                0.7853981633974483
+        """
+
         if self._control_flow_scopes:
             return self._control_flow_scopes[-1].global_phase
         return self._data.global_phase