QuantumCircuit
qiskit.circuit.QuantumCircuit(*regs, name=None, global_phase=0, metadata=None)
GitHub(opens in a new tab)
Bases: object
(opens in a new tab)
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 theQuantumRegister
and/orClassicalRegister
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 ofBit
s to be added to the circuit.


name (str(opens in a new tab)) – the name of the quantum circuit. If not set, an automatically generated string will be assigned.

global_phase (float(opens in a new tab) orParameterExpression) – The global phase of the circuit in radians.

metadata (dict(opens in a new tab)) – Arbitrary key value metadata to associate with the circuit. This gets stored as freeform 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('mpl')
Construct a 5qubit GHZ circuit.
from qiskit import QuantumCircuit
qc = QuantumCircuit(5)
qc.h(0)
qc.cx(0, range(1, 5))
qc.measure_all()
Construct a 4qubit BernsteinVazirani 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('mpl')
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 listlike object containing the CircuitInstruction
s for each instruction.
Return type
QuantumCircuitData
global_phase
Return the global phase of the current circuit scope in radians.
instances
= 182
layout
Return any associated layout information about the circuit
This attribute contains an optional TranspileLayout
object. This is typically set on the output from transpile()
or PassManager.run()
to retain information about the permutations caused on the input circuit by transpilation.
There are two types of permutations caused by the transpile()
function, an initial layout which permutes the qubits based on the selected physical qubits on the Target
, and a final layout which is an output permutation caused by SwapGate
s inserted during routing.
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
The number of parameter objects in the circuit.
num_qubits
Return number of qubits.
op_start_times
Return a list of operation start times.
This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit.
Returns
List of integers representing instruction start times. The index corresponds to the index of instruction in QuantumCircuit.data
.
Raises
AttributeError(opens in a new tab) – When circuit is not scheduled.
parameters
The parameters defined in the circuit.
This attribute returns the Parameter
objects in the circuit sorted alphabetically. Note that parameters instantiated with a ParameterVector
are still sorted numerically.
Examples
The snippet below shows that insertion order of parameters does not matter.
>>> from qiskit.circuit import QuantumCircuit, Parameter
>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant")
>>> circuit = QuantumCircuit(1)
>>> circuit.rx(b, 0)
>>> circuit.rz(elephant, 0)
>>> circuit.ry(a, 0)
>>> circuit.parameters # sorted alphabetically!
ParameterView([Parameter(a), Parameter(b), Parameter(elephant)])
Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting.
>>> from qiskit.circuit import QuantumCircuit, Parameter
>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")]
>>> circuit = QuantumCircuit(1)
>>> circuit.u(*angles, 0)
>>> circuit.draw()
┌─────────────────────────────┐
q: ┤ U(angle_1,angle_2,angle_10) ├
└─────────────────────────────┘
>>> circuit.parameters
ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)])
To respect numerical sorting, a ParameterVector
can be used.
>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector
>>> x = ParameterVector("x", 12)
>>> circuit = QuantumCircuit(1)
>>> for x_i in x:
... circuit.rx(x_i, 0)
>>> circuit.parameters
ParameterView([
ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
ParameterVectorElement(x[2]), ParameterVectorElement(x[3]),
..., ParameterVectorElement(x[11])
])
Returns
The sorted Parameter
objects in the circuit.
prefix
= 'circuit'
qubits
Returns a list of quantum bits in the order that the registers were added.
Methods
add_bits
add_bits(bits)
GitHub(opens in a new tab)
Add Bits to the circuit.
add_calibration
add_calibration(gate, qubits, schedule, params=None)
GitHub(opens in a new tab)
Register a lowlevel, custom pulse definition for the given gate.
Parameters
 gate (Union[Gate, str(opens in a new tab)]) – Gate information.
 qubits (Union[int(opens in a new tab), Tuple[int(opens in a new tab)]]) – List of qubits to be measured.
 schedule (Schedule) – Schedule information.
 params (Optional[List[Union[float(opens in a new tab), Parameter]]]) – A list of parameters.
Raises
Exception(opens in a new tab) – if the gate is of type string and params is None.
add_register
add_register(*regs)
GitHub(opens in a new tab)
Add registers.
append
append(instruction, qargs=None, cargs=None)
GitHub(opens in a new tab)
Append one or more instructions to the end of the circuit, modifying the circuit in place.
The qargs
and cargs
will be expanded and broadcast according to the rules of the given Instruction
, and any nonBit
specifiers (such as integer indices) will be resolved into the relevant instances.
If a CircuitInstruction
is given, it will be unwrapped, verified in the context of this circuit, and a new object will be appended to the circuit. In this case, you may not pass qargs
or cargs
separately.
Parameters
 instruction (Operation CircuitInstruction) –
Instruction
instance to append, or aCircuitInstruction
with all its context.  qargs (Sequence[QubitSpecifier]  None) – specifiers of the
Qubit
s to attach instruction to.  cargs (Sequence[ClbitSpecifier]  None) – specifiers of the
Clbit
s to attach instruction to.
Returns
a handle to the CircuitInstruction
s that were actually added to the circuit.
Return type
Raises
CircuitError – if the operation passed is not an instance of Instruction
.
assign_parameters
assign_parameters(parameters: Mapping[Parameter, ParameterExpression  float]  Sequence[ParameterExpression  float], inplace: Literal[False] = False, *, flat_input: bool = False, strict: bool = True) → QuantumCircuit
GitHub(opens in a new tab)
assign_parameters(parameters: Mapping[Parameter, ParameterExpression  float]  Sequence[ParameterExpression  float], inplace: Literal[True] = False, *, flat_input: bool = False, strict: bool = True) → None
Assign parameters to new parameters or values.
If parameters
is passed as a dictionary, the keys should be Parameter
instances in the current circuit. The values of the dictionary can either be numeric values or new parameter objects.
If parameters
is passed as a list or array, the elements are assigned to the current parameters in the order of parameters
which is sorted alphabetically (while respecting the ordering in ParameterVector
objects).
The values can be assigned to the current circuit object or to a copy of it.
When parameters
is given as a mapping, it is permissible to have keys that are strings of the parameter names; these will be looked up using get_parameter()
. You can also have keys that are ParameterVector
instances, and in this case, the dictionary value should be a sequence of values of the same length as the vector.
If you use either of these cases, you must leave the setting flat_input=False
; changing this to True
enables the fast path, where all keys must be Parameter
instances.
Parameters
 parameters – Either a dictionary or iterable specifying the new parameter values.
 inplace – If False, a copy of the circuit with the bound parameters is returned. If True the circuit instance itself is modified.
 flat_input – If
True
andparameters
is a mapping type, it is assumed to be exactly a mapping of{parameter: value}
. By default (False
), the mapping may also containParameterVector
keys that point to a corresponding sequence of values, and these will be unrolled during the mapping, or string keys, which will be converted toParameter
instances usingget_parameter()
.  strict – If
False
, any parameters given in the mapping that are not used in the circuit will be ignored. IfTrue
(the default), an error will be raised indicating a logic error.
Raises
 CircuitError – If parameters is a dict and contains parameters not present in the circuit.
 ValueError(opens in a new tab) – If parameters is a list/array and the length mismatches the number of free parameters in the circuit.
Returns
A copy of the circuit with bound parameters if inplace
is False, otherwise None.
Examples
Create a parameterized circuit and assign the parameters inplace.
from qiskit.circuit import QuantumCircuit, Parameter
circuit = QuantumCircuit(2)
params = [Parameter('A'), Parameter('B'), Parameter('C')]
circuit.ry(params[0], 0)
circuit.crx(params[1], 0, 1)
circuit.draw('mpl')
circuit.assign_parameters({params[0]: params[2]}, inplace=True)
circuit.draw('mpl')
Bind the values outofplace by list and get a copy of the original circuit.
from qiskit.circuit import QuantumCircuit, ParameterVector
circuit = QuantumCircuit(2)
params = ParameterVector('P', 2)
circuit.ry(params[0], 0)
circuit.crx(params[1], 0, 1)
bound_circuit = circuit.assign_parameters([1, 2])
bound_circuit.draw('mpl')
circuit.draw('mpl')
barrier
barrier(*qargs, label=None)
GitHub(opens in a new tab)
Apply Barrier
. If qargs
is empty, applies to all qubits in the circuit.
Parameters
 qargs (QubitSpecifier) – Specification for one or more qubit arguments.
 label (str(opens in a new tab)) – The string label of the barrier.
