Skip to main contentIBM Quantum Documentation

QuantumCircuit class

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

GitHub(opens in a new tab)

Core Qiskit representation of a quantum circuit.

Note

For more details setting the QuantumCircuit in context of all of the data structures that go with it, how it fits into the rest of the qiskit package, and the different regimes of quantum-circuit descriptions in Qiskit, see the module-level documentation of qiskit.circuit.


Circuit attributes

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 attributeSummary
global_phaseThe global phase of the circuit, measured in radians.
metadataArbitrary user mapping, which Qiskit will preserve through the transpiler, but otherwise completely ignore.
nameAn optional string name for the circuit.
Immutable data attributeSummary
ancillasList of AncillaQubits tracked by the circuit.
calibrationsCustom user-supplied pulse calibrations for individual instructions.
cregsList of ClassicalRegisters tracked by the circuit.
clbitsList of Clbits tracked by the circuit.
dataList of individual CircuitInstructions that make up the circuit.
durationTotal duration of the circuit, added by scheduling transpiler passes.
layoutHardware layout and routing information added by the transpiler.
num_ancillasThe number of ancilla qubits in the circuit.
num_clbitsThe number of clbits in the circuit.
num_captured_varsNumber of captured real-time classical variables.
num_declared_varsNumber of locally declared real-time classical variables in the outer circuit scope.
num_input_varsNumber of input real-time classical variables.
num_parametersNumber of compile-time Parameters in the circuit.
num_qubitsNumber of qubits in the circuit.
num_varsTotal number of real-time classical variables in the outer circuit scope.
op_start_timesStart times of scheduled operations, added by scheduling transpiler passes.
parametersOrdered set-like view of the compile-time Parameters tracked by the circuit.
qregsList of QuantumRegisters tracked by the circuit.
qubitsList of Qubits tracked by the circuit.
unitThe unit of the duration field.

The core attribute is data. This is a sequence-like object that exposes the CircuitInstructions contained in an ordered form. You generally should not mutate this object directly; QuantumCircuit is only designed for append-only operations (which should use append()). Most operations that mutate circuits in place should be written as transpiler passes (qiskit.transpiler).

data

The circuit data (instructions and context).

Returns

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

Return type

QuantumCircuitData

Alongside the data, the global_phase of a circuit can have some impact on its output, if the circuit is used to describe a Gate that may be controlled. This is measured in radians and is directly settable.

global_phase

The global phase of the current circuit scope in radians.

The name of a circuit becomes the name of the Instruction or Gate resulting from to_instruction() and to_gate() calls, which can be handy for visualizations.

name

Type: str

A human-readable name for the circuit.

You can attach arbitrary 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), 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() for more detail). This field is ignored during export to OpenQASM 2 or 3.

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.

QuantumCircuit exposes data attributes tracking its internal quantum and classical bits and registers. These appear as Python list(opens in a new tab)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.

qregs

Type: list[QuantumRegister]

A list of the QuantumRegisters in this circuit. You should not mutate this.

cregs

Type: list[ClassicalRegister]

A list of the ClassicalRegisters in this circuit. You should not mutate this.

qubits

A list of Qubits in the order that they were added. You should not mutate this.

ancillas

A list of AncillaQubits in the order that they were added. You should not mutate this.

clbits

A list of Clbits in the order that they were added. You should not mutate this.

The compile-time parameters present in instructions on the circuit are available in parameters. This has a canonical order (mostly lexical, except in the case of ParameterVector), which matches the order that parameters will be assigned when using the list forms of assign_parameters(), but also supports set(opens in a new tab)-like constant-time membership testing.

parameters

The parameters defined in the circuit.

This attribute returns the Parameter objects in the circuit sorted alphabetically. Note that parameters instantiated with a ParameterVector are still sorted numerically.

Examples

The snippet below shows that insertion order of parameters does not matter.

>>> from qiskit.circuit import QuantumCircuit, Parameter
>>> a, b, elephant = Parameter("a"), Parameter("b"), Parameter("elephant")
>>> circuit = QuantumCircuit(1)
>>> circuit.rx(b, 0)
>>> circuit.rz(elephant, 0)
>>> circuit.ry(a, 0)
>>> circuit.parameters  # sorted alphabetically!
ParameterView([Parameter(a), Parameter(b), Parameter(elephant)])

Bear in mind that alphabetical sorting might be unintuitive when it comes to numbers. The literal “10” comes before “2” in strict alphabetical sorting.

>>> from qiskit.circuit import QuantumCircuit, Parameter
>>> angles = [Parameter("angle_1"), Parameter("angle_2"), Parameter("angle_10")]
>>> circuit = QuantumCircuit(1)
>>> circuit.u(*angles, 0)
>>> circuit.draw()
   ┌─────────────────────────────┐
q:U(angle_1,angle_2,angle_10)
   └─────────────────────────────┘
>>> circuit.parameters
ParameterView([Parameter(angle_1), Parameter(angle_10), Parameter(angle_2)])

To respect numerical sorting, a ParameterVector can be used.

>>> from qiskit.circuit import QuantumCircuit, Parameter, ParameterVector
>>> x = ParameterVector("x", 12)
>>> circuit = QuantumCircuit(1)
>>> for x_i in x:
...     circuit.rx(x_i, 0)
>>> circuit.parameters
ParameterView([
    ParameterVectorElement(x[0]), ParameterVectorElement(x[1]),
    ParameterVectorElement(x[2]), ParameterVectorElement(x[3]),
    ..., ParameterVectorElement(x[11])
])

Returns

The sorted Parameter objects in the circuit.

The storage of any manual pulse-level calibrations for individual instructions on the circuit is in calibrations. This presents as a dict(opens in a new tab), but should not be mutated directly; use the methods discussed in Manual calibration of instructions.

calibrations

Return calibration dictionary.

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

If you have transpiled your circuit, so you have a physical circuit, you can inspect the 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

Return any associated layout information about the circuit

This attribute contains an optional TranspileLayout object. This is typically set on the output from transpile() or PassManager.run() to retain information about the permutations caused on the input circuit by transpilation.

There are two types of permutations caused by the transpile() function, an initial layout which permutes the qubits based on the selected physical qubits on the Target, and a final layout which is an output permutation caused by SwapGates inserted during routing.

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 of the circuit.

duration

Type: int | float | None

The total duration of the circuit, set by a scheduling transpiler pass. Its unit is specified by unit.

unit

