QuantumCircuit
class QuantumCircuit(*regs, name=None, global_phase=0, metadata=None)
Bases: object
Create a new circuit.
A circuit is a list of instructions bound to some registers.
Parameters

regs (list(
Register
) or list(int
) or list(list(Bit
))) –The registers to be included in the circuit.

If a list of
Register
objects, represents 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) – the name of the quantum circuit. If not set, an automatically generated string will be assigned.

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

metadata (dict) – Arbitrary key value metadata to associate with the circuit. This gets stored as 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')
(Source code, png, hires.png, pdf)
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')
(Source code, png, hires.png, pdf)
Methods
add_bits
QuantumCircuit.add_bits(bits)
Add Bits to the circuit.
Return type
None
add_calibration
QuantumCircuit.add_calibration(gate, qubits, schedule, params=None)
Register a lowlevel, custom pulse definition for the given gate.
Parameters
 gate (Union[Gate, str]) – Gate information.
 qubits (Union[int, Tuple[int]]) – List of qubits to be measured.
 schedule (Schedule) – Schedule information.
 params (Optional[List[Union[float, Parameter]]]) – A list of parameters.
Raises
Exception – if the gate is of type string and params is None.
Return type
None
add_register
QuantumCircuit.add_register(*regs)
Add registers.
Return type
None
append
QuantumCircuit.append(instruction, qargs=None, cargs=None)
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 (
Union
[Operation
,CircuitInstruction
]) –Instruction
instance to append, or aCircuitInstruction
with all its context.  qargs (
Optional
[Sequence
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]]]) – specifiers of theQubit
s to attach instruction to.  cargs (
Optional
[Sequence
[Union
[Clbit
,ClassicalRegister
,int
,slice
,Sequence
[Union
[Clbit
,int
]]]]]) – specifiers of theClbit
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
QuantumCircuit.assign_parameters(parameters, inplace=False)
Assign parameters to new parameters or values.
If parameters
is passed as a dictionary, the keys must 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.
Parameters
 parameters (
Union
[Mapping
[Parameter
,Union
[ParameterExpression
,float
]],Sequence
[Union
[ParameterExpression
,float
]]]) – Either a dictionary or iterable specifying the new parameter values.  inplace (
bool
) – If False, a copy of the circuit with the bound parameters is returned. If True the circuit instance itself is modified.
Raises
 CircuitError – If parameters is a dict and contains parameters not present in the circuit.
 ValueError – If parameters is a list/array and the length mismatches the number of free parameters in the circuit.
Return type
Optional
[QuantumCircuit]
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
QuantumCircuit.barrier(*qargs, label=None)
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) – The string label of the barrier.
Returns
handle to the added instructions.
Return type
bind_parameters
QuantumCircuit.bind_parameters(values)
Assign numeric parameters to values yielding a new circuit.
If the values are given as list or array they are bound to the circuit in the order of parameters
(see the docstring for more details).
To assign new Parameter objects or bind the values inplace, without yielding a new circuit, use the assign_parameters()
method.
Parameters
values (Union
[Mapping
[Parameter
, float
], Sequence
[float
]]) – {parameter: value, ...}
or [value1, value2, ...]
Raises
 CircuitError – If values is a dict and contains parameters not present in the circuit.
 TypeError – If values contains a ParameterExpression.