Returns
handle to the added instructions.
Return type
break_loop
break_loop()
GitHub(opens in a new tab)
Apply BreakLoopOp
.
If you are using the contextmanager “builder” forms of if_test()
, for_loop()
or while_loop()
, you can only call this method if you are within a loop context, because otherwise the “resource width” of the operation cannot be determined. This would quickly lead to invalid circuits, and so if you are trying to construct a reusable loop body (without the context managers), you must also use the noncontextmanager form of if_test()
and if_else()
. Take care that the BreakLoopOp
instruction must span all the resources of its containing loop, not just the immediate scope.
Returns
A handle to the instruction created.
Raises
CircuitError – if this method was called within a builder context, but not contained within a loop.
Return type
cast
static cast(value, type_)
GitHub(opens in a new tab)
Best effort to cast value to type. Otherwise, returns the value.
Return type
S  T
cbit_argument_conversion
cbit_argument_conversion(clbit_representation)
GitHub(opens in a new tab)
Converts several classical bit representations (such as indexes, range, etc.) into a list of classical bits.
Parameters
clbit_representation (Object) – representation to expand
Returns
Where each tuple is a classical bit.
Return type
ccx
ccx(control_qubit1, control_qubit2, target_qubit, ctrl_state=None)
GitHub(opens in a new tab)
Apply CCXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit1 (QubitSpecifier) – The qubit(s) used as the first control.
 control_qubit2 (QubitSpecifier) – The qubit(s) used as the second control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
ccz
ccz(control_qubit1, control_qubit2, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CCZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit1 (QubitSpecifier) – The qubit(s) used as the first control.
 control_qubit2 (QubitSpecifier) – The qubit(s) used as the second control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘10’). Defaults to controlling on the ‘11’ state.
