QuantumCircuit

class QuantumCircuit(*regs, name=None)[source]

Create a new circuit.

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

Parameters

  • regs –

    list(Register) or list(int) The registers to be included 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

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

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_0: ═══════════╩══╬═
                   ║ 
c_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 Berstein-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_0: ══════════════════════════════════╩══╬══╬═
                                                ║  ║ 
      c_1: ═════════════════════════════════════╩══╬═
                                                   ║ 
      c_2: ════════════════════════════════════════╩═

Attributes

QuantumCircuit.clbits

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

QuantumCircuit.data

Return the circuit data (instructions and context).

QuantumCircuit.extension_lib

QuantumCircuit.header

QuantumCircuit.instances

QuantumCircuit.n_qubits

Deprecated, use num_qubits instead.

QuantumCircuit.num_clbits

Return number of classical bits.

QuantumCircuit.num_parameters

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

QuantumCircuit.num_qubits

Return number of qubits.

QuantumCircuit.parameters

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

QuantumCircuit.prefix

QuantumCircuit.qubits

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

Methods

QuantumCircuit.AND(qr_variables, qb_target, …)

Build a collective conjunction (AND) circuit in place using mct.

QuantumCircuit.OR(qr_variables, qb_target, …)

Build a collective disjunction (OR) circuit in place using mct.

QuantumCircuit.__getitem__(item)

Return indexed operation.

QuantumCircuit.__len__()

Return number of operations in circuit.

QuantumCircuit.add_register(*regs)

Add registers.

QuantumCircuit.append(instruction[, qargs, …])

Append one or more instructions to the end of the circuit, modifying the circuit in place.

QuantumCircuit.assign_parameters(param_dict)

Assign parameters to new parameters or values.

QuantumCircuit.barrier(*qargs)

Apply Barrier.

QuantumCircuit.bind_parameters(value_dict)

Assign numeric parameters to values yielding a new circuit.

QuantumCircuit.cast(value, _type)

Best effort to cast value to type.

QuantumCircuit.cbit_argument_conversion(…)

Converts several classical bit representations (such as indexes, range, etc.) into a list of classical bits.

QuantumCircuit.ccx(control_qubit1, …[, …])

Apply CCXGate.

QuantumCircuit.ch(control_qubit, target_qubit, *)

Apply CHGate.

QuantumCircuit.cls_instances()

Return the current number of instances of this class, useful for auto naming.

QuantumCircuit.cls_prefix()

Return the prefix to use for auto naming.

QuantumCircuit.cnot(control_qubit, …[, …])

Apply CXGate.

QuantumCircuit.combine(rhs)

Append rhs to self if self contains compatible registers.

QuantumCircuit.compose(other[, qubits, …])

Compose circuit with other circuit or instruction, optionally permuting wires.

QuantumCircuit.copy([name])

Copy the circuit.

QuantumCircuit.count_ops()

Count each operation kind in the circuit.

QuantumCircuit.crx(theta, control_qubit, …)

Apply CRXGate.

QuantumCircuit.cry(theta, control_qubit, …)

Apply CRYGate.

QuantumCircuit.crz(theta, control_qubit, …)

Apply CRZGate.

QuantumCircuit.cswap(control_qubit, …[, …])

Apply CSwapGate.

QuantumCircuit.cu1(theta, control_qubit, …)

Apply CU1Gate.

QuantumCircuit.cu3(theta, phi, lam, …[, …])

Apply CU3Gate.

QuantumCircuit.cx(control_qubit, target_qubit, *)

Apply CXGate.

QuantumCircuit.cy(control_qubit, target_qubit, *)

Apply CYGate.

QuantumCircuit.cz(control_qubit, target_qubit, *)

Apply CZGate.

QuantumCircuit.dcx(qubit1, qubit2)

Apply DCXGate.

QuantumCircuit.decompose()

Call a decomposition pass on this circuit, to decompose one level (shallow decompose).

