diff --git a/qiskit/circuit/quantumcircuit.py b/qiskit/circuit/quantumcircuit.py index b637b5e4bb3..7dfc2a723cb 100644 --- a/qiskit/circuit/quantumcircuit.py +++ b/qiskit/circuit/quantumcircuit.py @@ -216,96 +216,18 @@ class QuantumCircuit: .. autoattribute:: data - 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),))] - Alongside the :attr:`data`, the :attr:`global_phase` of a circuit can have some impact on its output, if the circuit is used to describe a :class:`.Gate` that may be controlled. This is measured in radians and is directly settable. .. autoattribute:: global_phase - 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 - The :attr:`name` of a circuit becomes the name of the :class:`~.circuit.Instruction` or :class:`.Gate` resulting from :meth:`to_instruction` and :meth:`to_gate` calls, which can be handy for visualizations. .. autoattribute:: name - 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 - You can attach arbitrary :attr:`metadata` to a circuit. No part of core Qiskit will inspect this or change its behavior based on metadata, but it will be faithfully passed through the transpiler, so you can tag your circuits yourself. When serializing a circuit with QPY (see @@ -315,26 +237,6 @@ class QuantumCircuit: .. autoattribute:: 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'} - :class:`QuantumCircuit` exposes data attributes tracking its internal quantum and classical bits and registers. These appear as Python :class:`list`\\ s, but you should treat them as immutable; changing them will *at best* have no effect, and more likely will simply corrupt @@ -346,41 +248,6 @@ class QuantumCircuit: .. autoattribute:: ancillas .. autoattribute:: clbits - 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)] - The :ref:`compile-time parameters ` present in instructions on the circuit are available in :attr:`parameters`. This has a canonical order (mostly lexical, except in the case of :class:`.ParameterVector`), which matches the order that parameters will @@ -1240,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() @@ -1314,7 +1206,28 @@ def __init__( """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) @@ -1446,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) @@ -1574,6 +1505,26 @@ def metadata(self) -> dict: 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 @@ -2406,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 @@ -4292,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