Returns
A handle to the instructions created.
Return type
ch
ch(control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CHGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
clear
clear()
GitHub(opens in a new tab)
Clear all instructions in self.
Clearing the circuits will keep the metadata and calibrations.
cls_instances
classmethod cls_instances()
GitHub(opens in a new tab)
Return the current number of instances of this class, useful for auto naming.
Return type
cls_prefix
classmethod cls_prefix()
GitHub(opens in a new tab)
compose
compose(other, qubits=None, clbits=None, front=False, inplace=False, wrap=False)
GitHub(opens in a new tab)
Compose circuit with other
circuit or instruction, optionally permuting wires.
other
can be narrower or of equal width to self
.
Parameters
 other (qiskit.circuit.Instruction orQuantumCircuit) – (sub)circuit or instruction to compose onto self. If not a
QuantumCircuit
, this can be anything thatappend
will accept.  qubits (list(opens in a new tab)[Qubitint(opens in a new tab)]) – qubits of self to compose onto.
 clbits (list(opens in a new tab)[Clbitint(opens in a new tab)]) – clbits of self to compose onto.
 front (bool(opens in a new tab)) – If True, front composition will be performed. This is not possible within controlflow builder context managers.
 inplace (bool(opens in a new tab)) – If True, modify the object. Otherwise return composed circuit.
 wrap (bool(opens in a new tab)) – If True, wraps the other circuit into a gate (or instruction, depending on whether it contains only unitary instructions) before composing it onto self.
Returns
the composed circuit (returns None if inplace==True).
Return type
Raises
 CircuitError – if no correct wire mapping can be made between the two circuits, such as if
other
is wider thanself
.  CircuitError – if trying to emit a new circuit while
self
has a partially built controlflow context active, such as the contextmanager forms ofif_test()
,for_loop()
andwhile_loop()
.  CircuitError – if trying to compose to the front of a circuit when a controlflow builder block is active; there is no clear meaning to this action.
Examples
>>> lhs.compose(rhs, qubits=[3, 2], inplace=True)
┌───┐ ┌─────┐ ┌───┐
lqr_1_0: ───┤ H ├─── rqr_0: ──■──┤ Tdg ├ lqr_1_0: ───┤ H ├───────────────
├───┤ ┌─┴─┐└─────┘ ├───┤
lqr_1_1: ───┤ X ├─── rqr_1: ┤ X ├─────── lqr_1_1: ───┤ X ├───────────────
┌──┴───┴──┐ └───┘ ┌──┴───┴──┐┌───┐
lqr_1_2: ┤ U1(0.1) ├ + = lqr_1_2: ┤ U1(0.1) ├┤ X ├───────
└─────────┘ └─────────┘└─┬─┘┌─────┐
lqr_2_0: ─────■───── lqr_2_0: ─────■───────■──┤ Tdg ├
┌─┴─┐ ┌─┴─┐ └─────┘
lqr_2_1: ───┤ X ├─── lqr_2_1: ───┤ X ├───────────────
└───┘ └───┘
lcr_0: 0 ═══════════ lcr_0: 0 ═══════════════════════
lcr_1: 0 ═══════════ lcr_1: 0 ═══════════════════════
continue_loop
continue_loop()
GitHub(opens in a new tab)
Apply ContinueLoopOp
.
If you are using the contextmanager “builder” forms of if_test()
, for_loop()
or while_loop()
, you can only call this method if you are within a loop context, because otherwise the “resource width” of the operation cannot be determined. This would quickly lead to invalid circuits, and so if you are trying to construct a reusable loop body (without the context managers), you must also use the noncontextmanager form of if_test()
and if_else()
. Take care that the ContinueLoopOp
instruction must span all the resources of its containing loop, not just the immediate scope.
Returns
A handle to the instruction created.
Raises
CircuitError – if this method was called within a builder context, but not contained within a loop.
Return type
control
control(num_ctrl_qubits=1, label=None, ctrl_state=None, annotated=False)
GitHub(opens in a new tab)
Control this circuit on num_ctrl_qubits
qubits.
Parameters
 num_ctrl_qubits (int(opens in a new tab)) – The number of control qubits.
 label (str(opens in a new tab)) – An optional label to give the controlled operation for visualization.
 ctrl_state (str(opens in a new tab) orint(opens in a new tab)) – The control state in decimal or as a bitstring (e.g. ‘111’). If None, use
2**num_ctrl_qubits  1
.  annotated (bool(opens in a new tab)) – indicates whether the controlled gate can be implemented as an annotated gate.
Returns
The controlled version of this circuit.
Return type
Raises
CircuitError – If the circuit contains a nonunitary operation and cannot be controlled.
copy
copy(name=None)
GitHub(opens in a new tab)
Copy the circuit.
Parameters
name (str(opens in a new tab)) – name to be given to the copied circuit. If None, then the name stays the same.
Returns
a deepcopy of the current circuit, with the specified name
Return type
copy_empty_like
copy_empty_like(name=None)
GitHub(opens in a new tab)
Return a copy of self with the same structure but empty.
That structure includes:
 name, calibrations and other metadata
 global phase
 all the qubits and clbits, including the registers
Parameters
name (str(opens in a new tab)) – Name for the copied circuit. If None, then the name stays the same.
Returns
An empty copy of self.
Return type
count_ops
count_ops()
GitHub(opens in a new tab)
Count each operation kind in the circuit.
Returns
a breakdown of how many operations of each kind, sorted by amount.
Return type
OrderedDict
cp
cp(theta, control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CPhaseGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterValueType) – The angle of the rotation.
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
crx
crx(theta, control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CRXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterValueType) – The angle of the rotation.
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
cry
cry(theta, control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CRYGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterValueType) – The angle of the rotation.
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
crz
crz(theta, control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CRZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterValueType) – The angle of the rotation.
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
cs
cs(control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CSGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
csdg
csdg(control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CSdgGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
cswap
cswap(control_qubit, target_qubit1, target_qubit2, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CSwapGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit1 (QubitSpecifier) – The qubit(s) targeted by the gate.
 target_qubit2 (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g.
'1'
). Defaults to controlling on the'1'
state.
Returns
A handle to the instructions created.
Return type
csx
csx(control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CSXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
cu
cu(theta, phi, lam, gamma, control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CUGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterValueType) – The $\theta$ rotation angle of the gate.
 phi (ParameterValueType) – The $\phi$ rotation angle of the gate.
 lam (ParameterValueType) – The $\lambda$ rotation angle of the gate.
 gamma (ParameterValueType) – The global phase applied of the U gate, if applied.
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
cx
cx(control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (QubitSpecifier) – The qubit(s) used as the control.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
cy
cy(control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CYGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (QubitSpecifier) – The qubit(s) used as the controls.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
cz
cz(control_qubit, target_qubit, label=None, ctrl_state=None)
GitHub(opens in a new tab)
Apply CZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (QubitSpecifier) – The qubit(s) used as the controls.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
 ctrl_state (str(opens in a new tab) int(opens in a new tab)  None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Returns
A handle to the instructions created.
Return type
dcx
dcx(qubit1, qubit2)
GitHub(opens in a new tab)
Apply DCXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
 qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
decompose
decompose(gates_to_decompose=None, reps=1)
GitHub(opens in a new tab)
Call a decomposition pass on this circuit, to decompose one level (shallow decompose).
Parameters
 gates_to_decompose (type(opens in a new tab) orstr(opens in a new tab) orlist(opens in a new tab)(type(opens in a new tab), str(opens in a new tab))) – Optional subset of gates to decompose. Can be a gate type, such as
HGate
, or a gate name, such as ‘h’, or a gate label, such as ‘My H Gate’, or a list of any combination of these. If a gate name is entered, it will decompose all gates with that name, whether the gates have labels or not. Defaults to all gates in circuit.  reps (int(opens in a new tab)) – Optional number of times the circuit should be decomposed. For instance,
reps=2
equals callingcircuit.decompose().decompose()
. can decompose specific gates specific time
Returns
a circuit one level decomposed
Return type
delay
delay(duration, qarg=None, unit='dt')
GitHub(opens in a new tab)
Apply Delay
. If qarg is None
, applies to all qubits. When applying to multiple qubits, delays with the same duration will be created.
Parameters
 duration (int(opens in a new tab) orfloat(opens in a new tab) orParameterExpression) – duration of the delay.
 qarg (Object) – qubit argument to apply this delay.
 unit (str(opens in a new tab)) – unit of the duration. Supported units:
's'
,'ms'
,'us'
,'ns'
,'ps'
, and'dt'
. Default is'dt'
, i.e. integer time unit depending on the target backend.
Returns
handle to the added instructions.
Return type
Raises
CircuitError – if arguments have bad format.
depth
depth(filter_function=<function QuantumCircuit.<lambda>>)
GitHub(opens in a new tab)
Return circuit depth (i.e., length of critical path).
Parameters
filter_function (callable) – A function to filter instructions. Should take as input a tuple of (Instruction, list(Qubit), list(Clbit)). Instructions for which the function returns False are ignored in the computation of the circuit depth. By default filters out “directives”, such as barrier or snapshot.
Returns
Depth of circuit.
Return type
Notes
The circuit depth and the DAG depth need not be the same.
draw
draw(output=None, scale=None, filename=None, style=None, interactive=False, plot_barriers=True, reverse_bits=None, justify=None, vertical_compression='medium', idle_wires=True, with_layout=True, fold=None, ax=None, initial_state=False, cregbundle=None, wire_order=None, expr_len=30)
GitHub(opens in a new tab)
Draw the quantum circuit. Use the output parameter to choose the drawing format:
text: ASCII art TextDrawing that can be printed in the console.
mpl: images with color rendered purely in Python using matplotlib.
latex: highquality images compiled via latex.
latex_source: raw uncompiled latex output.
Support for Expr
nodes in conditions and SwitchCaseOp.target
fields is preliminary and incomplete. The text
and mpl
drawers will make a besteffort attempt to show data dependencies, but the LaTeXbased drawers will skip these completely.
Parameters

output (str(opens in a new tab)  None) – Select the output method to use for drawing the circuit. Valid choices are
text
,mpl
,latex
,latex_source
. By default the text drawer is used unless the user config file (usually~/.qiskit/settings.conf
) has an alternative backend set as the default. For example,circuit_drawer = latex
. If the output kwarg is set, that backend will always be used over the default in the user config file. 
scale (float(opens in a new tab)  None) – Scale of image to draw (shrink if
< 1.0
). Only used by thempl
,latex
andlatex_source
outputs. Defaults to1.0
. 
filename (str(opens in a new tab)  None) – File path to save image to. Defaults to
None
(result not saved in a file). 
style (dict(opens in a new tab) str(opens in a new tab)  None) –
Style name, file name of style JSON file, or a dictionary specifying the style.
 The supported style names are
"iqp"
(default),"iqpdark"
,"clifford"
,"textbook"
and"bw"
.  If given a JSON file, e.g.
my_style.json
ormy_style
(the.json
extension may be omitted), this function attempts to load the style dictionary from that location. Note, that the JSON file must completely specify the visualization specifications. The file is searched for inqiskit/visualization/circuit/styles
, the current working directory, and the location specified in~/.qiskit/settings.conf
.  If a dictionary, every entry overrides the default configuration. If the
"name"
key is given, the default configuration is given by that style. For example,{"name": "textbook", "subfontsize": 5}
loads the"texbook"
style and sets the subfontsize (e.g. the gate angles) to5
.  If
None
the default style"iqp"
is used or, if given, the default style specified in~/.qiskit/settings.conf
.
 The supported style names are

interactive (bool(opens in a new tab)) – When set to
True
, show the circuit in a new window (formpl
this depends on the matplotlib backend being used supporting this). Note when used with either the text or thelatex_source
output type this has no effect and will be silently ignored. Defaults toFalse
. 
reverse_bits (bool(opens in a new tab)  None) – When set to
True
, reverse the bit order inside registers for the output visualization. Defaults toFalse
unless the user config file (usually~/.qiskit/settings.conf
) has an alternative value set. For example,circuit_reverse_bits = True
. 
plot_barriers (bool(opens in a new tab)) – Enable/disable drawing barriers in the output circuit. Defaults to
True
. 
justify (str(opens in a new tab)  None) – Options are
left
,right
ornone
. If anything else is supplied, it defaults to left justified. It refers to where gates should be placed in the output circuit if there is an option.none
results in each gate being placed in its own column. 
vertical_compression (str(opens in a new tab)  None) –
high
,medium
orlow
. It merges the lines generated by the text output so the drawing will take less vertical room. Default ismedium
. Only used by thetext
output, will be silently ignored otherwise. 
idle_wires (bool(opens in a new tab)) – Include idle wires (wires with no circuit elements) in output visualization. Default is
True
. 
with_layout (bool(opens in a new tab)) – Include layout information, with labels on the physical layout. Default is
True
. 
fold (int(opens in a new tab)  None) – Sets pagination. It can be disabled using 1. In
text
, sets the length of the lines. This is useful when the drawing does not fit in the console. If None (default), it will try to guess the console width usingshutil.get_terminal_size()
. However, if running in jupyter, the default line length is set to 80 characters. Inmpl
, it is the number of (visual) layers before folding. Default is 25. 
ax (Any  None) – Only used by the mpl backend. An optional
matplotlib.axes.Axes
object to be used for the visualization output. If none is specified, a new matplotlib Figure will be created and used. Additionally, if specified there will be no returned Figure since it is redundant. 
initial_state (bool(opens in a new tab)) – Adds $0\rangle$ in the beginning of the qubit wires and $0$ to classical wires. Default is
False
. 
cregbundle (bool(opens in a new tab)  None) – If set to
True
, bundle classical registers. Default isTrue
, except for whenoutput
is set to"text"
. 
wire_order (list(opens in a new tab)[int(opens in a new tab)]  None) – A list of integers used to reorder the display of the bits. The list must have an entry for every bit with the bits in the range 0 to (
num_qubits
+num_clbits
). 
expr_len (int(opens in a new tab)) – The number of characters to display if an
Expr
is used for the condition in aControlFlowOp
. If this number is exceeded, the string will be truncated at that number and ‘…’ added to the end.
Returns
TextDrawing
or matplotlib.figure
or PIL.Image
or str
(opens in a new tab):

TextDrawing
(ifoutput='text'
)A drawing that can be printed as ascii art.

matplotlib.figure.Figure
(ifoutput='mpl'
)A matplotlib figure object for the circuit diagram.

PIL.Image
(ifoutput='latex
’)An inmemory representation of the image of the circuit diagram.

str
(ifoutput='latex_source'
)The LaTeX source code for visualizing the circuit diagram.
Raises
 VisualizationError – when an invalid output method is selected
 ImportError(opens in a new tab) – when the output methods requires noninstalled libraries.
Example
from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
qc = QuantumCircuit(1, 1)
qc.h(0)
qc.measure(0, 0)
qc.draw(output='mpl', style={'backgroundcolor': '#EEEEEE'})
ecr
ecr(qubit1, qubit2)
GitHub(opens in a new tab)
Apply ECRGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubits to apply the gate to.
 qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubits to apply the gate to.
Returns
A handle to the instructions created.
Return type
find_bit
find_bit(bit)
GitHub(opens in a new tab)
Find locations in the circuit which can be used to reference a given Bit
.
Parameters
bit (Bit) – The bit to locate.
Returns
A 2tuple. The first element (index
)
contains the index at which the Bit
can be found (in either qubits
, clbits
, depending on its type). The second element (registers
) is a list of (register, index)
pairs with an entry for each Register
in the circuit which contains the Bit
(and the index in the Register
at which it can be found).
Return type
namedtuple(int(opens in a new tab), List[Tuple(Register, int(opens in a new tab))])
Notes
The circuit index of an AncillaQubit
will be its index in qubits
, not ancillas
.
Raises
 CircuitError – If the supplied
Bit
was of an unknown type.  CircuitError – If the supplied
Bit
could not be found on the circuit.
Return type
BitLocations
for_loop
for_loop(indexset: Iterable[int], loop_parameter: Parameter  None, body: None, qubits: None, clbits: None, *, label: str  None) → ForLoopContext
GitHub(opens in a new tab)
for_loop(indexset: Iterable[int], loop_parameter: Parameter  None, body: QuantumCircuit, qubits: Sequence[Qubit  QuantumRegister  int  slice  Sequence[Qubit  int]], clbits: Sequence[Clbit  ClassicalRegister  int  slice  Sequence[Clbit  int]], *, label: str  None) → InstructionSet
Create a for
loop on this circuit.
There are two forms for calling this function. If called with all its arguments (with the possible exception of label
), it will create a ForLoopOp
with the given body
. If body
(and qubits
and clbits
) are not passed, then this acts as a context manager, which, when entered, provides a loop variable (unless one is given, in which case it will be reused) and will automatically build a ForLoopOp
when the scope finishes. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you.
For example:
from qiskit import QuantumCircuit
qc = QuantumCircuit(2, 1)
with qc.for_loop(range(5)) as i:
qc.h(0)
qc.cx(0, 1)
qc.measure(0, 0)
qc.break_loop().c_if(0, True)
Parameters

indexset (Iterable[int(opens in a new tab)]) – A collection of integers to loop over. Always necessary.

loop_parameter (Optional[Parameter]) –
The parameter used within
body
to which the values fromindexset
will be assigned. In the contextmanager form, if this argument is not supplied, then a loop parameter will be allocated for you and returned as the value of thewith
statement. This will only be bound into the circuit if it is used within the body.If this argument is
None
in the manual form of this method,body
will be repeated once for each of the items inindexset
but their values will be ignored. 
body (Optional[QuantumCircuit]) – The loop body to be repeatedly executed. Omit this to use the contextmanager mode.

qubits (Optional[Sequence[QubitSpecifier]]) – The circuit qubits over which the loop body should be run. Omit this to use the contextmanager mode.

clbits (Optional[Sequence[ClbitSpecifier]]) – The circuit clbits over which the loop body should be run. Omit this to use the contextmanager mode.

label (Optional[str(opens in a new tab)]) – The string label of the instruction in the circuit.
Returns
depending on the call signature, either a context manager for creating the for loop (it will automatically be added to the circuit at the end of the block), or an InstructionSet
handle to the appended loop operation.
Return type
InstructionSet or ForLoopContext
Raises
CircuitError – if an incorrect calling convention is used.
from_instructions
static from_instructions(instructions, *, qubits=(), clbits=(), name=None, global_phase=0, metadata=None)
GitHub(opens in a new tab)
Construct a circuit from an iterable of CircuitInstructions.
Parameters
 instructions (Iterable[CircuitInstruction tuple(opens in a new tab)[qiskit.circuit.Instruction]  tuple(opens in a new tab)[qiskit.circuit.Instruction, Iterable[Qubit]]  tuple(opens in a new tab)[qiskit.circuit.Instruction, Iterable[Qubit], Iterable[Clbit]]]) – The instructions to add to the circuit.
 qubits (Iterable[Qubit]) – Any qubits to add to the circuit. This argument can be used, for example, to enforce a particular ordering of qubits.
 clbits (Iterable[Clbit]) – Any classical bits to add to the circuit. This argument can be used, for example, to enforce a particular ordering of classical bits.
 name (str(opens in a new tab)  None) – The name of the circuit.
 global_phase (ParameterValueType) – The global phase of the circuit in radians.
 metadata (dict(opens in a new tab)  None) – Arbitrary key value metadata to associate with the circuit.
Returns
The quantum circuit.
Return type
from_qasm_file
static from_qasm_file(path)
GitHub(opens in a new tab)
Read an OpenQASM 2.0 program from a file and convert to an instance of QuantumCircuit
.
Parameters
path (str(opens in a new tab)) – Path to the file for an OpenQASM 2 program
Returns
The QuantumCircuit object for the input OpenQASM 2.
Return type
qasm2.load()
: the complete interface to the OpenQASM 2 importer.
from_qasm_str
static from_qasm_str(qasm_str)
GitHub(opens in a new tab)
Convert a string containing an OpenQASM 2.0 program to a QuantumCircuit
.
Parameters
qasm_str (str(opens in a new tab)) – A string containing an OpenQASM 2.0 program.
Returns
The QuantumCircuit object for the input OpenQASM 2
Return type
qasm2.loads()
: the complete interface to the OpenQASM 2 importer.
get_instructions
get_instructions(name)
GitHub(opens in a new tab)
Get instructions matching name.
Parameters
name (str(opens in a new tab)) – The name of instruction to.
Returns
list of (instruction, qargs, cargs).
Return type
get_parameter
get_parameter(name: str, default: T) → Parameter  T
GitHub(opens in a new tab)
get_parameter(name: str, default: ellipsis = Ellipsis) → Parameter
Retrieve a compiletime parameter that is accessible in this circuit scope by name.
Parameters
 name – the name of the parameter to retrieve.
 default – if given, this value will be returned if the parameter is not present. If it is not given, a
KeyError
(opens in a new tab) is raised instead.
Returns
The corresponding parameter.
Raises
KeyError(opens in a new tab) – if no default is given, but the parameter does not exist in the circuit.
Examples
Retrieve a parameter by name from a circuit:
from qiskit.circuit import QuantumCircuit, Parameter
my_param = Parameter("my_param")
# Create a parametrised circuit.
qc = QuantumCircuit(1)
qc.rx(my_param, 0)
# We can use 'my_param' as a parameter, but let's say we've lost the Python object
# and need to retrieve it.
my_param_again = qc.get_parameter("my_param")
assert my_param is my_param_again
Get a variable from a circuit by name, returning some default if it is not present:
assert qc.get_parameter("my_param", None) is my_param
assert qc.get_parameter("unknown_param", None) is None
h
h(qubit)
GitHub(opens in a new tab)
Apply HGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
has_calibration_for
has_calibration_for(instruction)
GitHub(opens in a new tab)
Return True if the circuit has a calibration defined for the instruction context. In this case, the operation does not need to be translated to the device basis.
has_parameter
has_parameter(name_or_param, /)
GitHub(opens in a new tab)
Check whether a parameter object exists in this circuit.
Parameters
name_or_param (str(opens in a new tab) Parameter) – the parameter, or name of a parameter to check. If this is a Parameter
node, the parameter must be exactly the given one for this function to return True
.
Returns
whether a matching parameter is assignable in this circuit.
Return type
QuantumCircuit.get_parameter()
Retrieve the Parameter
instance from this circuit by name.
has_register
has_register(register)
GitHub(opens in a new tab)
Test if this circuit has the register r.
Parameters
register (Register) – a quantum or classical register.
Returns
True if the register is contained in this circuit.
Return type
id
id(qubit)
GitHub(opens in a new tab)
Apply IGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
if_else
if_else(condition, true_body, false_body, qubits, clbits, label=None)
GitHub(opens in a new tab)
Apply IfElseOp
.
This method does not have an associated contextmanager form, because it is already handled by the if_test()
method. You can use the else
part of that with something such as:
from qiskit.circuit import QuantumCircuit, Qubit, Clbit
bits = [Qubit(), Qubit(), Clbit()]
qc = QuantumCircuit(bits)
qc.h(0)
qc.cx(0, 1)
qc.measure(0, 0)
with qc.if_test((bits[2], 0)) as else_:
qc.h(0)
with else_:
qc.x(0)
Parameters
 condition (tuple(opens in a new tab)[ClassicalRegister, int(opens in a new tab)]  tuple(opens in a new tab)[Clbit, int(opens in a new tab)]  tuple(opens in a new tab)[Clbit, bool(opens in a new tab)]) – A condition to be evaluated at circuit runtime which, if true, will trigger the evaluation of
true_body
. Can be specified as either a tuple of aClassicalRegister
to be tested for equality with a givenint
, or as a tuple of aClbit
to be compared to either abool
or anint
.  true_body (QuantumCircuit) – The circuit body to be run if
condition
is true.  false_body (QuantumCircuit) – The circuit to be run if
condition
is false.  qubits (Sequence[QubitSpecifier]) – The circuit qubits over which the if/else should be run.
 clbits (Sequence[ClbitSpecifier]) – The circuit clbits over which the if/else should be run.
 label (str(opens in a new tab)  None) – The string label of the instruction in the circuit.
Raises
CircuitError – If the provided condition references Clbits outside the enclosing circuit.
Returns
A handle to the instruction created.
Return type
if_test
if_test(condition: tuple[ClassicalRegister  Clbit, int], true_body: None, qubits: None, clbits: None, *, label: str  None) → IfContext
GitHub(opens in a new tab)
if_test(condition: tuple[ClassicalRegister  Clbit, int], true_body: QuantumCircuit, qubits: Sequence[Qubit  QuantumRegister  int  slice  Sequence[Qubit  int]], clbits: Sequence[Clbit  ClassicalRegister  int  slice  Sequence[Clbit  int]], *, label: str  None = None) → InstructionSet
Create an if
statement on this circuit.
There are two forms for calling this function. If called with all its arguments (with the possible exception of label
), it will create a IfElseOp
with the given true_body
, and there will be no branch for the false
condition (see also the if_else()
method). However, if true_body
(and qubits
and clbits
) are not passed, then this acts as a context manager, which can be used to build if
statements. The return value of the with
statement is a chainable context manager, which can be used to create subsequent else
blocks. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you.
For example:
from qiskit.circuit import QuantumCircuit, Qubit, Clbit
bits = [Qubit(), Qubit(), Qubit(), Clbit(), Clbit()]
qc = QuantumCircuit(bits)
qc.h(0)
qc.cx(0, 1)
qc.measure(0, 0)
qc.h(0)
qc.cx(0, 1)
qc.measure(0, 1)
with qc.if_test((bits[3], 0)) as else_:
qc.x(2)
with else_:
qc.h(2)
qc.z(2)
Parameters
 condition (Tuple[Union[ClassicalRegister, Clbit], int(opens in a new tab)]) – A condition to be evaluated at circuit runtime which, if true, will trigger the evaluation of
true_body
. Can be specified as either a tuple of aClassicalRegister
to be tested for equality with a givenint
, or as a tuple of aClbit
to be compared to either abool
or anint
.  true_body (Optional[QuantumCircuit]) – The circuit body to be run if
condition
is true.  qubits (Optional[Sequence[QubitSpecifier]]) – The circuit qubits over which the if/else should be run.
 clbits (Optional[Sequence[ClbitSpecifier]]) – The circuit clbits over which the if/else should be run.
 label (Optional[str(opens in a new tab)]) – The string label of the instruction in the circuit.
Returns
depending on the call signature, either a context manager for creating the if
block (it will automatically be added to the circuit at the end of the block), or an InstructionSet
handle to the appended conditional operation.
Return type
InstructionSet or IfContext
Raises
 CircuitError – If the provided condition references Clbits outside the enclosing circuit.
 CircuitError – if an incorrect calling convention is used.
Returns
A handle to the instruction created.
initialize
initialize(params, qubits=None, normalize=False)
GitHub(opens in a new tab)
Initialize qubits in a specific state.
Qubit initialization is done by first resetting the qubits to $0\rangle$ followed by calling StatePreparation
class to prepare the qubits in a specified state. Both these steps are included in the Initialize
instruction.
Parameters

params (Statevector  Sequence[complex(opens in a new tab)]  str(opens in a new tab) int(opens in a new tab)) –
The state to initialize to, can be either of the following.
 Statevector or vector of complex amplitudes to initialize to.
 Labels of basis states of the Pauli eigenstates Z, X, Y. See
Statevector.from_label()
. Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label ‘01’ initializes the qubit zero to $1\rangle$ and the qubit one to $0\rangle$.  An integer that is used as a bitmap indicating which qubits to initialize to $1\rangle$. Example: setting params to 5 would initialize qubit 0 and qubit 2 to $1\rangle$ and qubit 1 to $0\rangle$.

qubits (Sequence[QubitSpecifier]  None) – Qubits to initialize. If
None
the initialization is applied to all qubits in the circuit. 
normalize (bool(opens in a new tab)) – Whether to normalize an input array to a unit vector.
Returns
A handle to the instructions created.
Examples
Prepare a qubit in the state $(0\rangle  1\rangle) / \sqrt{2}$.
import numpy as np
from qiskit import QuantumCircuit
circuit = QuantumCircuit(1)
circuit.initialize([1/np.sqrt(2), 1/np.sqrt(2)], 0)
circuit.draw()
output:
┌──────────────────────────────┐
q_0: ┤ Initialize(0.70711,0.70711) ├
└──────────────────────────────┘
Initialize from a string two qubits in the state $10\rangle$. The order of the labels is reversed with respect to qubit index. More information about labels for basis states are in Statevector.from_label()
.
import numpy as np
from qiskit import QuantumCircuit
circuit = QuantumCircuit(2)
circuit.initialize('01', circuit.qubits)
circuit.draw()
output:
┌──────────────────┐
q_0: ┤0 ├
│ Initialize(0,1) │
q_1: ┤1 ├
└──────────────────┘
Initialize two qubits from an array of complex amplitudes.
import numpy as np
from qiskit import QuantumCircuit
circuit = QuantumCircuit(2)
circuit.initialize([0, 1/np.sqrt(2), 1.j/np.sqrt(2), 0], circuit.qubits)
circuit.draw()
output:
┌────────────────────────────────────┐
q_0: ┤0 ├
│ Initialize(0,0.70711,0.70711j,0) │
q_1: ┤1 ├
└────────────────────────────────────┘
inverse
inverse(annotated=False)
GitHub(opens in a new tab)
Invert (take adjoint of) this circuit.
This is done by recursively inverting all gates.
Parameters
annotated (bool(opens in a new tab)) – indicates whether the inverse gate can be implemented as an annotated gate.
Returns
the inverted circuit
Return type
Raises
CircuitError – if the circuit cannot be inverted.
Examples
input:
┌───┐
q_0: ┤ H ├─────■──────
└───┘┌────┴─────┐
q_1: ─────┤ RX(1.57) ├
└──────────┘
output:
┌───┐
q_0: ──────■──────┤ H ├
┌─────┴─────┐└───┘
q_1: ┤ RX(1.57) ├─────
└───────────┘
iswap
iswap(qubit1, qubit2)
GitHub(opens in a new tab)
Apply iSwapGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubits to apply the gate to.
 qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubits to apply the gate to.
Returns
A handle to the instructions created.
Return type
mcp
mcp(lam, control_qubits, target_qubit)
GitHub(opens in a new tab)
Apply MCPhaseGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 lam (ParameterExpression float(opens in a new tab)) – The angle of the rotation.
 control_qubits (Sequence(opens in a new tab)[Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]]) – The qubits used as the controls.
 target_qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) targeted by the gate.
Returns
A handle to the instructions created.
Return type
mcrx
mcrx(theta, q_controls, q_target, use_basis_gates=False)
GitHub(opens in a new tab)
Apply MultipleControlled X rotation gate
Parameters
 self (QuantumCircuit) – The QuantumCircuit object to apply the mcrx gate on.
 theta (float(opens in a new tab)) – angle theta
 q_controls (QuantumRegister orlist(opens in a new tab)(Qubit)) – The list of control qubits
 q_target (Qubit) – The target qubit
 use_basis_gates (bool(opens in a new tab)) – use p, u, cx
Raises
QiskitError – parameter errors
mcry
mcry(theta, q_controls, q_target, q_ancillae=None, mode=None, use_basis_gates=False)
GitHub(opens in a new tab)
Apply MultipleControlled Y rotation gate
Parameters
 self (QuantumCircuit) – The QuantumCircuit object to apply the mcry gate on.
 theta (float(opens in a new tab)) – angle theta
 q_controls (list(opens in a new tab)(Qubit)) – The list of control qubits
 q_target (Qubit) – The target qubit
 q_ancillae (QuantumRegister ortuple(opens in a new tab)(QuantumRegister, int(opens in a new tab))) – The list of ancillary qubits.
 mode (string) – The implementation mode to use
 use_basis_gates (bool(opens in a new tab)) – use p, u, cx
Raises
QiskitError – parameter errors
mcrz
mcrz(lam, q_controls, q_target, use_basis_gates=False)
GitHub(opens in a new tab)
Apply MultipleControlled Z rotation gate
Parameters
 self (QuantumCircuit) – The QuantumCircuit object to apply the mcrz gate on.
 lam (float(opens in a new tab)) – angle lambda
 q_controls (list(opens in a new tab)(Qubit)) – The list of control qubits
 q_target (Qubit) – The target qubit
 use_basis_gates (bool(opens in a new tab)) – use p, u, cx
Raises
QiskitError – parameter errors
mcx
mcx(control_qubits, target_qubit, ancilla_qubits=None, mode='noancilla')
GitHub(opens in a new tab)
Apply MCXGate
.
The multicX gate can be implemented using different techniques, which use different numbers of ancilla qubits and have varying circuit depth. These modes are:
'noancilla'
: Requires 0 ancilla qubits.'recursion'
: Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0.'vchain'
: Requires 2 less ancillas than the number of control qubits.'vchaindirty'
: Same as for the clean ancillas (but the circuit will be longer).
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubits (Sequence[QubitSpecifier]) – The qubits used as the controls.
 target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
 ancilla_qubits (QubitSpecifier  Sequence[QubitSpecifier]  None) – The qubits used as the ancillae, if the mode requires them.
 mode (str(opens in a new tab)) – The choice of mode, explained further above.
Returns
A handle to the instructions created.
Raises
 ValueError(opens in a new tab) – if the given mode is not known, or if too few ancilla qubits are passed.
 AttributeError(opens in a new tab) – if no ancilla qubits are passed, but some are needed.
Return type
measure
measure(qubit, cbit)
GitHub(opens in a new tab)
Measure a quantum bit (qubit
) in the Z basis into a classical bit (cbit
).
When a quantum state is measured, a qubit is projected in the computational (Pauli Z) basis to either $\lvert 0 \rangle$ or $\lvert 1 \rangle$. The classical bit cbit
indicates the result of that projection as a 0
or a 1
respectively. This operation is nonreversible.
Parameters
 qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – qubit(s) to measure.
 cbit (Clbit ClassicalRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Clbit int(opens in a new tab)]) – classical bit(s) to place the measurement result(s) in.
Returns
handle to the added instructions.
Return type
Raises
CircuitError – if arguments have bad format.
Examples
In this example, a qubit is measured and the result of that measurement is stored in the classical bit (usually expressed in diagrams as a double line):
from qiskit import QuantumCircuit
circuit = QuantumCircuit(1, 1)
circuit.h(0)
circuit.measure(0, 0)
circuit.draw()
┌───┐┌─┐
q: ┤ H ├┤M├
└───┘└╥┘
c: 1/══════╩═
0
It is possible to call measure
with lists of qubits
and cbits
as a shortcut for onetoone measurement. These two forms produce identical results:
circuit = QuantumCircuit(2, 2)
circuit.measure([0,1], [0,1])
circuit = QuantumCircuit(2, 2)
circuit.measure(0, 0)
circuit.measure(1, 1)
Instead of lists, you can use QuantumRegister
and ClassicalRegister
under the same logic.
from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister
qreg = QuantumRegister(2, "qreg")
creg = ClassicalRegister(2, "creg")
circuit = QuantumCircuit(qreg, creg)
circuit.measure(qreg, creg)
This is equivalent to:
circuit = QuantumCircuit(qreg, creg)
circuit.measure(qreg[0], creg[0])
circuit.measure(qreg[1], creg[1])
measure_active
measure_active(inplace=True)
GitHub(opens in a new tab)
Adds measurement to all nonidle qubits. Creates a new ClassicalRegister with a size equal to the number of nonidle qubits being measured.
Returns a new circuit with measurements if inplace=False.
Parameters
inplace (bool(opens in a new tab)) – All measurements inplace or return new circuit.
Returns
Returns circuit with measurements when inplace = False.
Return type
measure_all
measure_all(inplace=True, add_bits=True)
GitHub(opens in a new tab)
Adds measurement to all qubits.
By default, adds new classical bits in a ClassicalRegister
to store these measurements. If add_bits=False
, the results of the measurements will instead be stored in the already existing classical bits, with qubit n
being measured into classical bit n
.
Returns a new circuit with measurements if inplace=False
.
Parameters
 inplace (bool(opens in a new tab)) – All measurements inplace or return new circuit.
 add_bits (bool(opens in a new tab)) – Whether to add new bits to store the results.
Returns
Returns circuit with measurements when inplace=False
.
Return type
Raises
CircuitError – if add_bits=False
but there are not enough classical bits.
ms
ms(theta, qubits)
GitHub(opens in a new tab)
Apply MSGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterExpression float(opens in a new tab)) – The angle of the rotation.
 qubits (Sequence(opens in a new tab)[Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]]) – The qubits to apply the gate to.
Returns
A handle to the instructions created.
Return type
num_connected_components
num_connected_components(unitary_only=False)
GitHub(opens in a new tab)
How many nonentangled subcircuits can the circuit be factored to.
Parameters
unitary_only (bool(opens in a new tab)) – Compute only unitary part of graph.
Returns
Number of connected components in circuit.
Return type
num_nonlocal_gates
num_nonlocal_gates()
GitHub(opens in a new tab)
Return number of nonlocal gates (i.e. involving 2+ qubits).
Conditional nonlocal gates are also included.
Return type
num_tensor_factors
num_tensor_factors()
GitHub(opens in a new tab)
Computes the number of tensor factors in the unitary (quantum) part of the circuit only.
Notes
This is here for backwards compatibility, and will be removed in a future release of Qiskit. You should call num_unitary_factors instead.
Return type
num_unitary_factors
num_unitary_factors()
GitHub(opens in a new tab)
Computes the number of tensor factors in the unitary (quantum) part of the circuit only.
Return type
p
p(theta, qubit)
GitHub(opens in a new tab)
Apply PhaseGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterExpression float(opens in a new tab)) – THe angle of the rotation.
 qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
pauli
pauli(pauli_string, qubits)
GitHub(opens in a new tab)
Apply PauliGate
.
Parameters
 pauli_string (str(opens in a new tab)) – A string representing the Pauli operator to apply, e.g. ‘XX’.
 qubits (Sequence(opens in a new tab)[Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]]) – The qubits to apply this gate to.
Returns
A handle to the instructions created.
Return type
power
power(power, matrix_power=False)
GitHub(opens in a new tab)
Raise this circuit to the power of power
.
If power
is a positive integer and matrix_power
is False
, this implementation defaults to calling repeat
. Otherwise, if the circuit is unitary, the matrix is computed to calculate the matrix power.
Parameters
 power (float(opens in a new tab)) – The power to raise this circuit to.
 matrix_power (bool(opens in a new tab)) – If True, the circuit is converted to a matrix and then the matrix power is computed. If False, and
power
is a positive integer, the implementation defaults torepeat
.
Raises
CircuitError – If the circuit needs to be converted to a gate but it is not unitary.
Returns
A circuit implementing this circuit raised to the power of power
.
Return type
prepare_state
prepare_state(state, qubits=None, label=None, normalize=False)
GitHub(opens in a new tab)
Prepare qubits in a specific state.
This class implements a state preparing unitary. Unlike initialize()
it does not reset the qubits first.
Parameters

state (Statevector  Sequence[complex(opens in a new tab)]  str(opens in a new tab) int(opens in a new tab)) –
The state to initialize to, can be either of the following.
 Statevector or vector of complex amplitudes to initialize to.
 Labels of basis states of the Pauli eigenstates Z, X, Y. See
Statevector.from_label()
. Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label ‘01’ initializes the qubit zero to $1\rangle$ and the qubit one to $0\rangle$.  An integer that is used as a bitmap indicating which qubits to initialize to $1\rangle$. Example: setting params to 5 would initialize qubit 0 and qubit 2 to $1\rangle$ and qubit 1 to $0\rangle$.

qubits (Sequence[QubitSpecifier]  None) – Qubits to initialize. If
None
the initialization is applied to all qubits in the circuit. 
label (str(opens in a new tab)  None) – An optional label for the gate

normalize (bool(opens in a new tab)) – Whether to normalize an input array to a unit vector.
Returns
A handle to the instruction that was just initialized
Return type
Examples
Prepare a qubit in the state $(0\rangle  1\rangle) / \sqrt{2}$.
import numpy as np
from qiskit import QuantumCircuit
circuit = QuantumCircuit(1)
circuit.prepare_state([1/np.sqrt(2), 1/np.sqrt(2)], 0)
circuit.draw()
output:
┌─────────────────────────────────────┐
q_0: ┤ State Preparation(0.70711,0.70711) ├
└─────────────────────────────────────┘
Prepare from a string two qubits in the state $10\rangle$. The order of the labels is reversed with respect to qubit index. More information about labels for basis states are in Statevector.from_label()
.
import numpy as np
from qiskit import QuantumCircuit
circuit = QuantumCircuit(2)
circuit.prepare_state('01', circuit.qubits)
circuit.draw()
output:
┌─────────────────────────┐
q_0: ┤0 ├
│ State Preparation(0,1) │
q_1: ┤1 ├
└─────────────────────────┘
Initialize two qubits from an array of complex amplitudes .. codeblock:
import numpy as np
from qiskit import QuantumCircuit
circuit = QuantumCircuit(2)
circuit.prepare_state([0, 1/np.sqrt(2), 1.j/np.sqrt(2), 0], circuit.qubits)
circuit.draw()
output:
┌───────────────────────────────────────────┐
q_0: ┤0 ├
│ State Preparation(0,0.70711,0.70711j,0) │
q_1: ┤1 ├
└───────────────────────────────────────────┘
qbit_argument_conversion
qbit_argument_conversion(qubit_representation)
GitHub(opens in a new tab)
Converts several qubit representations (such as indexes, range, etc.) into a list of qubits.
Parameters
qubit_representation (Object) – representation to expand
Returns
the resolved instances of the qubits.
Return type
List(Qubit)
qubit_duration
qubit_duration(*qubits)
GitHub(opens in a new tab)
Return the duration between the start and stop time of the first and last instructions, excluding delays, over the supplied qubits. Its time unit is self.unit
.
Parameters
*qubits (Qubit int(opens in a new tab)) – Qubits within self
to include.
Returns
Return the duration between the first start and last stop time of nondelay instructions
Return type
qubit_start_time
qubit_start_time(*qubits)
GitHub(opens in a new tab)
Return the start time of the first instruction, excluding delays, over the supplied qubits. Its time unit is self.unit
.
Return 0 if there are no instructions over qubits
Parameters
 *qubits (Qubit int(opens in a new tab)) – Qubits within
self
to include. Integers are allowed for qubits, indicating  self.qubits. (indices of) –
Returns
Return the start time of the first instruction, excluding delays, over the qubits
Raises
CircuitError – if self
is a notyet scheduled circuit.
Return type
qubit_stop_time
qubit_stop_time(*qubits)
GitHub(opens in a new tab)
Return the stop time of the last instruction, excluding delays, over the supplied qubits. Its time unit is self.unit
.
Return 0 if there are no instructions over qubits
Parameters
 *qubits (Qubit int(opens in a new tab)) – Qubits within
self
to include. Integers are allowed for qubits, indicating  self.qubits. (indices of) –
Returns
Return the stop time of the last instruction, excluding delays, over the qubits
Raises
CircuitError – if self
is a notyet scheduled circuit.
Return type
r
r(theta, phi, qubit)
GitHub(opens in a new tab)
Apply RGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterExpression float(opens in a new tab)) – The angle of the rotation.
 phi (ParameterExpression float(opens in a new tab)) – The angle of the axis of rotation in the xy plane.
 qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
