QuantumCircuit

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

GitHub

Bases: object

Create a new circuit.

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

Parameters

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

The registers to be included in the circuit.
- If a list of Register objects, represents the QuantumRegister and/or ClassicalRegister objects to include in the circuit.
  
  For example:
  - QuantumCircuit(QuantumRegister(4))
  - QuantumCircuit(QuantumRegister(4), ClassicalRegister(3))
  - QuantumCircuit(QuantumRegister(4, 'qr0'), QuantumRegister(2, 'qr1'))
- If a list of int, the amount of qubits and/or classical bits to include in the circuit. It can either be a single int for just the number of quantum bits, or 2 ints for the number of quantum bits and classical bits, respectively.
  
  For example:
  - QuantumCircuit(4) # A QuantumCircuit with 4 qubits
  - QuantumCircuit(4, 3) # A QuantumCircuit with 4 qubits and 3 classical bits
- If a list of python lists containing Bit objects, a collection of Bit s to be added to the circuit.
name (str) – the name of the quantum circuit. If not set, an automatically generated string will be assigned.
global_phase (float orParameterExpression) – The global phase of the circuit in radians.
metadata (dict) – Arbitrary key value metadata to associate with the circuit. This gets stored as free-form data in a dict in the metadata attribute. It will not be directly used in the circuit.

Raises

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

Examples

Construct a simple Bell state circuit.

from qiskit import QuantumCircuit
 
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])
qc.draw('mpl')

../_images/qiskit-circuit-QuantumCircuit-1.png

Construct a 5-qubit GHZ circuit.

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

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

from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
 
qr = QuantumRegister(3, 'q')
anc = QuantumRegister(1, 'ancilla')
cr = ClassicalRegister(3, 'c')
qc = QuantumCircuit(qr, anc, cr)
 
qc.x(anc[0])
qc.h(anc[0])
qc.h(qr[0:3])
qc.cx(qr[0:3], anc[0])
qc.h(qr[0:3])
qc.barrier(qr)
qc.measure(qr, cr)
 
qc.draw('mpl')

../_images/qiskit-circuit-QuantumCircuit-2.png

Attributes

ancillas

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

calibrations

Return calibration dictionary.

The custom pulse definition of a given gate is of the form {'gate_name': {(qubits, params): schedule}}

clbits

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

data

Return the circuit data (instructions and context).

Returns

a list-like object containing the CircuitInstructions for each instruction.

Return type

QuantumCircuitData

global_phase

Return the global phase of the current circuit scope in radians.

instances

Default value: 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 SwapGates 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 – 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

Default value: 'circuit'

qubits

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

Methods

add_bits

add_bits(bits)

GitHub

Add Bits to the circuit.

add_calibration

add_calibration(gate, qubits, schedule, params=None)

GitHub

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.

add_register

add_register(*regs)

GitHub

Add registers.

append

append(instruction, qargs=None, cargs=None)

GitHub

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 non-Bit 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 a CircuitInstruction with all its context.
qargs (Sequence[QubitSpecifier] | None) – specifiers of the Qubits to attach instruction to.
cargs (Sequence[ClbitSpecifier] | None) – specifiers of the Clbits to attach instruction to.

Returns

a handle to the CircuitInstructions that were actually added to the circuit.

Return type

qiskit.circuit.InstructionSet

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

assign_parameters(parameters: Mapping[Parameter, ParameterExpression | float] | Sequence[ParameterExpression | float], inplace: Literal[True] = False, *, flat_input: bool = False, strict: bool = True) → None

GitHub

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.