Return type
Returns
Copy of self with assignment substitution.
break_loop
QuantumCircuit.break_loop()
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.
Return type
Returns
A handle to the instruction created.
Raises
CircuitError – if this method was called within a builder context, but not contained within a loop.
cast
static QuantumCircuit.cast(value, type_)
Best effort to cast value to type. Otherwise, returns the value.
Return type
Union
[TypeVar
(S
), TypeVar
(T
)]
cbit_argument_conversion
QuantumCircuit.cbit_argument_conversion(clbit_representation)
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
List(tuple)
ccx
QuantumCircuit.ccx(control_qubit1, control_qubit2, target_qubit, ctrl_state=None)
Apply CCXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the first control.  control_qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the second control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
ccz
QuantumCircuit.ccz(control_qubit1, control_qubit2, target_qubit, label=None, ctrl_state=None)
Apply CCZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the first control.  control_qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the second control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘10’). Defaults to controlling on the ‘11’ state.
Return type
Returns
A handle to the instructions created.
ch
QuantumCircuit.ch(control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CHGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
clear
QuantumCircuit.clear()
Clear all instructions in self.
Clearing the circuits will keep the metadata and calibrations.
Return type
None
cls_instances
classmethod QuantumCircuit.cls_instances()
Return the current number of instances of this class, useful for auto naming.
Return type
int
cls_prefix
classmethod QuantumCircuit.cls_prefix()
Return the prefix to use for auto naming.
Return type
str
cnot
QuantumCircuit.cnot(control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
QuantumCircuit.cx: the same function with a different name.
compose
QuantumCircuit.compose(other, qubits=None, clbits=None, front=False, inplace=False, wrap=False)
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[Qubitint]) – qubits of self to compose onto.
 clbits (list[Clbitint]) – clbits of self to compose onto.
 front (bool) – If True, front composition will be performed. This is not possible within controlflow builder context managers.
 inplace (bool) – If True, modify the object. Otherwise return composed circuit.
 wrap (bool) – 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
QuantumCircuit.continue_loop()
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.
Return type
Returns
A handle to the instruction created.
Raises
CircuitError – if this method was called within a builder context, but not contained within a loop.
control
QuantumCircuit.control(num_ctrl_qubits=1, label=None, ctrl_state=None)
Control this circuit on num_ctrl_qubits
qubits.
Parameters
 num_ctrl_qubits (int) – The number of control qubits.
 label (str) – An optional label to give the controlled operation for visualization.
 ctrl_state (str or int) – The control state in decimal or as a bitstring (e.g. ‘111’). If None, use
2**num_ctrl_qubits  1
.
Returns
The controlled version of this circuit.
Return type
Raises
CircuitError – If the circuit contains a nonunitary operation and cannot be controlled.
copy
QuantumCircuit.copy(name=None)
Copy the circuit.
Parameters
name (str) – 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
QuantumCircuit.copy_empty_like(name=None)
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) – Name for the copied circuit. If None, then the name stays the same.
Returns
An empty copy of self.
Return type
count_ops
QuantumCircuit.count_ops()
Count each operation kind in the circuit.
Returns
a breakdown of how many operations of each kind, sorted by amount.
Return type
OrderedDict
cp
QuantumCircuit.cp(theta, control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CPhaseGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The angle of the rotation.  control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
crx
QuantumCircuit.crx(theta, control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CRXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The angle of the rotation.  control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
cry
QuantumCircuit.cry(theta, control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CRYGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The angle of the rotation.  control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
crz
QuantumCircuit.crz(theta, control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CRZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The angle of the rotation.  control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
cs
QuantumCircuit.cs(control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CSGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
csdg
QuantumCircuit.csdg(control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CSdgGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
cswap
QuantumCircuit.cswap(control_qubit, target_qubit1, target_qubit2, label=None, ctrl_state=None)
Apply CSwapGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  target_qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
csx
QuantumCircuit.csx(control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CSXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
cu
QuantumCircuit.cu(theta, phi, lam, gamma, control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CUGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The $\theta$ rotation angle of the gate.  phi (
Union
[ParameterExpression
,float
]) – The $\phi$ rotation angle of the gate.  lam (
Union
[ParameterExpression
,float
]) – The $\lambda$ rotation angle of the gate.  gamma (
Union
[ParameterExpression
,float
]) – The global phase applied of the U gate, if applied.  control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
cx
QuantumCircuit.cx(control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
cy
QuantumCircuit.cy(control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CYGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the controls.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
cz
QuantumCircuit.cz(control_qubit, target_qubit, label=None, ctrl_state=None)
Apply CZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the controls.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  label (
Optional
[str
]) – The string label of the gate in the circuit.  ctrl_state (
Union
[str
,int
,None
]) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.
Return type
Returns
A handle to the instructions created.
dcx
QuantumCircuit.dcx(qubit1, qubit2)
Apply DCXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.  qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
decompose
QuantumCircuit.decompose(gates_to_decompose=None, reps=1)
Call a decomposition pass on this circuit, to decompose one level (shallow decompose).
Parameters
 gates_to_decompose (str or list(str)) – optional subset of gates to decompose. Defaults to all gates in circuit.
 reps (int) – 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
QuantumCircuit.delay(duration, qarg=None, unit='dt')
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 or float or ParameterExpression) – duration of the delay.
 qarg (Object) – qubit argument to apply this delay.
 unit (str) – unit of the duration. Supported units: ‘s’, ‘ms’, ‘us’, ‘ns’, ‘ps’, ‘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
QuantumCircuit.depth(filter_function=<function QuantumCircuit.<lambda>>)
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
int
Notes
The circuit depth and the DAG depth need not be the same.
diagonal
QuantumCircuit.diagonal(diag, qubit)
Attach a diagonal gate to a circuit.
The decomposition is based on Theorem 7 given in “Synthesis of Quantum Logic Circuits” by Shende et al. (https://arxiv.org/pdf/quantph/0406176.pdf(opens in a new tab)).
Parameters
 diag (list) – list of the 2^k diagonal entries (for a diagonal gate on k qubits). Must contain at least two entries
 qubit (QuantumRegisterlist) – list of k qubits the diagonal is acting on (the order of the qubits specifies the computational basis in which the diagonal gate is provided: the first element in diag acts on the state where all the qubits in q are in the state 0, the second entry acts on the state where all the qubits q[1],…,q[k1] are in the state zero and q[0] is in the state 1, and so on)
Returns
the diagonal gate which was attached to the circuit.
Return type
Raises
QiskitError – if the list of the diagonal entries or the qubit list is in bad format; if the number of diagonal entries is not 2^k, where k denotes the number of qubits
draw
QuantumCircuit.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)
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.
Parameters
 output (str) – 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) – scale of image to draw (shrink if < 1.0). Only used by the mpl, latex and latex_source outputs. Defaults to 1.0.
 filename (str) – file path to save image to. Defaults to None.
 style (dict or str) – dictionary of style or file name of style json file. This option is only used by the mpl or latex output type. If style is a str, it is used as the path to a json file which contains a style dict. The file will be opened, parsed, and then any style elements in the dict will replace the default values in the input dict. A file to be loaded must end in
.json
, but the name entered here can omit.json
. For example,style='iqx.json'
orstyle='iqx'
. If style is a dict and the'name'
key is set, that name will be used to load a json file, followed by loading the other items in the style dict. For example,style={'name': 'iqx'}
. If style is not a str and name is not a key in the style dict, then the default value from the user config file (usually~/.qiskit/settings.conf
) will be used, for example,circuit_mpl_style = iqx
. If none of these are set, the default style will be used. The search path for style json files can be specified in the user config, for example,circuit_mpl_style_path = /home/user/styles:/home/user
. See:DefaultStyle
for more information on the contents.  interactive (bool) – when set to true, show the circuit in a new window (for mpl this depends on the matplotlib backend being used supporting this). Note when used with either the text or the latex_source output type this has no effect and will be silently ignored. Defaults to False.
 reverse_bits (bool) – when set to True, reverse the bit order inside registers for the output visualization. Defaults to False unless the user config file (usually
~/.qiskit/settings.conf
) has an alternative value set. For example,circuit_reverse_bits = True
.  plot_barriers (bool) – enable/disable drawing barriers in the output circuit. Defaults to True.
 justify (string) – 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 (string) –
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 the text output, will be silently ignored otherwise.  idle_wires (bool) – include idle wires (wires with no circuit elements) in output visualization. Default is True.
 with_layout (bool) – include layout information, with labels on the physical layout. Default is True.
 fold (int) – 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 using
shutil.get_terminal_size()
. However, if running in jupyter, the default line length is set to 80 characters. In mpl, it is the number of (visual) layers before folding. Default is 25.  ax (matplotlib.axes.Axes) – Only used by the mpl backend. An optional 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) – Optional. Adds
0>
in the beginning of the wire. Default is False.  cregbundle (bool) – Optional. If set True, bundle classical registers. Default is True, except for when
output
is set to"text"
.  wire_order (list) – Optional. 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).
Returns
TextDrawing
or matplotlib.figure
or PIL.Image
or str
:

TextDrawing (output=’text’)
A drawing that can be printed as ascii art.

matplotlib.figure.Figure (output=’mpl’)
A matplotlib figure object for the circuit diagram.

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

str (output=’latex_source’)
The LaTeX source code for visualizing the circuit diagram.
Raises
 VisualizationError – when an invalid output method is selected
 ImportError – when the output methods requires noninstalled libraries.
Example
from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
q = QuantumRegister(1)
c = ClassicalRegister(1)
qc = QuantumCircuit(q, c)
qc.h(q)
qc.measure(q, c)
qc.draw(output='mpl', style={'backgroundcolor': '#EEEEEE'})
(Source code, png, hires.png, pdf)
ecr
QuantumCircuit.ecr(qubit1, qubit2)
Apply ECRGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubits to apply the gate to.  qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubits to apply the gate to.
Return type
Returns
A handle to the instructions created.
find_bit
QuantumCircuit.find_bit(bit)
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, List[Tuple(Register, int)])
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.
for_loop
QuantumCircuit.for_loop(indexset: Iterable[int], loop_parameter: Optional[qiskit.circuit.parameter.Parameter], body: None, qubits: None, clbits: None, *, label: Optional[str]) → qiskit.circuit.controlflow.for_loop.ForLoopContext
QuantumCircuit.for_loop(indexset: Iterable[int], loop_parameter: Optional[qiskit.circuit.parameter.Parameter], body: QuantumCircuit, qubits: Sequence[Union[qiskit.circuit.quantumregister.Qubit, qiskit.circuit.quantumregister.QuantumRegister, int, slice, Sequence[Union[qiskit.circuit.quantumregister.Qubit, int]]]], clbits: Sequence[Union[qiskit.circuit.classicalregister.Clbit, qiskit.circuit.classicalregister.ClassicalRegister, int, slice, Sequence[Union[qiskit.circuit.classicalregister.Clbit, int]]]], *, label: Optional[str]) → qiskit.circuit.instructionset.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]) – 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]) – 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.
fredkin
QuantumCircuit.fredkin(control_qubit, target_qubit1, target_qubit2)
Apply CSwapGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the control.  target_qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  target_qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.
Return type
Returns
A handle to the instructions created.
QuantumCircuit.cswap: the same function with a different name.
from_instructions
static QuantumCircuit.from_instructions(instructions, *, qubits=(), clbits=(), name=None, global_phase=0, metadata=None)
Construct a circuit from an iterable of CircuitInstructions.
Parameters
 instructions – The instructions to add to the circuit.
 qubits – Any qubits to add to the circuit. This argument can be used, for example, to enforce a particular ordering of qubits.
 clbits – Any classical bits to add to the circuit. This argument can be used, for example, to enforce a particular ordering of classical bits.
 name – The name of the circuit.
 global_phase – The global phase of the circuit in radians.
 metadata – Arbitrary key value metadata to associate with the circuit.
Returns
The quantum circuit.
from_qasm_file
static QuantumCircuit.from_qasm_file(path)
Take in a QASM file and generate a QuantumCircuit object.
Parameters
path (str) – Path to the file for a QASM program
Returns
The QuantumCircuit object for the input QASM
Return type
from_qasm_str
static QuantumCircuit.from_qasm_str(qasm_str)
Take in a QASM string and generate a QuantumCircuit object.
Parameters
qasm_str (str) – A QASM program string
Returns
The QuantumCircuit object for the input QASM
Return type
get_instructions
QuantumCircuit.get_instructions(name)
Get instructions matching name.
Parameters
name (str) – The name of instruction to.
Returns
list of (instruction, qargs, cargs).
Return type
list(tuple)
h
QuantumCircuit.h(qubit)
Apply HGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Union
[Qubit
, QuantumRegister
, int
, slice
, Sequence
[Union
[Qubit
, int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
hamiltonian
QuantumCircuit.hamiltonian(operator, time, qubits, label=None)
Apply hamiltonian evolution to qubits.
has_calibration_for
QuantumCircuit.has_calibration_for(instr_context)
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_register
QuantumCircuit.has_register(register)
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
bool
i
QuantumCircuit.i(qubit)
Apply IGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Union
[Qubit
, QuantumRegister
, int
, slice
, Sequence
[Union
[Qubit
, int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
id
QuantumCircuit.id(qubit)
Apply IGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Union
[Qubit
, QuantumRegister
, int
, slice
, Sequence
[Union
[Qubit
, int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
QuantumCircuit.i: the same function.
if_else
QuantumCircuit.if_else(condition, true_body, false_body, qubits, clbits, label=None)
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 (
Union
[Tuple
[ClassicalRegister
,int
],Tuple
[Clbit
,int
],Tuple
[Clbit
,bool
]]) – A condition to be evaluated at circuit runtime which, if true, will trigger the evaluation oftrue_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
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]]) – The circuit qubits over which the if/else should be run.  clbits (
Sequence
[Union
[Clbit
,ClassicalRegister
,int
,slice
,Sequence
[Union
[Clbit
,int
]]]]) – The circuit clbits over which the if/else should be run.  label (
Optional
[str
]) – The string label of the instruction in the circuit.
Raises
CircuitError – If the provided condition references Clbits outside the enclosing circuit.
Return type
Returns
A handle to the instruction created.
if_test
QuantumCircuit.if_test(condition: Tuple[Union[qiskit.circuit.classicalregister.ClassicalRegister, qiskit.circuit.classicalregister.Clbit], int], true_body: None, qubits: None, clbits: None, *, label: Optional[str]) → qiskit.circuit.controlflow.if_else.IfContext
QuantumCircuit.if_test(condition: Tuple[Union[qiskit.circuit.classicalregister.ClassicalRegister, qiskit.circuit.classicalregister.Clbit], int], true_body: QuantumCircuit, qubits: Sequence[Union[qiskit.circuit.quantumregister.Qubit, qiskit.circuit.quantumregister.QuantumRegister, int, slice, Sequence[Union[qiskit.circuit.quantumregister.Qubit, int]]]], clbits: Sequence[Union[qiskit.circuit.classicalregister.Clbit, qiskit.circuit.classicalregister.ClassicalRegister, int, slice, Sequence[Union[qiskit.circuit.classicalregister.Clbit, int]]]], *, label: Optional[str] = 'None') → qiskit.circuit.instructionset.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]) – 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]) – 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
QuantumCircuit.initialize(params, qubits=None)
Initialize qubits in a specific state.
Qubit initialization is done by first resetting the qubits to $0\rangle$ followed by calling qiskit.extensions.StatePreparation
class to prepare the qubits in a specified state. Both these steps are included in the qiskit.extensions.Initialize
instruction.
Parameters

params (str or list or int) –
 str: 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$.  list: vector of complex amplitudes to initialize to.
 int: 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$.
 str: labels of basis states of the Pauli eigenstates Z, X, Y. See

qubits (QuantumRegister orQubit or int) –
 QuantumRegister: A list of qubits to be initialized [Default: None].
 Qubit: Single qubit to be initialized [Default: None].
 int: Index of qubit to be initialized [Default: None].
 list: Indexes of qubits to be initialized [Default: None].
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.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
QuantumCircuit.inverse()
Invert (take adjoint of) this circuit.
This is done by recursively inverting all gates.
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) ├─────
└───────────┘
iso
QuantumCircuit.iso(isometry, q_input, q_ancillas_for_output, q_ancillas_zero=None, q_ancillas_dirty=None, epsilon=1e10)
Attach an arbitrary isometry from m to n qubits to a circuit. In particular, this allows to attach arbitrary unitaries on n qubits (m=n) or to prepare any state on n qubits (m=0). The decomposition used here was introduced by Iten et al. in https://arxiv.org/abs/1501.06911(opens in a new tab).
Parameters
 isometry (ndarray) – an isometry from m to n qubits, i.e., a (complex) ndarray of dimension 2^n×2^m with orthonormal columns (given in the computational basis specified by the order of the ancillas and the input qubits, where the ancillas are considered to be more significant than the input qubits.).
 q_input (QuantumRegisterlist[Qubit]) – list of m qubits where the input to the isometry is fed in (empty list for state preparation).
 q_ancillas_for_output (QuantumRegisterlist[Qubit]) – list of nm ancilla qubits that are used for the output of the isometry and which are assumed to start in the zero state. The qubits are listed with increasing significance.
 q_ancillas_zero (QuantumRegisterlist[Qubit]) – list of ancilla qubits which are assumed to start in the zero state. Default is q_ancillas_zero = None.
 q_ancillas_dirty (QuantumRegisterlist[Qubit]) – list of ancilla qubits which can start in an arbitrary state. Default is q_ancillas_dirty = None.
 epsilon (float) – error tolerance of calculations. Default is epsilon = _EPS.
Returns
the isometry is attached to the quantum circuit.
Return type
Raises
QiskitError – if the array is not an isometry of the correct size corresponding to the provided number of qubits.
isometry
QuantumCircuit.isometry(isometry, q_input, q_ancillas_for_output, q_ancillas_zero=None, q_ancillas_dirty=None, epsilon=1e10)
Attach an arbitrary isometry from m to n qubits to a circuit. In particular, this allows to attach arbitrary unitaries on n qubits (m=n) or to prepare any state on n qubits (m=0). The decomposition used here was introduced by Iten et al. in https://arxiv.org/abs/1501.06911(opens in a new tab).
Parameters
 isometry (ndarray) – an isometry from m to n qubits, i.e., a (complex) ndarray of dimension 2^n×2^m with orthonormal columns (given in the computational basis specified by the order of the ancillas and the input qubits, where the ancillas are considered to be more significant than the input qubits.).
 q_input (QuantumRegisterlist[Qubit]) – list of m qubits where the input to the isometry is fed in (empty list for state preparation).
 q_ancillas_for_output (QuantumRegisterlist[Qubit]) – list of nm ancilla qubits that are used for the output of the isometry and which are assumed to start in the zero state. The qubits are listed with increasing significance.
 q_ancillas_zero (QuantumRegisterlist[Qubit]) – list of ancilla qubits which are assumed to start in the zero state. Default is q_ancillas_zero = None.
 q_ancillas_dirty (QuantumRegisterlist[Qubit]) – list of ancilla qubits which can start in an arbitrary state. Default is q_ancillas_dirty = None.
 epsilon (float) – error tolerance of calculations. Default is epsilon = _EPS.
Returns
the isometry is attached to the quantum circuit.
Return type
Raises
QiskitError – if the array is not an isometry of the correct size corresponding to the provided number of qubits.
iswap
QuantumCircuit.iswap(qubit1, qubit2)
Apply iSwapGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubits to apply the gate to.  qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubits to apply the gate to.
Return type
Returns
A handle to the instructions created.
mcp
QuantumCircuit.mcp(lam, control_qubits, target_qubit)
Apply MCPhaseGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 lam (
Union
[ParameterExpression
,float
]) – The angle of the rotation.  control_qubits (
Sequence
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]]) – The qubits used as the controls.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.
Return type
Returns
A handle to the instructions created.
mcrx
QuantumCircuit.mcrx(theta, q_controls, q_target, use_basis_gates=False)
Apply MultipleControlled X rotation gate
Parameters
 self (QuantumCircuit) – The QuantumCircuit object to apply the mcrx gate on.
 theta (float) – angle theta
 q_controls (QuantumRegister or list(Qubit)) – The list of control qubits
 q_target (Qubit) – The target qubit
 use_basis_gates (bool) – use p, u, cx