QuantumCircuit.depth()

Return circuit depth (i.e., length of critical path).

QuantumCircuit.diag_gate(diag, qubit)

Deprecated version of QuantumCircuit.diagonal.

QuantumCircuit.diagonal(diag, qubit)

Attach a diagonal gate to a circuit.

QuantumCircuit.draw([output, scale, …])

Draw the quantum circuit.

QuantumCircuit.extend(rhs)

Append QuantumCircuit to the right hand side if it contains compatible registers.

QuantumCircuit.fredkin(control_qubit, …[, …])

Apply CSwapGate.

QuantumCircuit.from_qasm_file(path)

Take in a QASM file and generate a QuantumCircuit object.

QuantumCircuit.from_qasm_str(qasm_str)

Take in a QASM string and generate a QuantumCircuit object.

QuantumCircuit.h(qubit, *[, q])

Apply HGate.

QuantumCircuit.hamiltonian(operator, time, …)

Apply hamiltonian evolution to to qubits.

QuantumCircuit.has_register(register)

Test if this circuit has the register r.

QuantumCircuit.i(qubit, *[, q])

Apply IGate.

QuantumCircuit.id(qubit, *[, q])

Apply IGate.

QuantumCircuit.iden(qubit, *[, q])

Deprecated identity gate.

QuantumCircuit.initialize(params, qubits)

Apply initialize to circuit.

QuantumCircuit.inverse()

Invert this circuit.

QuantumCircuit.iso(isometry, q_input, …[, …])

Attach an arbitrary isometry from m to n qubits to a circuit.

QuantumCircuit.isometry(isometry, q_input, …)

Attach an arbitrary isometry from m to n qubits to a circuit.

QuantumCircuit.iswap(qubit1, qubit2)

Apply iSwapGate.

QuantumCircuit.mcmt(gate, control_qubits, …)

Apply a multi-control, multi-target using a generic gate.

QuantumCircuit.mcrx(theta, q_controls, q_target)

Apply Multiple-Controlled X rotation gate

QuantumCircuit.mcry(theta, q_controls, …)

Apply Multiple-Controlled Y rotation gate

QuantumCircuit.mcrz(lam, q_controls, q_target)

Apply Multiple-Controlled Z rotation gate

QuantumCircuit.mct(control_qubits, target_qubit)

Apply MCXGate.

QuantumCircuit.mcu1(lam, control_qubits, …)

Apply MCU1Gate.

QuantumCircuit.mcx(control_qubits, target_qubit)

Apply MCXGate.

QuantumCircuit.measure(qubit, cbit)

Measure quantum bit into classical bit (tuples).

QuantumCircuit.measure_active([inplace])

Adds measurement to all non-idle qubits.

QuantumCircuit.measure_all([inplace])

Adds measurement to all qubits.

QuantumCircuit.mirror()

Mirror the circuit by reversing the instructions.

QuantumCircuit.ms(theta, qubits)

Apply MSGate.

QuantumCircuit.num_connected_components([…])

How many non-entangled subcircuits can the circuit be factored to.

QuantumCircuit.num_nonlocal_gates()