Note

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 and parameters is a mapping type, it is assumed to be exactly a mapping of {parameter: value}. By default (False), the mapping may also contain ParameterVector keys that point to a corresponding sequence of values, and these will be unrolled during the mapping, or string keys, which will be converted to Parameter instances using get_parameter().
strict – If False, any parameters given in the mapping that are not used in the circuit will be ignored. If True (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 – 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 in-place.

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')

../_images/qiskit-circuit-QuantumCircuit-3_00.png

../_images/qiskit-circuit-QuantumCircuit-3_01.png

Bind the values out-of-place 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')

../_images/qiskit-circuit-QuantumCircuit-4_00.png

../_images/qiskit-circuit-QuantumCircuit-4_01.png

barrier

barrier(*qargs, label=None)

GitHub

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

qiskit.circuit.InstructionSet

break_loop

break_loop()

GitHub

Apply BreakLoopOp.

Warning

If you are using the context-manager “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 non-context-manager 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

InstructionSet

cast

static cast(value, type_)

GitHub

Best effort to cast value to type. Otherwise, returns the value.

Return type

S | T

cbit_argument_conversion

cbit_argument_conversion(clbit_representation)

GitHub

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

ccx(control_qubit1, control_qubit2, target_qubit, ctrl_state=None)

GitHub

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 |int | 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

InstructionSet

ccz

ccz(control_qubit1, control_qubit2, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

ch

ch(control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

clear

clear()

GitHub

Clear all instructions in self.

Clearing the circuits will keep the metadata and calibrations.

cls_instances

classmethod cls_instances()

GitHub

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

Return type

int

cls_prefix

classmethod cls_prefix()

GitHub

Return the prefix to use for auto naming.

Return type

str

compose

compose(other, qubits=None, clbits=None, front=False, inplace=False, wrap=False)

GitHub

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 that append will accept.
qubits (list[Qubit|int]) – qubits of self to compose onto.
clbits (list[Clbit|int]) – clbits of self to compose onto.
front (bool) – If True, front composition will be performed. This is not possible within control-flow 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

QuantumCircuit

Raises

CircuitError – if no correct wire mapping can be made between the two circuits, such as if other is wider than self.
CircuitError – if trying to emit a new circuit while self has a partially built control-flow context active, such as the context-manager forms of if_test(), for_loop() and while_loop().
CircuitError – if trying to compose to the front of a circuit when a control-flow 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

Apply ContinueLoopOp.

Warning

If you are using the context-manager “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 non-context-manager 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

InstructionSet

control

control(num_ctrl_qubits=1, label=None, ctrl_state=None, annotated=False)

GitHub

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 orint) – The control state in decimal or as a bitstring (e.g. ‘111’). If None, use 2**num_ctrl_qubits - 1.
annotated (bool) – indicates whether the controlled gate can be implemented as an annotated gate.

Returns

The controlled version of this circuit.

Return type

QuantumCircuit

Raises

CircuitError – If the circuit contains a non-unitary operation and cannot be controlled.

copy

copy(name=None)

GitHub

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

QuantumCircuit

copy_empty_like

copy_empty_like(name=None)

GitHub

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

QuantumCircuit

count_ops

count_ops()

GitHub

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

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

crx

crx(theta, control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

cry

cry(theta, control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

crz

crz(theta, control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

cs

cs(control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

csdg

csdg(control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

cswap

cswap(control_qubit, target_qubit1, target_qubit2, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

csx

csx(control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

cu

cu(theta, phi, lam, gamma, control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

cx

cx(control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

cy

cy(control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

cz

cz(control_qubit, target_qubit, label=None, ctrl_state=None)

GitHub

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 | None) – The string label of the gate in the circuit.
ctrl_state (str |int | 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

InstructionSet

dcx

dcx(qubit1, qubit2)

GitHub

Apply DCXGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.
qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

decompose

decompose(gates_to_decompose=None, reps=1)

GitHub

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

Parameters

gates_to_decompose (type orstr orlist(type, str)) – 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) – Optional number of times the circuit should be decomposed. For instance, reps=2 equals calling circuit.decompose().decompose(). can decompose specific gates specific time

Returns

a circuit one level decomposed

Return type

QuantumCircuit

delay

delay(duration, qarg=None, unit='dt')

GitHub

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 orfloat orParameterExpression) – 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', and 'dt'. Default is 'dt', i.e. integer time unit depending on the target backend.

Returns

handle to the added instructions.

Return type

qiskit.circuit.InstructionSet

Raises

CircuitError – if arguments have bad format.

depth

depth(filter_function=<function QuantumCircuit.<lambda>>)

GitHub

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.

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

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: high-quality images compiled via latex.

latex_source: raw uncompiled latex output.

Warning

Support for Expr nodes in conditions and SwitchCaseOp.target fields is preliminary and incomplete. The text and mpl drawers will make a best-effort attempt to show data dependencies, but the LaTeX-based drawers will skip these completely.

Parameters

output (str | 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 | None) – 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 | None) – File path to save image to. Defaults to None (result not saved in a file).
style (dict |str | None) –

Style name, file name of style JSON file, or a dictionary specifying the style.
- The supported style names are "iqp" (default), "iqp-dark", "clifford", "textbook" and "bw".
- If given a JSON file, e.g. my_style.json or my_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 in qiskit/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) to 5.
- If None the default style "iqp" is used or, if given, the default style specified in ~/.qiskit/settings.conf.
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 | None) – 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 (str | None) – Options are left, right or none. 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 | None) – high, medium or low. It merges the lines generated by the text output so the drawing will take less vertical room. Default is medium. 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 | 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 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 (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) – Adds $|0\rangle$ in the beginning of the qubit wires and $0$ to classical wires. Default is False.
cregbundle (bool | None) – If set to True, bundle classical registers. Default is True, except for when output is set to "text".
wire_order (list[int] | 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) – The number of characters to display if an Expr is used for the condition in a ControlFlowOp. 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:

TextDrawing (if output='text')

A drawing that can be printed as ascii art.
matplotlib.figure.Figure (if output='mpl')

A matplotlib figure object for the circuit diagram.
PIL.Image (if output='latex’)

An in-memory representation of the image of the circuit diagram.
str (if 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 non-installed 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'})

../_images/qiskit-circuit-QuantumCircuit-5.png

ecr

ecr(qubit1, qubit2)

GitHub

Apply ECRGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubits to apply the gate to.
qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubits to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

find_bit

find_bit(bit)

GitHub

Find locations in the circuit which can be used to reference a given Bit.

Parameters

bit (Bit) – The bit to locate.

Returns

A 2-tuple. 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.

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

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 from indexset will be assigned. In the context-manager form, if this argument is not supplied, then a loop parameter will be allocated for you and returned as the value of the with 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 in indexset but their values will be ignored.
body (Optional[QuantumCircuit]) – The loop body to be repeatedly executed. Omit this to use the context-manager mode.
qubits (Optional[Sequence[QubitSpecifier]]) – The circuit qubits over which the loop body should be run. Omit this to use the context-manager mode.
clbits (Optional[Sequence[ClbitSpecifier]]) – The circuit clbits over which the loop body should be run. Omit this to use the context-manager 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.

from_instructions

static from_instructions(instructions, *, qubits=(), clbits=(), name=None, global_phase=0, metadata=None)

GitHub

Construct a circuit from an iterable of CircuitInstructions.

Parameters

instructions (Iterable[CircuitInstruction |tuple[qiskit.circuit.Instruction] | tuple[qiskit.circuit.Instruction, Iterable[Qubit]] | tuple[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 | None) – The name of the circuit.
global_phase (ParameterValueType) – The global phase of the circuit in radians.
metadata (dict | None) – Arbitrary key value metadata to associate with the circuit.

Returns

The quantum circuit.

Return type

QuantumCircuit

from_qasm_file

static from_qasm_file(path)

GitHub

Read an OpenQASM 2.0 program from a file and convert to an instance of QuantumCircuit.

Parameters

path (str) – Path to the file for an OpenQASM 2 program

Returns

The QuantumCircuit object for the input OpenQASM 2.

Return type

QuantumCircuit

from_qasm_str

static from_qasm_str(qasm_str)

GitHub

Convert a string containing an OpenQASM 2.0 program to a QuantumCircuit.

Parameters

qasm_str (str) – A string containing an OpenQASM 2.0 program.

Returns

The QuantumCircuit object for the input OpenQASM 2

Return type

QuantumCircuit

get_instructions

get_instructions(name)

GitHub

Get instructions matching name.

Parameters

name (str) – The name of instruction to.

Returns

list of (instruction, qargs, cargs).

Return type

list(tuple)

get_parameter

get_parameter(name: str, default: T) → Parameter | T

get_parameter(name: str, default: ellipsis = Ellipsis) → Parameter

GitHub

Retrieve a compile-time 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 is raised instead.

Returns

The corresponding parameter.

Raises

KeyError – 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

Apply HGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

has_calibration_for

has_calibration_for(instruction)

GitHub

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

Check whether a parameter object exists in this circuit.

Parameters

name_or_param (str |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

bool

has_register

has_register(register)

GitHub

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

id

id(qubit)

GitHub

Apply IGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

if_else

if_else(condition, true_body, false_body, qubits, clbits, label=None)

GitHub

Apply IfElseOp.

Note

This method does not have an associated context-manager 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[ClassicalRegister, int] | tuple[Clbit, int] | tuple[Clbit, bool]) – 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 a ClassicalRegister to be tested for equality with a given int, or as a tuple of a Clbit to be compared to either a bool or an int.
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 | 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

InstructionSet

if_test

if_test(condition: tuple[ClassicalRegister | Clbit, int], true_body: None, qubits: None, clbits: None, *, label: str | None) → IfContext

GitHub

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 a ClassicalRegister to be tested for equality with a given int, or as a tuple of a Clbit to be compared to either a bool or an int.
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

initialize(params, qubits=None, normalize=False)

GitHub

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] | str |int) –

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) – 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

Invert (take adjoint of) this circuit.

This is done by recursively inverting all gates.

Parameters

annotated (bool) – indicates whether the inverse gate can be implemented as an annotated gate.

Returns

the inverted circuit

Return type

QuantumCircuit

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

Apply iSwapGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubits to apply the gate to.
qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubits to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

mcp

mcp(lam, control_qubits, target_qubit)

GitHub

Apply MCPhaseGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

lam (ParameterExpression |float) – The angle of the rotation.
control_qubits (Sequence[Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]]) – The qubits used as the controls.
target_qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) targeted by the gate.

Returns

A handle to the instructions created.

Return type

InstructionSet

mcrx

mcrx(theta, q_controls, q_target, use_basis_gates=False)

GitHub

Apply Multiple-Controlled X rotation gate

Parameters

self (QuantumCircuit) – The QuantumCircuit object to apply the mcrx gate on.
theta (float) – angle theta
q_controls (QuantumRegister orlist(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

mcry(theta, q_controls, q_target, q_ancillae=None, mode=None, use_basis_gates=False)

GitHub

Apply Multiple-Controlled 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 ortuple(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

mcrz(lam, q_controls, q_target, use_basis_gates=False)

GitHub

Apply Multiple-Controlled 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

mcx

mcx(control_qubits, target_qubit, ancilla_qubits=None, mode='noancilla')

GitHub

Apply MCXGate.

The multi-cX 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.
'v-chain': Requires 2 less ancillas than the number of control qubits.
'v-chain-dirty': 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) – The choice of mode, explained further above.

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.

Return type

InstructionSet

measure

measure(qubit, cbit)

GitHub

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 non-reversible.

Parameters

qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – qubit(s) to measure.
cbit (Clbit |ClassicalRegister |int |slice |Sequence[Clbit |int]) – classical bit(s) to place the measurement result(s) in.

Returns

handle to the added instructions.

Return type

qiskit.circuit.InstructionSet

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 one-to-one 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

Adds measurement to all non-idle qubits. Creates a new ClassicalRegister with a size equal to the number of non-idle 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

QuantumCircuit

measure_all

measure_all(inplace=True, add_bits=True)

GitHub

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

QuantumCircuit

Raises

CircuitError – if add_bits=False but there are not enough classical bits.

ms

ms(theta, qubits)

GitHub

Apply MSGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

theta (ParameterExpression |float) – The angle of the rotation.
qubits (Sequence[Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]]) – The qubits to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

num_connected_components

num_connected_components(unitary_only=False)

GitHub

How many non-entangled 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

num_nonlocal_gates()

GitHub

Return number of non-local gates (i.e. involving 2+ qubits).

Conditional nonlocal gates are also included.

Return type

int

num_tensor_factors

num_tensor_factors()

GitHub

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

num_unitary_factors()

GitHub

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

Return type

int

p

p(theta, qubit)

GitHub

Apply PhaseGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

theta (ParameterExpression |float) – THe angle of the rotation.
qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

pauli

pauli(pauli_string, qubits)

GitHub

Apply PauliGate.

Parameters

pauli_string (str) – A string representing the Pauli operator to apply, e.g. ‘XX’.
qubits (Sequence[Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]]) – The qubits to apply this gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

power

power(power, matrix_power=False)

GitHub

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 to repeat.

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

QuantumCircuit

prepare_state

prepare_state(state, qubits=None, label=None, normalize=False)

GitHub

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] | str |int) –

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 | None) – An optional label for the gate
normalize (bool) – Whether to normalize an input array to a unit vector.

Returns

A handle to the instruction that was just initialized

Return type

InstructionSet

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 .. code-block:

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

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

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) – Qubits within self to include.

Returns

Return the duration between the first start and last stop time of non-delay instructions

Return type

float

qubit_start_time

qubit_start_time(*qubits)

GitHub

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) – 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 not-yet scheduled circuit.

