QuantumCircuit

class QuantumCircuit(*regs, name=None, global_phase=0, metadata=None)

Bases: object

Create a new circuit.

A circuit is a list of instructions bound to some registers.

Parameters

• regs (list(Register) or list(int) or list(list(Bit))) –

  The registers to be included in the circuit.

  • If a list of Register objects, represents the QuantumRegister and/or ClassicalRegister objects to include in the circuit.

    For example:

    • QuantumCircuit(QuantumRegister(4))

    • QuantumCircuit(QuantumRegister(4), ClassicalRegister(3))

    • QuantumCircuit(QuantumRegister(4, 'qr0'), QuantumRegister(2, 'qr1'))

  • If a list of int, the amount of qubits and/or classical bits to include in the circuit. It can either be a single int for just the number of quantum bits, or 2 ints for the number of quantum bits and classical bits, respectively.

    For example:

    • QuantumCircuit(4) # A QuantumCircuit with 4 qubits

    • QuantumCircuit(4, 3) # A QuantumCircuit with 4 qubits and 3 classical bits

  • If a list of python lists containing Bit objects, a collection of Bit s to be added to the circuit.

• name (str) – the name of the quantum circuit. If not set, an automatically generated string will be assigned.

• global_phase (float or ParameterExpression) – The global phase of the circuit in radians.

• metadata (dict) – Arbitrary key value metadata to associate with the circuit. This gets stored as free-form data in a dict in the metadata attribute. It will not be directly used in the circuit.

Raises

CircuitError – if the circuit name, if given, is not valid.

Examples

Construct a simple Bell state circuit.

from qiskit import QuantumCircuit

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])
qc.draw()

     ┌───┐     ┌─┐   
q_0: ┤ H ├──■──┤M├───
     └───┘┌─┴─┐└╥┘┌─┐
q_1: ─────┤ X ├─╫─┤M├
          └───┘ ║ └╥┘
c: 2/═══════════╩══╩═
                0  1 

Construct a 5-qubit GHZ circuit.

from qiskit import QuantumCircuit

qc = QuantumCircuit(5)
qc.h(0)
qc.cx(0, range(1, 5))
qc.measure_all()

Construct a 4-qubit Bernstein-Vazirani circuit using registers.

from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit

qr = QuantumRegister(3, 'q')
anc = QuantumRegister(1, 'ancilla')
cr = ClassicalRegister(3, 'c')
qc = QuantumCircuit(qr, anc, cr)

qc.x(anc[0])
qc.h(anc[0])
qc.h(qr[0:3])
qc.cx(qr[0:3], anc[0])
qc.h(qr[0:3])
qc.barrier(qr)
qc.measure(qr, cr)

qc.draw()

           ┌───┐          ┌───┐           ░ ┌─┐      
      q_0: ┤ H ├───────■──┤ H ├───────────░─┤M├──────
           ├───┤       │  └───┘┌───┐      ░ └╥┘┌─┐   
      q_1: ┤ H ├───────┼────■──┤ H ├──────░──╫─┤M├───
           ├───┤       │    │  └───┘┌───┐ ░  ║ └╥┘┌─┐
      q_2: ┤ H ├───────┼────┼────■──┤ H ├─░──╫──╫─┤M├
           ├───┤┌───┐┌─┴─┐┌─┴─┐┌─┴─┐└───┘ ░  ║  ║ └╥┘
ancilla_0: ┤ X ├┤ H ├┤ X ├┤ X ├┤ X ├─────────╫──╫──╫─
           └───┘└───┘└───┘└───┘└───┘         ║  ║  ║ 
      c: 3/══════════════════════════════════╩══╩══╩═
                                             0  1  2 

Methods