The unit that duration is specified in.

op_start_times

Return a list of operation start times.

This attribute is enabled once one of scheduling analysis passes runs on the quantum circuit.

Returns

List of integers representing instruction start times. The index corresponds to the index of instruction in QuantumCircuit.data.

Raises

AttributeError(opens in a new tab) – When circuit is not scheduled.

Finally, QuantumCircuit exposes several simple properties as dynamic read-only numeric attributes.

num_ancillas

Return the number of ancilla qubits.

num_clbits

Return number of classical bits.

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() iterable. If this is non-zero, num_input_vars must be zero.

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() iterable.

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() iterable. If this is non-zero, num_captured_vars must be zero.

num_parameters

The number of parameter objects in the circuit.

num_qubits

Return number of qubits.

num_vars

The number of real-time classical variables in the circuit.

This is the length of the iter_vars() iterable.


Creating new circuits

MethodSummary
__init__()Default constructor of no-instruction circuits.
copy()Make a complete copy of an existing circuit.
copy_empty_like()Copy data objects from one circuit into a new one without any instructions.
from_instructions()Infer data objects needed from a list of instructions.
from_qasm_file()Legacy interface to qasm2.load().
from_qasm_str()Legacy interface to 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__

__init__(*regs, name=None, global_phase=0, metadata=None, inputs=(), captures=(), declarations=())

GitHub(opens in a new tab)

Default constructor of QuantumCircuit.