Raises
QiskitError – parameter errors
mcry
QuantumCircuit.mcry(theta, q_controls, q_target, q_ancillae=None, mode=None, use_basis_gates=False)
Apply MultipleControlled Y rotation gate
Parameters
 self (QuantumCircuit) – The QuantumCircuit object to apply the mcry gate on.
 theta (float) – angle theta
 q_controls (list(Qubit)) – The list of control qubits
 q_target (Qubit) – The target qubit
 q_ancillae (QuantumRegister or tuple(QuantumRegister, int)) – The list of ancillary qubits.
 mode (string) – The implementation mode to use
 use_basis_gates (bool) – use p, u, cx
Raises
QiskitError – parameter errors
mcrz
QuantumCircuit.mcrz(lam, q_controls, q_target, use_basis_gates=False)
Apply MultipleControlled Z rotation gate
Parameters
 self (QuantumCircuit) – The QuantumCircuit object to apply the mcrz gate on.
 lam (float) – angle lambda
 q_controls (list(Qubit)) – The list of control qubits
 q_target (Qubit) – The target qubit
 use_basis_gates (bool) – use p, u, cx
Raises
QiskitError – parameter errors
mct
QuantumCircuit.mct(control_qubits, target_qubit, ancilla_qubits=None, mode='noancilla')
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
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]]) – The qubits used as the controls.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  ancilla_qubits (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]],Sequence
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]],None
]) – The qubits used as the ancillae, if the mode requires them.  mode (
str
) – The choice of mode, explained further above.
Return type
Returns
A handle to the instructions created.
Raises
 ValueError – if the given mode is not known, or if too few ancilla qubits are passed.
 AttributeError – if no ancilla qubits are passed, but some are needed.