Return type

float

qubit_stop_time

qubit_stop_time(*qubits)

GitHub

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) – 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 not-yet scheduled circuit.

Return type

float

r

r(theta, phi, qubit)

GitHub

Apply RGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

theta (ParameterExpression |float) – The angle of the rotation.
phi (ParameterExpression |float) – The angle of the axis of rotation in the x-y plane.
qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

rcccx

rcccx(control_qubit1, control_qubit2, control_qubit3, target_qubit)

GitHub

Apply RC3XGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

control_qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) used as the first control.
control_qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) used as the second control.
control_qubit3 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) used as the third control.
target_qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) targeted by the gate.

Returns

A handle to the instructions created.

Return type

InstructionSet

rccx

rccx(control_qubit1, control_qubit2, target_qubit)

GitHub

Apply RCCXGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

control_qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) used as the first control.
control_qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) used as the second control.
target_qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) targeted by the gate.

Returns

A handle to the instructions created.

Return type

InstructionSet

remove_final_measurements

remove_final_measurements(inplace=True)

GitHub

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

QuantumCircuit

repeat

repeat(reps)

GitHub

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

QuantumCircuit

reset

reset(qubit)

GitHub

Reset the quantum bit(s) to their default state.

Parameters

Returns

handle to the added instruction.

Return type