Parameters

  • regs (Register |int(opens in a new tab) | Sequence[Bit]) –

    The registers to be included in the circuit.

    • If a list of Register objects, represents the QuantumRegister and/or ClassicalRegister objects to include in the circuit.

      For example:

      • QuantumCircuit(QuantumRegister(4))
      • QuantumCircuit(QuantumRegister(4), ClassicalRegister(3))
      • QuantumCircuit(QuantumRegister(4, 'qr0'), QuantumRegister(2, 'qr1'))
    • If a list of int, the amount of qubits and/or classical bits to include in the circuit. It can either be a single int for just the number of quantum bits, or 2 ints for the number of quantum bits and classical bits, respectively.

      For example:

      • QuantumCircuit(4) # A QuantumCircuit with 4 qubits
      • QuantumCircuit(4, 3) # A QuantumCircuit with 4 qubits and 3 classical bits
    • If a list of python lists containing Bit objects, a collection of Bit s to be added to the circuit.

  • name (str(opens in a new tab) | 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(opens in a new tab) | None) – Arbitrary key value metadata to associate with the circuit. This gets stored as free-form data in a dict in the metadata attribute. It will not be directly used in the circuit.

  • inputs (Iterable[expr.Var]) – any variables to declare as input runtime variables for this circuit. These should already be existing expr.Var nodes that you build from somewhere else; if you need to create the inputs as well, use QuantumCircuit.add_input(). The variables given in this argument will be passed directly to add_input(). A circuit cannot have both inputs and captures.

  • captures (Iterable[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(). A circuit cannot have both inputs and captures.

  • declarations (Mapping[expr.Var, expr.Expr] | Iterable[Tuple[expr.Var, 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() 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(), which you can use directly if this is the first time you are creating the variable.

Raises

If you have an existing circuit, you can produce a copy of it using 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

copy(name=None)

GitHub(opens in a new tab)

Copy the circuit.

Parameters

name (str(opens in a new tab)) – name to be given to the copied circuit. If None, then the name stays the same.

Returns

a deepcopy of the current circuit, with the specified name

Return type

QuantumCircuit

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(). 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(), or to do a full rewrite of a circuit’s instructions.

copy_empty_like

copy_empty_like(name=None, *, vars_mode='alike')

GitHub(opens in a new tab)

Return a copy of self with the same structure but empty.

That structure includes:

  • name, calibrations and other metadata
  • global phase
  • all the qubits and clbits, including the registers
  • the realtime variables defined in the circuit, handled according to the vars keyword argument.
Warning

If the circuit contains any local variable declarations (those added by the declarations argument to the circuit constructor, or using add_var()), they may be uninitialized in the output circuit. You will need to manually add store instructions for them (see Store and QuantumCircuit.store()) to initialize them.

Parameters

  • name (str(opens in a new tab) | 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() onto the base, since 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

In some cases, it is most convenient to generate a list of CircuitInstructions separately to an entire circuit context, and then to build a circuit from this. The from_instructions() constructor will automatically capture all Qubit and Clbit instances used in the instructions, and create a new QuantumCircuit object that has the correct resources and all the instructions.

from_instructions

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

GitHub(opens in a new tab)

Construct a circuit from an iterable of CircuitInstructions.

Parameters

Returns

The quantum circuit.

Return type

QuantumCircuit

QuantumCircuit also still has two constructor methods that are legacy wrappers around the importers in qiskit.qasm2. These automatically apply the legacy compatibility settings of load() and loads().

from_qasm_file

static from_qasm_file(path)

GitHub(opens in a new tab)

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

Parameters

path (str(opens in a new tab)) – Path to the file for an OpenQASM 2 program

Returns

The QuantumCircuit object for the input OpenQASM 2.

Return type

QuantumCircuit

See also

qasm2.load(): the complete interface to the OpenQASM 2 importer.

from_qasm_str

static from_qasm_str(qasm_str)

GitHub(opens in a new tab)

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

Parameters

qasm_str (str(opens in a new tab)) – A string containing an OpenQASM 2.0 program.

Returns

The QuantumCircuit object for the input OpenQASM 2

Return type

QuantumCircuit

See also

qasm2.loads(): the complete interface to the OpenQASM 2 importer.


Data objects on circuits

Adding data objects

MethodAdds this kind of data
add_bits()Qubits and Clbits.
add_register()QuantumRegister and ClassicalRegister.
add_var()Var nodes with local scope and initializers.
add_input()Var nodes that are treated as circuit inputs.
add_capture()Var nodes captured from containing scopes.
add_uninitialized_var()Var nodes with local scope and undefined state.

Typically you add most of the data objects (Qubit, Clbit, ClassicalRegister, etc) to the circuit as part of using the __init__() default constructor, or copy_empty_like(). However, it is also possible to add these afterwards. Typed classical data, such as standalone Var nodes (see Real-time classical computation), can be both constructed and added with separate methods.

New registerless Qubit and Clbit objects are added using 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().

add_bits

add_bits(bits)

GitHub(opens in a new tab)

Add Bits to the circuit.

Registers are added to the circuit with 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().

add_register

add_register(*regs)

GitHub(opens in a new tab)

Add registers.

Real-time, typed classical data is represented on the circuit by Var nodes with a well-defined Type. It is possible to instantiate these separately to a circuit (see 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() (locally scoped variables) and add_input() (inputs to the circuit).

add_var

add_var(name_or_var, /, initial)

GitHub(opens in a new tab)

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(opens in a new tab) |expr.Var) – either a string of the variable name, or an existing instance of Var to re-use. Variables cannot shadow names that are already in use within the circuit.

  • initial (Any(opens in a new tab)) –

    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() to manually construct a new variable with the desired type, or use expr.cast() to cast the initializer to the desired type.

    This must be either a Expr node, or a value that can be lifted to one using expr.lift.

Returns

The created variable. If a Var instance was given, the exact same object will be returned.

Raises

CircuitError – if the variable cannot be created due to shadowing an existing variable.

Return type

expr.Var

Examples

Define a new variable given just a name and an initializer expression:

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:

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

add_input

add_input(name_or_var: str, type_: Type, /) → Var

add_input(name_or_var: Var, type_: None = None, /) → Var

GitHub(opens in a new tab)

Register a variable as an input to the circuit.

Parameters

  • name_or_var – either a string name, or an existing Var node to use as the input variable.
  • type – if the name is given as a string, then this must be a Type to use for the variable. If the variable is given as an existing 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 – if the variable cannot be created due to shadowing an existing variable.

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() are part of copy_empty_like(), and most uses of add_capture() would be better off using the control-flow builder interface.

add_uninitialized_var

add_uninitialized_var(var, /)

GitHub(opens in a new tab)

Add a variable with no initializer.

In most cases, you should use add_var() to initialize the variable. To use this function, you must already hold a Var instance, as the use of the function typically only makes sense in copying contexts.

Warning

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.

Parameters

var (Var) – the variable to add.

add_capture

add_capture(var)

GitHub(opens in a new tab)

Add a variable to the circuit that it should capture from a scope it will be contained within.

This method requires a 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() 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) – the variable to capture from an enclosing scope.

Raises

CircuitError – if the variable cannot be created due to shadowing an existing variable.

Working with bits and registers

A Bit instance is, on its own, just a unique handle for circuits to use in their own contexts. If you have got a Bit instance and a cirucit, just can find the contexts that the bit exists in using find_bit(), such as its integer index in the circuit and any registers it is contained in.

find_bit

find_bit(bit)

GitHub(opens in a new tab)

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

In particular, this function can find the integer index of a qubit, which corresponds to its hardware index for a transpiled circuit.

Note

The circuit index of a AncillaQubit will be its index in qubits, not ancillas.

Parameters

bit (Bit) – The bit to locate.

Returns

A 2-tuple. The first element (index) contains the index at which the Bit can be found (in either qubits, clbits, depending on its type). The second element (registers) is a list of (register, index) pairs with an entry for each Register in the circuit which contains the Bit (and the index in the Register at which it can be found).

Return type

namedtuple(int(opens in a new tab), List[Tuple(Register, int(opens in a new tab))])

Raises

Examples

Loop through a circuit, getting the qubit and clbit indices of each operation:

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
]

Similarly, you can query a circuit to see if a register has already been added to it by using has_register().

has_register

has_register(register)

GitHub(opens in a new tab)

Test if this circuit has the register r.

Parameters

register (Register) – a quantum or classical register.

Returns

True if the register is contained in this circuit.

Return type

bool(opens in a new tab)

Working with compile-time parameters

See also

Compile-time parametrization

A more complete discussion of what compile-time parametrization is, and how it fits into Qiskit’s data model.

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.

The most common operation on Parameter instances is to replace them in symbolic operations with some numeric value, or another symbolic expression. This is done with assign_parameters().

assign_parameters

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

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

GitHub(opens in a new tab)

Assign parameters to new parameters or values.

If parameters is passed as a dictionary, the keys should be Parameter instances in the current circuit. The values of the dictionary can either be numeric values or new parameter objects.

If parameters is passed as a list or array, the elements are assigned to the current parameters in the order of parameters which is sorted alphabetically (while respecting the ordering in ParameterVector objects).

The values can be assigned to the current circuit object or to a copy of it.

Note

When parameters is given as a mapping, it is permissible to have keys that are strings of the parameter names; these will be looked up using get_parameter(). You can also have keys that are ParameterVector instances, and in this case, the dictionary value should be a sequence of values of the same length as the vector.

If you use either of these cases, you must leave the setting flat_input=False; changing this to True enables the fast path, where all keys must be Parameter instances.

Parameters

  • parameters – Either a dictionary or iterable specifying the new parameter values.
  • inplace – If False, a copy of the circuit with the bound parameters is returned. If True the circuit instance itself is modified.
  • flat_input – If True and parameters is a mapping type, it is assumed to be exactly a mapping of {parameter: value}. By default (False), the mapping may also contain ParameterVector keys that point to a corresponding sequence of values, and these will be unrolled during the mapping, or string keys, which will be converted to Parameter instances using get_parameter().
  • strict – If False, any parameters given in the mapping that are not used in the circuit will be ignored. If True (the default), an error will be raised indicating a logic error.

Raises

  • CircuitError – If parameters is a dict and contains parameters not present in the circuit.
  • ValueError(opens in a new tab) – If parameters is a list/array and the length mismatches the number of free parameters in the circuit.

Returns

A copy of the circuit with bound parameters if inplace is False, otherwise None.

Examples

Create a parameterized circuit and assign the parameters in-place.

from qiskit.circuit import QuantumCircuit, Parameter
 
circuit = QuantumCircuit(2)
params = [Parameter('A'), Parameter('B'), Parameter('C')]
circuit.ry(params[0], 0)
circuit.crx(params[1], 0, 1)
circuit.draw('mpl')
circuit.assign_parameters({params[0]: params[2]}, inplace=True)
circuit.draw('mpl')
../_images/qiskit-circuit-QuantumCircuit-1_00.png../_images/qiskit-circuit-QuantumCircuit-1_01.png

Bind the values out-of-place by list and get a copy of the original circuit.

from qiskit.circuit import QuantumCircuit, ParameterVector
 
circuit = QuantumCircuit(2)
params = ParameterVector('P', 2)
circuit.ry(params[0], 0)
circuit.crx(params[1], 0, 1)
 
bound_circuit = circuit.assign_parameters([1, 2])
bound_circuit.draw('mpl')
 
circuit.draw('mpl')
../_images/qiskit-circuit-QuantumCircuit-2_00.png../_images/qiskit-circuit-QuantumCircuit-2_01.png

The circuit tracks parameters by 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() and get_parameter() to query the circuit for a parameter with the given string name.

has_parameter

has_parameter(name_or_param, /)

GitHub(opens in a new tab)

Check whether a parameter object exists in this circuit.

Parameters

name_or_param (str(opens in a new tab) |Parameter) – the parameter, or name of a parameter to check. If this is a Parameter node, the parameter must be exactly the given one for this function to return True.

Returns

whether a matching parameter is assignable in this circuit.

Return type

bool(opens in a new tab)

See also

QuantumCircuit.get_parameter()

Retrieve the Parameter instance from this circuit by name.

QuantumCircuit.has_var()

A similar method to this, but for run-time expr.Var variables instead of compile-time Parameters.

get_parameter

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

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

GitHub(opens in a new tab)

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(opens in a new tab) is raised instead.

Returns

The corresponding parameter.

Raises

KeyError(opens in a new tab) – if no default is given, but the parameter does not exist in the circuit.

Examples

Retrieve a parameter by name from a circuit:

from qiskit.circuit import QuantumCircuit, Parameter
 
my_param = Parameter("my_param")
 
# Create a parametrised circuit.
qc = QuantumCircuit(1)
qc.rx(my_param, 0)
 
# We can use 'my_param' as a parameter, but let's say we've lost the Python object
# and need to retrieve it.
my_param_again = qc.get_parameter("my_param")
 
assert my_param is my_param_again

Get a variable from a circuit by name, returning some default if it is not present:

assert qc.get_parameter("my_param", None) is my_param
assert qc.get_parameter("unknown_param", None) is None
See also

get_var()

A similar method, but for expr.Var run-time variables instead of Parameter compile-time parameters.

Working with real-time typed classical data

See also

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

A discussion of how real-time data fits into the entire qiskit.circuit data model as a whole.

Adding data objects

The methods for adding new Var variables to a circuit after initialization.

You can retrive a Var instance attached to a circuit by using its variable name using get_var(), or check if a circuit contains a given variable with has_var().

get_var

get_var(name: str, default: T) → Var | T

get_var(name: str, default: ellipsis = Ellipsis) → Var

GitHub(opens in a new tab)

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(opens in a new tab) is raised instead.

Returns

The corresponding variable.

Raises

KeyError(opens in a new tab) – if no default is given, but the variable does not exist.

Examples

Retrieve a variable by name from a circuit:

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:

assert qc.get_var("my_var", None) is my_var
assert qc.get_var("unknown_variable", None) is None
See also

get_parameter()

A similar method, but for Parameter compile-time parameters instead of expr.Var run-time variables.

has_var

has_var(name_or_var, /)

GitHub(opens in a new tab)

Check whether a variable is accessible in this scope.

Parameters

name_or_var (str(opens in a new tab) |expr.Var) – the variable, or name of a variable to check. If this is a 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(opens in a new tab)

See also

QuantumCircuit.get_var()

Retrieve the expr.Var instance from this circuit by name.

QuantumCircuit.has_parameter()

A similar method to this, but for compile-time Parameters instead of run-time expr.Var variables.

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() and iter_captured_vars() will be empty, as inputs and captures are mutually exclusive. All of the iterators have corresponding dynamic properties on QuantumCircuit that contain their length: num_vars, num_input_vars, num_captured_vars and num_declared_vars.

iter_vars

iter_vars()

GitHub(opens in a new tab)

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(), iter_input_vars() and iter_captured_vars().

Return type

Iterable(opens in a new tab)[Var]

iter_input_vars

iter_input_vars()

GitHub(opens in a new tab)

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()) and captured variables (see iter_captured_vars()).

Return type

Iterable(opens in a new tab)[Var]

iter_captured_vars

iter_captured_vars()

GitHub(opens in a new tab)

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()) and locally declared variables (see iter_declared_vars()).

Return type

Iterable(opens in a new tab)[Var]

iter_declared_vars

iter_declared_vars()

GitHub(opens in a new tab)

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()) and captured variables (see iter_captured_vars()).

Return type

Iterable(opens in a new tab)[Var]


Adding operations to circuits

You can add anything that implements the Operation interface to a circuit as a single instruction, though most things you will want to add will be Instruction or Gate instances.

See also

Operations, instructions and gates

The qiskit.circuit-level documentation on the different interfaces that Qiskit uses to define circuit-level instructions.

Methods to add general operations

These are the base methods that handle adding any object, including user-defined ones, onto circuits.

MethodWhen to use it
append()Add an instruction as a single object onto a circuit.
_append()Same as append(), but a low-level interface that elides almost all error checking.
compose()Inline the instructions from one circuit onto another.
tensor()Like compose(), but strictly for joining circuits that act on disjoint qubits.

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()), or whether you want to join the instructions from two circuits together (compose()).