QuantumCircuit.mcx: the same gate with a different name.
mcx
QuantumCircuit.mcx(control_qubits, target_qubit, ancilla_qubits=None, mode='noancilla')
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
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]]) – The qubits used as the controls.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.  ancilla_qubits (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]],Sequence
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]],None
]) – The qubits used as the ancillae, if the mode requires them.  mode (
str
) – The choice of mode, explained further above.
Return type
Returns
A handle to the instructions created.
Raises
 ValueError – if the given mode is not known, or if too few ancilla qubits are passed.
 AttributeError – if no ancilla qubits are passed, but some are needed.
measure
QuantumCircuit.measure(qubit, cbit)
Measure quantum bit into classical bit (tuples).
Parameters
 qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – qubit to measure.  cbit (
Union
[Clbit
,ClassicalRegister
,int
,slice
,Sequence
[Union
[Clbit
,int
]]]) – classical bit to place the measurement in.
Returns
handle to the added instructions.
Return type
Raises
CircuitError – if arguments have bad format.
measure_active
QuantumCircuit.measure_active(inplace=True)
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) – All measurements inplace or return new circuit.
Returns
Returns circuit with measurements when inplace = False.
Return type
measure_all
QuantumCircuit.measure_all(inplace=True, add_bits=True)
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) – All measurements inplace or return new circuit.
 add_bits (bool) – 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