qiskit.circuit.InstructionSet

reverse_bits

reverse_bits()

GitHub

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 little-endian convention to the big-endian equivalent, and vice versa.

Returns

the circuit with reversed bit order.

Return type

QuantumCircuit

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

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

QuantumCircuit

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

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) – x-component of the rotation axis.
vy (ParameterExpression |float) – y-component of the rotation axis.
vz (ParameterExpression |float) – z-component of the rotation axis.
qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

rx

rx(theta, qubit, label=None)

GitHub

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 | None) – The string label of the gate in the circuit.

Returns

A handle to the instructions created.

Return type

InstructionSet

rxx

rxx(theta, qubit1, qubit2)

GitHub

Apply RXXGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

theta (ParameterExpression |float) – The angle of the rotation.
qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.
qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

ry

ry(theta, qubit, label=None)

GitHub

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 | None) – The string label of the gate in the circuit.

Returns

A handle to the instructions created.

Return type

InstructionSet

ryy

ryy(theta, qubit1, qubit2)

GitHub

Apply RYYGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

theta (ParameterExpression |float) – The rotation angle of the gate.
qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.
qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

rz

rz(phi, qubit)

GitHub

Apply RZGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

phi (ParameterExpression |float) – The rotation angle of the gate.
qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

rzx

rzx(theta, qubit1, qubit2)