A single instruction or operation appears as a single entry in the data of the circuit, and as a single box when drawn in the circuit visualizers (see draw()). A single instruction is the “unit” that a hardware backend might be defined in terms of (see Target). An Instruction can come with a definition, which is one rule the transpiler (see qiskit.transpiler) will be able to fall back on to decompose it for hardware, if needed. An Operation that is not also an Instruction can only be decomposed if it has some associated high-level synthesis method registered for it (see qiskit.transpiler.passes.synthesis.plugin).

A QuantumCircuit alone is not a single 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 using to_gate(), and simple circuits acting only on qubits and clbits into a Instruction with to_instruction().

When you have an Operation, Instruction, or Gate, add it to the circuit, specifying the qubit and clbit arguments with append().

append

append(instruction, qargs=None, cargs=None, *, copy=True)

GitHub(opens in a new tab)

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

The qargs and cargs will be expanded and broadcast according to the rules of the given Instruction, and any non-Bit specifiers (such as integer indices) will be resolved into the relevant instances.

If a CircuitInstruction is given, it will be unwrapped, verified in the context of this circuit, and a new object will be appended to the circuit. In this case, you may not pass qargs or cargs separately.

Parameters

  • instruction (Operation |CircuitInstruction) – Instruction instance to append, or a CircuitInstruction with all its context.
  • qargs (Sequence[QubitSpecifier] | None) – specifiers of the Qubits to attach instruction to.
  • cargs (Sequence[ClbitSpecifier] | None) – specifiers of the Clbits to attach instruction to.
  • copy (bool(opens in a new tab)) – 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 CircuitInstructions that were actually added to the circuit.