rcccx
rcccx(control_qubit1, control_qubit2, control_qubit3, target_qubit)
GitHub(opens in a new tab)
Apply RC3XGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) used as the first control.
 control_qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) used as the second control.
 control_qubit3 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) used as the third control.
 target_qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) targeted by the gate.
Returns
A handle to the instructions created.
Return type
rccx
rccx(control_qubit1, control_qubit2, target_qubit)
GitHub(opens in a new tab)
Apply RCCXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) used as the first control.
 control_qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) used as the second control.
 target_qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) targeted by the gate.
Returns
A handle to the instructions created.
Return type
remove_final_measurements
remove_final_measurements(inplace=True)
GitHub(opens in a new tab)
Removes final measurements and barriers on all qubits if they are present. Deletes the classical registers that were used to store the values from these measurements that become idle as a result of this operation, and deletes classical bits that are referenced only by removed registers, or that aren’t referenced at all but have become idle as a result of this operation.
Measurements and barriers are considered final if they are followed by no other operations (aside from other measurements or barriers.)
Parameters
inplace (bool(opens in a new tab)) – All measurements removed inplace or return new circuit.
Returns
Returns the resulting circuit when inplace=False
, else None.
Return type
repeat
repeat(reps)
GitHub(opens in a new tab)
Repeat this circuit reps
times.
Parameters
reps (int(opens in a new tab)) – How often this circuit should be repeated.
Returns
A circuit containing reps
repetitions of this circuit.
Return type
reset
reset(qubit)
GitHub(opens in a new tab)
Reset the quantum bit(s) to their default state.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – qubit(s) to reset.
Returns
handle to the added instruction.
Return type
reverse_bits
reverse_bits()
GitHub(opens in a new tab)
Return a circuit with the opposite order of wires.
The circuit is “vertically” flipped. If a circuit is defined over multiple registers, the resulting circuit will have the same registers but with their order flipped.
This method is useful for converting a circuit written in littleendian convention to the bigendian equivalent, and vice versa.
Returns
the circuit with reversed bit order.
Return type
Examples
input:
┌───┐
a_0: ┤ H ├──■─────────────────
└───┘┌─┴─┐
a_1: ─────┤ X ├──■────────────
└───┘┌─┴─┐
a_2: ──────────┤ X ├──■───────
└───┘┌─┴─┐
b_0: ───────────────┤ X ├──■──
└───┘┌─┴─┐
b_1: ────────────────────┤ X ├
└───┘
output:
┌───┐
b_0: ────────────────────┤ X ├
┌───┐└─┬─┘
b_1: ───────────────┤ X ├──■──
┌───┐└─┬─┘
a_0: ──────────┤ X ├──■───────
┌───┐└─┬─┘
a_1: ─────┤ X ├──■────────────
┌───┐└─┬─┘
a_2: ┤ H ├──■─────────────────
└───┘
reverse_ops
reverse_ops()
GitHub(opens in a new tab)
Reverse the circuit by reversing the order of instructions.
This is done by recursively reversing all instructions. It does not invert (adjoint) any gate.
Returns
the reversed circuit.
Return type
Examples
input:
┌───┐
q_0: ┤ H ├─────■──────
└───┘┌────┴─────┐
q_1: ─────┤ RX(1.57) ├
└──────────┘
output:
┌───┐
q_0: ─────■──────┤ H ├
┌────┴─────┐└───┘
q_1: ┤ RX(1.57) ├─────
└──────────┘
rv
rv(vx, vy, vz, qubit)
GitHub(opens in a new tab)
Apply RVGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Rotation around an arbitrary rotation axis $v$, where $v$ is the angle of rotation in radians.
Parameters
 vx (ParameterExpression float(opens in a new tab)) – xcomponent of the rotation axis.
 vy (ParameterExpression float(opens in a new tab)) – ycomponent of the rotation axis.
 vz (ParameterExpression float(opens in a new tab)) – zcomponent of the rotation axis.
 qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
