4109 lines
296 KiB
Plaintext
4109 lines
296 KiB
Plaintext
---
|
||
title: QuantumCircuit (v1.2)
|
||
description: API reference for qiskit.circuit.QuantumCircuit in qiskit v1.2
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.circuit.QuantumCircuit
|
||
---
|
||
|
||
<span id="quantumcircuit-class" />
|
||
|
||
<span id="qiskit-circuit-quantumcircuit" />
|
||
|
||
# [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") class
|
||
|
||
<Class id="qiskit.circuit.QuantumCircuit" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L119-L6609" signature="qiskit.circuit.QuantumCircuit(*regs, name=None, global_phase=0, metadata=None, inputs=(), captures=(), declarations=())" modifiers="class">
|
||
Core Qiskit representation of a quantum circuit.
|
||
|
||
<Admonition title="Note" type="note">
|
||
For more details setting the [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") in context of all of the data structures that go with it, how it fits into the rest of the [`qiskit`](index#module-qiskit "qiskit") package, and the different regimes of quantum-circuit descriptions in Qiskit, see the module-level documentation of [`qiskit.circuit`](circuit#module-qiskit.circuit "qiskit.circuit").
|
||
</Admonition>
|
||
|
||
## Circuit attributes
|
||
|
||
[`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") has a small number of public attributes, which are mostly older functionality. Most of its functionality is accessed through methods.
|
||
|
||
A small handful of the attributes are intentionally mutable, the rest are data attributes that should be considered immutable.
|
||
|
||
| Mutable attribute | Summary |
|
||
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||
| [`global_phase`](#qiskit.circuit.QuantumCircuit.global_phase "qiskit.circuit.QuantumCircuit.global_phase") | The global phase of the circuit, measured in radians. |
|
||
| [`metadata`](#qiskit.circuit.QuantumCircuit.metadata "qiskit.circuit.QuantumCircuit.metadata") | Arbitrary user mapping, which Qiskit will preserve through the transpiler, but otherwise completely ignore. |
|
||
| [`name`](#qiskit.circuit.QuantumCircuit.name "qiskit.circuit.QuantumCircuit.name") | An optional string name for the circuit. |
|
||
|
||
| Immutable data attribute | Summary |
|
||
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| [`ancillas`](#qiskit.circuit.QuantumCircuit.ancillas "qiskit.circuit.QuantumCircuit.ancillas") | List of [`AncillaQubit`](circuit#qiskit.circuit.AncillaQubit "qiskit.circuit.AncillaQubit")s tracked by the circuit. |
|
||
| [`calibrations`](#qiskit.circuit.QuantumCircuit.calibrations "qiskit.circuit.QuantumCircuit.calibrations") | Custom user-supplied pulse calibrations for individual instructions. |
|
||
| [`cregs`](#qiskit.circuit.QuantumCircuit.cregs "qiskit.circuit.QuantumCircuit.cregs") | List of [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")s tracked by the circuit. |
|
||
| [`clbits`](#qiskit.circuit.QuantumCircuit.clbits "qiskit.circuit.QuantumCircuit.clbits") | List of [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")s tracked by the circuit. |
|
||
| [`data`](#qiskit.circuit.QuantumCircuit.data "qiskit.circuit.QuantumCircuit.data") | List of individual [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s that make up the circuit. |
|
||
| [`duration`](#qiskit.circuit.QuantumCircuit.duration "qiskit.circuit.QuantumCircuit.duration") | Total duration of the circuit, added by scheduling transpiler passes. |
|
||
| [`layout`](#qiskit.circuit.QuantumCircuit.layout "qiskit.circuit.QuantumCircuit.layout") | Hardware layout and routing information added by the transpiler. |
|
||
| [`num_ancillas`](#qiskit.circuit.QuantumCircuit.num_ancillas "qiskit.circuit.QuantumCircuit.num_ancillas") | The number of ancilla qubits in the circuit. |
|
||
| [`num_clbits`](#qiskit.circuit.QuantumCircuit.num_clbits "qiskit.circuit.QuantumCircuit.num_clbits") | The number of clbits in the circuit. |
|
||
| [`num_captured_vars`](#qiskit.circuit.QuantumCircuit.num_captured_vars "qiskit.circuit.QuantumCircuit.num_captured_vars") | Number of captured real-time classical variables. |
|
||
| [`num_declared_vars`](#qiskit.circuit.QuantumCircuit.num_declared_vars "qiskit.circuit.QuantumCircuit.num_declared_vars") | Number of locally declared real-time classical variables in the outer circuit scope. |
|
||
| [`num_input_vars`](#qiskit.circuit.QuantumCircuit.num_input_vars "qiskit.circuit.QuantumCircuit.num_input_vars") | Number of input real-time classical variables. |
|
||
| [`num_parameters`](#qiskit.circuit.QuantumCircuit.num_parameters "qiskit.circuit.QuantumCircuit.num_parameters") | Number of compile-time [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")s in the circuit. |
|
||
| [`num_qubits`](#qiskit.circuit.QuantumCircuit.num_qubits "qiskit.circuit.QuantumCircuit.num_qubits") | Number of qubits in the circuit. |
|
||
| [`num_vars`](#qiskit.circuit.QuantumCircuit.num_vars "qiskit.circuit.QuantumCircuit.num_vars") | Total number of real-time classical variables in the outer circuit scope. |
|
||
| [`op_start_times`](#qiskit.circuit.QuantumCircuit.op_start_times "qiskit.circuit.QuantumCircuit.op_start_times") | Start times of scheduled operations, added by scheduling transpiler passes. |
|
||
| [`parameters`](#qiskit.circuit.QuantumCircuit.parameters "qiskit.circuit.QuantumCircuit.parameters") | Ordered set-like view of the compile-time [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")s tracked by the circuit. |
|
||
| [`qregs`](#qiskit.circuit.QuantumCircuit.qregs "qiskit.circuit.QuantumCircuit.qregs") | List of [`QuantumRegister`](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")s tracked by the circuit. |
|
||
| [`qubits`](#qiskit.circuit.QuantumCircuit.qubits "qiskit.circuit.QuantumCircuit.qubits") | List of [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")s tracked by the circuit. |
|
||
| [`unit`](#qiskit.circuit.QuantumCircuit.unit "qiskit.circuit.QuantumCircuit.unit") | The unit of the [`duration`](#qiskit.circuit.QuantumCircuit.duration "qiskit.circuit.QuantumCircuit.duration") field. |
|
||
|
||
The core attribute is [`data`](#qiskit.circuit.QuantumCircuit.data "qiskit.circuit.QuantumCircuit.data"). This is a sequence-like object that exposes the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s contained in an ordered form. You generally should not mutate this object directly; [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") is only designed for append-only operations (which should use [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append")). Most operations that mutate circuits in place should be written as transpiler passes ([`qiskit.transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler")).
|
||
|
||
### data
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.data">
|
||
The circuit data (instructions and context).
|
||
|
||
**Returns**
|
||
|
||
a list-like object containing the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s for each instruction.
|
||
|
||
**Return type**
|
||
|
||
QuantumCircuitData
|
||
</Attribute>
|
||
|
||
Alongside the [`data`](#qiskit.circuit.QuantumCircuit.data "qiskit.circuit.QuantumCircuit.data"), the [`global_phase`](#qiskit.circuit.QuantumCircuit.global_phase "qiskit.circuit.QuantumCircuit.global_phase") of a circuit can have some impact on its output, if the circuit is used to describe a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") that may be controlled. This is measured in radians and is directly settable.
|
||
|
||
### global\_phase
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.global_phase">
|
||
The global phase of the current circuit scope in radians.
|
||
</Attribute>
|
||
|
||
The [`name`](#qiskit.circuit.QuantumCircuit.name "qiskit.circuit.QuantumCircuit.name") of a circuit becomes the name of the [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") or [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") resulting from [`to_instruction()`](#qiskit.circuit.QuantumCircuit.to_instruction "qiskit.circuit.QuantumCircuit.to_instruction") and [`to_gate()`](#qiskit.circuit.QuantumCircuit.to_gate "qiskit.circuit.QuantumCircuit.to_gate") calls, which can be handy for visualizations.
|
||
|
||
### name
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.name" attributeTypeHint="str">
|
||
A human-readable name for the circuit.
|
||
</Attribute>
|
||
|
||
You can attach arbitrary [`metadata`](#qiskit.circuit.QuantumCircuit.metadata "qiskit.circuit.QuantumCircuit.metadata") to a circuit. No part of core Qiskit will inspect this or change its behavior based on metadata, but it will be faithfully passed through the transpiler, so you can tag your circuits yourself. When serializing a circuit with QPY (see [`qiskit.qpy`](qpy#module-qiskit.qpy "qiskit.qpy")), the metadata will be JSON-serialized and you may need to pass a custom serializer to handle non-JSON-compatible objects within it (see [`qpy.dump()`](qpy#qiskit.qpy.dump "qiskit.qpy.dump") for more detail). This field is ignored during export to OpenQASM 2 or 3.
|
||
|
||
### metadata
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.metadata">
|
||
Arbitrary user-defined metadata for the circuit.
|
||
|
||
Qiskit will not examine the content of this mapping, but it will pass it through the transpiler and reattach it to the output, so you can track your own metadata.
|
||
</Attribute>
|
||
|
||
[`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") exposes data attributes tracking its internal quantum and classical bits and registers. These appear as Python [`list`](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")s, but you should treat them as immutable; changing them will *at best* have no effect, and more likely will simply corrupt the internal data of the [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
|
||
|
||
### qregs
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.qregs" attributeTypeHint="list[QuantumRegister]">
|
||
A list of the [`QuantumRegister`](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")s in this circuit. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### cregs
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.cregs" attributeTypeHint="list[ClassicalRegister]">
|
||
A list of the [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")s in this circuit. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### qubits
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.qubits">
|
||
A list of [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")s in the order that they were added. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### ancillas
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.ancillas">
|
||
A list of [`AncillaQubit`](circuit#qiskit.circuit.AncillaQubit "qiskit.circuit.AncillaQubit")s in the order that they were added. You should not mutate this.
|
||
</Attribute>
|
||
|
||
### clbits
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.clbits">
|
||
A list of [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")s in the order that they were added. You should not mutate this.
|
||
</Attribute>
|
||
|
||
The [compile-time parameters](circuit#circuit-compile-time-parameters) present in instructions on the circuit are available in [`parameters`](#qiskit.circuit.QuantumCircuit.parameters "qiskit.circuit.QuantumCircuit.parameters"). This has a canonical order (mostly lexical, except in the case of [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector")), which matches the order that parameters will be assigned when using the list forms of [`assign_parameters()`](#qiskit.circuit.QuantumCircuit.assign_parameters "qiskit.circuit.QuantumCircuit.assign_parameters"), but also supports [`set`](https://docs.python.org/3/library/stdtypes.html#set "(in Python v3.13)")-like constant-time membership testing.
|
||
|
||
### parameters
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.parameters">
|
||
The parameters defined in the circuit.
|
||
|
||
This attribute returns the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit sorted alphabetically. Note that parameters instantiated with a [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") are still sorted numerically.
|
||
|
||
**Examples**
|
||
|
||
The snippet below shows that insertion order of parameters does not matter.
|
||
|
||
```python
|
||
>>> 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.
|
||
|
||
```python
|
||
>>> 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`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") can be used.
|
||
|
||
```python
|
||
>>> 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`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") objects in the circuit.
|
||
</Attribute>
|
||
|
||
The storage of any [manual pulse-level calibrations](#circuit-calibrations) for individual instructions on the circuit is in [`calibrations`](#qiskit.circuit.QuantumCircuit.calibrations "qiskit.circuit.QuantumCircuit.calibrations"). This presents as a [`dict`](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)"), but should not be mutated directly; use the methods discussed in [Manual calibration of instructions](#circuit-calibrations).
|
||
|
||
### calibrations
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.calibrations">
|
||
Return calibration dictionary.
|
||
|
||
The custom pulse definition of a given gate is of the form `{'gate_name': {(qubits, params): schedule}}`
|
||
</Attribute>
|
||
|
||
If you have transpiled your circuit, so you have a physical circuit, you can inspect the [`layout`](#qiskit.circuit.QuantumCircuit.layout "qiskit.circuit.QuantumCircuit.layout") attribute for information stored by the transpiler about how the virtual qubits of the source circuit map to the hardware qubits of your physical circuit, both at the start and end of the circuit.
|
||
|
||
### layout
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.layout">
|
||
Return any associated layout information about the circuit
|
||
|
||
This attribute contains an optional [`TranspileLayout`](qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") object. This is typically set on the output from [`transpile()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") or [`PassManager.run()`](qiskit.transpiler.PassManager#run "qiskit.transpiler.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()`](compiler#qiskit.compiler.transpile "qiskit.compiler.transpile") function, an initial layout which permutes the qubits based on the selected physical qubits on the [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target"), and a final layout which is an output permutation caused by [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted during routing.
|
||
</Attribute>
|
||
|
||
If your circuit was also *scheduled* as part of a transpilation, it will expose the individual timings of each instruction, along with the total [`duration`](#qiskit.circuit.QuantumCircuit.duration "qiskit.circuit.QuantumCircuit.duration") of the circuit.
|
||
|
||
### duration
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.duration" attributeTypeHint="int | float | None">
|
||
The total duration of the circuit, set by a scheduling transpiler pass. Its unit is specified by [`unit`](#qiskit.circuit.QuantumCircuit.unit "qiskit.circuit.QuantumCircuit.unit").
|
||
</Attribute>
|
||
|
||
### unit
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.unit">
|
||
The unit that [`duration`](#qiskit.circuit.QuantumCircuit.duration "qiskit.circuit.QuantumCircuit.duration") is specified in.
|
||
</Attribute>
|
||
|
||
### op\_start\_times
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.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`](#qiskit.circuit.QuantumCircuit.data "qiskit.circuit.QuantumCircuit.data").
|
||
|
||
**Raises**
|
||
|
||
[**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.13)") – When circuit is not scheduled.
|
||
</Attribute>
|
||
|
||
Finally, [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") exposes several simple properties as dynamic read-only numeric attributes.
|
||
|
||
### num\_ancillas
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.num_ancillas">
|
||
Return the number of ancilla qubits.
|
||
</Attribute>
|
||
|
||
### num\_clbits
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.num_clbits">
|
||
Return number of classical bits.
|
||
</Attribute>
|
||
|
||
### num\_captured\_vars
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.num_captured_vars">
|
||
The number of real-time classical variables in the circuit marked as captured from an enclosing scope.
|
||
|
||
This is the length of the [`iter_captured_vars()`](#qiskit.circuit.QuantumCircuit.iter_captured_vars "qiskit.circuit.QuantumCircuit.iter_captured_vars") iterable. If this is non-zero, [`num_input_vars`](#qiskit.circuit.QuantumCircuit.num_input_vars "qiskit.circuit.QuantumCircuit.num_input_vars") must be zero.
|
||
</Attribute>
|
||
|
||
### num\_declared\_vars
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.num_declared_vars">
|
||
The number of real-time classical variables in the circuit that are declared by this circuit scope, excluding inputs or captures.
|
||
|
||
This is the length of the [`iter_declared_vars()`](#qiskit.circuit.QuantumCircuit.iter_declared_vars "qiskit.circuit.QuantumCircuit.iter_declared_vars") iterable.
|
||
</Attribute>
|
||
|
||
### num\_input\_vars
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.num_input_vars">
|
||
The number of real-time classical variables in the circuit marked as circuit inputs.
|
||
|
||
This is the length of the [`iter_input_vars()`](#qiskit.circuit.QuantumCircuit.iter_input_vars "qiskit.circuit.QuantumCircuit.iter_input_vars") iterable. If this is non-zero, [`num_captured_vars`](#qiskit.circuit.QuantumCircuit.num_captured_vars "qiskit.circuit.QuantumCircuit.num_captured_vars") must be zero.
|
||
</Attribute>
|
||
|
||
### num\_parameters
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.num_parameters">
|
||
The number of parameter objects in the circuit.
|
||
</Attribute>
|
||
|
||
### num\_qubits
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.num_qubits">
|
||
Return number of qubits.
|
||
</Attribute>
|
||
|
||
### num\_vars
|
||
|
||
<Attribute id="qiskit.circuit.QuantumCircuit.num_vars">
|
||
The number of real-time classical variables in the circuit.
|
||
|
||
This is the length of the [`iter_vars()`](#qiskit.circuit.QuantumCircuit.iter_vars "qiskit.circuit.QuantumCircuit.iter_vars") iterable.
|
||
</Attribute>
|
||
|
||
## Creating new circuits
|
||
|
||
| Method | Summary |
|
||
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||
| [`__init__()`](#qiskit.circuit.QuantumCircuit.__init__ "qiskit.circuit.QuantumCircuit.__init__") | Default constructor of no-instruction circuits. |
|
||
| [`copy()`](#qiskit.circuit.QuantumCircuit.copy "qiskit.circuit.QuantumCircuit.copy") | Make a complete copy of an existing circuit. |
|
||
| [`copy_empty_like()`](#qiskit.circuit.QuantumCircuit.copy_empty_like "qiskit.circuit.QuantumCircuit.copy_empty_like") | Copy data objects from one circuit into a new one without any instructions. |
|
||
| [`from_instructions()`](#qiskit.circuit.QuantumCircuit.from_instructions "qiskit.circuit.QuantumCircuit.from_instructions") | Infer data objects needed from a list of instructions. |
|
||
| [`from_qasm_file()`](#qiskit.circuit.QuantumCircuit.from_qasm_file "qiskit.circuit.QuantumCircuit.from_qasm_file") | Legacy interface to [`qasm2.load()`](qasm2#qiskit.qasm2.load "qiskit.qasm2.load"). |
|
||
| [`from_qasm_str()`](#qiskit.circuit.QuantumCircuit.from_qasm_str "qiskit.circuit.QuantumCircuit.from_qasm_str") | Legacy interface to [`qasm2.loads()`](qasm2#qiskit.qasm2.loads "qiskit.qasm2.loads"). |
|
||
|
||
The default constructor (`QuantumCircuit(...)`) produces a circuit with no initial instructions. The arguments to the default constructor can be used to seed the circuit with quantum and classical data storage, and to provide a name, global phase and arbitrary metadata. All of these fields can be expanded later.
|
||
|
||
### \_\_init\_\_
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.__init__" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L989-L1157" signature="__init__(*regs, name=None, global_phase=0, metadata=None, inputs=(), captures=(), declarations=())">
|
||
Default constructor of [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
|
||
|
||
**Parameters**
|
||
|
||
* **regs** ([*Register*](circuit#qiskit.circuit.Register "qiskit.circuit.Register") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| Sequence\[*[*Bit*](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit")*]*) –
|
||
|
||
The registers to be included in the circuit.
|
||
|
||
* If a list of [`Register`](circuit#qiskit.circuit.Register "qiskit.circuit.Register") objects, represents the [`QuantumRegister`](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") and/or [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.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`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit") objects, a collection of [`Bit`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit") s to be added to the circuit.
|
||
|
||
* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – the name of the quantum circuit. If not set, an automatically generated string will be assigned.
|
||
|
||
* **global\_phase** (*ParameterValueType*) – The global phase of the circuit in radians.
|
||
|
||
* **metadata** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)") *| None*) – Arbitrary key value metadata to associate with the circuit. This gets stored as free-form data in a dict in the [`metadata`](#qiskit.circuit.QuantumCircuit.metadata "qiskit.circuit.QuantumCircuit.metadata") attribute. It will not be directly used in the circuit.
|
||
|
||
* **inputs** (*Iterable\[*[*expr.Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var")*]*) – any variables to declare as `input` runtime variables for this circuit. These should already be existing [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes that you build from somewhere else; if you need to create the inputs as well, use [`QuantumCircuit.add_input()`](#qiskit.circuit.QuantumCircuit.add_input "qiskit.circuit.QuantumCircuit.add_input"). The variables given in this argument will be passed directly to [`add_input()`](#qiskit.circuit.QuantumCircuit.add_input "qiskit.circuit.QuantumCircuit.add_input"). A circuit cannot have both `inputs` and `captures`.
|
||
|
||
* **captures** (*Iterable\[*[*expr.Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var")*]*) – any variables that that this circuit scope should capture from a containing scope. The variables given here will be passed directly to [`add_capture()`](#qiskit.circuit.QuantumCircuit.add_capture "qiskit.circuit.QuantumCircuit.add_capture"). A circuit cannot have both `inputs` and `captures`.
|
||
|
||
* **declarations** (*Mapping\[*[*expr.Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var")*,* [*expr.Expr*](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr")*] | Iterable\[Tuple\[*[*expr.Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var")*,* [*expr.Expr*](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr")*]]*) –
|
||
|
||
any variables that this circuit should declare and initialize immediately. You can order this input so that later declarations depend on earlier ones (including inputs or captures). If you need to depend on values that will be computed later at runtime, use [`add_var()`](#qiskit.circuit.QuantumCircuit.add_var "qiskit.circuit.QuantumCircuit.add_var") at an appropriate point in the circuit execution.
|
||
|
||
This argument is intended for convenient circuit initialization when you already have a set of created variables. The variables used here will be directly passed to [`add_var()`](#qiskit.circuit.QuantumCircuit.add_var "qiskit.circuit.QuantumCircuit.add_var"), which you can use directly if this is the first time you are creating the variable.
|
||
|
||
**Raises**
|
||
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the circuit name, if given, is not valid.
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if both `inputs` and `captures` are given.
|
||
</Function>
|
||
|
||
If you have an existing circuit, you can produce a copy of it using [`copy()`](#qiskit.circuit.QuantumCircuit.copy "qiskit.circuit.QuantumCircuit.copy"), including all its instructions. This is useful if you want to keep partial circuits while extending another, or to have a version you can mutate in-place while leaving the prior one intact.
|
||
|
||
### copy
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.copy" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3650-L3661" signature="copy(name=None)">
|
||
Copy the circuit.
|
||
|
||
**Parameters**
|
||
|
||
**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – 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](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
Similarly, if you want a circuit that contains all the same data objects (bits, registers, variables, etc) but with none of the instructions, you can use [`copy_empty_like()`](#qiskit.circuit.QuantumCircuit.copy_empty_like "qiskit.circuit.QuantumCircuit.copy_empty_like"). This is quite common when you want to build up a new layer of a circuit to then use apply onto the back with [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose"), or to do a full rewrite of a circuit’s instructions.
|
||
|
||
### copy\_empty\_like
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.copy_empty_like" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3663-L3748" signature="copy_empty_like(name=None, *, vars_mode='alike')">
|
||
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
|
||
* the realtime variables defined in the circuit, handled according to the `vars` keyword argument.
|
||
|
||
<Admonition title="Warning" type="caution">
|
||
If the circuit contains any local variable declarations (those added by the `declarations` argument to the circuit constructor, or using [`add_var()`](#qiskit.circuit.QuantumCircuit.add_var "qiskit.circuit.QuantumCircuit.add_var")), they may be **uninitialized** in the output circuit. You will need to manually add store instructions for them (see [`Store`](circuit#qiskit.circuit.Store "qiskit.circuit.Store") and [`QuantumCircuit.store()`](#qiskit.circuit.QuantumCircuit.store "qiskit.circuit.QuantumCircuit.store")) to initialize them.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
* **name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – Name for the copied circuit. If None, then the name stays the same.
|
||
|
||
* **vars\_mode** (*Literal\['alike', 'captures', 'drop']*) –
|
||
|
||
The mode to handle realtime variables in.
|
||
|
||
**alike**
|
||
|
||
The variables in the output circuit will have the same declaration semantics as in the original circuit. For example, `input` variables in the source will be `input` variables in the output circuit.
|
||
|
||
**captures**
|
||
|
||
All variables will be converted to captured variables. This is useful when you are building a new layer for an existing circuit that you will want to [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") onto the base, since [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") can inline captures onto the base circuit (but not other variables).
|
||
|
||
**drop**
|
||
|
||
The output circuit will have no variables defined.
|
||
|
||
**Returns**
|
||
|
||
An empty copy of self.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
In some cases, it is most convenient to generate a list of [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s separately to an entire circuit context, and then to build a circuit from this. The [`from_instructions()`](#qiskit.circuit.QuantumCircuit.from_instructions "qiskit.circuit.QuantumCircuit.from_instructions") constructor will automatically capture all [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") and [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit") instances used in the instructions, and create a new [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object that has the correct resources and all the instructions.
|
||
|
||
### from\_instructions
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.from_instructions" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1192-L1243" signature="from_instructions(instructions, *, qubits=(), clbits=(), name=None, global_phase=0, metadata=None)" modifiers="static">
|
||
Construct a circuit from an iterable of [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s.
|
||
|
||
**Parameters**
|
||
|
||
* **instructions** (*Iterable\[*[*CircuitInstruction*](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") *|*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*, Iterable\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction")*, Iterable\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*], Iterable\[*[*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]]]*) – The instructions to add to the circuit.
|
||
* **qubits** (*Iterable\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.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*](circuit#qiskit.circuit.Clbit "qiskit.circuit.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The name of the circuit.
|
||
* **global\_phase** (*ParameterValueType*) – The global phase of the circuit in radians.
|
||
* **metadata** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)") *| None*) – Arbitrary key value metadata to associate with the circuit.
|
||
|
||
**Returns**
|
||
|
||
The quantum circuit.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
[`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") also still has two constructor methods that are legacy wrappers around the importers in [`qiskit.qasm2`](qasm2#module-qiskit.qasm2 "qiskit.qasm2"). These automatically apply [the legacy compatibility settings](qasm2#qasm2-legacy-compatibility) of [`load()`](qasm2#qiskit.qasm2.load "qiskit.qasm2.load") and [`loads()`](qasm2#qiskit.qasm2.loads "qiskit.qasm2.loads").
|
||
|
||
### from\_qasm\_file
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.from_qasm_file" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4066-L4089" signature="from_qasm_file(path)" modifiers="static">
|
||
Read an OpenQASM 2.0 program from a file and convert to an instance of [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
|
||
|
||
**Parameters**
|
||
|
||
**path** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – Path to the file for an OpenQASM 2 program
|
||
|
||
**Returns**
|
||
|
||
The QuantumCircuit object for the input OpenQASM 2.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
<Admonition title="See also" type="note">
|
||
[`qasm2.load()`](qasm2#qiskit.qasm2.load "qiskit.qasm2.load"): the complete interface to the OpenQASM 2 importer.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
### from\_qasm\_str
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.from_qasm_str" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4091-L4112" signature="from_qasm_str(qasm_str)" modifiers="static">
|
||
Convert a string containing an OpenQASM 2.0 program to a [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit").
|
||
|
||
**Parameters**
|
||
|
||
**qasm\_str** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – A string containing an OpenQASM 2.0 program.
|
||
|
||
**Returns**
|
||
|
||
The QuantumCircuit object for the input OpenQASM 2
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
<Admonition title="See also" type="note">
|
||
[`qasm2.loads()`](qasm2#qiskit.qasm2.loads "qiskit.qasm2.loads"): the complete interface to the OpenQASM 2 importer.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
## Data objects on circuits
|
||
|
||
<span id="circuit-adding-data-objects" />
|
||
|
||
### Adding data objects
|
||
|
||
| Method | Adds this kind of data |
|
||
| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| [`add_bits()`](#qiskit.circuit.QuantumCircuit.add_bits "qiskit.circuit.QuantumCircuit.add_bits") | [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")s and [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")s. |
|
||
| [`add_register()`](#qiskit.circuit.QuantumCircuit.add_register "qiskit.circuit.QuantumCircuit.add_register") | [`QuantumRegister`](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") and [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister"). |
|
||
| [`add_var()`](#qiskit.circuit.QuantumCircuit.add_var "qiskit.circuit.QuantumCircuit.add_var") | [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes with local scope and initializers. |
|
||
| [`add_input()`](#qiskit.circuit.QuantumCircuit.add_input "qiskit.circuit.QuantumCircuit.add_input") | [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes that are treated as circuit inputs. |
|
||
| [`add_capture()`](#qiskit.circuit.QuantumCircuit.add_capture "qiskit.circuit.QuantumCircuit.add_capture") | [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes captured from containing scopes. |
|
||
| [`add_uninitialized_var()`](#qiskit.circuit.QuantumCircuit.add_uninitialized_var "qiskit.circuit.QuantumCircuit.add_uninitialized_var") | [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes with local scope and undefined state. |
|
||
|
||
Typically you add most of the data objects ([`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit"), [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit"), [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister"), etc) to the circuit as part of using the [`__init__()`](#qiskit.circuit.QuantumCircuit.__init__ "qiskit.circuit.QuantumCircuit.__init__") default constructor, or [`copy_empty_like()`](#qiskit.circuit.QuantumCircuit.copy_empty_like "qiskit.circuit.QuantumCircuit.copy_empty_like"). However, it is also possible to add these afterwards. Typed classical data, such as standalone [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes (see [Real-time classical computation](circuit#circuit-repr-real-time-classical)), can be both constructed and added with separate methods.
|
||
|
||
New registerless [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") and [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit") objects are added using [`add_bits()`](#qiskit.circuit.QuantumCircuit.add_bits "qiskit.circuit.QuantumCircuit.add_bits"). These objects must not already be present in the circuit. You can check if a bit exists in the circuit already using [`find_bit()`](#qiskit.circuit.QuantumCircuit.find_bit "qiskit.circuit.QuantumCircuit.find_bit").
|
||
|
||
#### add\_bits
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.add_bits" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3069-L3090" signature="add_bits(bits)">
|
||
Add Bits to the circuit.
|
||
</Function>
|
||
|
||
Registers are added to the circuit with [`add_register()`](#qiskit.circuit.QuantumCircuit.add_register "qiskit.circuit.QuantumCircuit.add_register"). In this method, it is not an error if some of the bits are already present in the circuit. In this case, the register will be an “alias” over the bits. This is not generally well-supported by hardware backends; it is probably best to stay away from relying on it. The registers a given bit is in are part of the return of [`find_bit()`](#qiskit.circuit.QuantumCircuit.find_bit "qiskit.circuit.QuantumCircuit.find_bit").
|
||
|
||
#### add\_register
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.add_register" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2997-L3057" signature="add_register(*regs)">
|
||
Add registers.
|
||
</Function>
|
||
|
||
[Real-time, typed classical data](circuit#circuit-repr-real-time-classical) is represented on the circuit by [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes with a well-defined [`Type`](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type"). It is possible to instantiate these separately to a circuit (see [`Var.new()`](circuit_classical#qiskit.circuit.classical.expr.Var.new "qiskit.circuit.classical.expr.Var.new")), but it is often more convenient to use circuit methods that will automatically manage the types and expression initialization for you. The two most common methods are [`add_var()`](#qiskit.circuit.QuantumCircuit.add_var "qiskit.circuit.QuantumCircuit.add_var") (locally scoped variables) and [`add_input()`](#qiskit.circuit.QuantumCircuit.add_input "qiskit.circuit.QuantumCircuit.add_input") (inputs to the circuit).
|
||
|
||
#### add\_var
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.add_var" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2802-L2896" signature="add_var(name_or_var, /, initial)">
|
||
Add a classical variable with automatic storage and scope to this circuit.
|
||
|
||
The variable is considered to have been “declared” at the beginning of the circuit, but it only becomes initialized at the point of the circuit that you call this method, so it can depend on variables defined before it.
|
||
|
||
**Parameters**
|
||
|
||
* **name\_or\_var** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*expr.Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var")) – either a string of the variable name, or an existing instance of [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") to re-use. Variables cannot shadow names that are already in use within the circuit.
|
||
|
||
* **initial** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.13)")) –
|
||
|
||
the value to initialize this variable with. If the first argument was given as a string name, the type of the resulting variable is inferred from the initial expression; to control this more manually, either use [`Var.new()`](circuit_classical#qiskit.circuit.classical.expr.Var.new "qiskit.circuit.classical.expr.Var.new") to manually construct a new variable with the desired type, or use [`expr.cast()`](circuit_classical#qiskit.circuit.classical.expr.cast "qiskit.circuit.classical.expr.cast") to cast the initializer to the desired type.
|
||
|
||
This must be either a [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") node, or a value that can be lifted to one using `expr.lift`.
|
||
|
||
**Returns**
|
||
|
||
The created variable. If a [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") instance was given, the exact same object will be returned.
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the variable cannot be created due to shadowing an existing variable.
|
||
|
||
**Return type**
|
||
|
||
[expr.Var](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var")
|
||
|
||
**Examples**
|
||
|
||
Define a new variable given just a name and an initializer expression:
|
||
|
||
```python
|
||
from qiskit.circuit import QuantumCircuit
|
||
|
||
qc = QuantumCircuit(2)
|
||
my_var = qc.add_var("my_var", False)
|
||
```
|
||
|
||
Reuse a variable that may have been taken from a related circuit, or otherwise constructed manually, and initialize it to some more complicated expression:
|
||
|
||
```python
|
||
from qiskit.circuit import QuantumCircuit, QuantumRegister, ClassicalRegister
|
||
from qiskit.circuit.classical import expr, types
|
||
|
||
my_var = expr.Var.new("my_var", types.Uint(8))
|
||
|
||
cr1 = ClassicalRegister(8, "cr1")
|
||
cr2 = ClassicalRegister(8, "cr2")
|
||
qc = QuantumCircuit(QuantumRegister(8), cr1, cr2)
|
||
|
||
# Get some measurement results into each register.
|
||
qc.h(0)
|
||
for i in range(1, 8):
|
||
qc.cx(0, i)
|
||
qc.measure(range(8), cr1)
|
||
|
||
qc.reset(range(8))
|
||
qc.h(0)
|
||
for i in range(1, 8):
|
||
qc.cx(0, i)
|
||
qc.measure(range(8), cr2)
|
||
|
||
# Now when we add the variable, it is initialized using the real-time state of the
|
||
# two classical registers we measured into above.
|
||
qc.add_var(my_var, expr.bit_and(cr1, cr2))
|
||
```
|
||
</Function>
|
||
|
||
#### add\_input
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.add_input" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2969-L2995" signature="add_input(name_or_var: str, type_: Type, /) → Var" extraSignatures={["add_input(name_or_var: Var, type_: None = None, /) → Var"]}>
|
||
Register a variable as an input to the circuit.
|
||
|
||
**Parameters**
|
||
|
||
* **name\_or\_var** – either a string name, or an existing [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") node to use as the input variable.
|
||
* **type** – if the name is given as a string, then this must be a [`Type`](circuit_classical#qiskit.circuit.classical.types.Type "qiskit.circuit.classical.types.Type") to use for the variable. If the variable is given as an existing [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var"), then this must not be given, and will instead be read from the object itself.
|
||
|
||
**Returns**
|
||
|
||
the variable created, or the same variable as was passed in.
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the variable cannot be created due to shadowing an existing variable.
|
||
</Function>
|
||
|
||
In addition, there are two lower-level methods that can be useful for programmatic generation of circuits. When working interactively, you will most likely not need these; most uses of [`add_uninitialized_var()`](#qiskit.circuit.QuantumCircuit.add_uninitialized_var "qiskit.circuit.QuantumCircuit.add_uninitialized_var") are part of [`copy_empty_like()`](#qiskit.circuit.QuantumCircuit.copy_empty_like "qiskit.circuit.QuantumCircuit.copy_empty_like"), and most uses of [`add_capture()`](#qiskit.circuit.QuantumCircuit.add_capture "qiskit.circuit.QuantumCircuit.add_capture") would be better off using [the control-flow builder interface](#circuit-control-flow-methods).
|
||
|
||
#### add\_uninitialized\_var
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.add_uninitialized_var" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2898-L2929" signature="add_uninitialized_var(var, /)">
|
||
Add a variable with no initializer.
|
||
|
||
In most cases, you should use [`add_var()`](#qiskit.circuit.QuantumCircuit.add_var "qiskit.circuit.QuantumCircuit.add_var") to initialize the variable. To use this function, you must already hold a [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") instance, as the use of the function typically only makes sense in copying contexts.
|
||
|
||
<Admonition title="Warning" type="caution">
|
||
Qiskit makes no assertions about what an uninitialized variable will evaluate to at runtime, and some hardware may reject this as an error.
|
||
|
||
You should treat this function with caution, and as a low-level primitive that is useful only in special cases of programmatically rebuilding two like circuits.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
**var** ([*Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var")) – the variable to add.
|
||
</Function>
|
||
|
||
#### add\_capture
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.add_capture" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2931-L2961" signature="add_capture(var)">
|
||
Add a variable to the circuit that it should capture from a scope it will be contained within.
|
||
|
||
This method requires a [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") node to enforce that you’ve got a handle to one, because you will need to declare the same variable using the same object into the outer circuit.
|
||
|
||
This is a low-level method, which is only really useful if you are manually constructing control-flow operations. You typically will not need to call this method, assuming you are using the builder interface for control-flow scopes (`with` context-manager statements for [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test") and the other scoping constructs). The builder interface will automatically make the inner scopes closures on your behalf by capturing any variables that are used within them.
|
||
|
||
**Parameters**
|
||
|
||
**var** ([*Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var")) – the variable to capture from an enclosing scope.
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the variable cannot be created due to shadowing an existing variable.
|
||
</Function>
|
||
|
||
### Working with bits and registers
|
||
|
||
A [`Bit`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit") instance is, on its own, just a unique handle for circuits to use in their own contexts. If you have got a [`Bit`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit") instance and a circuit, just can find the contexts that the bit exists in using [`find_bit()`](#qiskit.circuit.QuantumCircuit.find_bit "qiskit.circuit.QuantumCircuit.find_bit"), such as its integer index in the circuit and any registers it is contained in.
|
||
|
||
#### find\_bit
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.find_bit" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3092-L3153" signature="find_bit(bit)">
|
||
Find locations in the circuit which can be used to reference a given [`Bit`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit").
|
||
|
||
In particular, this function can find the integer index of a qubit, which corresponds to its hardware index for a transpiled circuit.
|
||
|
||
<Admonition title="Note" type="note">
|
||
The circuit index of a [`AncillaQubit`](circuit#qiskit.circuit.AncillaQubit "qiskit.circuit.AncillaQubit") will be its index in [`qubits`](#qiskit.circuit.QuantumCircuit.qubits "qiskit.circuit.QuantumCircuit.qubits"), not [`ancillas`](#qiskit.circuit.QuantumCircuit.ancillas "qiskit.circuit.QuantumCircuit.ancillas").
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
**bit** ([*Bit*](circuit#qiskit.circuit.Bit "qiskit.circuit.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`](#qiskit.circuit.QuantumCircuit.qubits "qiskit.circuit.QuantumCircuit.qubits"), [`clbits`](#qiskit.circuit.QuantumCircuit.clbits "qiskit.circuit.QuantumCircuit.clbits"), depending on its type). The second element (`registers`) is a list of `(register, index)` pairs with an entry for each [`Register`](circuit#qiskit.circuit.Register "qiskit.circuit.Register") in the circuit which contains the [`Bit`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit") (and the index in the [`Register`](circuit#qiskit.circuit.Register "qiskit.circuit.Register") at which it can be found).
|
||
|
||
**Return type**
|
||
|
||
namedtuple([int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)"), List\[Tuple([Register](circuit#qiskit.circuit.Register "qiskit.circuit.Register"), [int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)"))])
|
||
|
||
**Raises**
|
||
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the supplied [`Bit`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit") was of an unknown type.
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the supplied [`Bit`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit") could not be found on the circuit.
|
||
|
||
**Examples**
|
||
|
||
Loop through a circuit, getting the qubit and clbit indices of each operation:
|
||
|
||
```python
|
||
from qiskit.circuit import QuantumCircuit, Qubit
|
||
|
||
qc = QuantumCircuit(3, 3)
|
||
qc.h(0)
|
||
qc.cx(0, 1)
|
||
qc.cx(1, 2)
|
||
qc.measure([0, 1, 2], [0, 1, 2])
|
||
|
||
# The `.qubits` and `.clbits` fields are not integers.
|
||
assert isinstance(qc.data[0].qubits[0], Qubit)
|
||
# ... but we can use `find_bit` to retrieve them.
|
||
assert qc.find_bit(qc.data[0].qubits[0]).index == 0
|
||
|
||
simple = [
|
||
(
|
||
instruction.operation.name,
|
||
[qc.find_bit(bit).index for bit in instruction.qubits],
|
||
[qc.find_bit(bit).index for bit in instruction.clbits],
|
||
)
|
||
for instruction in qc.data
|
||
]
|
||
```
|
||
</Function>
|
||
|
||
Similarly, you can query a circuit to see if a register has already been added to it by using [`has_register()`](#qiskit.circuit.QuantumCircuit.has_register "qiskit.circuit.QuantumCircuit.has_register").
|
||
|
||
#### has\_register
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.has_register" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1467-L1482" signature="has_register(register)">
|
||
Test if this circuit has the register r.
|
||
|
||
**Parameters**
|
||
|
||
**register** ([*Register*](circuit#qiskit.circuit.Register "qiskit.circuit.Register")) – a quantum or classical register.
|
||
|
||
**Returns**
|
||
|
||
True if the register is contained in this circuit.
|
||
|
||
**Return type**
|
||
|
||
[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")
|
||
</Function>
|
||
|
||
### Working with compile-time parameters
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[Compile-time parametrization](circuit#circuit-compile-time-parameters)**
|
||
|
||
A more complete discussion of what compile-time parametrization is, and how it fits into Qiskit’s data model.
|
||
</Admonition>
|
||
|
||
Unlike bits, registers, and real-time typed classical data, compile-time symbolic parameters are not manually added to a circuit. Their presence is inferred by being contained in operations added to circuits and the global phase. An ordered list of all parameters currently in a circuit is at [`QuantumCircuit.parameters`](#qiskit.circuit.QuantumCircuit.parameters "qiskit.circuit.QuantumCircuit.parameters").
|
||
|
||
The most common operation on [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") instances is to replace them in symbolic operations with some numeric value, or another symbolic expression. This is done with [`assign_parameters()`](#qiskit.circuit.QuantumCircuit.assign_parameters "qiskit.circuit.QuantumCircuit.assign_parameters").
|
||
|
||
#### assign\_parameters
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.assign_parameters" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4233-L4382" signature="assign_parameters(parameters: Mapping[Parameter, ParameterExpression | float] | Iterable[ParameterExpression | float], inplace: Literal[False] = False, *, flat_input: bool = False, strict: bool = True) → QuantumCircuit" extraSignatures={["assign_parameters(parameters: Mapping[Parameter, ParameterExpression | float] | Iterable[ParameterExpression | float], inplace: Literal[True] = False, *, flat_input: bool = False, strict: bool = True) → None"]}>
|
||
Assign parameters to new parameters or values.
|
||
|
||
If `parameters` is passed as a dictionary, the keys should be [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.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`](#qiskit.circuit.QuantumCircuit.parameters "qiskit.circuit.QuantumCircuit.parameters") which is sorted alphabetically (while respecting the ordering in [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.ParameterVector") objects).
|
||
|
||
The values can be assigned to the current circuit object or to a copy of it.
|
||
|
||
<Admonition title="Note" type="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()`](#qiskit.circuit.QuantumCircuit.get_parameter "qiskit.circuit.QuantumCircuit.get_parameter"). You can also have keys that are [`ParameterVector`](qiskit.circuit.ParameterVector "qiskit.circuit.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`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") instances.
|
||
</Admonition>
|
||
|
||
**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`](qiskit.circuit.ParameterVector "qiskit.circuit.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`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") instances using [`get_parameter()`](#qiskit.circuit.QuantumCircuit.get_parameter "qiskit.circuit.QuantumCircuit.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**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If parameters is a dict and contains parameters not present in the circuit.
|
||
* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – 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.
|
||
|
||
```python
|
||
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 out-of-place by list and get a copy of the original circuit.
|
||
|
||
```python
|
||
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')
|
||
```
|
||
|
||
|
||
|
||
|
||
</Function>
|
||
|
||
The circuit tracks parameters by [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") instances themselves, and forbids having multiple parameters of the same name to avoid some problems when interoperating with OpenQASM or other external formats. You can use [`has_parameter()`](#qiskit.circuit.QuantumCircuit.has_parameter "qiskit.circuit.QuantumCircuit.has_parameter") and [`get_parameter()`](#qiskit.circuit.QuantumCircuit.get_parameter "qiskit.circuit.QuantumCircuit.get_parameter") to query the circuit for a parameter with the given string name.
|
||
|
||
#### has\_parameter
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.has_parameter" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2675-L2695" signature="has_parameter(name_or_param, /)">
|
||
Check whether a parameter object exists in this circuit.
|
||
|
||
**Parameters**
|
||
|
||
**name\_or\_param** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")) – the parameter, or name of a parameter to check. If this is a [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.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](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`QuantumCircuit.get_parameter()`](#qiskit.circuit.QuantumCircuit.get_parameter "qiskit.circuit.QuantumCircuit.get_parameter")**
|
||
|
||
Retrieve the [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") instance from this circuit by name.
|
||
|
||
**[`QuantumCircuit.has_var()`](#qiskit.circuit.QuantumCircuit.has_var "qiskit.circuit.QuantumCircuit.has_var")**
|
||
|
||
A similar method to this, but for run-time [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") variables instead of compile-time [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")s.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
#### get\_parameter
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.get_parameter" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2628-L2673" signature="get_parameter(name: str, default: T) → Parameter | T" extraSignatures={["get_parameter(name: str, default: ellipsis = Ellipsis) → Parameter"]}>
|
||
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`](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.13)") is raised instead.
|
||
|
||
**Returns**
|
||
|
||
The corresponding parameter.
|
||
|
||
**Raises**
|
||
|
||
[**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.13)") – if no default is given, but the parameter does not exist in the circuit.
|
||
|
||
**Examples**
|
||
|
||
Retrieve a parameter by name from a circuit:
|
||
|
||
```python
|
||
from qiskit.circuit import QuantumCircuit, Parameter
|
||
|
||
my_param = Parameter("my_param")
|
||
|
||
# Create a parametrized 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:
|
||
|
||
```python
|
||
assert qc.get_parameter("my_param", None) is my_param
|
||
assert qc.get_parameter("unknown_param", None) is None
|
||
```
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`get_var()`](#qiskit.circuit.QuantumCircuit.get_var "qiskit.circuit.QuantumCircuit.get_var")**
|
||
|
||
A similar method, but for [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") run-time variables instead of [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") compile-time parameters.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
<span id="circuit-real-time-methods" />
|
||
|
||
### Working with real-time typed classical data
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`qiskit.circuit.classical`](circuit_classical#module-qiskit.circuit.classical "qiskit.circuit.classical")**
|
||
|
||
Module-level documentation for how the variable-, expression- and type-systems work, the objects used to represent them, and the classical operations available.
|
||
|
||
**[Real-time classical computation](circuit#circuit-repr-real-time-classical)**
|
||
|
||
A discussion of how real-time data fits into the entire [`qiskit.circuit`](circuit#module-qiskit.circuit "qiskit.circuit") data model as a whole.
|
||
|
||
**[Adding data objects](#circuit-adding-data-objects)**
|
||
|
||
The methods for adding new [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") variables to a circuit after initialization.
|
||
</Admonition>
|
||
|
||
You can retrive a [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") instance attached to a circuit by using its variable name using [`get_var()`](#qiskit.circuit.QuantumCircuit.get_var "qiskit.circuit.QuantumCircuit.get_var"), or check if a circuit contains a given variable with [`has_var()`](#qiskit.circuit.QuantumCircuit.has_var "qiskit.circuit.QuantumCircuit.has_var").
|
||
|
||
#### get\_var
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.get_var" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2705-L2748" signature="get_var(name: str, default: T) → Var | T" extraSignatures={["get_var(name: str, default: ellipsis = Ellipsis) → Var"]}>
|
||
Retrieve a variable that is accessible in this circuit scope by name.
|
||
|
||
**Parameters**
|
||
|
||
* **name** – the name of the variable to retrieve.
|
||
* **default** – if given, this value will be returned if the variable is not present. If it is not given, a [`KeyError`](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.13)") is raised instead.
|
||
|
||
**Returns**
|
||
|
||
The corresponding variable.
|
||
|
||
**Raises**
|
||
|
||
[**KeyError**](https://docs.python.org/3/library/exceptions.html#KeyError "(in Python v3.13)") – if no default is given, but the variable does not exist.
|
||
|
||
**Examples**
|
||
|
||
Retrieve a variable by name from a circuit:
|
||
|
||
```python
|
||
from qiskit.circuit import QuantumCircuit
|
||
|
||
# Create a circuit and create a variable in it.
|
||
qc = QuantumCircuit()
|
||
my_var = qc.add_var("my_var", False)
|
||
|
||
# We can use 'my_var' as a variable, but let's say we've lost the Python object and
|
||
# need to retrieve it.
|
||
my_var_again = qc.get_var("my_var")
|
||
|
||
assert my_var is my_var_again
|
||
```
|
||
|
||
Get a variable from a circuit by name, returning some default if it is not present:
|
||
|
||
```python
|
||
assert qc.get_var("my_var", None) is my_var
|
||
assert qc.get_var("unknown_variable", None) is None
|
||
```
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`get_parameter()`](#qiskit.circuit.QuantumCircuit.get_parameter "qiskit.circuit.QuantumCircuit.get_parameter")**
|
||
|
||
A similar method, but for [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter") compile-time parameters instead of [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") run-time variables.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
#### has\_var
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.has_var" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2750-L2770" signature="has_var(name_or_var, /)">
|
||
Check whether a variable is accessible in this scope.
|
||
|
||
**Parameters**
|
||
|
||
**name\_or\_var** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*expr.Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var")) – the variable, or name of a variable to check. If this is a [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") node, the variable must be exactly the given one for this function to return `True`.
|
||
|
||
**Returns**
|
||
|
||
whether a matching variable is accessible.
|
||
|
||
**Return type**
|
||
|
||
[bool](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`QuantumCircuit.get_var()`](#qiskit.circuit.QuantumCircuit.get_var "qiskit.circuit.QuantumCircuit.get_var")**
|
||
|
||
Retrieve the [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") instance from this circuit by name.
|
||
|
||
**[`QuantumCircuit.has_parameter()`](#qiskit.circuit.QuantumCircuit.has_parameter "qiskit.circuit.QuantumCircuit.has_parameter")**
|
||
|
||
A similar method to this, but for compile-time [`Parameter`](qiskit.circuit.Parameter "qiskit.circuit.Parameter")s instead of run-time [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") variables.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
There are also several iterator methods that you can use to get the full set of variables tracked by a circuit. At least one of [`iter_input_vars()`](#qiskit.circuit.QuantumCircuit.iter_input_vars "qiskit.circuit.QuantumCircuit.iter_input_vars") and [`iter_captured_vars()`](#qiskit.circuit.QuantumCircuit.iter_captured_vars "qiskit.circuit.QuantumCircuit.iter_captured_vars") will be empty, as inputs and captures are mutually exclusive. All of the iterators have corresponding dynamic properties on [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") that contain their length: [`num_vars`](#qiskit.circuit.QuantumCircuit.num_vars "qiskit.circuit.QuantumCircuit.num_vars"), [`num_input_vars`](#qiskit.circuit.QuantumCircuit.num_input_vars "qiskit.circuit.QuantumCircuit.num_input_vars"), [`num_captured_vars`](#qiskit.circuit.QuantumCircuit.num_captured_vars "qiskit.circuit.QuantumCircuit.num_captured_vars") and [`num_declared_vars`](#qiskit.circuit.QuantumCircuit.num_declared_vars "qiskit.circuit.QuantumCircuit.num_declared_vars").
|
||
|
||
#### iter\_vars
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.iter_vars" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2246-L2256" signature="iter_vars()">
|
||
Get an iterable over all real-time classical variables in scope within this circuit.
|
||
|
||
This method will iterate over all variables in scope. For more fine-grained iterators, see [`iter_declared_vars()`](#qiskit.circuit.QuantumCircuit.iter_declared_vars "qiskit.circuit.QuantumCircuit.iter_declared_vars"), [`iter_input_vars()`](#qiskit.circuit.QuantumCircuit.iter_input_vars "qiskit.circuit.QuantumCircuit.iter_input_vars") and [`iter_captured_vars()`](#qiskit.circuit.QuantumCircuit.iter_captured_vars "qiskit.circuit.QuantumCircuit.iter_captured_vars").
|
||
|
||
**Return type**
|
||
|
||
[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.13)")\[[*Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var")]
|
||
</Function>
|
||
|
||
#### iter\_input\_vars
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.iter_input_vars" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2266-L2272" signature="iter_input_vars()">
|
||
Get an iterable over all real-time classical variables that are declared as inputs to this circuit scope. This excludes locally declared variables (see [`iter_declared_vars()`](#qiskit.circuit.QuantumCircuit.iter_declared_vars "qiskit.circuit.QuantumCircuit.iter_declared_vars")) and captured variables (see [`iter_captured_vars()`](#qiskit.circuit.QuantumCircuit.iter_captured_vars "qiskit.circuit.QuantumCircuit.iter_captured_vars")).
|
||
|
||
**Return type**
|
||
|
||
[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.13)")\[[*Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var")]
|
||
</Function>
|
||
|
||
#### iter\_captured\_vars
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.iter_captured_vars" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2274-L2280" signature="iter_captured_vars()">
|
||
Get an iterable over all real-time classical variables that are captured by this circuit scope from a containing scope. This excludes input variables (see [`iter_input_vars()`](#qiskit.circuit.QuantumCircuit.iter_input_vars "qiskit.circuit.QuantumCircuit.iter_input_vars")) and locally declared variables (see [`iter_declared_vars()`](#qiskit.circuit.QuantumCircuit.iter_declared_vars "qiskit.circuit.QuantumCircuit.iter_declared_vars")).
|
||
|
||
**Return type**
|
||
|
||
[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.13)")\[[*Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var")]
|
||
</Function>
|
||
|
||
#### iter\_declared\_vars
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.iter_declared_vars" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2258-L2264" signature="iter_declared_vars()">
|
||
Get an iterable over all real-time classical variables that are declared with automatic storage duration in this scope. This excludes input variables (see [`iter_input_vars()`](#qiskit.circuit.QuantumCircuit.iter_input_vars "qiskit.circuit.QuantumCircuit.iter_input_vars")) and captured variables (see [`iter_captured_vars()`](#qiskit.circuit.QuantumCircuit.iter_captured_vars "qiskit.circuit.QuantumCircuit.iter_captured_vars")).
|
||
|
||
**Return type**
|
||
|
||
[*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.13)")\[[*Var*](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.expr.Var")]
|
||
</Function>
|
||
|
||
<span id="circuit-adding-operations" />
|
||
|
||
## Adding operations to circuits
|
||
|
||
You can add anything that implements the [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") interface to a circuit as a single instruction, though most things you will want to add will be [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") or [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances.
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[Operations, instructions and gates](circuit#circuit-operations-instructions)**
|
||
|
||
The [`qiskit.circuit`](circuit#module-qiskit.circuit "qiskit.circuit")-level documentation on the different interfaces that Qiskit uses to define circuit-level instructions.
|
||
</Admonition>
|
||
|
||
<span id="circuit-append-compose" />
|
||
|
||
### Methods to add general operations
|
||
|
||
These are the base methods that handle adding any object, including user-defined ones, onto circuits.
|
||
|
||
| Method | When to use it |
|
||
| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") | Add an instruction as a single object onto a circuit. |
|
||
| [`_append()`](#qiskit.circuit.QuantumCircuit._append "qiskit.circuit.QuantumCircuit._append") | Same as [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append"), but a low-level interface that elides almost all error checking. |
|
||
| [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") | Inline the instructions from one circuit onto another. |
|
||
| [`tensor()`](#qiskit.circuit.QuantumCircuit.tensor "qiskit.circuit.QuantumCircuit.tensor") | Like [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose"), but strictly for joining circuits that act on disjoint qubits. |
|
||
|
||
[`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") has two main ways that you will add more operations onto a circuit. Which to use depends on whether you want to add your object as a single “instruction” ([`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append")), or whether you want to join the instructions from two circuits together ([`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose")).
|
||
|
||
A single instruction or operation appears as a single entry in the [`data`](#qiskit.circuit.QuantumCircuit.data "qiskit.circuit.QuantumCircuit.data") of the circuit, and as a single box when drawn in the circuit visualizers (see [`draw()`](#qiskit.circuit.QuantumCircuit.draw "qiskit.circuit.QuantumCircuit.draw")). A single instruction is the “unit” that a hardware backend might be defined in terms of (see [`Target`](qiskit.transpiler.Target "qiskit.transpiler.Target")). An [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") can come with a [`definition`](qiskit.circuit.Instruction#definition "qiskit.circuit.Instruction.definition"), which is one rule the transpiler (see [`qiskit.transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler")) will be able to fall back on to decompose it for hardware, if needed. An [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") that is not also an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") can only be decomposed if it has some associated high-level synthesis method registered for it (see [`qiskit.transpiler.passes.synthesis.plugin`](transpiler_synthesis_plugins#module-qiskit.transpiler.passes.synthesis.plugin "qiskit.transpiler.passes.synthesis.plugin")).
|
||
|
||
A [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") alone is not a single [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction"); it is rather more complicated, since it can, in general, represent a complete program with typed classical memory inputs and outputs, and control flow. Qiskit’s (and most hardware’s) data model does not yet have the concept of re-usable callable subroutines with virtual quantum operands. You can convert simple circuits that act only on qubits with unitary operations into a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") using [`to_gate()`](#qiskit.circuit.QuantumCircuit.to_gate "qiskit.circuit.QuantumCircuit.to_gate"), and simple circuits acting only on qubits and clbits into a [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") with [`to_instruction()`](#qiskit.circuit.QuantumCircuit.to_instruction "qiskit.circuit.QuantumCircuit.to_instruction").
|
||
|
||
When you have an [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation"), [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction"), or [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate"), add it to the circuit, specifying the qubit and clbit arguments with [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append").
|
||
|
||
#### append
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.append" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2430-L2533" signature="append(instruction, qargs=None, cargs=None, *, copy=True)">
|
||
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`](qiskit.circuit.Instruction "qiskit.circuit.Instruction"), and any non-[`Bit`](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit") specifiers (such as integer indices) will be resolved into the relevant instances.
|
||
|
||
If a [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.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*](qiskit.circuit.Operation "qiskit.circuit.Operation") *|*[*CircuitInstruction*](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")) – [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") instance to append, or a [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") with all its context.
|
||
* **qargs** (*Sequence\[QubitSpecifier] | None*) – specifiers of the [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")s to attach instruction to.
|
||
* **cargs** (*Sequence\[ClbitSpecifier] | None*) – specifiers of the [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")s to attach instruction to.
|
||
* **copy** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – if `True` (the default), then the incoming `instruction` is copied before adding it to the circuit if it contains symbolic parameters, so it can be safely mutated without affecting other circuits the same instruction might be in. If you are sure this instruction will not be in other circuits, you can set this `False` for a small speedup.
|
||
|
||
**Returns**
|
||
|
||
a handle to the [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")s that were actually added to the circuit.
|
||
|
||
**Return type**
|
||
|
||
[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the operation passed is not an instance of [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") .
|
||
</Function>
|
||
|
||
[`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") does quite substantial error checking to ensure that you cannot accidentally break the data model of [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"). If you are programmatically generating a circuit from known-good data, you can elide much of this error checking by using the fast-path appender [`_append()`](#qiskit.circuit.QuantumCircuit._append "qiskit.circuit.QuantumCircuit._append"), but at the risk that the caller is responsible for ensuring they are passing only valid data.
|
||
|
||
#### \_append
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit._append" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2550-L2618" signature="_append(instruction: CircuitInstruction, *, _standard_gate: bool) → CircuitInstruction" extraSignatures={["_append(instruction: Operation, qargs: Sequence[Qubit], cargs: Sequence[Clbit]) → Operation"]}>
|
||
Append an instruction to the end of the circuit, modifying the circuit in place.
|
||
|
||
<Admonition title="Warning" type="caution">
|
||
This is an internal fast-path function, and it is the responsibility of the caller to ensure that all the arguments are valid; there is no error checking here. In particular:
|
||
|
||
* all the qubits and clbits must already exist in the circuit and there can be no duplicates in the list.
|
||
* any control-flow operations or classically conditioned instructions must act only on variables present in the circuit.
|
||
* the circuit must not be within a control-flow builder context.
|
||
</Admonition>
|
||
|
||
<Admonition title="Note" type="note">
|
||
This function may be used by callers other than [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") when the caller is sure that all error-checking, broadcasting and scoping has already been performed, and the only reference to the circuit the instructions are being appended to is within that same function. In particular, it is not safe to call [`QuantumCircuit._append()`](#qiskit.circuit.QuantumCircuit._append "qiskit.circuit.QuantumCircuit._append") on a circuit that is received by a function argument. This is because [`QuantumCircuit._append()`](#qiskit.circuit.QuantumCircuit._append "qiskit.circuit.QuantumCircuit._append") will not recognize the scoping constructs of the control-flow builder interface.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
* **instruction** –
|
||
|
||
A complete well-formed [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") of the operation and its context to be added.
|
||
|
||
In the legacy compatibility form, this can be a bare [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation"), in which case `qargs` and `cargs` must be explicitly given.
|
||
|
||
* **qargs** – Legacy argument for qubits to attach the bare [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") to. Ignored if the first argument is in the preferential [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") form.
|
||
|
||
* **cargs** – Legacy argument for clbits to attach the bare [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") to. Ignored if the first argument is in the preferential [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction") form.
|
||
|
||
**Returns**
|
||
|
||
a handle to the instruction that was just added.
|
||
|
||
**Return type**
|
||
|
||
[CircuitInstruction](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction")
|
||
</Function>
|
||
|
||
In other cases, you may want to join two circuits together, applying the instructions from one circuit onto specified qubits and clbits on another circuit. This “inlining” operation is called [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") in Qiskit. [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") is, in general, more powerful than a [`to_instruction()`](#qiskit.circuit.QuantumCircuit.to_instruction "qiskit.circuit.QuantumCircuit.to_instruction")-plus-[`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") combination for joining two circuits, because it can also link typed classical data together, and allows for circuit control-flow operations to be joined onto another circuit.
|
||
|
||
The downsides to [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") are that it is a more complex operation that can involve more rewriting of the operand, and that it necessarily must move data from one circuit object to another. If you are building up a circuit for yourself and raw performance is a core goal, consider passing around your base circuit and having different parts of your algorithm write directly to the base circuit, rather than building a temporary layer circuit.
|
||
|
||
#### compose
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.compose" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1768-L2104" signature="compose(other, qubits=None, clbits=None, front=False, inplace=False, wrap=False, *, copy=True, var_remap=None, inline_captures=False)">
|
||
Apply the instructions from one circuit onto specified qubits and/or clbits on another.
|
||
|
||
<Admonition title="Note" type="note">
|
||
By default, this creates a new circuit object, leaving `self` untouched. For most uses of this function, it is far more efficient to set `inplace=True` and modify the base circuit in-place.
|
||
</Admonition>
|
||
|
||
When dealing with realtime variables ([`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") instances), there are two principal strategies for using [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose"):
|
||
|
||
1. The `other` circuit is treated as entirely additive, including its variables. The variables in `other` must be entirely distinct from those in `self` (use `var_remap` to help with this), and all variables in `other` will be declared anew in the output with matching input/capture/local scoping to how they are in `other`. This is generally what you want if you’re joining two unrelated circuits.
|
||
2. The `other` circuit was created as an exact extension to `self` to be inlined onto it, including acting on the existing variables in their states at the end of `self`. In this case, `other` should be created with all these variables to be inlined declared as “captures”, and then you can use `inline_captures=True` in this method to link them. This is generally what you want if you’re building up a circuit by defining layers on-the-fly, or rebuilding a circuit using layers taken from itself. You might find the `vars_mode="captures"` argument to [`copy_empty_like()`](#qiskit.circuit.QuantumCircuit.copy_empty_like "qiskit.circuit.QuantumCircuit.copy_empty_like") useful to create each layer’s base, in this case.
|
||
|
||
**Parameters**
|
||
|
||
* **other** ([*qiskit.circuit.Instruction*](qiskit.circuit.Instruction "qiskit.circuit.Instruction") *or*[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – (sub)circuit or instruction to compose onto self. If not a [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit"), this can be anything that [`append`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") will accept.
|
||
|
||
* **qubits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – qubits of self to compose onto.
|
||
|
||
* **clbits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – clbits of self to compose onto.
|
||
|
||
* **front** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – If `True`, front composition will be performed. This is not possible within control-flow builder context managers.
|
||
|
||
* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – If `True`, modify the object. Otherwise, return composed circuit.
|
||
|
||
* **copy** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – If `True` (the default), then the input is treated as shared, and any contained instructions will be copied, if they might need to be mutated in the future. You can set this to `False` if the input should be considered owned by the base circuit, in order to avoid unnecessary copies; in this case, it is not valid to use `other` afterward, and some instructions may have been mutated in place.
|
||
|
||
* **var\_remap** (*Mapping*) –
|
||
|
||
mapping to use to rewrite [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes in `other` as they are inlined into `self`. This can be used to avoid naming conflicts.
|
||
|
||
Both keys and values can be given as strings or direct [`expr.Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") instances. If a key is a string, it matches any [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") with the same name. If a value is a string, whenever a new key matches a it, a new [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") is created with the correct type. If a value is a [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var"), its `type` must exactly match that of the variable it is replacing.
|
||
|
||
* **inline\_captures** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) –
|
||
|
||
if `True`, then all “captured” [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") nodes in the `other` [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") are assumed to refer to variables already declared in `self` (as any input/capture/local type), and the uses in `other` will apply to the existing variables. If you want to build up a layer for an existing circuit to use with [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose"), you might find the `vars_mode="captures"` argument to [`copy_empty_like()`](#qiskit.circuit.QuantumCircuit.copy_empty_like "qiskit.circuit.QuantumCircuit.copy_empty_like") useful. Any remapping in `vars_remap` occurs before evaluating this variable inlining.
|
||
|
||
If this is `False` (the default), then all variables in `other` will be required to be distinct from those in `self`, and new declarations will be made for them.
|
||
|
||
* **wrap** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – If True, wraps the other circuit into a gate (or instruction, depending on whether it contains only unitary instructions) before composing it onto self. Rather than using this option, it is almost always better to manually control this yourself by using [`to_instruction()`](#qiskit.circuit.QuantumCircuit.to_instruction "qiskit.circuit.QuantumCircuit.to_instruction") or [`to_gate()`](#qiskit.circuit.QuantumCircuit.to_gate "qiskit.circuit.QuantumCircuit.to_gate"), and then call [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append").
|
||
|
||
**Returns**
|
||
|
||
the composed circuit (returns None if inplace==True).
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Raises**
|
||
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if no correct wire mapping can be made between the two circuits, such as if `other` is wider than `self`.
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.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()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test"), [`for_loop()`](#qiskit.circuit.QuantumCircuit.for_loop "qiskit.circuit.QuantumCircuit.for_loop") and [`while_loop()`](#qiskit.circuit.QuantumCircuit.while_loop "qiskit.circuit.QuantumCircuit.while_loop").
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.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**
|
||
|
||
```python
|
||
>>> lhs.compose(rhs, qubits=[3, 2], inplace=True)
|
||
```
|
||
|
||
```python
|
||
┌───┐ ┌─────┐ ┌───┐
|
||
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 ═══════════════════════
|
||
```
|
||
</Function>
|
||
|
||
If you are trying to join two circuits that will apply to completely disjoint qubits and clbits, [`tensor()`](#qiskit.circuit.QuantumCircuit.tensor "qiskit.circuit.QuantumCircuit.tensor") is a convenient wrapper around manually adding bit objects and calling [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose").
|
||
|
||
#### tensor
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.tensor" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2106-L2194" signature="tensor(other, inplace=False)">
|
||
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](/build/circuit-construction) for more information.
|
||
|
||
```python
|
||
┌────────┐ ┌─────┐ ┌─────┐
|
||
q_0: ┤ bottom ├ ⊗ q_0: ┤ top ├ = q_0: ─┤ top ├──
|
||
└────────┘ └─────┘ ┌┴─────┴─┐
|
||
q_1: ┤ bottom ├
|
||
└────────┘
|
||
```
|
||
|
||
**Parameters**
|
||
|
||
* **other** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The other circuit to tensor this circuit with.
|
||
* **inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – If `True`, modify the object. Otherwise return composed circuit.
|
||
|
||
**Return type**
|
||
|
||
[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.quantumcircuit.QuantumCircuit") | None
|
||
|
||
**Examples**
|
||
|
||
```python
|
||
from qiskit import QuantumCircuit
|
||
top = QuantumCircuit(1)
|
||
top.x(0);
|
||
bottom = QuantumCircuit(2)
|
||
bottom.cry(0.2, 0, 1);
|
||
tensored = bottom.tensor(top)
|
||
tensored.draw('mpl')
|
||
```
|
||
|
||
|
||
|
||
**Returns**
|
||
|
||
The tensored circuit (returns `None` if `inplace=True`).
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
As some rules of thumb:
|
||
|
||
* If you have a single [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation"), [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") or [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate"), you should definitely use [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") or [`_append()`](#qiskit.circuit.QuantumCircuit._append "qiskit.circuit.QuantumCircuit._append").
|
||
* If you have a [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") that represents a single atomic instruction for a larger circuit that you want to re-use, you probably want to call [`to_instruction()`](#qiskit.circuit.QuantumCircuit.to_instruction "qiskit.circuit.QuantumCircuit.to_instruction") or [`to_gate()`](#qiskit.circuit.QuantumCircuit.to_gate "qiskit.circuit.QuantumCircuit.to_gate"), and then apply the result of that to the circuit using [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append").
|
||
* If you have a [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") that represents a larger “layer” of another circuit, or contains typed classical variables or control flow, you should use [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") to merge it onto another circuit.
|
||
* [`tensor()`](#qiskit.circuit.QuantumCircuit.tensor "qiskit.circuit.QuantumCircuit.tensor") is wanted far more rarely than either [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") or [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose"). Internally, it is mostly a wrapper around [`add_bits()`](#qiskit.circuit.QuantumCircuit.add_bits "qiskit.circuit.QuantumCircuit.add_bits") and [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose").
|
||
|
||
Some potential pitfalls to beware of:
|
||
|
||
* Even if you re-use a custom [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") during circuit construction, the transpiler will generally have to “unroll” each invocation of it to its inner decomposition before beginning work on it. This should not prevent you from using the [`to_instruction()`](#qiskit.circuit.QuantumCircuit.to_instruction "qiskit.circuit.QuantumCircuit.to_instruction")-plus-[`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") pattern, as the transpiler will improve in this regard over time.
|
||
* [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") will, by default, produce a new circuit for backwards compatibility. This is more expensive, and not usually what you want, so you should set `inplace=True`.
|
||
* Both [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") and [`compose()`](#qiskit.circuit.QuantumCircuit.compose "qiskit.circuit.QuantumCircuit.compose") (but not [`_append()`](#qiskit.circuit.QuantumCircuit._append "qiskit.circuit.QuantumCircuit._append")) have a `copy` keyword argument that defaults to `True`. In these cases, the incoming [`Operation`](qiskit.circuit.Operation "qiskit.circuit.Operation") instances will be copied if Qiskit detects that the objects have mutability about them (such as taking gate parameters). If you are sure that you will not re-use the objects again in other places, you should set `copy=False` to prevent this copying, which can be a substantial speed-up for large objects.
|
||
|
||
### Methods to add standard instructions
|
||
|
||
The [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") class has helper methods to add many of the Qiskit standard-library instructions and gates onto a circuit. These are generally equivalent to manually constructing an instance of the relevent [`qiskit.circuit.library`](circuit_library#module-qiskit.circuit.library "qiskit.circuit.library") object, then passing that to [`append()`](#qiskit.circuit.QuantumCircuit.append "qiskit.circuit.QuantumCircuit.append") with the remaining arguments placed into the `qargs` and `cargs` fields as appropriate.
|
||
|
||
The following methods apply special non-unitary [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") operations to the circuit:
|
||
|
||
| [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") method | [`qiskit.circuit`](circuit#module-qiskit.circuit "qiskit.circuit") [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") |
|
||
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| [`barrier()`](#qiskit.circuit.QuantumCircuit.barrier "qiskit.circuit.QuantumCircuit.barrier") | [`Barrier`](circuit#qiskit.circuit.Barrier "qiskit.circuit.Barrier") |
|
||
| [`delay()`](#qiskit.circuit.QuantumCircuit.delay "qiskit.circuit.QuantumCircuit.delay") | [`Delay`](circuit#qiskit.circuit.Delay "qiskit.circuit.Delay") |
|
||
| [`initialize()`](#qiskit.circuit.QuantumCircuit.initialize "qiskit.circuit.QuantumCircuit.initialize") | [`Initialize`](qiskit.circuit.library.Initialize "qiskit.circuit.library.Initialize") |
|
||
| [`measure()`](#qiskit.circuit.QuantumCircuit.measure "qiskit.circuit.QuantumCircuit.measure") | [`Measure`](circuit#qiskit.circuit.Measure "qiskit.circuit.Measure") |
|
||
| [`reset()`](#qiskit.circuit.QuantumCircuit.reset "qiskit.circuit.QuantumCircuit.reset") | [`Reset`](circuit#qiskit.circuit.Reset "qiskit.circuit.Reset") |
|
||
| [`store()`](#qiskit.circuit.QuantumCircuit.store "qiskit.circuit.QuantumCircuit.store") | [`Store`](circuit#qiskit.circuit.Store "qiskit.circuit.Store") |
|
||
|
||
These methods apply uncontrolled unitary [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances to the circuit:
|
||
|
||
| [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") method | [`qiskit.circuit.library`](circuit_library#module-qiskit.circuit.library "qiskit.circuit.library") [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") |
|
||
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| [`dcx()`](#qiskit.circuit.QuantumCircuit.dcx "qiskit.circuit.QuantumCircuit.dcx") | [`DCXGate`](qiskit.circuit.library.DCXGate "qiskit.circuit.library.DCXGate") |
|
||
| [`ecr()`](#qiskit.circuit.QuantumCircuit.ecr "qiskit.circuit.QuantumCircuit.ecr") | [`ECRGate`](qiskit.circuit.library.ECRGate "qiskit.circuit.library.ECRGate") |
|
||
| [`h()`](#qiskit.circuit.QuantumCircuit.h "qiskit.circuit.QuantumCircuit.h") | [`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate") |
|
||
| [`id()`](#qiskit.circuit.QuantumCircuit.id "qiskit.circuit.QuantumCircuit.id") | [`IGate`](qiskit.circuit.library.IGate "qiskit.circuit.library.IGate") |
|
||
| [`iswap()`](#qiskit.circuit.QuantumCircuit.iswap "qiskit.circuit.QuantumCircuit.iswap") | [`iSwapGate`](qiskit.circuit.library.iSwapGate "qiskit.circuit.library.iSwapGate") |
|
||
| [`ms()`](#qiskit.circuit.QuantumCircuit.ms "qiskit.circuit.QuantumCircuit.ms") | [`MSGate`](qiskit.circuit.library.MSGate "qiskit.circuit.library.MSGate") |
|
||
| [`p()`](#qiskit.circuit.QuantumCircuit.p "qiskit.circuit.QuantumCircuit.p") | [`PhaseGate`](qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate") |
|
||
| [`pauli()`](#qiskit.circuit.QuantumCircuit.pauli "qiskit.circuit.QuantumCircuit.pauli") | [`PauliGate`](qiskit.circuit.library.PauliGate "qiskit.circuit.library.PauliGate") |
|
||
| [`prepare_state()`](#qiskit.circuit.QuantumCircuit.prepare_state "qiskit.circuit.QuantumCircuit.prepare_state") | [`StatePreparation`](qiskit.circuit.library.StatePreparation "qiskit.circuit.library.StatePreparation") |
|
||
| [`r()`](#qiskit.circuit.QuantumCircuit.r "qiskit.circuit.QuantumCircuit.r") | [`RGate`](qiskit.circuit.library.RGate "qiskit.circuit.library.RGate") |
|
||
| [`rcccx()`](#qiskit.circuit.QuantumCircuit.rcccx "qiskit.circuit.QuantumCircuit.rcccx") | [`RC3XGate`](qiskit.circuit.library.RC3XGate "qiskit.circuit.library.RC3XGate") |
|
||
| [`rccx()`](#qiskit.circuit.QuantumCircuit.rccx "qiskit.circuit.QuantumCircuit.rccx") | [`RCCXGate`](qiskit.circuit.library.RCCXGate "qiskit.circuit.library.RCCXGate") |
|
||
| [`rv()`](#qiskit.circuit.QuantumCircuit.rv "qiskit.circuit.QuantumCircuit.rv") | [`RVGate`](qiskit.circuit.library.RVGate "qiskit.circuit.library.RVGate") |
|
||
| [`rx()`](#qiskit.circuit.QuantumCircuit.rx "qiskit.circuit.QuantumCircuit.rx") | [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate") |
|
||
| [`rxx()`](#qiskit.circuit.QuantumCircuit.rxx "qiskit.circuit.QuantumCircuit.rxx") | [`RXXGate`](qiskit.circuit.library.RXXGate "qiskit.circuit.library.RXXGate") |
|
||
| [`ry()`](#qiskit.circuit.QuantumCircuit.ry "qiskit.circuit.QuantumCircuit.ry") | [`RYGate`](qiskit.circuit.library.RYGate "qiskit.circuit.library.RYGate") |
|
||
| [`ryy()`](#qiskit.circuit.QuantumCircuit.ryy "qiskit.circuit.QuantumCircuit.ryy") | [`RYYGate`](qiskit.circuit.library.RYYGate "qiskit.circuit.library.RYYGate") |
|
||
| [`rz()`](#qiskit.circuit.QuantumCircuit.rz "qiskit.circuit.QuantumCircuit.rz") | [`RZGate`](qiskit.circuit.library.RZGate "qiskit.circuit.library.RZGate") |
|
||
| [`rzx()`](#qiskit.circuit.QuantumCircuit.rzx "qiskit.circuit.QuantumCircuit.rzx") | [`RZXGate`](qiskit.circuit.library.RZXGate "qiskit.circuit.library.RZXGate") |
|
||
| [`rzz()`](#qiskit.circuit.QuantumCircuit.rzz "qiskit.circuit.QuantumCircuit.rzz") | [`RZZGate`](qiskit.circuit.library.RZZGate "qiskit.circuit.library.RZZGate") |
|
||
| [`s()`](#qiskit.circuit.QuantumCircuit.s "qiskit.circuit.QuantumCircuit.s") | [`SGate`](qiskit.circuit.library.SGate "qiskit.circuit.library.SGate") |
|
||
| [`sdg()`](#qiskit.circuit.QuantumCircuit.sdg "qiskit.circuit.QuantumCircuit.sdg") | [`SdgGate`](qiskit.circuit.library.SdgGate "qiskit.circuit.library.SdgGate") |
|
||
| [`swap()`](#qiskit.circuit.QuantumCircuit.swap "qiskit.circuit.QuantumCircuit.swap") | [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate") |
|
||
| [`sx()`](#qiskit.circuit.QuantumCircuit.sx "qiskit.circuit.QuantumCircuit.sx") | [`SXGate`](qiskit.circuit.library.SXGate "qiskit.circuit.library.SXGate") |
|
||
| [`sxdg()`](#qiskit.circuit.QuantumCircuit.sxdg "qiskit.circuit.QuantumCircuit.sxdg") | [`SXdgGate`](qiskit.circuit.library.SXdgGate "qiskit.circuit.library.SXdgGate") |
|
||
| [`t()`](#qiskit.circuit.QuantumCircuit.t "qiskit.circuit.QuantumCircuit.t") | [`TGate`](qiskit.circuit.library.TGate "qiskit.circuit.library.TGate") |
|
||
| [`tdg()`](#qiskit.circuit.QuantumCircuit.tdg "qiskit.circuit.QuantumCircuit.tdg") | [`TdgGate`](qiskit.circuit.library.TdgGate "qiskit.circuit.library.TdgGate") |
|
||
| [`u()`](#qiskit.circuit.QuantumCircuit.u "qiskit.circuit.QuantumCircuit.u") | [`UGate`](qiskit.circuit.library.UGate "qiskit.circuit.library.UGate") |
|
||
| [`unitary()`](#qiskit.circuit.QuantumCircuit.unitary "qiskit.circuit.QuantumCircuit.unitary") | [`UnitaryGate`](qiskit.circuit.library.UnitaryGate "qiskit.circuit.library.UnitaryGate") |
|
||
| [`x()`](#qiskit.circuit.QuantumCircuit.x "qiskit.circuit.QuantumCircuit.x") | [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") |
|
||
| [`y()`](#qiskit.circuit.QuantumCircuit.y "qiskit.circuit.QuantumCircuit.y") | [`YGate`](qiskit.circuit.library.YGate "qiskit.circuit.library.YGate") |
|
||
| [`z()`](#qiskit.circuit.QuantumCircuit.z "qiskit.circuit.QuantumCircuit.z") | [`ZGate`](qiskit.circuit.library.ZGate "qiskit.circuit.library.ZGate") |
|
||
|
||
The following methods apply [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") instances that are also controlled gates, so are direct subclasses of [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate"):
|
||
|
||
| [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") method | [`qiskit.circuit.library`](circuit_library#module-qiskit.circuit.library "qiskit.circuit.library") [`ControlledGate`](qiskit.circuit.ControlledGate "qiskit.circuit.ControlledGate") |
|
||
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| [`ccx()`](#qiskit.circuit.QuantumCircuit.ccx "qiskit.circuit.QuantumCircuit.ccx") | [`CCXGate`](qiskit.circuit.library.CCXGate "qiskit.circuit.library.CCXGate") |
|
||
| [`ccz()`](#qiskit.circuit.QuantumCircuit.ccz "qiskit.circuit.QuantumCircuit.ccz") | [`CCZGate`](qiskit.circuit.library.CCZGate "qiskit.circuit.library.CCZGate") |
|
||
| [`ch()`](#qiskit.circuit.QuantumCircuit.ch "qiskit.circuit.QuantumCircuit.ch") | [`CHGate`](qiskit.circuit.library.CHGate "qiskit.circuit.library.CHGate") |
|
||
| [`cp()`](#qiskit.circuit.QuantumCircuit.cp "qiskit.circuit.QuantumCircuit.cp") | [`CPhaseGate`](qiskit.circuit.library.CPhaseGate "qiskit.circuit.library.CPhaseGate") |
|
||
| [`crx()`](#qiskit.circuit.QuantumCircuit.crx "qiskit.circuit.QuantumCircuit.crx") | [`CRXGate`](qiskit.circuit.library.CRXGate "qiskit.circuit.library.CRXGate") |
|
||
| [`cry()`](#qiskit.circuit.QuantumCircuit.cry "qiskit.circuit.QuantumCircuit.cry") | [`CRYGate`](qiskit.circuit.library.CRYGate "qiskit.circuit.library.CRYGate") |
|
||
| [`crz()`](#qiskit.circuit.QuantumCircuit.crz "qiskit.circuit.QuantumCircuit.crz") | [`CRZGate`](qiskit.circuit.library.CRZGate "qiskit.circuit.library.CRZGate") |
|
||
| [`cs()`](#qiskit.circuit.QuantumCircuit.cs "qiskit.circuit.QuantumCircuit.cs") | [`CSGate`](qiskit.circuit.library.CSGate "qiskit.circuit.library.CSGate") |
|
||
| [`csdg()`](#qiskit.circuit.QuantumCircuit.csdg "qiskit.circuit.QuantumCircuit.csdg") | [`CSdgGate`](qiskit.circuit.library.CSdgGate "qiskit.circuit.library.CSdgGate") |
|
||
| [`cswap()`](#qiskit.circuit.QuantumCircuit.cswap "qiskit.circuit.QuantumCircuit.cswap") | [`CSwapGate`](qiskit.circuit.library.CSwapGate "qiskit.circuit.library.CSwapGate") |
|
||
| [`csx()`](#qiskit.circuit.QuantumCircuit.csx "qiskit.circuit.QuantumCircuit.csx") | [`CSXGate`](qiskit.circuit.library.CSXGate "qiskit.circuit.library.CSXGate") |
|
||
| [`cu()`](#qiskit.circuit.QuantumCircuit.cu "qiskit.circuit.QuantumCircuit.cu") | [`CUGate`](qiskit.circuit.library.CUGate "qiskit.circuit.library.CUGate") |
|
||
| [`cx()`](#qiskit.circuit.QuantumCircuit.cx "qiskit.circuit.QuantumCircuit.cx") | [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.CXGate") |
|
||
| [`cy()`](#qiskit.circuit.QuantumCircuit.cy "qiskit.circuit.QuantumCircuit.cy") | [`CYGate`](qiskit.circuit.library.CYGate "qiskit.circuit.library.CYGate") |
|
||
| [`cz()`](#qiskit.circuit.QuantumCircuit.cz "qiskit.circuit.QuantumCircuit.cz") | [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.CZGate") |
|
||
|
||
Finally, these methods apply particular generalized multiply controlled gates to the circuit, often with eager syntheses. They are listed in terms of the *base* gate they are controlling, since their exact output is often a synthesized version of a gate.
|
||
|
||
| [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") method | Base [`qiskit.circuit.library`](circuit_library#module-qiskit.circuit.library "qiskit.circuit.library") [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") |
|
||
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| [`mcp()`](#qiskit.circuit.QuantumCircuit.mcp "qiskit.circuit.QuantumCircuit.mcp") | [`PhaseGate`](qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate") |
|
||
| [`mcrx()`](#qiskit.circuit.QuantumCircuit.mcrx "qiskit.circuit.QuantumCircuit.mcrx") | [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.RXGate") |
|
||
| [`mcry()`](#qiskit.circuit.QuantumCircuit.mcry "qiskit.circuit.QuantumCircuit.mcry") | [`RYGate`](qiskit.circuit.library.RYGate "qiskit.circuit.library.RYGate") |
|
||
| [`mcrz()`](#qiskit.circuit.QuantumCircuit.mcrz "qiskit.circuit.QuantumCircuit.mcrz") | [`RZGate`](qiskit.circuit.library.RZGate "qiskit.circuit.library.RZGate") |
|
||
| [`mcx()`](#qiskit.circuit.QuantumCircuit.mcx "qiskit.circuit.QuantumCircuit.mcx") | [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") |
|
||
|
||
The rest of this section is the API listing of all the individual methods; the tables above are summaries whose links will jump you to the correct place.
|
||
|
||
#### barrier
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.barrier" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4402-L4427" signature="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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – The string label of the barrier.
|
||
|
||
**Returns**
|
||
|
||
handle to the added instructions.
|
||
|
||
**Return type**
|
||
|
||
[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### ccx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.ccx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5357-L5394" signature="ccx(control_qubit1, control_qubit2, target_qubit, ctrl_state=None)">
|
||
Apply [`CCXGate`](qiskit.circuit.library.CCXGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### ccz
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.ccz" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5583-L5623" signature="ccz(control_qubit1, control_qubit2, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CCZGate`](qiskit.circuit.library.CCZGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### ch
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.ch" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4468-L4503" signature="ch(control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CHGate`](qiskit.circuit.library.CHGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### cp
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cp" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4549-L4586" signature="cp(theta, control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CPhaseGate`](qiskit.circuit.library.CPhaseGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### crx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.crx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4729-L4766" signature="crx(theta, control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CRXGate`](qiskit.circuit.library.CRXGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### cry
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cry" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4802-L4839" signature="cry(theta, control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CRYGate`](qiskit.circuit.library.CRYGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### crz
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.crz" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4872-L4909" signature="crz(theta, control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CRZGate`](qiskit.circuit.library.CRZGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### cs
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cs" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4984-L5019" signature="cs(control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CSGate`](qiskit.circuit.library.CSGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### csdg
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.csdg" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5021-L5056" signature="csdg(control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CSdgGate`](qiskit.circuit.library.CSdgGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### cswap
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cswap" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5088-L5128" signature="cswap(control_qubit, target_qubit1, target_qubit2, label=None, ctrl_state=None)">
|
||
Apply [`CSwapGate`](qiskit.circuit.library.CSwapGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### csx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.csx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5156-L5191" signature="csx(control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CSXGate`](qiskit.circuit.library.CSXGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### cu
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cu" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5241-L5287" signature="cu(theta, phi, lam, gamma, control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CUGate`](qiskit.circuit.library.CUGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### cx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5303-L5341" signature="cx(control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CXGate`](qiskit.circuit.library.CXGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### cy
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cy" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5493-L5531" signature="cy(control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CYGate`](qiskit.circuit.library.CYGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### cz
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cz" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5546-L5581" signature="cz(control_qubit, target_qubit, label=None, ctrl_state=None)">
|
||
Apply [`CZGate`](qiskit.circuit.library.CZGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### dcx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.dcx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5343-L5355" signature="dcx(qubit1, qubit2)">
|
||
Apply [`DCXGate`](qiskit.circuit.library.DCXGate "qiskit.circuit.library.DCXGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
* **qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### delay
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.delay" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4429-L4453" signature="delay(duration, qarg=None, unit='dt')">
|
||
Apply [`Delay`](circuit#qiskit.circuit.Delay "qiskit.circuit.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*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *or*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *or*[*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.ParameterExpression")) – duration of the delay.
|
||
* **qarg** (*Object*) – qubit argument to apply this delay.
|
||
* **unit** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if arguments have bad format.
|
||
</Function>
|
||
|
||
#### ecr
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.ecr" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4945-L4956" signature="ecr(qubit1, qubit2)">
|
||
Apply [`ECRGate`](qiskit.circuit.library.ECRGate "qiskit.circuit.library.ECRGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubits to apply the gate to.
|
||
* **qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubits to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### h
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.h" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4455-L4466" signature="h(qubit)">
|
||
Apply [`HGate`](qiskit.circuit.library.HGate "qiskit.circuit.library.HGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### id
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.id" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4505-L4516" signature="id(qubit)">
|
||
Apply [`IGate`](qiskit.circuit.library.IGate "qiskit.circuit.library.IGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### initialize
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.initialize" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5757-L5866" signature="initialize(params, qubits=None, normalize=False)">
|
||
Initialize qubits in a specific state.
|
||
|
||
Qubit initialization is done by first resetting the qubits to $|0\rangle$ followed by calling [`StatePreparation`](qiskit.circuit.library.StatePreparation "qiskit.circuit.library.StatePreparation") class to prepare the qubits in a specified state. Both these steps are included in the [`Initialize`](qiskit.circuit.library.Initialize "qiskit.circuit.library.Initialize") instruction.
|
||
|
||
**Parameters**
|
||
|
||
* **params** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *| Sequence\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.13)")*] |* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) –
|
||
|
||
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()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – 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}$.
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
┌──────────────────────────────┐
|
||
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()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.Statevector.from_label").
|
||
|
||
```python
|
||
import numpy as np
|
||
from qiskit import QuantumCircuit
|
||
|
||
circuit = QuantumCircuit(2)
|
||
circuit.initialize('01', circuit.qubits)
|
||
circuit.draw()
|
||
```
|
||
|
||
output:
|
||
|
||
```python
|
||
┌──────────────────┐
|
||
q_0: ┤0 ├
|
||
│ Initialize(0,1) │
|
||
q_1: ┤1 ├
|
||
└──────────────────┘
|
||
```
|
||
|
||
Initialize two qubits from an array of complex amplitudes.
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
┌────────────────────────────────────┐
|
||
q_0: ┤0 ├
|
||
│ Initialize(0,0.70711,-0.70711j,0) │
|
||
q_1: ┤1 ├
|
||
└────────────────────────────────────┘
|
||
```
|
||
</Function>
|
||
|
||
#### iswap
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.iswap" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5075-L5086" signature="iswap(qubit1, qubit2)">
|
||
Apply [`iSwapGate`](qiskit.circuit.library.iSwapGate "qiskit.circuit.library.iSwapGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubits to apply the gate to.
|
||
* **qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubits to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### mcp
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.mcp" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4588-L4618" signature="mcp(lam, control_qubits, target_qubit, ctrl_state=None)">
|
||
Apply [`MCPhaseGate`](qiskit.circuit.library.MCPhaseGate "qiskit.circuit.library.MCPhaseGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **lam** (*ParameterValueType*) – The angle of the rotation.
|
||
* **control\_qubits** (*Sequence\[QubitSpecifier]*) – The qubits used as the controls.
|
||
* **target\_qubit** (*QubitSpecifier*) – The qubit(s) targeted by the gate.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### mcrx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.mcrx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/library/standard_gates/multi_control_rotation_gates.py#L208-L269" signature="mcrx(theta, q_controls, q_target, use_basis_gates=False)">
|
||
Apply Multiple-Controlled X rotation gate
|
||
|
||
**Parameters**
|
||
|
||
* **self** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The QuantumCircuit object to apply the mcrx gate on.
|
||
* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – angle theta
|
||
* **q\_controls** ([*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*(*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*)*) – The list of control qubits
|
||
* **q\_target** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – The target qubit
|
||
* **use\_basis\_gates** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – use p, u, cx
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – parameter errors
|
||
</Function>
|
||
|
||
#### mcry
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.mcry" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/library/standard_gates/multi_control_rotation_gates.py#L272-L349" signature="mcry(theta, q_controls, q_target, q_ancillae=None, mode=None, use_basis_gates=False)">
|
||
Apply Multiple-Controlled Y rotation gate
|
||
|
||
**Parameters**
|
||
|
||
* **self** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The QuantumCircuit object to apply the mcry gate on.
|
||
* **theta** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – angle theta
|
||
* **q\_controls** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*(*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*)*) – The list of control qubits
|
||
* **q\_target** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – The target qubit
|
||
* **q\_ancillae** ([*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") *or*[*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*(*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*)*) – The list of ancillary qubits.
|
||
* **mode** (*string*) – The implementation mode to use
|
||
* **use\_basis\_gates** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – use p, u, cx
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – parameter errors
|
||
</Function>
|
||
|
||
#### mcrz
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.mcrz" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/library/standard_gates/multi_control_rotation_gates.py#L352-L400" signature="mcrz(lam, q_controls, q_target, use_basis_gates=False)">
|
||
Apply Multiple-Controlled Z rotation gate
|
||
|
||
**Parameters**
|
||
|
||
* **self** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The QuantumCircuit object to apply the mcrz gate on.
|
||
* **lam** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – angle lambda
|
||
* **q\_controls** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*(*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*)*) – The list of control qubits
|
||
* **q\_target** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")) – The target qubit
|
||
* **use\_basis\_gates** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – use p, u, cx
|
||
|
||
**Raises**
|
||
|
||
[**QiskitError**](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") – parameter errors
|
||
</Function>
|
||
|
||
#### mcx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.mcx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5396-L5478" signature="mcx(control_qubits, target_qubit, ancilla_qubits=None, mode='noancilla', ctrl_state=None)">
|
||
Apply [`MCXGate`](qiskit.circuit.library.MCXGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – The choice of mode, explained further above.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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.
|
||
|
||
**Raises**
|
||
|
||
* [**ValueError**](https://docs.python.org/3/library/exceptions.html#ValueError "(in Python v3.13)") – if the given mode is not known, or if too few ancilla qubits are passed.
|
||
* [**AttributeError**](https://docs.python.org/3/library/exceptions.html#AttributeError "(in Python v3.13)") – if no ancilla qubits are passed, but some are needed.
|
||
|
||
**Return type**
|
||
|
||
[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### measure
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.measure" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3830-L3905" signature="measure(qubit, cbit)">
|
||
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*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – qubit(s) to measure.
|
||
* **cbit** ([*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.classicalregister.Clbit") *|*[*ClassicalRegister*](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.classicalregister.ClassicalRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.classicalregister.Clbit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – classical bit(s) to place the measurement result(s) in.
|
||
|
||
**Returns**
|
||
|
||
handle to the added instructions.
|
||
|
||
**Return type**
|
||
|
||
[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.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):
|
||
|
||
```python
|
||
from qiskit import QuantumCircuit
|
||
circuit = QuantumCircuit(1, 1)
|
||
circuit.h(0)
|
||
circuit.measure(0, 0)
|
||
circuit.draw()
|
||
```
|
||
|
||
```python
|
||
┌───┐┌─┐
|
||
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:
|
||
|
||
```python
|
||
circuit = QuantumCircuit(2, 2)
|
||
circuit.measure([0,1], [0,1])
|
||
```
|
||
|
||
```python
|
||
circuit = QuantumCircuit(2, 2)
|
||
circuit.measure(0, 0)
|
||
circuit.measure(1, 1)
|
||
```
|
||
|
||
Instead of lists, you can use [`QuantumRegister`](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.QuantumRegister") and [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") under the same logic.
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
circuit = QuantumCircuit(qreg, creg)
|
||
circuit.measure(qreg[0], creg[0])
|
||
circuit.measure(qreg[1], creg[1])
|
||
```
|
||
</Function>
|
||
|
||
#### ms
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.ms" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4518-L4533" signature="ms(theta, qubits)">
|
||
Apply [`MSGate`](qiskit.circuit.library.MSGate "qiskit.circuit.library.MSGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The angle of the rotation.
|
||
* **qubits** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]]*) – The qubits to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### p
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.p" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4535-L4547" signature="p(theta, qubit)">
|
||
Apply [`PhaseGate`](qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – THe angle of the rotation.
|
||
* **qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### pauli
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.pauli" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5625-L5641" signature="pauli(pauli_string, qubits)">
|
||
Apply [`PauliGate`](qiskit.circuit.library.PauliGate "qiskit.circuit.library.PauliGate").
|
||
|
||
**Parameters**
|
||
|
||
* **pauli\_string** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – A string representing the Pauli operator to apply, e.g. ‘XX’.
|
||
* **qubits** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]]*) – The qubits to apply this gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### prepare\_state
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.prepare_state" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5643-L5755" signature="prepare_state(state, qubits=None, label=None, normalize=False)">
|
||
Prepare qubits in a specific state.
|
||
|
||
This class implements a state preparing unitary. Unlike [`initialize()`](#qiskit.circuit.QuantumCircuit.initialize "qiskit.circuit.QuantumCircuit.initialize") it does not reset the qubits first.
|
||
|
||
**Parameters**
|
||
|
||
* **state** ([*Statevector*](qiskit.quantum_info.Statevector "qiskit.quantum_info.Statevector") *| Sequence\[*[*complex*](https://docs.python.org/3/library/functions.html#complex "(in Python v3.13)")*] |* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) –
|
||
|
||
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()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – An optional label for the gate
|
||
|
||
* **normalize** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to normalize an input array to a unit vector.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instruction that was just initialized
|
||
|
||
**Return type**
|
||
|
||
[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
|
||
**Examples**
|
||
|
||
Prepare a qubit in the state $(|0\rangle - |1\rangle) / \sqrt{2}$.
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
┌─────────────────────────────────────┐
|
||
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()`](qiskit.quantum_info.Statevector#from_label "qiskit.quantum_info.Statevector.from_label").
|
||
|
||
```python
|
||
import numpy as np
|
||
from qiskit import QuantumCircuit
|
||
|
||
circuit = QuantumCircuit(2)
|
||
circuit.prepare_state('01', circuit.qubits)
|
||
circuit.draw()
|
||
```
|
||
|
||
output:
|
||
|
||
```python
|
||
┌─────────────────────────┐
|
||
q_0: ┤0 ├
|
||
│ State Preparation(0,1) │
|
||
q_1: ┤1 ├
|
||
└─────────────────────────┘
|
||
```
|
||
|
||
Initialize two qubits from an array of complex amplitudes .. code-block:
|
||
|
||
```python
|
||
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:
|
||
|
||
```python
|
||
┌───────────────────────────────────────────┐
|
||
q_0: ┤0 ├
|
||
│ State Preparation(0,0.70711,-0.70711j,0) │
|
||
q_1: ┤1 ├
|
||
└───────────────────────────────────────────┘
|
||
```
|
||
</Function>
|
||
|
||
#### r
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.r" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4620-L4635" signature="r(theta, phi, qubit)">
|
||
Apply [`RGate`](qiskit.circuit.library.RGate "qiskit.circuit.library.RGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The angle of the rotation.
|
||
* **phi** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The angle of the axis of rotation in the x-y plane.
|
||
* **qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### rcccx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.rcccx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4686-L4710" signature="rcccx(control_qubit1, control_qubit2, control_qubit3, target_qubit)">
|
||
Apply [`RC3XGate`](qiskit.circuit.library.RC3XGate "qiskit.circuit.library.RC3XGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **control\_qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) used as the first control.
|
||
* **control\_qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) used as the second control.
|
||
* **control\_qubit3** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) used as the third control.
|
||
* **target\_qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) targeted by the gate.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### rccx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.rccx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4664-L4684" signature="rccx(control_qubit1, control_qubit2, target_qubit)">
|
||
Apply [`RCCXGate`](qiskit.circuit.library.RCCXGate "qiskit.circuit.library.RCCXGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **control\_qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) used as the first control.
|
||
* **control\_qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) used as the second control.
|
||
* **target\_qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) targeted by the gate.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### reset
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.reset" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3786-L3797" signature="reset(qubit)">
|
||
Reset the quantum bit(s) to their default state.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – qubit(s) to reset.
|
||
|
||
**Returns**
|
||
|
||
handle to the added instruction.
|
||
|
||
**Return type**
|
||
|
||
[qiskit.circuit.InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### rv
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.rv" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4637-L4662" signature="rv(vx, vy, vz, qubit)">
|
||
Apply [`RVGate`](qiskit.circuit.library.RVGate "qiskit.circuit.library.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*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – x-component of the rotation axis.
|
||
* **vy** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – y-component of the rotation axis.
|
||
* **vz** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – z-component of the rotation axis.
|
||
* **qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### rx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.rx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4712-L4727" signature="rx(theta, qubit, label=None)">
|
||
Apply [`RXGate`](qiskit.circuit.library.RXGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### rxx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.rxx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4768-L4783" signature="rxx(theta, qubit1, qubit2)">
|
||
Apply [`RXXGate`](qiskit.circuit.library.RXXGate "qiskit.circuit.library.RXXGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The angle of the rotation.
|
||
* **qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
* **qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### ry
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.ry" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4785-L4800" signature="ry(theta, qubit, label=None)">
|
||
Apply [`RYGate`](qiskit.circuit.library.RYGate "qiskit.circuit.library.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### ryy
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.ryy" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4841-L4856" signature="ryy(theta, qubit1, qubit2)">
|
||
Apply [`RYYGate`](qiskit.circuit.library.RYYGate "qiskit.circuit.library.RYYGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The rotation angle of the gate.
|
||
* **qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
* **qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### rz
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.rz" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4858-L4870" signature="rz(phi, qubit)">
|
||
Apply [`RZGate`](qiskit.circuit.library.RZGate "qiskit.circuit.library.RZGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **phi** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The rotation angle of the gate.
|
||
* **qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### rzx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.rzx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4911-L4926" signature="rzx(theta, qubit1, qubit2)">
|
||
Apply [`RZXGate`](qiskit.circuit.library.RZXGate "qiskit.circuit.library.RZXGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The rotation angle of the gate.
|
||
* **qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
* **qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### rzz
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.rzz" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4928-L4943" signature="rzz(theta, qubit1, qubit2)">
|
||
Apply [`RZZGate`](qiskit.circuit.library.RZZGate "qiskit.circuit.library.RZZGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The rotation angle of the gate.
|
||
* **qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
* **qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### s
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.s" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4958-L4969" signature="s(qubit)">
|
||
Apply [`SGate`](qiskit.circuit.library.SGate "qiskit.circuit.library.SGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### sdg
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.sdg" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L4971-L4982" signature="sdg(qubit)">
|
||
Apply [`SdgGate`](qiskit.circuit.library.SdgGate "qiskit.circuit.library.SdgGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### store
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.store" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3799-L3828" signature="store(lvalue, rvalue, /)">
|
||
Store the result of the given real-time classical expression `rvalue` in the memory location defined by `lvalue`.
|
||
|
||
Typically `lvalue` will be a [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") node and `rvalue` will be some [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") to write into it, but anything that [`expr.lift()`](circuit_classical#qiskit.circuit.classical.expr.lift "qiskit.circuit.classical.expr.lift") can raise to an [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") is permissible in both places, and it will be called on them.
|
||
|
||
**Parameters**
|
||
|
||
* **lvalue** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.13)")) – a valid specifier for a memory location in the circuit. This will typically be a [`Var`](circuit_classical#qiskit.circuit.classical.expr.Var "qiskit.circuit.classical.expr.Var") node, but you can also write to [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit") or [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") memory locations if your hardware supports it. The memory location must already be present in the circuit.
|
||
* **rvalue** ([*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.13)")) – a real-time classical expression whose result should be written into the given memory location.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`Store`](circuit#qiskit.circuit.Store "qiskit.circuit.Store")**
|
||
|
||
The backing [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") class that represents this operation.
|
||
|
||
**[`add_var()`](#qiskit.circuit.QuantumCircuit.add_var "qiskit.circuit.QuantumCircuit.add_var")**
|
||
|
||
Create a new variable in the circuit that can be written to with this method.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
#### swap
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.swap" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5058-L5073" signature="swap(qubit1, qubit2)">
|
||
Apply [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **qubit1** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubits to apply the gate to.
|
||
* **qubit2** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubits to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### sx
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.sx" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5130-L5141" signature="sx(qubit)">
|
||
Apply [`SXGate`](qiskit.circuit.library.SXGate "qiskit.circuit.library.SXGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### sxdg
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.sxdg" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5143-L5154" signature="sxdg(qubit)">
|
||
Apply [`SXdgGate`](qiskit.circuit.library.SXdgGate "qiskit.circuit.library.SXdgGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### t
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.t" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5193-L5204" signature="t(qubit)">
|
||
Apply [`TGate`](qiskit.circuit.library.TGate "qiskit.circuit.library.TGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### tdg
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.tdg" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5206-L5217" signature="tdg(qubit)">
|
||
Apply [`TdgGate`](qiskit.circuit.library.TdgGate "qiskit.circuit.library.TdgGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### u
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.u" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5219-L5239" signature="u(theta, phi, lam, qubit)">
|
||
Apply [`UGate`](qiskit.circuit.library.UGate "qiskit.circuit.library.UGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **theta** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The $\theta$ rotation angle of the gate.
|
||
* **phi** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The $\phi$ rotation angle of the gate.
|
||
* **lam** ([*ParameterExpression*](qiskit.circuit.ParameterExpression "qiskit.circuit.parameterexpression.ParameterExpression") *|*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The $\lambda$ rotation angle of the gate.
|
||
* **qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### unitary
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.unitary" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5868-L5909" signature="unitary(obj, qubits, label=None)">
|
||
Apply unitary gate specified by `obj` to `qubits`.
|
||
|
||
**Parameters**
|
||
|
||
* **obj** (*np.ndarray |* [*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate") *| BaseOperator*) – Unitary operator.
|
||
* **qubits** (*Sequence\[QubitSpecifier]*) – The circuit qubits to apply the transformation to.
|
||
* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – Unitary name for backend \[Default: None].
|
||
|
||
**Returns**
|
||
|
||
The quantum circuit.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Example**
|
||
|
||
Apply a gate specified by a unitary matrix to a quantum circuit
|
||
|
||
```python
|
||
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])
|
||
```
|
||
</Function>
|
||
|
||
#### x
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.x" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5289-L5301" signature="x(qubit, label=None)">
|
||
Apply [`XGate`](qiskit.circuit.library.XGate "qiskit.circuit.library.XGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
* **qubit** (*QubitSpecifier*) – The qubit(s) to apply the gate to.
|
||
* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the gate in the circuit.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### y
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.y" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5480-L5491" signature="y(qubit)">
|
||
Apply [`YGate`](qiskit.circuit.library.YGate "qiskit.circuit.library.YGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### z
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.z" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L5533-L5544" signature="z(qubit)">
|
||
Apply [`ZGate`](qiskit.circuit.library.ZGate "qiskit.circuit.library.ZGate").
|
||
|
||
For the full matrix form of this gate, see the underlying gate documentation.
|
||
|
||
**Parameters**
|
||
|
||
**qubit** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – The qubit(s) to apply the gate to.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instructions created.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
<span id="circuit-control-flow-methods" />
|
||
|
||
### Adding control flow to circuits
|
||
|
||
<Admonition title="See also" type="note">
|
||
[Control flow in circuits](circuit#circuit-control-flow-repr)
|
||
|
||
Discussion of how control-flow operations are represented in the whole [`qiskit.circuit`](circuit#module-qiskit.circuit "qiskit.circuit") context.
|
||
</Admonition>
|
||
|
||
| [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") method | Control-flow instruction |
|
||
| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
||
| [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test") | [`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp") with only a `True` body. |
|
||
| [`if_else()`](#qiskit.circuit.QuantumCircuit.if_else "qiskit.circuit.QuantumCircuit.if_else") | [`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp") with both `True` and `False` bodies. |
|
||
| [`while_loop()`](#qiskit.circuit.QuantumCircuit.while_loop "qiskit.circuit.QuantumCircuit.while_loop") | [`WhileLoopOp`](qiskit.circuit.WhileLoopOp "qiskit.circuit.WhileLoopOp"). |
|
||
| [`switch()`](#qiskit.circuit.QuantumCircuit.switch "qiskit.circuit.QuantumCircuit.switch") | [`SwitchCaseOp`](qiskit.circuit.SwitchCaseOp "qiskit.circuit.SwitchCaseOp"). |
|
||
| [`for_loop()`](#qiskit.circuit.QuantumCircuit.for_loop "qiskit.circuit.QuantumCircuit.for_loop") | [`ForLoopOp`](qiskit.circuit.ForLoopOp "qiskit.circuit.ForLoopOp"). |
|
||
| [`break_loop()`](#qiskit.circuit.QuantumCircuit.break_loop "qiskit.circuit.QuantumCircuit.break_loop") | [`BreakLoopOp`](qiskit.circuit.BreakLoopOp "qiskit.circuit.BreakLoopOp"). |
|
||
| [`continue_loop()`](#qiskit.circuit.QuantumCircuit.continue_loop "qiskit.circuit.QuantumCircuit.continue_loop") | [`ContinueLoopOp`](qiskit.circuit.ContinueLoopOp "qiskit.circuit.ContinueLoopOp"). |
|
||
|
||
[`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") has corresponding methods for all of the control-flow operations that are supported by Qiskit. These have two forms for calling them. The first is a very straightfowards convenience wrapper that takes in the block bodies of the instructions as [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") arguments, and simply constructs and appends the corresponding [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.ControlFlowOp").
|
||
|
||
The second form, which we strongly recommend you use for constructing control flow, is called *the builder interface*. Here, the methods take only the real-time discriminant of the operation, and return [context managers](https://docs.python.org/3/library/stdtypes.html#typecontextmanager) that you enter using `with`. You can then use regular [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") methods within those blocks to build up the control-flow bodies, and Qiskit will automatically track which of the data resources are needed for the inner blocks, building the complete [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.ControlFlowOp") as you leave the `with` statement. It is far simpler and less error-prone to build control flow programmatically this way.
|
||
|
||
#### break\_loop
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.break_loop" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6406-L6433" signature="break_loop()">
|
||
Apply [`BreakLoopOp`](qiskit.circuit.BreakLoopOp "qiskit.circuit.BreakLoopOp").
|
||
|
||
<Admonition title="Warning" type="caution">
|
||
If you are using the context-manager “builder” forms of [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test"), [`for_loop()`](#qiskit.circuit.QuantumCircuit.for_loop "qiskit.circuit.QuantumCircuit.for_loop") or [`while_loop()`](#qiskit.circuit.QuantumCircuit.while_loop "qiskit.circuit.QuantumCircuit.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()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test") and [`if_else()`](#qiskit.circuit.QuantumCircuit.if_else "qiskit.circuit.QuantumCircuit.if_else"). Take care that the [`BreakLoopOp`](qiskit.circuit.BreakLoopOp "qiskit.circuit.BreakLoopOp") instruction must span all the resources of its containing loop, not just the immediate scope.
|
||
</Admonition>
|
||
|
||
**Returns**
|
||
|
||
A handle to the instruction created.
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if this method was called within a builder context, but not contained within a loop.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### continue\_loop
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.continue_loop" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6435-L6462" signature="continue_loop()">
|
||
Apply [`ContinueLoopOp`](qiskit.circuit.ContinueLoopOp "qiskit.circuit.ContinueLoopOp").
|
||
|
||
<Admonition title="Warning" type="caution">
|
||
If you are using the context-manager “builder” forms of [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test"), [`for_loop()`](#qiskit.circuit.QuantumCircuit.for_loop "qiskit.circuit.QuantumCircuit.for_loop") or [`while_loop()`](#qiskit.circuit.QuantumCircuit.while_loop "qiskit.circuit.QuantumCircuit.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()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test") and [`if_else()`](#qiskit.circuit.QuantumCircuit.if_else "qiskit.circuit.QuantumCircuit.if_else"). Take care that the [`ContinueLoopOp`](qiskit.circuit.ContinueLoopOp "qiskit.circuit.ContinueLoopOp") instruction must span all the resources of its containing loop, not just the immediate scope.
|
||
</Admonition>
|
||
|
||
**Returns**
|
||
|
||
A handle to the instruction created.
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if this method was called within a builder context, but not contained within a loop.
|
||
|
||
**Return type**
|
||
|
||
[*InstructionSet*](qiskit.circuit.InstructionSet "qiskit.circuit.instructionset.InstructionSet")
|
||
</Function>
|
||
|
||
#### for\_loop
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.for_loop" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6089-L6154" signature="for_loop(indexset: Iterable[int], loop_parameter: Parameter | None, body: None, qubits: None, clbits: None, *, label: str | None) → ForLoopContext" extraSignatures={["for_loop(indexset: Iterable[int], loop_parameter: Parameter | None, body: QuantumCircuit, qubits: Sequence[Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]], clbits: Sequence[Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int]], *, label: str | None) → InstructionSet"]}>
|
||
Create a `for` loop on this circuit.
|
||
|
||
There are two forms for calling this function. If called with all its arguments (with the possible exception of `label`), it will create a [`ForLoopOp`](qiskit.circuit.ForLoopOp "qiskit.circuit.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`](qiskit.circuit.ForLoopOp "qiskit.circuit.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:
|
||
|
||
```python
|
||
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*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – A collection of integers to loop over. Always necessary.
|
||
|
||
* **loop\_parameter** (*Optional\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.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*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*]*) – 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`](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") handle to the appended loop operation.
|
||
|
||
**Return type**
|
||
|
||
[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") or ForLoopContext
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if an incorrect calling convention is used.
|
||
</Function>
|
||
|
||
#### if\_else
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.if_else" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6258-L6313" signature="if_else(condition, true_body, false_body, qubits, clbits, label=None)">
|
||
Apply [`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp").
|
||
|
||
<Admonition title="Note" type="note">
|
||
This method does not have an associated context-manager form, because it is already handled by the [`if_test()`](#qiskit.circuit.QuantumCircuit.if_test "qiskit.circuit.QuantumCircuit.if_test") method. You can use the `else` part of that with something such as:
|
||
|
||
```python
|
||
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)
|
||
```
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
* **condition** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*ClassicalRegister*](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*,* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*] |* [*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")*\[*[*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*,* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")*]*) – A condition to be evaluated in real time at circuit execution, 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*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")) – The circuit body to be run if `condition` is true.
|
||
* **false\_body** ([*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – The string label of the instruction in the circuit.
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the provided condition references Clbits outside the enclosing circuit.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instruction created.
|
||
|
||
**Return type**
|
||
|
||
[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet")
|
||
</Function>
|
||
|
||
#### if\_test
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.if_test" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6170-L6256" signature="if_test(condition: tuple[ClassicalRegister | Clbit, int]) → IfContext" extraSignatures={["if_test(condition: tuple[ClassicalRegister | Clbit, int], true_body: QuantumCircuit, qubits: Sequence[Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]], clbits: Sequence[Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int]], *, label: str | None = None) → InstructionSet"]}>
|
||
Create an `if` statement on this circuit.
|
||
|
||
There are two forms for calling this function. If called with all its arguments (with the possible exception of `label`), it will create a [`IfElseOp`](qiskit.circuit.IfElseOp "qiskit.circuit.IfElseOp") with the given `true_body`, and there will be no branch for the `false` condition (see also the [`if_else()`](#qiskit.circuit.QuantumCircuit.if_else "qiskit.circuit.QuantumCircuit.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:
|
||
|
||
```python
|
||
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*](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – A condition to be evaluated in real time during circuit execution, 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*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*]*) – 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`](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") handle to the appended conditional operation.
|
||
|
||
**Return type**
|
||
|
||
[InstructionSet](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") or IfContext
|
||
|
||
**Raises**
|
||
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the provided condition references Clbits outside the enclosing circuit.
|
||
* [**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if an incorrect calling convention is used.
|
||
|
||
**Returns**
|
||
|
||
A handle to the instruction created.
|
||
</Function>
|
||
|
||
#### switch
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.switch" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6337-L6404" signature="switch(target: Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int], cases: None, qubits: None, clbits: None, *, label: str | None) → SwitchContext" extraSignatures={["switch(target: Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int], cases: Iterable[Tuple[Any, QuantumCircuit]], qubits: Sequence[Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]], clbits: Sequence[Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int]], *, label: str | None) → InstructionSet"]}>
|
||
Create a `switch`/`case` structure on this circuit.
|
||
|
||
There are two forms for calling this function. If called with all its arguments (with the possible exception of `label`), it will create a [`SwitchCaseOp`](qiskit.circuit.SwitchCaseOp "qiskit.circuit.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`](qiskit.circuit.SwitchCaseOp "qiskit.circuit.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:
|
||
|
||
```python
|
||
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*](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – The classical value to switch one. This must be integer-like.
|
||
* **cases** (*Iterable\[Tuple\[*[*Any*](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.13)")*,* [*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.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`](circuit#qiskit.circuit.CASE_DEFAULT "qiskit.circuit.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`](circuit#qiskit.circuit.CASE_DEFAULT "qiskit.circuit.CASE_DEFAULT") matches all possible values. Omit in context-manager form.
|
||
* **qubits** (*Sequence\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]*) – The circuit qubits over which all case bodies execute. Omit in context-manager form.
|
||
* **clbits** (*Sequence\[*[*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]*) – The circuit clbits over which all case bodies execute. Omit in context-manager form.
|
||
* **label** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*]*) – 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") or SwitchCaseContext
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if an incorrect calling convention is used.
|
||
</Function>
|
||
|
||
#### while\_loop
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.while_loop" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6002-L6063" signature="while_loop(condition: tuple[ClassicalRegister | Clbit, int] | expr.Expr, body: None, qubits: None, clbits: None, *, label: str | None) → WhileLoopContext" extraSignatures={["while_loop(condition: tuple[ClassicalRegister | Clbit, int] | expr.Expr, body: QuantumCircuit, qubits: Sequence[Qubit | QuantumRegister | int | slice | Sequence[Qubit | int]], clbits: Sequence[Clbit | ClassicalRegister | int | slice | Sequence[Clbit | int]], *, label: str | None) → InstructionSet"]}>
|
||
Create a `while` loop on this circuit.
|
||
|
||
There are two forms for calling this function. If called with all its arguments (with the possible exception of `label`), it will create a `WhileLoopOp` with the given `body`. If `body` (and `qubits` and `clbits`) are *not* passed, then this acts as a context manager, which will automatically build a `WhileLoopOp` when the scope finishes. In this form, you do not need to keep track of the qubits or clbits you are using, because the scope will handle it for you.
|
||
|
||
Example usage:
|
||
|
||
```python
|
||
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*](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister")*,* [*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*],* [*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – An equality condition to be checked prior to executing `body`. The left-hand side of the condition must be a [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.ClassicalRegister") or a [`Clbit`](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit"), and the right-hand side must be an integer or boolean.
|
||
* **body** (*Optional\[*[*QuantumCircuit*](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")*]*) – The loop body to be repeatedly executed. Omit this to use the context-manager mode.
|
||
* **qubits** (*Optional\[Sequence\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*]]*) – The circuit qubits over which the loop body should be run. Omit this to use the context-manager mode.
|
||
* **clbits** (*Optional\[Sequence\[*[*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.Clbit")*]]*) – The circuit clbits over which the loop body should be run. Omit this to use the context-manager mode.
|
||
* **label** (*Optional\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*]*) – 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](qiskit.circuit.InstructionSet "qiskit.circuit.InstructionSet") or WhileLoopContext
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if an incorrect calling convention is used.
|
||
</Function>
|
||
|
||
### Converting circuits to single objects
|
||
|
||
As discussed in [Methods to add general operations](#circuit-append-compose), you can convert a circuit to either an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") or a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") using two helper methods.
|
||
|
||
#### to\_instruction
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.to_instruction" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3161-L3185" signature="to_instruction(parameter_map=None, label=None)">
|
||
Create an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") out of this circuit.
|
||
|
||
<Admonition title="See also" type="note">
|
||
**`circuit_to_instruction()`**
|
||
|
||
The underlying driver of this method.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
* **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*, ParameterValueType] | None*) – 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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – Optional gate label.
|
||
|
||
**Returns**
|
||
|
||
**a composite instruction encapsulating this circuit (can be**
|
||
|
||
decomposed back).
|
||
|
||
**Return type**
|
||
|
||
[qiskit.circuit.Instruction](qiskit.circuit.Instruction "qiskit.circuit.Instruction")
|
||
</Function>
|
||
|
||
#### to\_gate
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.to_gate" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3187-L3210" signature="to_gate(parameter_map=None, label=None)">
|
||
Create a [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") out of this circuit. The circuit must act only qubits and contain only unitary operations.
|
||
|
||
<Admonition title="See also" type="note">
|
||
**`circuit_to_gate()`**
|
||
|
||
The underlying driver of this method.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
* **parameter\_map** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")*\[*[*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*, ParameterValueType] | None*) – 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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – Optional gate label.
|
||
|
||
**Returns**
|
||
|
||
a composite gate encapsulating this circuit (can be decomposed back).
|
||
|
||
**Return type**
|
||
|
||
[Gate](qiskit.circuit.Gate "qiskit.circuit.Gate")
|
||
</Function>
|
||
|
||
### Helper mutation methods
|
||
|
||
There are two higher-level methods on [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") for appending measurements to the end of a circuit. Note that by default, these also add an extra register.
|
||
|
||
#### measure\_active
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.measure_active" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3907-L3935" signature="measure_active(inplace=True)">
|
||
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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – All measurements inplace or return new circuit.
|
||
|
||
**Returns**
|
||
|
||
Returns circuit with measurements when `inplace = False`.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
#### measure\_all
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.measure_all" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3937-L3980" signature="measure_all(inplace=True, add_bits=True)">
|
||
Adds measurement to all qubits.
|
||
|
||
By default, adds new classical bits in a [`ClassicalRegister`](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – All measurements inplace or return new circuit.
|
||
* **add\_bits** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to add new bits to store the results.
|
||
|
||
**Returns**
|
||
|
||
Returns circuit with measurements when `inplace=False`.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `add_bits=False` but there are not enough classical bits.
|
||
</Function>
|
||
|
||
There are two “subtractive” methods on [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") as well. This is not a use-case that [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") is designed for; typically you should just look to use [`copy_empty_like()`](#qiskit.circuit.QuantumCircuit.copy_empty_like "qiskit.circuit.QuantumCircuit.copy_empty_like") in place of [`clear()`](#qiskit.circuit.QuantumCircuit.clear "qiskit.circuit.QuantumCircuit.clear"), and run [`remove_final_measurements()`](#qiskit.circuit.QuantumCircuit.remove_final_measurements "qiskit.circuit.QuantumCircuit.remove_final_measurements") as its transpiler-pass form [`RemoveFinalMeasurements`](qiskit.transpiler.passes.RemoveFinalMeasurements "qiskit.transpiler.passes.RemoveFinalMeasurements").
|
||
|
||
#### clear
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.clear" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3750-L3762" signature="clear()">
|
||
Clear all instructions in self.
|
||
|
||
Clearing the circuits will keep the metadata and calibrations.
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`copy_empty_like()`](#qiskit.circuit.QuantumCircuit.copy_empty_like "qiskit.circuit.QuantumCircuit.copy_empty_like")**
|
||
|
||
A method to produce a new circuit with no instructions and all the same tracking of quantum and classical typed data, but without mutating the original circuit.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
#### remove\_final\_measurements
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.remove_final_measurements" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3982-L4064" signature="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.)
|
||
|
||
<Admonition title="Note" type="note">
|
||
This method has rather complex behavior, particularly around the removal of newly idle classical bits and registers. It is much more efficient to avoid adding unnecessary classical data in the first place, rather than trying to remove it later.
|
||
</Admonition>
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`RemoveFinalMeasurements`](qiskit.transpiler.passes.RemoveFinalMeasurements "qiskit.transpiler.passes.RemoveFinalMeasurements")**
|
||
|
||
A transpiler pass that removes final measurements and barriers. This does not remove the classical data. If this is your goal, you can call that with:
|
||
|
||
```python
|
||
from qiskit.circuit import QuantumCircuit
|
||
from qiskit.transpiler.passes import RemoveFinalMeasurements
|
||
|
||
qc = QuantumCircuit(2, 2)
|
||
qc.h(0)
|
||
qc.cx(0, 1)
|
||
qc.barrier()
|
||
qc.measure([0, 1], [0, 1])
|
||
|
||
pass_ = RemoveFinalMeasurements()
|
||
just_bell = pass_(qc)
|
||
```
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
**inplace** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – All measurements removed inplace or return new circuit.
|
||
|
||
**Returns**
|
||
|
||
Returns the resulting circuit when `inplace=False`, else None.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
<span id="circuit-calibrations" />
|
||
|
||
### Manual calibration of instructions
|
||
|
||
[`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") can store [`calibrations`](#qiskit.circuit.QuantumCircuit.calibrations "qiskit.circuit.QuantumCircuit.calibrations") of instructions that define the pulses used to run them on one particular hardware backend. You can
|
||
|
||
#### add\_calibration
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.add_calibration" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6464-L6512" signature="add_calibration(gate, qubits, schedule, params=None)">
|
||
Register a low-level, custom pulse definition for the given gate.
|
||
|
||
**Parameters**
|
||
|
||
* **gate** (*Union\[*[*Gate*](qiskit.circuit.Gate "qiskit.circuit.Gate")*,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*]*) – Gate information.
|
||
* **qubits** (*Union\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*, Tuple\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]]*) – List of qubits to be measured.
|
||
* **schedule** ([*Schedule*](qiskit.pulse.Schedule "qiskit.pulse.Schedule")) – Schedule information.
|
||
* **params** (*Optional\[List\[Union\[*[*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")*,* [*Parameter*](qiskit.circuit.Parameter "qiskit.circuit.Parameter")*]]]*) – A list of parameters.
|
||
|
||
**Raises**
|
||
|
||
[**Exception**](https://docs.python.org/3/library/exceptions.html#Exception "(in Python v3.13)") – if the gate is of type string and params is None.
|
||
</Function>
|
||
|
||
#### has\_calibration\_for
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.has_calibration_for" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1342-L1361" signature="has_calibration_for(instruction)">
|
||
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.
|
||
</Function>
|
||
|
||
## Circuit properties
|
||
|
||
### Simple circuit metrics
|
||
|
||
When constructing quantum circuits, there are several properties that help quantify the “size” of the circuits, and their ability to be run on a noisy quantum device. Some of these, like number of qubits, are straightforward to understand, while others like depth and number of tensor components require a bit more explanation. Here we will explain all of these properties, and, in preparation for understanding how circuits change when run on actual devices, highlight the conditions under which they change.
|
||
|
||
Consider the following circuit:
|
||
|
||
```python
|
||
from qiskit import QuantumCircuit
|
||
qc = QuantumCircuit(12)
|
||
for idx in range(5):
|
||
qc.h(idx)
|
||
qc.cx(idx, idx+5)
|
||
|
||
qc.cx(1, 7)
|
||
qc.x(8)
|
||
qc.cx(1, 9)
|
||
qc.x(7)
|
||
qc.cx(1, 11)
|
||
qc.swap(6, 11)
|
||
qc.swap(6, 9)
|
||
qc.swap(6, 10)
|
||
qc.x(6)
|
||
qc.draw('mpl')
|
||
```
|
||
|
||
|
||
|
||
From the plot, it is easy to see that this circuit has 12 qubits, and a collection of Hadamard, CNOT, X, and SWAP gates. But how to quantify this programmatically? Because we can do single-qubit gates on all the qubits simultaneously, the number of qubits in this circuit is equal to the [`width()`](#qiskit.circuit.QuantumCircuit.width "qiskit.circuit.QuantumCircuit.width") of the circuit:
|
||
|
||
```python
|
||
assert qc.width() == 12
|
||
```
|
||
|
||
We can also just get the number of qubits directly using [`num_qubits`](#qiskit.circuit.QuantumCircuit.num_qubits "qiskit.circuit.QuantumCircuit.num_qubits"):
|
||
|
||
```python
|
||
assert qc.num_qubits == 12
|
||
```
|
||
|
||
<Admonition title="Important" type="danger">
|
||
For a quantum circuit composed from just qubits, the circuit width is equal to the number of qubits. This is the definition used in quantum computing. However, for more complicated circuits with classical registers, and classically controlled gates, this equivalence breaks down. As such, from now on we will not refer to the number of qubits in a quantum circuit as the width.
|
||
</Admonition>
|
||
|
||
It is also straightforward to get the number and type of the gates in a circuit using [`count_ops()`](#qiskit.circuit.QuantumCircuit.count_ops "qiskit.circuit.QuantumCircuit.count_ops"):
|
||
|
||
```python
|
||
qc.count_ops()
|
||
```
|
||
|
||
```python
|
||
OrderedDict([('cx', 8), ('h', 5), ('x', 3), ('swap', 3)])
|
||
```
|
||
|
||
We can also get just the raw count of operations by computing the circuits [`size()`](#qiskit.circuit.QuantumCircuit.size "qiskit.circuit.QuantumCircuit.size"):
|
||
|
||
```python
|
||
assert qc.size() == 19
|
||
```
|
||
|
||
A particularly important circuit property is known as the circuit [`depth()`](#qiskit.circuit.QuantumCircuit.depth "qiskit.circuit.QuantumCircuit.depth"). The depth of a quantum circuit is a measure of how many “layers” of quantum gates, executed in parallel, it takes to complete the computation defined by the circuit. Because quantum gates take time to implement, the depth of a circuit roughly corresponds to the amount of time it takes the quantum computer to execute the circuit. Thus, the depth of a circuit is one important quantity used to measure if a quantum circuit can be run on a device.
|
||
|
||
The depth of a quantum circuit has a mathematical definition as the longest path in a directed acyclic graph (DAG). However, such a definition is a bit hard to grasp, even for experts. Fortunately, the depth of a circuit can be easily understood by anyone familiar with playing [Tetris](https://en.wikipedia.org/wiki/Tetris). Lets see how to compute this graphically:
|
||
|
||
|
||
|
||
We can verify our graphical result using [`QuantumCircuit.depth()`](#qiskit.circuit.QuantumCircuit.depth "qiskit.circuit.QuantumCircuit.depth"):
|
||
|
||
```python
|
||
assert qc.depth() == 9
|
||
```
|
||
|
||
#### count\_ops
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.count_ops" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3531-L3540" signature="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
|
||
</Function>
|
||
|
||
#### depth
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.depth" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3433-L3502" signature="depth(filter_function=<function QuantumCircuit.<lambda>>)">
|
||
Return circuit depth (i.e., length of critical path).
|
||
|
||
<Admonition title="Warning" type="caution">
|
||
This operation is not well defined if the circuit contains control-flow operations.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
**filter\_function** ([*Callable*](https://docs.python.org/3/library/typing.html#typing.Callable "(in Python v3.13)")*\[\[*[*CircuitInstruction*](qiskit.circuit.CircuitInstruction "qiskit._accelerate.circuit.CircuitInstruction")*],* [*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")*]*) – A function to decide which instructions count to increase depth. Should take as a single positional input a [`CircuitInstruction`](qiskit.circuit.CircuitInstruction "qiskit.circuit.CircuitInstruction"). Instructions for which the function returns `False` are ignored in the computation of the circuit depth. By default, filters out “directives”, such as [`Barrier`](circuit#qiskit.circuit.Barrier "qiskit.circuit.Barrier").
|
||
|
||
**Returns**
|
||
|
||
Depth of circuit.
|
||
|
||
**Return type**
|
||
|
||
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")
|
||
|
||
**Examples**
|
||
|
||
Simple calculation of total circuit depth:
|
||
|
||
```python
|
||
from qiskit.circuit import QuantumCircuit
|
||
qc = QuantumCircuit(4)
|
||
qc.h(0)
|
||
qc.cx(0, 1)
|
||
qc.h(2)
|
||
qc.cx(2, 3)
|
||
assert qc.depth() == 2
|
||
```
|
||
|
||
Modifying the previous example to only calculate the depth of multi-qubit gates:
|
||
|
||
```python
|
||
assert qc.depth(lambda instr: len(instr.qubits) > 1) == 1
|
||
```
|
||
</Function>
|
||
|
||
#### get\_instructions
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.get_instructions" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3549-L3558" signature="get_instructions(name)">
|
||
Get instructions matching name.
|
||
|
||
**Parameters**
|
||
|
||
**name** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – The name of instruction to.
|
||
|
||
**Returns**
|
||
|
||
list of (instruction, qargs, cargs).
|
||
|
||
**Return type**
|
||
|
||
[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")([tuple](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)"))
|
||
</Function>
|
||
|
||
#### num\_connected\_components
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.num_connected_components" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3560-L3631" signature="num_connected_components(unitary_only=False)">
|
||
How many non-entangled subcircuits can the circuit be factored to.
|
||
|
||
**Parameters**
|
||
|
||
**unitary\_only** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Compute only unitary part of graph.
|
||
|
||
**Returns**
|
||
|
||
Number of connected components in circuit.
|
||
|
||
**Return type**
|
||
|
||
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")
|
||
</Function>
|
||
|
||
#### num\_nonlocal\_gates
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.num_nonlocal_gates" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3542-L3547" signature="num_nonlocal_gates()">
|
||
Return number of non-local gates (i.e. involving 2+ qubits).
|
||
|
||
Conditional nonlocal gates are also included.
|
||
|
||
**Return type**
|
||
|
||
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")
|
||
</Function>
|
||
|
||
#### num\_tensor\_factors
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.num_tensor_factors" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3639-L3648" signature="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](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")
|
||
</Function>
|
||
|
||
#### num\_unitary\_factors
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.num_unitary_factors" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3633-L3637" signature="num_unitary_factors()">
|
||
Computes the number of tensor factors in the unitary (quantum) part of the circuit only.
|
||
|
||
**Return type**
|
||
|
||
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")
|
||
</Function>
|
||
|
||
#### size
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.size" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3415-L3431" signature="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](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")
|
||
</Function>
|
||
|
||
#### width
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.width" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3504-L3511" signature="width()">
|
||
Return number of qubits plus clbits in circuit.
|
||
|
||
**Returns**
|
||
|
||
Width of circuit.
|
||
|
||
**Return type**
|
||
|
||
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")
|
||
</Function>
|
||
|
||
### Accessing scheduling information
|
||
|
||
If a [`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") has been scheduled as part of a transpilation pipeline, the timing information for individual qubits can be accessed. The whole-circuit timing information is available through the [`duration`](#qiskit.circuit.QuantumCircuit.duration "qiskit.circuit.QuantumCircuit.duration"), [`unit`](#qiskit.circuit.QuantumCircuit.unit "qiskit.circuit.QuantumCircuit.unit") and [`op_start_times`](#qiskit.circuit.QuantumCircuit.op_start_times "qiskit.circuit.QuantumCircuit.op_start_times") attributes.
|
||
|
||
#### qubit\_duration
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.qubit_duration" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6515-L6525" signature="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** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – Qubits within `self` to include.
|
||
|
||
**Returns**
|
||
|
||
Return the duration between the first start and last stop time of non-delay instructions
|
||
|
||
**Return type**
|
||
|
||
[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")
|
||
</Function>
|
||
|
||
#### qubit\_start\_time
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.qubit_start_time" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6527-L6567" signature="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** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – 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**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `self` is a not-yet scheduled circuit.
|
||
|
||
**Return type**
|
||
|
||
[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")
|
||
</Function>
|
||
|
||
#### qubit\_stop\_time
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.qubit_stop_time" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L6569-L6609" signature="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** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – 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**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if `self` is a not-yet scheduled circuit.
|
||
|
||
**Return type**
|
||
|
||
[float](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")
|
||
</Function>
|
||
|
||
## Instruction-like methods
|
||
|
||
[`QuantumCircuit`](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") also contains a small number of methods that are very [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction")-like in detail. You may well find better integration and more API support if you first convert your circuit to an [`Instruction`](qiskit.circuit.Instruction "qiskit.circuit.Instruction") ([`to_instruction()`](#qiskit.circuit.QuantumCircuit.to_instruction "qiskit.circuit.QuantumCircuit.to_instruction")) or [`Gate`](qiskit.circuit.Gate "qiskit.circuit.Gate") ([`to_gate()`](#qiskit.circuit.QuantumCircuit.to_gate "qiskit.circuit.QuantumCircuit.to_gate")) as appropriate, then call the corresponding method.
|
||
|
||
### control
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.control" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1727-L1766" signature="control(num_ctrl_qubits=1, label=None, ctrl_state=None, annotated=False)">
|
||
Control this circuit on `num_ctrl_qubits` qubits.
|
||
|
||
**Parameters**
|
||
|
||
* **num\_ctrl\_qubits** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of control qubits.
|
||
* **label** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")) – An optional label to give the controlled operation for visualization.
|
||
* **ctrl\_state** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The control state in decimal or as a bitstring (e.g. ‘111’). If None, use `2**num_ctrl_qubits - 1`.
|
||
* **annotated** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – indicates whether the controlled gate should be implemented as an annotated gate.
|
||
|
||
**Returns**
|
||
|
||
The controlled version of this circuit.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the circuit contains a non-unitary operation and cannot be controlled.
|
||
</Function>
|
||
|
||
### inverse
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.inverse" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1592-L1642" signature="inverse(annotated=False)">
|
||
Invert (take adjoint of) this circuit.
|
||
|
||
This is done by recursively inverting all gates.
|
||
|
||
**Parameters**
|
||
|
||
**annotated** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – indicates whether the inverse gate can be implemented as an annotated gate.
|
||
|
||
**Returns**
|
||
|
||
the inverted circuit
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – if the circuit cannot be inverted.
|
||
|
||
**Examples**
|
||
|
||
input:
|
||
|
||
```python
|
||
┌───┐
|
||
q_0: ┤ H ├─────■──────
|
||
└───┘┌────┴─────┐
|
||
q_1: ─────┤ RX(1.57) ├
|
||
└──────────┘
|
||
```
|
||
|
||
output:
|
||
|
||
```python
|
||
┌───┐
|
||
q_0: ──────■──────┤ H ├
|
||
┌─────┴─────┐└───┘
|
||
q_1: ┤ RX(-1.57) ├─────
|
||
└───────────┘
|
||
```
|
||
</Function>
|
||
|
||
### power
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.power" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1672-L1725" signature="power(power, matrix_power=False, annotated=False)">
|
||
Raise this circuit to the power of `power`.
|
||
|
||
If `power` is a positive integer and both `matrix_power` and `annotated` are `False`, this implementation defaults to calling `repeat`. Otherwise, the circuit is converted into a gate, and a new circuit, containing this gate raised to the given power, is returned. The gate raised to the given power is implemented either as a unitary gate if `annotated` is `False` or as an annotated operation if `annotated` is `True`.
|
||
|
||
**Parameters**
|
||
|
||
* **power** ([*float*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)")) – The power to raise this circuit to.
|
||
* **matrix\_power** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – indicates whether the inner power gate can be implemented as a unitary gate.
|
||
* **annotated** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – indicates whether the inner power gate can be implemented as an annotated operation.
|
||
|
||
**Raises**
|
||
|
||
[**CircuitError**](circuit#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") – If the circuit needs to be converted to a unitary gate, but is not unitary.
|
||
|
||
**Returns**
|
||
|
||
A circuit implementing this circuit raised to the power of `power`.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
### repeat
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.repeat" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1644-L1670" signature="repeat(reps, *, insert_barriers=False)">
|
||
Repeat this circuit `reps` times.
|
||
|
||
**Parameters**
|
||
|
||
* **reps** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – How often this circuit should be repeated.
|
||
* **insert\_barriers** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Whether to include barriers between circuit repetitions.
|
||
|
||
**Returns**
|
||
|
||
A circuit containing `reps` repetitions of this circuit.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
### reverse\_ops
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.reverse_ops" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1484-L1522" signature="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**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Examples**
|
||
|
||
input:
|
||
|
||
```python
|
||
┌───┐
|
||
q_0: ┤ H ├─────■──────
|
||
└───┘┌────┴─────┐
|
||
q_1: ─────┤ RX(1.57) ├
|
||
└──────────┘
|
||
```
|
||
|
||
output:
|
||
|
||
```python
|
||
┌───┐
|
||
q_0: ─────■──────┤ H ├
|
||
┌────┴─────┐└───┘
|
||
q_1: ┤ RX(1.57) ├─────
|
||
└──────────┘
|
||
```
|
||
</Function>
|
||
|
||
## Visualization
|
||
|
||
Qiskit includes some drawing tools to give you a quick feel for what your circuit looks like. This tooling is primarily targeted at producing either a [Matplotlib](https://matplotlib.org/)- or text-based drawing. There is also a lesser-featured LaTeX backend for drawing, but this is only for simple circuits, and is not as actively maintained.
|
||
|
||
<Admonition title="See also" type="note">
|
||
**[`qiskit.visualization`](visualization#module-qiskit.visualization "qiskit.visualization")**
|
||
|
||
The primary documentation for all of Qiskit’s visualization tooling.
|
||
</Admonition>
|
||
|
||
### draw
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.draw" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3247-L3413" signature="draw(output=None, scale=None, filename=None, style=None, interactive=False, plot_barriers=True, reverse_bits=None, justify=None, vertical_compression='medium', idle_wires=None, with_layout=True, fold=None, ax=None, initial_state=False, cregbundle=None, wire_order=None, expr_len=30)">
|
||
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.
|
||
|
||
<Admonition title="Warning" type="caution">
|
||
Support for [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.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.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
* **output** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| 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*](https://docs.python.org/3/library/functions.html#float "(in Python v3.13)") *| 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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – File path to save image to. Defaults to `None` (result not saved in a file).
|
||
|
||
* **style** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)") *|*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| 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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – 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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") *| 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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Enable/disable drawing barriers in the output circuit. Defaults to `True`.
|
||
|
||
* **justify** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| None*) – Options are `"left"`, `"right"` or `"none"` (str). If anything else is supplied, left justified will be used instead. 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. Defaults to `left`.
|
||
|
||
* **vertical\_compression** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *| 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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") *| None*) – Include idle wires (wires with no circuit elements) in output visualization. Default is `True` unless the user config file (usually `~/.qiskit/settings.conf`) has an alternative value set. For example, `circuit_idle_wires = False`.
|
||
|
||
* **with\_layout** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Include layout information, with labels on the physical layout. Default is `True`.
|
||
|
||
* **fold** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *| 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*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)")) – Adds $|0\rangle$ in the beginning of the qubit wires and $0$ to classical wires. Default is `False`.
|
||
|
||
* **cregbundle** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.13)") *| None*) – If set to `True`, bundle classical registers. Default is `True`, except for when `output` is set to `"text"`.
|
||
|
||
* **wire\_order** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*] | 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*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – The number of characters to display if an [`Expr`](circuit_classical#qiskit.circuit.classical.expr.Expr "qiskit.circuit.classical.expr.Expr") is used for the condition in a [`ControlFlowOp`](qiskit.circuit.ControlFlowOp "qiskit.circuit.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`](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)"):
|
||
|
||
* **`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**](visualization#qiskit.visualization.VisualizationError "qiskit.visualization.VisualizationError") – when an invalid output method is selected
|
||
* [**ImportError**](https://docs.python.org/3/library/exceptions.html#ImportError "(in Python v3.13)") – when the output methods requires non-installed libraries.
|
||
|
||
**Example**
|
||
|
||
```python
|
||
from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit
|
||
qc = QuantumCircuit(1, 1)
|
||
qc.h(0)
|
||
qc.measure(0, 0)
|
||
qc.draw(output='mpl', style={'backgroundcolor': '#EEEEEE'})
|
||
```
|
||
|
||
|
||
</Function>
|
||
|
||
In addition to the core [`draw()`](#qiskit.circuit.QuantumCircuit.draw "qiskit.circuit.QuantumCircuit.draw") driver, there are two visualization-related helper methods, which are mostly useful for quickly unwrapping some inner instructions or reversing the [qubit-labelling conventions](circuit#circuit-conventions) in the drawing. For more general mutation, including basis-gate rewriting, you should use the transpiler ([`qiskit.transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler")).
|
||
|
||
### decompose
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.decompose" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L3212-L3245" signature="decompose(gates_to_decompose=None, reps=1)">
|
||
Call a decomposition pass on this circuit, to decompose one level (shallow decompose).
|
||
|
||
**Parameters**
|
||
|
||
* **gates\_to\_decompose** ([*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.13)") *or*[*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)") *or*[*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*(*[*type*](https://docs.python.org/3/library/functions.html#type "(in Python v3.13)")*,* [*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")*)*) – 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*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – 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](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
</Function>
|
||
|
||
### reverse\_bits
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.reverse_bits" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1524-L1590" signature="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 little-endian convention to the big-endian equivalent, and vice versa.
|
||
|
||
**Returns**
|
||
|
||
the circuit with reversed bit order.
|
||
|
||
**Return type**
|
||
|
||
[QuantumCircuit](#qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")
|
||
|
||
**Examples**
|
||
|
||
input:
|
||
|
||
```python
|
||
┌───┐
|
||
a_0: ┤ H ├──■─────────────────
|
||
└───┘┌─┴─┐
|
||
a_1: ─────┤ X ├──■────────────
|
||
└───┘┌─┴─┐
|
||
a_2: ──────────┤ X ├──■───────
|
||
└───┘┌─┴─┐
|
||
b_0: ───────────────┤ X ├──■──
|
||
└───┘┌─┴─┐
|
||
b_1: ────────────────────┤ X ├
|
||
└───┘
|
||
```
|
||
|
||
output:
|
||
|
||
```python
|
||
┌───┐
|
||
b_0: ────────────────────┤ X ├
|
||
┌───┐└─┬─┘
|
||
b_1: ───────────────┤ X ├──■──
|
||
┌───┐└─┬─┘
|
||
a_0: ──────────┤ X ├──■───────
|
||
┌───┐└─┬─┘
|
||
a_1: ─────┤ X ├──■────────────
|
||
┌───┐└─┬─┘
|
||
a_2: ┤ H ├──■─────────────────
|
||
└───┘
|
||
```
|
||
</Function>
|
||
|
||
## Internal utilities
|
||
|
||
These functions are not intended for public use, but were accidentally left documented in the public API during the 1.0 release. They will be removed in Qiskit 2.0, but will be supported until then.
|
||
|
||
### cast
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cast" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2314-L2326" signature="cast(value, type_)" modifiers="static">
|
||
Best effort to cast value to type. Otherwise, returns the value.
|
||
|
||
<Admonition title="Deprecated since version 1.2" type="danger">
|
||
The method `qiskit.circuit.quantumcircuit.QuantumCircuit.cast()` is deprecated as of qiskit 1.2. It will be removed in the 2.0 release. This method is only used as an internal helper and will be removed with no replacement.
|
||
</Admonition>
|
||
|
||
**Return type**
|
||
|
||
*S* | *T*
|
||
</Function>
|
||
|
||
### cbit\_argument\_conversion
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cbit_argument_conversion" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2371-L2388" signature="cbit_argument_conversion(clbit_representation)">
|
||
Converts several classical bit representations (such as indexes, range, etc.) into a list of classical bits.
|
||
|
||
<Admonition title="Deprecated since version 1.2" type="danger">
|
||
The method `qiskit.circuit.quantumcircuit.QuantumCircuit.cbit_argument_conversion()` is deprecated as of qiskit 1.2. It will be removed in the 2.0 release. This method is only used as an internal helper and will be removed with no replacement.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
**clbit\_representation** ([*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.classicalregister.Clbit") *|*[*ClassicalRegister*](circuit#qiskit.circuit.ClassicalRegister "qiskit.circuit.classicalregister.ClassicalRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Clbit*](circuit#qiskit.circuit.Clbit "qiskit.circuit.classicalregister.Clbit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – Representation to expand.
|
||
|
||
**Returns**
|
||
|
||
A list of tuples where each tuple is a classical bit.
|
||
|
||
**Return type**
|
||
|
||
[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[qiskit.circuit.classicalregister.Clbit](circuit#qiskit.circuit.Clbit "qiskit.circuit.classicalregister.Clbit")]
|
||
</Function>
|
||
|
||
### cls\_instances
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cls_instances" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1424-L1434" signature="cls_instances()" modifiers="classmethod">
|
||
Return the current number of instances of this class, useful for auto naming.
|
||
|
||
<Admonition title="Deprecated since version 1.2" type="danger">
|
||
The method `qiskit.circuit.quantumcircuit.QuantumCircuit.cls_instances()` is deprecated as of qiskit 1.2. It will be removed in the 2.0 release. This method is only used as an internal helper and will be removed with no replacement.
|
||
</Admonition>
|
||
|
||
**Return type**
|
||
|
||
[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")
|
||
</Function>
|
||
|
||
### cls\_prefix
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.cls_prefix" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L1442-L1451" signature="cls_prefix()" modifiers="classmethod">
|
||
Return the prefix to use for auto naming.
|
||
|
||
<Admonition title="Deprecated since version 1.2" type="danger">
|
||
The method `qiskit.circuit.quantumcircuit.QuantumCircuit.cls_prefix()` is deprecated as of qiskit 1.2. It will be removed in the 2.0 release. This method is only used as an internal helper and will be removed with no replacement.
|
||
</Admonition>
|
||
|
||
**Return type**
|
||
|
||
[str](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.13)")
|
||
</Function>
|
||
|
||
### qbit\_argument\_conversion
|
||
|
||
<Function id="qiskit.circuit.QuantumCircuit.qbit_argument_conversion" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/circuit/quantumcircuit.py#L2336-L2354" signature="qbit_argument_conversion(qubit_representation)">
|
||
Converts several qubit representations (such as indexes, range, etc.) into a list of qubits.
|
||
|
||
<Admonition title="Deprecated since version 1.2" type="danger">
|
||
The method `qiskit.circuit.quantumcircuit.QuantumCircuit.qbit_argument_conversion()` is deprecated as of qiskit 1.2. It will be removed in the 2.0 release. This method is only used as an internal helper and will be removed with no replacement.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
**qubit\_representation** ([*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*QuantumRegister*](circuit#qiskit.circuit.QuantumRegister "qiskit.circuit.quantumregister.QuantumRegister") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)") *|*[*slice*](https://docs.python.org/3/library/functions.html#slice "(in Python v3.13)") *|*[*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit") *|*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")*]*) – Representation to expand.
|
||
|
||
**Returns**
|
||
|
||
The resolved instances of the qubits.
|
||
|
||
**Return type**
|
||
|
||
[list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")\[[qiskit.circuit.quantumregister.Qubit](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit")]
|
||
</Function>
|
||
</Class>
|
||
|