QuantumCircuit.ms(theta, qubits)
Apply MSGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The angle of the rotation.  qubits (
Sequence
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]]) – The qubits to apply the gate to.
Return type
Returns
A handle to the instructions created.
num_connected_components
QuantumCircuit.num_connected_components(unitary_only=False)
How many nonentangled subcircuits can the circuit be factored to.
Parameters
unitary_only (bool) – Compute only unitary part of graph.
Returns
Number of connected components in circuit.
Return type
int
num_nonlocal_gates
QuantumCircuit.num_nonlocal_gates()
Return number of nonlocal gates (i.e. involving 2+ qubits).
Conditional nonlocal gates are also included.
Return type
int
num_tensor_factors
QuantumCircuit.num_tensor_factors()
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
int
num_unitary_factors
QuantumCircuit.num_unitary_factors()
Computes the number of tensor factors in the unitary (quantum) part of the circuit only.
Return type
int
p
QuantumCircuit.p(theta, qubit)
Apply PhaseGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – THe angle of the rotation.  qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
pauli
QuantumCircuit.pauli(pauli_string, qubits)
Apply PauliGate
.
Parameters
 pauli_string (
str
) – A string representing the Pauli operator to apply, e.g. ‘XX’.  qubits (
Sequence
[Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]]) – The qubits to apply this gate to.
Return type
Returns
A handle to the instructions created.
power
QuantumCircuit.power(power, matrix_power=False)
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) – The power to raise this circuit to.
 matrix_power (bool) – 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
QuantumCircuit.prepare_state(state, qubits=None, label=None)
Prepare qubits in a specific state.
This class implements a state preparing unitary. Unlike qiskit.extensions.Initialize
it does not reset the qubits first.
Parameters