Return type

qiskit.circuit.InstructionSet

Raises

CircuitError – if the operation passed is not an instance of Instruction .

append() does quite substantial error checking to ensure that you cannot accidentally break the data model of 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(), but at the risk that the caller is responsible for ensuring they are passing only valid data.

_append

_append(instruction: CircuitInstruction) → CircuitInstruction

_append(instruction: Operation, qargs: Sequence[Qubit], cargs: Sequence[Clbit]) → Operation

GitHub(opens in a new tab)

Append an instruction to the end of the circuit, modifying the circuit in place.

Warning

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.
Note

This function may be used by callers other than 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() on a circuit that is received by a function argument. This is because QuantumCircuit._append() will not recognise the scoping constructs of the control-flow builder interface.

Parameters

  • instruction

    A complete well-formed CircuitInstruction of the operation and its context to be added.

    In the legacy compatibility form, this can be a bare Operation, in which case qargs and cargs must be explicitly given.

  • qargs – Legacy argument for qubits to attach the bare Operation to. Ignored if the first argument is in the preferential CircuitInstruction form.

  • cargs – Legacy argument for clbits to attach the bare Operation to. Ignored if the first argument is in the preferential CircuitInstruction form.

Returns

a handle to the instruction that was just added.

Return type

CircuitInstruction

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() in Qiskit. compose() is, in general, more powerful than a to_instruction()-plus-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() 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

compose(other, qubits=None, clbits=None, front=False, inplace=False, wrap=False, *, copy=True, var_remap=None, inline_captures=False)

GitHub(opens in a new tab)

Apply the instructions from one circuit onto specified qubits and/or clbits on another.

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.

When dealing with realtime variables (expr.Var instances), there are two principal strategies for using 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() useful to create each layer’s base, in this case.

Parameters

  • other (qiskit.circuit.Instruction orQuantumCircuit) – (sub)circuit or instruction to compose onto self. If not a QuantumCircuit, this can be anything that append will accept.

  • qubits (list(opens in a new tab)[Qubit|int(opens in a new tab)]) – qubits of self to compose onto.

  • clbits (list(opens in a new tab)[Clbit|int(opens in a new tab)]) – clbits of self to compose onto.

  • front (bool(opens in a new tab)) – If True, front composition will be performed. This is not possible within control-flow builder context managers.

  • inplace (bool(opens in a new tab)) – If True, modify the object. Otherwise return composed circuit.

  • copy (bool(opens in a new tab)) – 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 afterwards, and some instructions may have been mutated in place.

  • var_remap (Mapping) –

    mapping to use to rewrite 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 instances. If a key is a string, it matches any Var with the same name. If a value is a string, whenever a new key matches a it, a new Var is created with the correct type. If a value is a Var, its type must exactly match that of the variable it is replacing.

  • inline_captures (bool(opens in a new tab)) –

    if True, then all “captured” Var nodes in the other 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(), you might find the vars_mode="captures" argument to 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(opens in a new tab)) – If True, wraps the other circuit into a gate (or instruction, depending on whether it contains only unitary instructions) before composing it onto self. Rather than using this option, it is almost always better to manually control this yourself by using to_instruction() or to_gate(), and then call append().

Returns

the composed circuit (returns None if inplace==True).

Return type

QuantumCircuit

Raises

  • CircuitError – if no correct wire mapping can be made between the two circuits, such as if other is wider than self.
  • CircuitError – if trying to emit a new circuit while self has a partially built control-flow context active, such as the context-manager forms of if_test(), for_loop() and while_loop().
  • CircuitError – if trying to compose to the front of a circuit when a control-flow builder block is active; there is no clear meaning to this action.

Examples

>>> lhs.compose(rhs, qubits=[3, 2], inplace=True)
            ┌───┐                   ┌─────┐                ┌───┐
lqr_1_0: ───┤ H ├───    rqr_0: ──■──┤ Tdg ├    lqr_1_0: ───┤ H ├───────────────
            ├───┤              ┌─┴─┐└─────┘                ├───┤
lqr_1_1: ───┤ X ├───    rqr_1: ┤ X ├───────    lqr_1_1: ───┤ X ├───────────────
         ┌──┴───┴──┐           └───┘                    ┌──┴───┴──┐┌───┐
lqr_1_2:U1(0.1)+                     =  lqr_1_2:U1(0.1) ├┤ X ├───────
         └─────────┘                                    └─────────┘└─┬─┘┌─────┐
lqr_2_0: ─────■─────                           lqr_2_0: ─────■───────■──┤ Tdg ├
            ┌─┴─┐                                          ┌─┴─┐        └─────┘
lqr_2_1: ───┤ X ├───                           lqr_2_1: ───┤ X ├───────────────
            └───┘                                          └───┘
lcr_0: 0 ═══════════                           lcr_0: 0 ═══════════════════════
 
lcr_1: 0 ═══════════                           lcr_1: 0 ═══════════════════════

If you are trying to join two circuits that will apply to completely disjoint qubits and clbits, tensor() is a convenient wrapper around manually adding bit objects and calling compose().

tensor

tensor(other, inplace=False)

GitHub(opens in a new tab)

Tensor self with other.

Remember that in the little-endian convention the leftmost operation will be at the bottom of the circuit. See also the docs for more information.

     ┌────────┐        ┌─────┐          ┌─────┐
q_0: ┤ bottom ├ ⊗ q_0: ┤ top ├  = q_0: ─┤ top ├──
     └────────┘        └─────┘         ┌┴─────┴─┐
                                  q_1: ┤ bottom ├
                                       └────────┘

Parameters

Return type

QuantumCircuit | None

Examples

from qiskit import QuantumCircuit
top = QuantumCircuit(1)
top.x(0);
bottom = QuantumCircuit(2)
bottom.cry(0.2, 0, 1);
tensored = bottom.tensor(top)
tensored.draw('mpl')
../_images/qiskit-circuit-QuantumCircuit-3.png

Returns

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

Return type

QuantumCircuit

As some rules of thumb:

Some potential pitfalls to beware of:

  • Even if you re-use a custom 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()-plus-append() pattern, as the transpiler will improve in this regard over time.
  • 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() and compose() (but not _append()) have a copy keyword argument that defaults to True. In these cases, the incoming 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 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 object, then passing that to append() with the remaining arguments placed into the qargs and cargs fields as appropriate.

The following methods apply special non-unitary Instruction operations to the circuit:

QuantumCircuit methodqiskit.circuit Instruction
barrier()Barrier
delay()Delay
initialize()Initialize
measure()Measure
reset()Reset
store()Store

These methods apply uncontrolled unitary Gate instances to the circuit:

QuantumCircuit methodqiskit.circuit.library Gate
dcx()DCXGate
ecr()ECRGate
h()HGate
id()IGate
iswap()iSwapGate
ms()MSGate
p()PhaseGate
pauli()PauliGate
prepare_state()StatePreparation
r()RGate
rcccx()RC3XGate
rccx()RCCXGate
rv()RVGate
rx()RXGate
rxx()RXXGate
ry()RYGate
ryy()RYYGate
rz()RZGate
rzx()RZXGate
rzz()RZZGate
s()SGate
sdg()SdgGate
swap()SwapGate
sx()SXGate
sxdg()SXdgGate
t()TGate
tdg()TdgGate
u()UGate
unitary()UnitaryGate
x()XGate
y()YGate
z()ZGate

The following methods apply Gate instances that are also controlled gates, so are direct subclasses of ControlledGate:

QuantumCircuit methodqiskit.circuit.library ControlledGate
ccx()CCXGate
ccz()CCZGate
ch()CHGate
cp()CPhaseGate
crx()CRXGate
cry()CRYGate
crz()CRZGate
cs()CSGate
csdg()CSdgGate
cswap()CSwapGate
csx()CSXGate
cu()CUGate
cx()CXGate
cy()CYGate
cz()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 synthesised version of a gate.

QuantumCircuit methodBase qiskit.circuit.library Gate
mcp()PhaseGate
mcrx()RXGate
mcry()RYGate
mcrz()RZGate
mcx()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

barrier(*qargs, label=None)

GitHub(opens in a new tab)

Apply Barrier. If qargs is empty, applies to all qubits in the circuit.

Parameters

  • qargs (QubitSpecifier) – Specification for one or more qubit arguments.
  • label (str(opens in a new tab)) – The string label of the barrier.

Returns

handle to the added instructions.

Return type

qiskit.circuit.InstructionSet

ccx

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

GitHub(opens in a new tab)

Apply CCXGate.

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

Parameters

  • control_qubit1 (QubitSpecifier) – The qubit(s) used as the first control.
  • control_qubit2 (QubitSpecifier) – The qubit(s) used as the second control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

ccz

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

GitHub(opens in a new tab)

Apply CCZGate.

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

Parameters

  • control_qubit1 (QubitSpecifier) – The qubit(s) used as the first control.
  • control_qubit2 (QubitSpecifier) – The qubit(s) used as the second control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘10’). Defaults to controlling on the ‘11’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

ch

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

GitHub(opens in a new tab)

Apply CHGate.

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

Parameters

  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

cp

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

GitHub(opens in a new tab)

Apply CPhaseGate.

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

Parameters

  • theta (ParameterValueType) – The angle of the rotation.
  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

crx

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

GitHub(opens in a new tab)

Apply CRXGate.

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

Parameters

  • theta (ParameterValueType) – The angle of the rotation.
  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

cry

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

GitHub(opens in a new tab)

Apply CRYGate.

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

Parameters

  • theta (ParameterValueType) – The angle of the rotation.
  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

crz

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

GitHub(opens in a new tab)

Apply CRZGate.

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

Parameters

  • theta (ParameterValueType) – The angle of the rotation.
  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

cs

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

GitHub(opens in a new tab)

Apply CSGate.

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

Parameters

  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

csdg

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

GitHub(opens in a new tab)

Apply CSdgGate.

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

Parameters

  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

cswap

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

GitHub(opens in a new tab)

Apply CSwapGate.

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

Parameters

  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit1 (QubitSpecifier) – The qubit(s) targeted by the gate.
  • target_qubit2 (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. '1'). Defaults to controlling on the '1' state.

Returns

A handle to the instructions created.

Return type

InstructionSet

csx

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

GitHub(opens in a new tab)

Apply CSXGate.

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

Parameters

  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

cu

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

GitHub(opens in a new tab)

Apply CUGate.

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

Parameters

  • theta (ParameterValueType) – The θ\theta rotation angle of the gate.
  • phi (ParameterValueType) – The ϕ\phi rotation angle of the gate.
  • lam (ParameterValueType) – The λ\lambda rotation angle of the gate.
  • gamma (ParameterValueType) – The global phase applied of the U gate, if applied.
  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

cx

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

GitHub(opens in a new tab)

Apply CXGate.

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

Parameters

  • control_qubit (QubitSpecifier) – The qubit(s) used as the control.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

cy

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

GitHub(opens in a new tab)

Apply CYGate.

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

Parameters

  • control_qubit (QubitSpecifier) – The qubit(s) used as the controls.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

cz

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

GitHub(opens in a new tab)

Apply CZGate.

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

Parameters

  • control_qubit (QubitSpecifier) – The qubit(s) used as the controls.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

dcx

dcx(qubit1, qubit2)

GitHub(opens in a new tab)

Apply DCXGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

delay

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

GitHub(opens in a new tab)

Apply Delay. If qarg is None, applies to all qubits. When applying to multiple qubits, delays with the same duration will be created.

Parameters

Returns

handle to the added instructions.

Return type

qiskit.circuit.InstructionSet

Raises

CircuitError – if arguments have bad format.

ecr

ecr(qubit1, qubit2)

GitHub(opens in a new tab)

Apply ECRGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

h

h(qubit)

GitHub(opens in a new tab)

Apply HGate.

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

Parameters