add_bits	Add Bits to the circuit.
add_calibration	Register a low-level, custom pulse definition for the given gate.
add_register	Add registers.
append	Append one or more instructions to the end of the circuit, modifying the circuit in place.
assign_parameters	Assign parameters to new parameters or values.
barrier	Apply Barrier.
bind_parameters	Assign numeric parameters to values yielding a new circuit.
cast	Best effort to cast value to type.
cbit_argument_conversion	Converts several classical bit representations (such as indexes, range, etc.) into a list of classical bits.
ccx	Apply CCXGate.
ch	Apply CHGate.
cls_instances	Return the current number of instances of this class, useful for auto naming.
cls_prefix	Return the prefix to use for auto naming.
cnot	Apply CXGate.
combine	DEPRECATED - Returns rhs appended to self if self contains compatible registers.
compose	Compose circuit with other circuit or instruction, optionally permuting wires.
control	Control this circuit on num_ctrl_qubits qubits.
copy	Copy the circuit.
count_ops	Count each operation kind in the circuit.
cp	Apply CPhaseGate.
crx	Apply CRXGate.
cry	Apply CRYGate.
crz	Apply CRZGate.
cswap	Apply CSwapGate.
csx	Apply CSXGate.
cu	Apply CUGate.
cu1	Apply CU1Gate.
cu3	Apply CU3Gate.
cx	Apply CXGate.
cy	Apply CYGate.
cz	Apply CZGate.
dcx	Apply DCXGate.
decompose	Call a decomposition pass on this circuit, to decompose one level (shallow decompose).
delay	Apply Delay.
depth	Return circuit depth (i.e., length of critical path).
diagonal	Attach a diagonal gate to a circuit.
draw	Draw the quantum circuit.
ecr	Apply ECRGate.
extend	DEPRECATED - Append QuantumCircuit to the RHS if it contains compatible registers.
fredkin	Apply CSwapGate.
from_qasm_file	Take in a QASM file and generate a QuantumCircuit object.
from_qasm_str	Take in a QASM string and generate a QuantumCircuit object.
get_instructions	Get instructions matching name.
h	Apply HGate.
hamiltonian	Apply hamiltonian evolution to qubits.
has_register	Test if this circuit has the register r.
i	Apply IGate.
id	Apply IGate.
initialize	Initialize qubits in a specific state.
inverse	Invert (take adjoint of) this circuit.
iso	Attach an arbitrary isometry from m to n qubits to a circuit.
isometry	Attach an arbitrary isometry from m to n qubits to a circuit.
iswap	Apply iSwapGate.
mcp	Apply MCPhaseGate.
mcrx	Apply Multiple-Controlled X rotation gate
mcry	Apply Multiple-Controlled Y rotation gate
mcrz	Apply Multiple-Controlled Z rotation gate
mct	Apply MCXGate.
mcu1	Apply MCU1Gate.
mcx	Apply MCXGate.
measure	Measure quantum bit into classical bit (tuples).
measure_active	Adds measurement to all non-idle qubits.
measure_all	Adds measurement to all qubits.
ms	Apply MSGate.
num_connected_components	How many non-entangled subcircuits can the circuit be factored to.
num_nonlocal_gates	Return number of non-local gates (i.e.
num_tensor_factors	Computes the number of tensor factors in the unitary (quantum) part of the circuit only.
num_unitary_factors	Computes the number of tensor factors in the unitary (quantum) part of the circuit only.
p	Apply PhaseGate.
pauli	Apply PauliGate.
power	Raise this circuit to the power of power.
qasm	Return OpenQASM string.
qbit_argument_conversion	Converts several qubit representations (such as indexes, range, etc.) into a list of qubits.
qubit_duration	Return the duration between the start and stop time of the first and last instructions, excluding delays, over the supplied qubits.
qubit_start_time	Return the start time of the first instruction, excluding delays, over the supplied qubits.
qubit_stop_time	Return the stop time of the last instruction, excluding delays, over the supplied qubits.
r	Apply RGate.
rcccx	Apply RC3XGate.
rccx	Apply RCCXGate.
remove_final_measurements	Removes final measurement on all qubits if they are present.
repeat	Repeat this circuit reps times.
reset	Reset q.
reverse_bits	Return a circuit with the opposite order of wires.
reverse_ops	Reverse the circuit by reversing the order of instructions.
rv	Apply RVGate.
rx	Apply RXGate.
rxx	Apply RXXGate.
ry	Apply RYGate.
ryy	Apply RYYGate.
rz	Apply RZGate.
rzx	Apply RZXGate.
rzz	Apply RZZGate.
s	Apply SGate.
save_amplitudes	Save complex statevector amplitudes.
save_amplitudes_squared	Save squared statevector amplitudes (probabilities).
save_density_matrix	Save the current simulator quantum state as a density matrix.
save_expectation_value	Save the expectation value of a Hermitian operator.
save_expectation_value_variance	Save the expectation value of a Hermitian operator.
save_matrix_product_state	Save the current simulator quantum state as a matrix product state.
save_probabilities	Save measurement outcome probabilities vector.
save_probabilities_dict	Save measurement outcome probabilities vector.
save_stabilizer	Save the current stabilizer simulator quantum state as a Clifford.
save_state	Save the current simulator quantum state.
save_statevector	Save the current simulator quantum state as a statevector.
save_statevector_dict	Save the current simulator quantum state as a statevector as a dict.
save_superop	Save the current state of the superop simulator.
save_unitary	Save the current state of the unitary simulator.
sdg	Apply SdgGate.
set_density_matrix	Set the density matrix state of the simulator.
set_matrix_product_state	Set the matrix product state of the simulator.
set_stabilizer	Set the Clifford stabilizer state of the simulator.
set_statevector	Set the statevector state of the simulator.
set_superop	Set the superop state of the simulator.
set_unitary	Set the state state of the simulator.
size	Returns total number of gate operations in circuit.
snapshot	Take a statevector snapshot of the internal simulator representation.
snapshot_density_matrix	Take a density matrix snapshot of simulator state.
snapshot_expectation_value	Take a snapshot of expectation value <O> of an Operator.
snapshot_probabilities	Take a probability snapshot of the simulator state.
snapshot_stabilizer	Take a stabilizer snapshot of the simulator state.
snapshot_statevector	Take a statevector snapshot of the simulator state.
squ	Decompose an arbitrary 2*2 unitary into three rotation gates.
swap	Apply SwapGate.
sx	Apply SXGate.
sxdg	Apply SXdgGate.
t	Apply TGate.
tdg	Apply TdgGate.
tensor	Tensor self with other.
to_gate	Create a Gate out of this circuit.
to_instruction	Create an Instruction out of this circuit.
toffoli	Apply CCXGate.
u	Apply UGate.
u1	Apply U1Gate.
u2	Apply U2Gate.
u3	Apply U3Gate.
uc	Attach a uniformly controlled gates (also called multiplexed gates) to a circuit.
ucrx	Attach a uniformly controlled (also called multiplexed) Rx rotation gate to a circuit.
ucry	Attach a uniformly controlled (also called multiplexed) Ry rotation gate to a circuit.
ucrz	Attach a uniformly controlled (also called multiplexed gates) Rz rotation gate to a circuit.
unitary	Apply unitary gate to q.
width	Return number of qubits plus clbits in circuit.
x	Apply XGate.
y	Apply YGate.
z	Apply ZGate.

Attributes

ancillas

Returns a list of ancilla bits in the order that the registers were added.

calibrations

Return calibration dictionary.

The custom pulse definition of a given gate is of the form

{‘gate_name’: {(qubits, params): schedule}}

clbits

Returns a list of classical bits in the order that the registers were added.

data

Return the circuit data (instructions and context).

Returns

a list-like object containing the tuples for the circuit’s data.

Each tuple is in the format (instruction, qargs, cargs), where instruction is an Instruction (or subclass) object, qargs is a list of Qubit objects, and cargs is a list of Clbit objects.

Return type

QuantumCircuitData

extension_lib = 'include "qelib1.inc";'

global_phase

Return the global phase of the circuit in radians.

header = 'OPENQASM 2.0;'

instances = 16

metadata

The user provided metadata associated with the circuit

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 associate any circuit metadata with the results it returns from execution of that circuit.

num_ancillas

Return the number of ancilla qubits.

num_clbits

Return number of classical bits.

num_parameters

Convenience function to get the number of parameter objects in the circuit.

num_qubits

Return number of qubits.

parameters

Convenience function to get the parameters defined in the parameter table.

prefix = 'circuit'

qubits

Returns a list of quantum bits in the order that the registers were added.