state (str or list or int or Statevector) –
 Statevector: Statevector to initialize to.
 str: 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$.  list: vector of complex amplitudes to initialize to.
 int: 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 (QuantumRegister orQubit or int) –
 QuantumRegister: A list of qubits to be initialized [Default: None].
 Qubit: Single qubit to be initialized [Default: None].
 int: Index of qubit to be initialized [Default: None].
 list: Indexes of qubits to be initialized [Default: None].

label (str) – An optional label for the gate
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 ├
└───────────────────────────────────────────┘
qasm
QuantumCircuit.qasm(formatted=False, filename=None, encoding=None)
Return OpenQASM string.
Parameters
 formatted (bool) – Return formatted Qasm string.
 filename (str) – Save Qasm to file with name ‘filename’.
 encoding (str) – Optionally specify the encoding to use for the output file if
filename
is specified. By default this is set to the system’s default encoding (ie whateverlocale.getpreferredencoding()
returns) and can be set to any valid codec or alias from stdlib’s codec module(opens in a new tab)
Returns
If formatted=False.
Return type
str
Raises
 MissingOptionalLibraryError – If pygments is not installed and
formatted
isTrue
.  QasmError – If circuit has free parameters.
qbit_argument_conversion
QuantumCircuit.qbit_argument_conversion(qubit_representation)
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
QuantumCircuit.qubit_duration(*qubits)
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 – Qubits within self
to include.
Return type
float
Returns
Return the duration between the first start and last stop time of nondelay instructions
qubit_start_time
QuantumCircuit.qubit_start_time(*qubits)
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 – Qubits within
self
to include. Integers are allowed for qubits, indicating  self.qubits. (indices of) –
Return type
float
Returns
Return the start time of the first instruction, excluding delays, over the qubits
Raises
CircuitError – if self
is a notyet scheduled circuit.
qubit_stop_time
QuantumCircuit.qubit_stop_time(*qubits)
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 – Qubits within
self
to include. Integers are allowed for qubits, indicating  self.qubits. (indices of) –
Return type
float
Returns
Return the stop time of the last instruction, excluding delays, over the qubits
Raises
CircuitError – if self
is a notyet scheduled circuit.
r
QuantumCircuit.r(theta, phi, qubit)
Apply RGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The angle of the rotation.  phi (
Union
[ParameterExpression
,float
]) – The angle of the axis of rotation in the xy plane.  qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
rcccx
QuantumCircuit.rcccx(control_qubit1, control_qubit2, control_qubit3, target_qubit)
Apply RC3XGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the first control.  control_qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the second control.  control_qubit3 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the third control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.
Return type
Returns
A handle to the instructions created.
rccx
QuantumCircuit.rccx(control_qubit1, control_qubit2, target_qubit)
Apply RCCXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 control_qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the first control.  control_qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) used as the second control.  target_qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) targeted by the gate.
Return type
Returns
A handle to the instructions created.
remove_final_measurements
QuantumCircuit.remove_final_measurements(inplace=True)
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) – All measurements removed inplace or return new circuit.
Returns
Returns the resulting circuit when inplace=False
, else None.
Return type
repeat
QuantumCircuit.repeat(reps)
Repeat this circuit reps
times.
Parameters
reps (int) – How often this circuit should be repeated.
Returns
A circuit containing reps
repetitions of this circuit.
Return type
reset
QuantumCircuit.reset(qubit)
Reset the quantum bit(s) to their default state.
Parameters
qubit (Union
[Qubit
, QuantumRegister
, int
, slice
, Sequence
[Union
[Qubit
, int
]]]) – qubit(s) to reset.
Returns
handle to the added instruction.
Return type
reverse_bits
QuantumCircuit.reverse_bits()
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
QuantumCircuit.reverse_ops()
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
QuantumCircuit.rv(vx, vy, vz, qubit)
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 (
Union
[ParameterExpression
,float
]) – xcompenent of the rotation axis.  vy (
Union
[ParameterExpression
,float
]) – ycompenent of the rotation axis.  vz (
Union
[ParameterExpression
,float
]) – zcompenent of the rotation axis.  qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
rx
QuantumCircuit.rx(theta, qubit, label=None)
Apply RXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The rotation angle of the gate.  qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.  label (
Optional
[str
]) – The string label of the gate in the circuit.
Return type
Returns
A handle to the instructions created.
rxx
QuantumCircuit.rxx(theta, qubit1, qubit2)
Apply RXXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The angle of the rotation.  qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.  qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
ry
QuantumCircuit.ry(theta, qubit, label=None)
Apply RYGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The rotation angle of the gate.  qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.  label (
Optional
[str
]) – The string label of the gate in the circuit.
Return type
Returns
A handle to the instructions created.
ryy
QuantumCircuit.ryy(theta, qubit1, qubit2)
Apply RYYGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The rotation angle of the gate.  qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.  qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
rz
QuantumCircuit.rz(phi, qubit)
Apply RZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 phi (
Union
[ParameterExpression
,float
]) – The rotation angle of the gate.  qubit (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
rzx
QuantumCircuit.rzx(theta, qubit1, qubit2)
Apply RZXGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The rotation angle of the gate.  qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.  qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
rzz
QuantumCircuit.rzz(theta, qubit1, qubit2)
Apply RZZGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
 theta (
Union
[ParameterExpression
,float
]) – The rotation angle of the gate.  qubit1 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.  qubit2 (
Union
[Qubit
,QuantumRegister
,int
,slice
,Sequence
[Union
[Qubit
,int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
s
QuantumCircuit.s(qubit)
Apply SGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Union
[Qubit
, QuantumRegister
, int
, slice
, Sequence
[Union
[Qubit
, int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
save_amplitudes
QuantumCircuit.save_amplitudes(params, label='amplitudes', pershot=False, conditional=False)
Save complex statevector amplitudes.
Parameters
 params (List[int] or List[str]) – the basis states to return amplitudes for.
 label (str) – the key for retrieving saved data from results.
 pershot (bool) – if True save a list of amplitudes vectors for each shot of the simulation rather than the a single amplitude vector [Default: False].
 conditional (bool) – if True save the amplitudes vector conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
Raises
ExtensionError – if params is invalid for the specified number of qubits.
save_amplitudes_squared
QuantumCircuit.save_amplitudes_squared(params, label='amplitudes_squared', unnormalized=False, pershot=False, conditional=False)
Save squared statevector amplitudes (probabilities).
Parameters
 params (List[int] or List[str]) – the basis states to return amplitudes for.
 label (str) – the key for retrieving saved data from results.
 unnormalized (bool) – If True return save the unnormalized accumulated probabilities over all shots [Default: False].
 pershot (bool) – if True save a list of probability vectors for each shot of the simulation rather than the a single amplitude vector [Default: False].
 conditional (bool) – if True save the probability vector conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
Raises
ExtensionError – if params is invalid for the specified number of qubits.
save_clifford
QuantumCircuit.save_clifford(label='clifford', pershot=False)
Save the current stabilizer simulator quantum state as a Clifford.
Parameters
 label (str) – the key for retrieving saved data from results.
 pershot (bool) – if True save a list of Cliffords for each shot of the simulation [Default: False].
Returns
with attached instruction.
Return type
This instruction is always defined across all qubits in a circuit.
save_density_matrix
QuantumCircuit.save_density_matrix(qubits=None, label='density_matrix', unnormalized=False, pershot=False, conditional=False)
Save the current simulator quantum state as a density matrix.
Parameters
 qubits (list or None) – the qubits to save reduced density matrix on. If None the full density matrix of qubits will be saved [Default: None].
 label (str) – the key for retrieving saved data from results.
 unnormalized (bool) – If True return save the unnormalized accumulated or conditional accumulated density matrix over all shots [Default: False].
 pershot (bool) – if True save a list of density matrices for each shot of the simulation rather than the average over all shots [Default: False].
 conditional (bool) – if True save the average or pershot data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
save_expectation_value
QuantumCircuit.save_expectation_value(operator, qubits, label='expectation_value', unnormalized=False, pershot=False, conditional=False)
Save the expectation value of a Hermitian operator.
Parameters
 operator (Pauli orSparsePauliOp orOperator) – a Hermitian operator.
 qubits (list) – circuit qubits to apply instruction.
 label (str) – the key for retrieving saved data from results.
 unnormalized (bool) – If True return save the unnormalized accumulated or conditional accumulated expectation value over all shot [Default: False].
 pershot (bool) – if True save a list of expectation values for each shot of the simulation rather than the average over all shots [Default: False].
 conditional (bool) – if True save the average or pershot data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
Raises
ExtensionError – if the input operator is invalid or not Hermitian.
This method appends a SaveExpectationValue
instruction to the quantum circuit.
save_expectation_value_variance
QuantumCircuit.save_expectation_value_variance(operator, qubits, label='expectation_value_variance', unnormalized=False, pershot=False, conditional=False)
Save the expectation value of a Hermitian operator.
Parameters
 operator (Pauli orSparsePauliOp orOperator) – a Hermitian operator.
 qubits (list) – circuit qubits to apply instruction.
 label (str) – the key for retrieving saved data from results.
 unnormalized (bool) – If True return save the unnormalized accumulated or conditional accumulated expectation value and variance over all shot [Default: False].
 pershot (bool) – if True save a list of expectation values and variances for each shot of the simulation rather than the average over all shots [Default: False].
 conditional (bool) – if True save the data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
Raises
ExtensionError – if the input operator is invalid or not Hermitian.
This method appends a SaveExpectationValueVariance
instruction to the quantum circuit.
save_matrix_product_state
QuantumCircuit.save_matrix_product_state(label='matrix_product_state', pershot=False, conditional=False)
Save the current simulator quantum state as a matrix product state.
Parameters
 label (str) – the key for retrieving saved data from results.
 pershot (bool) – if True save the mps for each shot of the simulation [Default: False].
 conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
save_probabilities
QuantumCircuit.save_probabilities(qubits=None, label='probabilities', unnormalized=False, pershot=False, conditional=False)
Save measurement outcome probabilities vector.
Parameters
 qubits (list or None) – the qubits to apply snapshot to. If None all qubits will be snapshot [Default: None].
 label (str) – the key for retrieving saved data from results.
 unnormalized (bool) – If True return save the unnormalized accumulated probabilities over all shots [Default: False].
 pershot (bool) – if True save a list of probabilities for each shot of the simulation rather than the average over all shots [Default: False].
 conditional (bool) – if True save the probabilities data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
save_probabilities_dict
QuantumCircuit.save_probabilities_dict(qubits=None, label='probabilities', unnormalized=False, pershot=False, conditional=False)
Save measurement outcome probabilities vector.
Parameters
 qubits (list or None) – the qubits to apply snapshot to. If None all qubits will be snapshot [Default: None].
 label (str) – the key for retrieving saved data from results.
 unnormalized (bool) – If True return save the unnormalized accumulated probabilities over all shots [Default: False].
 pershot (bool) – if True save a list of probabilities for each shot of the simulation rather than the average over all shots [Default: False].
 conditional (bool) – if True save the probabilities data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
save_stabilizer
QuantumCircuit.save_stabilizer(label='stabilizer', pershot=False, conditional=False)
Save the current stabilizer simulator quantum state as a StabilizerState.
Parameters
 label (str) – the key for retrieving saved data from results.
 pershot (bool) – if True save a list of StabilizerStates for each shot of the simulation [Default: False].
 conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
This instruction is always defined across all qubits in a circuit.
save_state
QuantumCircuit.save_state(label=None, pershot=False, conditional=False)
Save the current simulator quantum state.
Parameters
 label (str or None) – Optional, the key for retrieving saved data from results. If None the key will be the state type of the simulator.
 pershot (bool) – if True save a list of statevectors for each shot of the simulation [Default: False].
 conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
save_statevector
QuantumCircuit.save_statevector(label='statevector', pershot=False, conditional=False)
Save the current simulator quantum state as a statevector.
Parameters
 pershot (bool) – if True save a list of statevectors for each shot of the simulation [Default: False].
 label (str) – the key for retrieving saved data from results.
 conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
This instruction is always defined across all qubits in a circuit.
save_statevector_dict
QuantumCircuit.save_statevector_dict(label='statevector', pershot=False, conditional=False)
Save the current simulator quantum state as a statevector as a dict.
Parameters
 label (str) – the key for retrieving saved data from results.
 pershot (bool) – if True save a list of statevectors for each shot of the simulation [Default: False].
 conditional (bool) – if True save pershot data conditional on the current classical register values [Default: False].
Returns
with attached instruction.
Return type
This instruction is always defined across all qubits in a circuit.
save_superop
QuantumCircuit.save_superop(label='superop', pershot=False)
Save the current state of the superop simulator.
Parameters
 label (str) – the key for retrieving saved data from results.
 pershot (bool) – if True save a list of SuperOp matrices for each shot of the simulation [Default: False].
Returns
with attached instruction.
Return type
This instruction is always defined across all qubits in a circuit.
save_unitary
QuantumCircuit.save_unitary(label='unitary', pershot=False)
Save the current state of the unitary simulator.
Parameters
 label (str) – the key for retrieving saved data from results.
 pershot (bool) – if True save a list of unitaries for each shot of the simulation [Default: False].
Returns
with attached instruction.
Return type
This instruction is always defined across all qubits in a circuit.
sdg
QuantumCircuit.sdg(qubit)
Apply SdgGate
.
For the full matrix form of this gate, see the underlying gate documentation.
Parameters
qubit (Union
[Qubit
, QuantumRegister
, int
, slice
, Sequence
[Union
[Qubit
, int
]]]) – The qubit(s) to apply the gate to.
Return type
Returns
A handle to the instructions created.
set_density_matrix
QuantumCircuit.set_density_matrix(state)
Set the density matrix state of the simulator.
Parameters
state (DensityMatrix) – a density matrix.
Returns
with attached instruction.
Return type
Raises
ExtensionError – If the density matrix is the incorrect size for the current circuit.
set_matrix_product_state
QuantumCircuit.set_matrix_product_state(state)
Set the matrix product state of the simulator.
Parameters
state (Tuple[List[Tuple[np.array[complex_t]]]], List[List[float]]) – A matrix_product_state.
Returns
with attached instruction.
Return type
Raises
ExtensionError – If the structure of the state is incorrect
set_stabilizer
QuantumCircuit.set_stabilizer(state)
Set the Clifford stabilizer state of the simulator.
Parameters
state (Clifford) – A clifford operator.
Returns
with attached instruction.
Return type
Raises
ExtensionError – If the state is the incorrect size for the current circuit.
set_statevector
QuantumCircuit.set_statevector(state)
Set the statevector state of the simulator.
Parameters
state (Statevector) – A state matrix.
Returns
with attached instruction.
Return type
Raises
ExtensionError – If the state is the incorrect size for the current circuit.
set_superop
QuantumCircuit.set_superop(state)
Set the superop state of the simulator.
Parameters
state (QuantumChannel) – A CPTP quantum channel.
Returns
with attached instruction.
Return type
Raises
 ExtensionError – If the state is the incorrect size for the current circuit.
 ExtensionError – if the input QuantumChannel is not CPTP.
set_unitary
QuantumCircuit.set_unitary(state)
Set the state state of the simulator.
Parameters
state (Operator) – A state matrix.
Returns
with attached instruction.
Return type
Raises
 ExtensionError – If the state is the incorrect size for the current circuit.
 ExtensionError – if the input matrix is not unitary.
size
QuantumCircuit.size(filter_function=<function QuantumCircuit.<lambda>>)
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
int
snapshot
QuantumCircuit.snapshot(label, snapshot_type='statevector', qubits=None, params=None)
Take a statevector snapshot of the internal simulator representation. Works on all qubits, and prevents reordering (like barrier).
For other types of snapshots use the Snapshot extension directly.
Parameters
 label (str) – a snapshot label to report the result.
 snapshot_type (str) – the type of the snapshot.
 qubits (list or None) – the qubits to apply snapshot to [Default: None].
 params (list or None) – the parameters for snapshot_type [Default: None].
Returns
with attached command
Return type
Raises
ExtensionError – malformed command
squ
QuantumCircuit.squ(unitary_matrix, qubit, mode='ZYZ', up_to_diagonal=False)
Decompose an arbitrary 2*2 unitary into three rotation gates.
Note that the decomposition is up to a global phase shift. (This is a well known decomposition which can be found for example in Nielsen and Chuang’s book “Quantum computation and quantum information”.)
Parameters
 unitary_matrix (ndarray) – 2*2 unitary (given as a (complex) ndarray).
 qubit (QuantumRegister orQubit) – The qubit which the gate is acting on.
 mode (string) – determines the used decomposition by providing the rotation axes. The allowed modes are: “ZYZ” (default)
 up_to_diagonal (bool) – if set to True, the singlequbit unitary is decomposed up to a diagonal matrix, i.e. a unitary u’ is implemented such that there exists a 2*2 diagonal gate d with u = d.dot(u’)
Returns
The singlequbit unitary instruction attached to the circuit.
Return type
Raises
QiskitError – if the format is wrong; if the array u is not unitary