qubit (Qubit |QuantumRegister |int(opens in a new tab) |slice(opens in a new tab) |Sequence(opens in a new tab)[Qubit |int(opens in a new tab)]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

id

id(qubit)

GitHub(opens in a new tab)

Apply IGate.

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

Parameters

qubit (Qubit |QuantumRegister |int(opens in a new tab) |slice(opens in a new tab) |Sequence(opens in a new tab)[Qubit |int(opens in a new tab)]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

initialize

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

GitHub(opens in a new tab)

Initialize qubits in a specific state.

Qubit initialization is done by first resetting the qubits to 0|0\rangle followed by calling StatePreparation class to prepare the qubits in a specified state. Both these steps are included in the Initialize instruction.

Parameters

  • params (Statevector | Sequence[complex(opens in a new tab)] | str(opens in a new tab) |int(opens in a new tab)) –

    The state to initialize to, can be either of the following.

    • Statevector or vector of complex amplitudes to initialize to.
    • Labels of basis states of the Pauli eigenstates Z, X, Y. See Statevector.from_label(). Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label ‘01’ initializes the qubit zero to 1|1\rangle and the qubit one to 0|0\rangle.
    • An integer that is used as a bitmap indicating which qubits to initialize to 1|1\rangle. Example: setting params to 5 would initialize qubit 0 and qubit 2 to 1|1\rangle and qubit 1 to 0|0\rangle.
  • qubits (Sequence[QubitSpecifier] | None) – Qubits to initialize. If None the initialization is applied to all qubits in the circuit.

  • normalize (bool(opens in a new tab)) – Whether to normalize an input array to a unit vector.

Returns

A handle to the instructions created.

Examples

Prepare a qubit in the state (01)/2(|0\rangle - |1\rangle) / \sqrt{2}.

import numpy as np
from qiskit import QuantumCircuit
 
circuit = QuantumCircuit(1)
circuit.initialize([1/np.sqrt(2), -1/np.sqrt(2)], 0)
circuit.draw()

output:

     ┌──────────────────────────────┐
q_0:Initialize(0.70711,-0.70711)
     └──────────────────────────────┘

Initialize from a string two qubits in the state 10|10\rangle. The order of the labels is reversed with respect to qubit index. More information about labels for basis states are in Statevector.from_label().

import numpy as np
from qiskit import QuantumCircuit
 
circuit = QuantumCircuit(2)
circuit.initialize('01', circuit.qubits)
circuit.draw()

output:

     ┌──────────────────┐
q_0:0
Initialize(0,1)
q_1:1
     └──────────────────┘

Initialize two qubits from an array of complex amplitudes.

import numpy as np
from qiskit import QuantumCircuit
 
circuit = QuantumCircuit(2)
circuit.initialize([0, 1/np.sqrt(2), -1.j/np.sqrt(2), 0], circuit.qubits)
circuit.draw()

output:

     ┌────────────────────────────────────┐
q_0:0
Initialize(0,0.70711,-0.70711j,0)
q_1:1
     └────────────────────────────────────┘

iswap

iswap(qubit1, qubit2)

GitHub(opens in a new tab)

Apply iSwapGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

mcp

mcp(lam, control_qubits, target_qubit, ctrl_state=None)

GitHub(opens in a new tab)

Apply 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(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Return type

InstructionSet

mcrx

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

GitHub(opens in a new tab)

Apply Multiple-Controlled X rotation gate

Parameters

Raises

QiskitError – parameter errors

mcry

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

GitHub(opens in a new tab)

Apply Multiple-Controlled Y rotation gate

Parameters

Raises

QiskitError – parameter errors

mcrz

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

GitHub(opens in a new tab)

Apply Multiple-Controlled Z rotation gate

Parameters

Raises

QiskitError – parameter errors

mcx

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

GitHub(opens in a new tab)

Apply MCXGate.

The multi-cX gate can be implemented using different techniques, which use different numbers of ancilla qubits and have varying circuit depth. These modes are:

  • 'noancilla': Requires 0 ancilla qubits.
  • 'recursion': Requires 1 ancilla qubit if more than 4 controls are used, otherwise 0.
  • 'v-chain': Requires 2 less ancillas than the number of control qubits.
  • 'v-chain-dirty': Same as for the clean ancillas (but the circuit will be longer).

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

Parameters

  • control_qubits (Sequence[QubitSpecifier]) – The qubits used as the controls.
  • target_qubit (QubitSpecifier) – The qubit(s) targeted by the gate.
  • ancilla_qubits (QubitSpecifier | Sequence[QubitSpecifier] | None) – The qubits used as the ancillae, if the mode requires them.
  • mode (str(opens in a new tab)) – The choice of mode, explained further above.
  • ctrl_state (str(opens in a new tab) |int(opens in a new tab) | None) – The control state in decimal, or as a bitstring (e.g. ‘1’). Defaults to controlling on the ‘1’ state.

Returns

A handle to the instructions created.

Raises

Return type

InstructionSet

measure

measure(qubit, cbit)

GitHub(opens in a new tab)

Measure a quantum bit (qubit) in the Z basis into a classical bit (cbit).

When a quantum state is measured, a qubit is projected in the computational (Pauli Z) basis to either 0\lvert 0 \rangle or 1\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

Returns

handle to the added instructions.

Return type

qiskit.circuit.InstructionSet

Raises

CircuitError – if arguments have bad format.

Examples

In this example, a qubit is measured and the result of that measurement is stored in the classical bit (usually expressed in diagrams as a double line):

from qiskit import QuantumCircuit
circuit = QuantumCircuit(1, 1)
circuit.h(0)
circuit.measure(0, 0)
circuit.draw()
     ┌───┐┌─┐
  q: ┤ H ├┤M├
     └───┘└╥┘
c: 1/══════╩═
           0

It is possible to call measure with lists of qubits and cbits as a shortcut for one-to-one measurement. These two forms produce identical results:

circuit = QuantumCircuit(2, 2)
circuit.measure([0,1], [0,1])
circuit = QuantumCircuit(2, 2)
circuit.measure(0, 0)
circuit.measure(1, 1)

Instead of lists, you can use QuantumRegister and ClassicalRegister under the same logic.

from qiskit import QuantumCircuit, QuantumRegister, ClassicalRegister
qreg = QuantumRegister(2, "qreg")
creg = ClassicalRegister(2, "creg")
circuit = QuantumCircuit(qreg, creg)
circuit.measure(qreg, creg)

This is equivalent to:

circuit = QuantumCircuit(qreg, creg)
circuit.measure(qreg[0], creg[0])
circuit.measure(qreg[1], creg[1])

ms

ms(theta, qubits)

GitHub(opens in a new tab)

Apply MSGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

p

p(theta, qubit)

GitHub(opens in a new tab)

Apply PhaseGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

pauli

pauli(pauli_string, qubits)

GitHub(opens in a new tab)

Apply PauliGate.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

prepare_state

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

GitHub(opens in a new tab)

Prepare qubits in a specific state.

This class implements a state preparing unitary. Unlike initialize() it does not reset the qubits first.

Parameters

  • state (Statevector | Sequence[complex(opens in a new tab)] | str(opens in a new tab) |int(opens in a new tab)) –

    The state to initialize to, can be either of the following.

    • Statevector or vector of complex amplitudes to initialize to.
    • Labels of basis states of the Pauli eigenstates Z, X, Y. See Statevector.from_label(). Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label ‘01’ initializes the qubit zero to 1|1\rangle and the qubit one to 0|0\rangle.
    • An integer that is used as a bitmap indicating which qubits to initialize to 1|1\rangle. Example: setting params to 5 would initialize qubit 0 and qubit 2 to 1|1\rangle and qubit 1 to 0|0\rangle.
  • qubits (Sequence[QubitSpecifier] | None) – Qubits to initialize. If None the initialization is applied to all qubits in the circuit.

  • label (str(opens in a new tab) | None) – An optional label for the gate

  • normalize (bool(opens in a new tab)) – Whether to normalize an input array to a unit vector.

Returns

A handle to the instruction that was just initialized

Return type

InstructionSet

Examples

Prepare a qubit in the state (01)/2(|0\rangle - |1\rangle) / \sqrt{2}.

import numpy as np
from qiskit import QuantumCircuit
 
circuit = QuantumCircuit(1)
circuit.prepare_state([1/np.sqrt(2), -1/np.sqrt(2)], 0)
circuit.draw()

output:

     ┌─────────────────────────────────────┐
q_0: ┤ State Preparation(0.70711,-0.70711)
     └─────────────────────────────────────┘

Prepare from a string two qubits in the state 10|10\rangle. The order of the labels is reversed with respect to qubit index. More information about labels for basis states are in Statevector.from_label().

import numpy as np
from qiskit import QuantumCircuit
 
circuit = QuantumCircuit(2)
circuit.prepare_state('01', circuit.qubits)
circuit.draw()

output:

     ┌─────────────────────────┐
q_0:0
     │  State Preparation(0,1)
q_1:1
     └─────────────────────────┘

Initialize two qubits from an array of complex amplitudes .. code-block:

import numpy as np
from qiskit import QuantumCircuit
 
circuit = QuantumCircuit(2)
circuit.prepare_state([0, 1/np.sqrt(2), -1.j/np.sqrt(2), 0], circuit.qubits)
circuit.draw()

output:

     ┌───────────────────────────────────────────┐
q_0:0
     │  State Preparation(0,0.70711,-0.70711j,0)
q_1:1
     └───────────────────────────────────────────┘

r

r(theta, phi, qubit)

GitHub(opens in a new tab)

Apply RGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

rcccx

rcccx(control_qubit1, control_qubit2, control_qubit3, target_qubit)

GitHub(opens in a new tab)

Apply RC3XGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

rccx

rccx(control_qubit1, control_qubit2, target_qubit)

GitHub(opens in a new tab)

Apply RCCXGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

reset

reset(qubit)

GitHub(opens in a new tab)

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

Parameters

qubit (Qubit |QuantumRegister |int(opens in a new tab) |slice(opens in a new tab) |Sequence(opens in a new tab)[Qubit |int(opens in a new tab)]) – qubit(s) to reset.

Returns

handle to the added instruction.

Return type

qiskit.circuit.InstructionSet

rv

rv(vx, vy, vz, qubit)

GitHub(opens in a new tab)

Apply RVGate.

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

Rotation around an arbitrary rotation axis vv, where v|v| is the angle of rotation in radians.

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

rx

rx(theta, qubit, label=None)

GitHub(opens in a new tab)

Apply RXGate.

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

Parameters

  • theta (ParameterValueType) – The rotation angle of the gate.
  • qubit (QubitSpecifier) – The qubit(s) to apply the gate to.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.

Returns

A handle to the instructions created.

Return type

InstructionSet

rxx

rxx(theta, qubit1, qubit2)

GitHub(opens in a new tab)

Apply RXXGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

ry

ry(theta, qubit, label=None)

GitHub(opens in a new tab)

Apply RYGate.

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

Parameters

  • theta (ParameterValueType) – The rotation angle of the gate.
  • qubit (QubitSpecifier) – The qubit(s) to apply the gate to.
  • label (str(opens in a new tab) | None) – The string label of the gate in the circuit.

Returns

A handle to the instructions created.

Return type

InstructionSet

ryy

ryy(theta, qubit1, qubit2)

GitHub(opens in a new tab)

Apply RYYGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

rz

rz(phi, qubit)

GitHub(opens in a new tab)

Apply RZGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

rzx

rzx(theta, qubit1, qubit2)

GitHub(opens in a new tab)

Apply RZXGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

rzz

rzz(theta, qubit1, qubit2)

GitHub(opens in a new tab)

Apply RZZGate.

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

Parameters

Returns

A handle to the instructions created.

Return type

InstructionSet

s

s(qubit)

GitHub(opens in a new tab)

Apply SGate.

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

Parameters

qubit (Qubit |QuantumRegister |int(opens in a new tab) |slice(opens in a new tab) |Sequence(opens in a new tab)[Qubit |int(opens in a new tab)]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

sdg

sdg(qubit)

GitHub(opens in a new tab)

Apply SdgGate.

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

Parameters

qubit (Qubit |QuantumRegister |int(opens in a new tab) |slice(opens in a new tab) |Sequence(opens in a new tab)[Qubit |int(opens in a new tab)]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

store

store(lvalue, rvalue, /)

GitHub(opens in a new tab)

Store the result of the given real-time classical expression rvalue in the memory location defined by lvalue.

Typically lvalue will be a Var node and rvalue will be some Expr to write into it, but anything that expr.lift() can raise to an Expr is permissible in both places, and it will be called on them.

Parameters

  • lvalue (Any(opens in a new tab)) – a valid specifier for a memory location in the circuit. This will typically be a Var node, but you can also write to Clbit or ClassicalRegister memory locations if your hardware supports it. The memory location must already be present in the circuit.
  • rvalue (Any(opens in a new tab)) – a real-time classical expression whose result should be written into the given memory location.

Return type

InstructionSet

See also

Store

The backing Instruction class that represents this operation.

add_var()

Create a new variable in the circuit that can be written to with this method.

swap

swap(qubit1, qubit2)

GitHub(opens in a new tab)

Apply SwapGate.

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

Parameters