Return number of non-local gates (i.e.

QuantumCircuit.num_tensor_factors()

Computes the number of tensor factors in the unitary (quantum) part of the circuit only.

QuantumCircuit.num_unitary_factors()

Computes the number of tensor factors in the unitary (quantum) part of the circuit only.

QuantumCircuit.qasm([formatted, filename])

Return OpenQASM string.

QuantumCircuit.qbit_argument_conversion(…)

Converts several qubit representations (such as indexes, range, etc.) into a list of qubits.

QuantumCircuit.r(theta, phi, qubit, *[, q])

Apply RGate.

QuantumCircuit.rcccx(control_qubit1, …)

Apply RC3XGate.

QuantumCircuit.rccx(control_qubit1, …)

Apply RCCXGate.

QuantumCircuit.remove_final_measurements([…])

Removes final measurement on all qubits if they are present.

QuantumCircuit.reset(qubit)

Reset q.

QuantumCircuit.rx(theta, qubit, *[, label, q])

Apply RXGate.

QuantumCircuit.rxx(theta, qubit1, qubit2)

Apply RXXGate.

QuantumCircuit.ry(theta, qubit, *[, label, q])

Apply RYGate.

QuantumCircuit.ryy(theta, qubit1, qubit2)

Apply RYYGate.

QuantumCircuit.rz(phi, qubit, *[, q])

Apply RZGate.

QuantumCircuit.rzx(theta, qubit1, qubit2)

Apply RZXGate.

QuantumCircuit.rzz(theta, qubit1, qubit2)

Apply RZZGate.

QuantumCircuit.s(qubit, *[, q])

Apply SGate.

QuantumCircuit.sdg(qubit, *[, q])

Apply SdgGate.

QuantumCircuit.size()

Returns total number of gate operations in circuit.

QuantumCircuit.snapshot(label[, …])

Take a statevector snapshot of the internal simulator representation.

QuantumCircuit.snapshot_density_matrix(label)

Take a density matrix snapshot of simulator state.

QuantumCircuit.snapshot_expectation_value(…)

Take a snapshot of expectation value <O> of an Operator.

QuantumCircuit.snapshot_probabilities(label, …)

Take a probability snapshot of the simulator state.

QuantumCircuit.snapshot_stabilizer(label)

Take a stabilizer snapshot of the simulator state.

QuantumCircuit.snapshot_statevector(label)

Take a statevector snapshot of the simulator state.

QuantumCircuit.squ(unitary_matrix, qubit[, …])

Decompose an arbitrary 2*2 unitary into three rotation gates.

QuantumCircuit.swap(qubit1, qubit2)

Apply SwapGate.

QuantumCircuit.t(qubit, *[, q])

Apply TGate.

QuantumCircuit.tdg(qubit, *[, q])

Apply TdgGate.

QuantumCircuit.to_gate([parameter_map])

Create a Gate out of this circuit.

QuantumCircuit.to_instruction([parameter_map])

Create an Instruction out of this circuit.

QuantumCircuit.toffoli(control_qubit1, …)

Apply CCXGate.

QuantumCircuit.u1(theta, qubit, *[, q])

Apply U1Gate.

QuantumCircuit.u2(phi, lam, qubit, *[, q])

Apply U2Gate.

QuantumCircuit.u3(theta, phi, lam, qubit, *)

Apply U3Gate.

QuantumCircuit.uc(gate_list, q_controls, …)

Attach a uniformly controlled gates (also called multiplexed gates) to a circuit.

QuantumCircuit.ucg(angle_list, q_controls, …)

Deprecated version of uc.

QuantumCircuit.ucrx(angle_list, q_controls, …)

Attach a uniformly controlled (also called multiplexed) Rx rotation gate to a circuit.

QuantumCircuit.ucry(angle_list, q_controls, …)

Attach a uniformly controlled (also called multiplexed) Ry rotation gate to a circuit.

QuantumCircuit.ucrz(angle_list, q_controls, …)

Attach a uniformly controlled (also called multiplexed gates) Rz rotation gate to a circuit.

QuantumCircuit.ucx(angle_list, q_controls, …)

Deprecated version of ucrx.

QuantumCircuit.ucy(angle_list, q_controls, …)

Deprecated version of ucry.

QuantumCircuit.ucz(angle_list, q_controls, …)

Deprecated version of ucrz.

QuantumCircuit.unitary(obj, qubits[, label])

Apply unitary gate to q.

QuantumCircuit.width()

Return number of qubits plus clbits in circuit.

QuantumCircuit.x(qubit, *[, label, …])

Apply XGate.

QuantumCircuit.y(qubit, *[, q])

Apply YGate.

QuantumCircuit.z(qubit, *[, q])

Apply ZGate.