GitHub

Apply RZXGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

theta (ParameterExpression |float) – The rotation angle of the gate.
qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.
qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

rzz

rzz(theta, qubit1, qubit2)

GitHub

Apply RZZGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

theta (ParameterExpression |float) – The rotation angle of the gate.
qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.
qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

s

s(qubit)

GitHub

Apply SGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

sdg

sdg(qubit)

GitHub

Apply SdgGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

size

size(filter_function=<function QuantumCircuit.<lambda>>)

GitHub

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

swap

swap(qubit1, qubit2)

GitHub

Apply SwapGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

qubit1 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubits to apply the gate to.
qubit2 (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubits to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

switch

GitHub

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 integer-like.
cases (Iterable[Tuple[Any, 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 context-manager form.
qubits (Sequence[Qubit]) – The circuit qubits over which all case bodies execute. Omit in context-manager form.
clbits (Sequence[Clbit]) – The circuit clbits over which all case bodies execute. Omit in context-manager form.
label (Optional[str]) – The string label of the instruction in the circuit.

Returns

If used in context-manager 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

Apply SXGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

sxdg

sxdg(qubit)

GitHub

Apply SXdgGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

t

t(qubit)

GitHub

Apply TGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

tdg

tdg(qubit)

GitHub

Apply TdgGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

tensor

tensor(other, inplace=False)

GitHub

Tensor self with other.

Remember that in the little-endian 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) – 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')

../_images/qiskit-circuit-QuantumCircuit-6.png

Returns

The tensored circuit (returns None if inplace==True).

Return type

QuantumCircuit

to_gate

to_gate(parameter_map=None, label=None)

GitHub

Create a Gate out of this circuit.

Parameters

parameter_map (dict) – 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) – Optional gate label.

Returns

a composite gate encapsulating this circuit (can be decomposed back)

Return type

Gate

to_instruction

to_instruction(parameter_map=None, label=None)

GitHub

Create an Instruction out of this circuit.

Parameters

parameter_map (dict) – 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) – Optional gate label.

Returns

a composite instruction encapsulating this circuit (can be decomposed back)

Return type

qiskit.circuit.Instruction

u

u(theta, phi, lam, qubit)

GitHub

Apply UGate.

For the full matrix form of this gate, see the underlying gate documentation.

Parameters

theta (ParameterExpression |float) – The $\theta$ rotation angle of the gate.
phi (ParameterExpression |float) – The $\phi$ rotation angle of the gate.
lam (ParameterExpression |float) – The $\lambda$ rotation angle of the gate.
qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

unitary

unitary(obj, qubits, label=None)

GitHub

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 | None) – Unitary name for backend [Default: None].

Returns

The quantum circuit.

Return type

QuantumCircuit

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

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]) – An equality condition to be checked prior to executing body. The left-hand side of the condition must be a ClassicalRegister or a Clbit, and the right-hand side must be an integer or boolean.
body (Optional[QuantumCircuit]) – The loop body to be repeatedly executed. Omit this to use the context-manager mode.
qubits (Optional[Sequence[Qubit]]) – The circuit qubits over which the loop body should be run. Omit this to use the context-manager mode.
clbits (Optional[Sequence[Clbit]]) – The circuit clbits over which the loop body should be run. Omit this to use the context-manager mode.
label (Optional[str]) – The string label of the instruction in the circuit.

Returns

If used in context-manager 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.