rx
rx(theta, qubit, label=None)
GitHub(opens in a new tab)
Apply RXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterValueType) – The rotation angle of the gate.
 qubit (QubitSpecifier) – The qubit(s) to apply the gate to.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
Returns
A handle to the instructions created.
Return type
rxx
rxx(theta, qubit1, qubit2)
GitHub(opens in a new tab)
Apply RXXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterExpression float(opens in a new tab)) – The angle of the rotation.
 qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
 qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
ry
ry(theta, qubit, label=None)
GitHub(opens in a new tab)
Apply RYGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterValueType) – The rotation angle of the gate.
 qubit (QubitSpecifier) – The qubit(s) to apply the gate to.
 label (str(opens in a new tab)  None) – The string label of the gate in the circuit.
Returns
A handle to the instructions created.
Return type
ryy
ryy(theta, qubit1, qubit2)
GitHub(opens in a new tab)
Apply RYYGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterExpression float(opens in a new tab)) – The rotation angle of the gate.
 qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
 qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
rz
rz(phi, qubit)
GitHub(opens in a new tab)
Apply RZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 phi (ParameterExpression float(opens in a new tab)) – The rotation angle of the gate.
 qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
rzx
rzx(theta, qubit1, qubit2)
GitHub(opens in a new tab)
Apply RZXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterExpression float(opens in a new tab)) – The rotation angle of the gate.
 qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
 qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
rzz
rzz(theta, qubit1, qubit2)
GitHub(opens in a new tab)
Apply RZZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterExpression float(opens in a new tab)) – The rotation angle of the gate.
 qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
 qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
s
s(qubit)
GitHub(opens in a new tab)
Apply SGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
sdg
sdg(qubit)
GitHub(opens in a new tab)
Apply SdgGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
size
size(filter_function=<function QuantumCircuit.<lambda>>)
GitHub(opens in a new tab)
Returns total number of instructions in circuit.
Parameters
filter_function (callable) – a function to filter out some instructions. Should take as input a tuple of (Instruction, list(Qubit), list(Clbit)). By default filters out “directives”, such as barrier or snapshot.
Returns
Total number of gate operations.
Return type
swap
swap(qubit1, qubit2)
GitHub(opens in a new tab)
Apply SwapGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 qubit1 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubits to apply the gate to.
 qubit2 (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubits to apply the gate to.
Returns
A handle to the instructions created.
Return type
switch
switch(target: Clbit  ClassicalRegister  int  slice  Sequence[Clbit  int], cases: None, qubits: None, clbits: None, *, label: str  None) → SwitchContext
GitHub(opens in a new tab)
switch(target: Clbit  ClassicalRegister  int  slice  Sequence[Clbit  int], cases: Iterable[Tuple[Any, QuantumCircuit]], qubits: Sequence[Qubit  QuantumRegister  int  slice  Sequence[Qubit  int]], clbits: Sequence[Clbit  ClassicalRegister  int  slice  Sequence[Clbit  int]], *, label: str  None) → InstructionSet
Create a switch
/case
structure on this circuit.
There are two forms for calling this function. If called with all its arguments (with the possible exception of label
), it will create a SwitchCaseOp
with the given case structure. If cases
(and qubits
and clbits
) are not passed, then this acts as a context manager, which will automatically build a SwitchCaseOp
when the scope finishes. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you.
Example usage:
from qiskit.circuit import QuantumCircuit, ClassicalRegister, QuantumRegister
qreg = QuantumRegister(3)
creg = ClassicalRegister(3)
qc = QuantumCircuit(qreg, creg)
qc.h([0, 1, 2])
qc.measure([0, 1, 2], [0, 1, 2])
with qc.switch(creg) as case:
with case(0):
qc.x(0)
with case(1, 2):
qc.z(1)
with case(case.DEFAULT):
qc.cx(0, 1)
Parameters
 target (Union[ClassicalRegister, Clbit]) – The classical value to switch one. This must be integerlike.
 cases (Iterable[Tuple[Any(opens in a new tab), QuantumCircuit]]) – A sequence of case specifiers. Each tuple defines one case body (the second item). The first item of the tuple can be either a single integer value, the special value
CASE_DEFAULT
, or a tuple of several integer values. Each of the integer values will be tried in turn; control will then pass to the body corresponding to the first match.CASE_DEFAULT
matches all possible values. Omit in contextmanager form.  qubits (Sequence[Qubit]) – The circuit qubits over which all case bodies execute. Omit in contextmanager form.
 clbits (Sequence[Clbit]) – The circuit clbits over which all case bodies execute. Omit in contextmanager form.
 label (Optional[str(opens in a new tab)]) – The string label of the instruction in the circuit.
Returns
If used in contextmanager mode, then this should be used as a with
resource, which will return an object that can be repeatedly entered to produce cases for the switch statement. If the full form is used, then this returns a handle to the instructions created.
Return type
InstructionSet or SwitchCaseContext
Raises
CircuitError – if an incorrect calling convention is used.
sx
sx(qubit)
GitHub(opens in a new tab)
Apply SXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
sxdg
sxdg(qubit)
GitHub(opens in a new tab)
Apply SXdgGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
t
t(qubit)
GitHub(opens in a new tab)
Apply TGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
tdg
tdg(qubit)
GitHub(opens in a new tab)
Apply TdgGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
tensor
tensor(other, inplace=False)
GitHub(opens in a new tab)
Tensor self
with other
.
Remember that in the littleendian convention the leftmost operation will be at the bottom of the circuit. See also the docs for more information.
┌────────┐ ┌─────┐ ┌─────┐
q_0: ┤ bottom ├ ⊗ q_0: ┤ top ├ = q_0: ─┤ top ├──
└────────┘ └─────┘ ┌┴─────┴─┐
q_1: ┤ bottom ├
└────────┘
Parameters
 other (QuantumCircuit) – The other circuit to tensor this circuit with.
 inplace (bool(opens in a new tab)) – If True, modify the object. Otherwise return composed circuit.
Return type
QuantumCircuit  None
Examples
from qiskit import QuantumCircuit
top = QuantumCircuit(1)
top.x(0);
bottom = QuantumCircuit(2)
bottom.cry(0.2, 0, 1);
tensored = bottom.tensor(top)
tensored.draw('mpl')
Returns
The tensored circuit (returns None if inplace==True).
Return type
to_gate
to_gate(parameter_map=None, label=None)
GitHub(opens in a new tab)
Create a Gate out of this circuit.
Parameters
 parameter_map (dict(opens in a new tab)) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the gate. If None, existing circuit parameters will also parameterize the gate.
 label (str(opens in a new tab)) – Optional gate label.
Returns
a composite gate encapsulating this circuit (can be decomposed back)
Return type
to_instruction
to_instruction(parameter_map=None, label=None)
GitHub(opens in a new tab)
Create an Instruction out of this circuit.
Parameters
 parameter_map (dict(opens in a new tab)) – For parameterized circuits, a mapping from parameters in the circuit to parameters to be used in the instruction. If None, existing circuit parameters will also parameterize the instruction.
 label (str(opens in a new tab)) – Optional gate label.
Returns
a composite instruction encapsulating this circuit (can be decomposed back)
Return type
u
u(theta, phi, lam, qubit)
GitHub(opens in a new tab)
Apply UGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (ParameterExpression float(opens in a new tab)) – The $\theta$ rotation angle of the gate.
 phi (ParameterExpression float(opens in a new tab)) – The $\phi$ rotation angle of the gate.
 lam (ParameterExpression float(opens in a new tab)) – The $\lambda$ rotation angle of the gate.
 qubit (Qubit QuantumRegister int(opens in a new tab) slice(opens in a new tab) Sequence(opens in a new tab)[Qubit int(opens in a new tab)]) – The qubit(s) to apply the gate to.
Returns
A handle to the instructions created.
Return type
unitary
unitary(obj, qubits, label=None)
GitHub(opens in a new tab)
Apply unitary gate specified by obj
to qubits
.
Parameters
 obj (np.ndarray  Gate  BaseOperator) – Unitary operator.
 qubits (Sequence[QubitSpecifier]) – The circuit qubits to apply the transformation to.
 label (str(opens in a new tab)  None) – Unitary name for backend [Default: None].
Returns
The quantum circuit.
Return type
Example
Apply a gate specified by a unitary matrix to a quantum circuit
from qiskit import QuantumCircuit
matrix = [[0, 0, 0, 1],
[0, 0, 1, 0],
[1, 0, 0, 0],
[0, 1, 0, 0]]
circuit = QuantumCircuit(2)
circuit.unitary(matrix, [0, 1])
while_loop
while_loop(condition: tuple[ClassicalRegister  Clbit, int]  expr.Expr, body: None, qubits: None, clbits: None, *, label: str  None) → WhileLoopContext
GitHub(opens in a new tab)
while_loop(condition: tuple[ClassicalRegister  Clbit, int]  expr.Expr, body: QuantumCircuit, qubits: Sequence[Qubit  QuantumRegister  int  slice  Sequence[Qubit  int]], clbits: Sequence[Clbit  ClassicalRegister  int  slice  Sequence[Clbit  int]], *, label: str  None) → InstructionSet
Create a while
loop on this circuit.
There are two forms for calling this function. If called with all its arguments (with the possible exception of label
), it will create a WhileLoopOp
with the given body
. If body
(and qubits
and clbits
) are not passed, then this acts as a context manager, which will automatically build a WhileLoopOp
when the scope finishes. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you.
Example usage:
from qiskit.circuit import QuantumCircuit, Clbit, Qubit
bits = [Qubit(), Qubit(), Clbit()]
qc = QuantumCircuit(bits)
with qc.while_loop((bits[2], 0)):
qc.h(0)
qc.cx(0, 1)
qc.measure(0, 0)
Parameters
 condition (Tuple[Union[ClassicalRegister, Clbit], int(opens in a new tab)]) – An equality condition to be checked prior to executing
body
. The lefthand side of the condition must be aClassicalRegister
or aClbit
, and the righthand side must be an integer or boolean.  body (Optional[QuantumCircuit]) – The loop body to be repeatedly executed. Omit this to use the contextmanager mode.
 qubits (Optional[Sequence[Qubit]]) – The circuit qubits over which the loop body should be run. Omit this to use the contextmanager mode.
 clbits (Optional[Sequence[Clbit]]) – The circuit clbits over which the loop body should be run. Omit this to use the contextmanager mode.
 label (Optional[str(opens in a new tab)]) – The string label of the instruction in the circuit.
Returns
If used in contextmanager mode, then this should be used as a with
resource, which will infer the block content and operands on exit. If the full form is used, then this returns a handle to the instructions created.
Return type
InstructionSet or WhileLoopContext
Raises
CircuitError – if an incorrect calling convention is used.