QuantumCircuit class

The circuit data (instructions and context).

Returns

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

Return type

QuantumCircuitData

The global phase of the current circuit scope in radians.

Type: str

A human-readable name for the circuit.

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.

Type: list[qiskit.circuit.quantumregister.QuantumRegister]

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

Type: list[qiskit.circuit.classicalregister.ClassicalRegister]

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

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

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

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

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.

Return calibration dictionary.

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

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.

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

The unit that duration is specified in.

Return a list of operation start times.

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

Returns

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

Raises

AttributeError – When circuit is not scheduled.

Return the number of ancilla qubits.

Return number of classical bits.

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.

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.

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.

The number of parameter objects in the circuit.

Return number of qubits.

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

This is the length of the iter_vars() iterable.

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

Default constructor of QuantumCircuit.

Parameters

• regs (Register |int | 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 | 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 | 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

• CircuitError – if the circuit name, if given, is not valid.
• CircuitError – if both inputs and captures are given.

copy(name=None)

Copy the circuit.

Parameters

name (str) – name to be given to the copied circuit. If None, then the name stays the same.

Returns

a deepcopy of the current circuit, with the specified name

Return type

QuantumCircuit

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.

Parameters

• name (str | 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

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

Construct a circuit from an iterable of CircuitInstructions.

Parameters

• instructions (Iterable[CircuitInstruction |tuple[qiskit.circuit.Instruction] | tuple[qiskit.circuit.Instruction, Iterable[Qubit]] | tuple[qiskit.circuit.Instruction, Iterable[Qubit], Iterable[Clbit]]]) – The instructions to add to the circuit.
• qubits (Iterable[Qubit]) – Any qubits to add to the circuit. This argument can be used, for example, to enforce a particular ordering of qubits.
• clbits (Iterable[Clbit]) – Any classical bits to add to the circuit. This argument can be used, for example, to enforce a particular ordering of classical bits.
• name (str | None) – The name of the circuit.
• global_phase (ParameterValueType) – The global phase of the circuit in radians.
• metadata (dict | None) – Arbitrary key value metadata to associate with the circuit.

Returns

The quantum circuit.

Return type

QuantumCircuit

static from_qasm_file(path)

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

Parameters

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

Returns

The QuantumCircuit object for the input OpenQASM 2.

Return type

QuantumCircuit

static from_qasm_str(qasm_str)

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

Parameters

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

Returns

The QuantumCircuit object for the input OpenQASM 2

Return type

QuantumCircuit

add_bits(bits)

Add Bits to the circuit.

add_register(*regs)

Add registers.

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

  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(name_or_var: str, type_: Type, /) → Var

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

add_uninitialized_var(var, /)

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.

Parameters

var (Var) – the variable to add.

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

find_bit(bit)

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.

Parameters

bit (Bit) – The bit to locate.

Returns

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

Return type

namedtuple(int, List[Tuple(Register, int)])

Raises

• CircuitError – If the supplied Bit was of an unknown type.
• CircuitError – If the supplied Bit could not be found on the circuit.

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
]

has_register(register)

Test if this circuit has the register r.

Parameters

register (Register) – a quantum or classical register.

Returns

True if the register is contained in this circuit.

Return type

bool

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

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 instances in the current circuit. The values of the dictionary can either be numeric values or new parameter objects.

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

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

Parameters

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

Raises

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

Returns

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

Examples

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

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

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

has_parameter(name_or_param, /)

Check whether a parameter object exists in this circuit.

Parameters

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

Returns

whether a matching parameter is assignable in this circuit.

Return type

bool

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

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 is raised instead.

Returns

The corresponding parameter.

Raises

KeyError – if no default is given, but the parameter does not exist in the circuit.

Examples

Retrieve a parameter by name from a circuit:

from qiskit.circuit import QuantumCircuit, Parameter
 
my_param = Parameter("my_param")
 
# Create a 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:

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

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

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 is raised instead.

Returns

The corresponding variable.

Raises

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

has_var(name_or_var, /)

Check whether a variable is accessible in this scope.

Parameters

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

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

Return type

Iterable[Var]

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

Return type

Iterable[Var]

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

Return type

Iterable[Var]

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

Return type

Iterable[Var]

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, 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) – 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(instruction: CircuitInstruction, *, _standard_gate: bool) → CircuitInstruction

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

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

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

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.

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[Qubit|int]) – qubits of self to compose onto.

• clbits (list[Clbit|int]) – clbits of self to compose onto.

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

• inplace (bool) – If True, modify the object. Otherwise, return composed circuit.

• copy (bool) – 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 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) –

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

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 for more information.

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

Parameters

• other (QuantumCircuit) – The other circuit to tensor this circuit with.
• inplace (bool) – If True, modify the object. Otherwise return composed circuit.

Return type

QuantumCircuit | None

Examples

from qiskit import QuantumCircuit
top = QuantumCircuit(1)
top.x(0);
bottom = QuantumCircuit(2)
bottom.cry(0.2, 0, 1);
tensored = bottom.tensor(top)
tensored.draw('mpl')

Returns

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

Return type

QuantumCircuit

barrier(*qargs, label=None)

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

Parameters

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

Returns

handle to the added instructions.

Return type

qiskit.circuit.InstructionSet

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

Apply CCXGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CCZGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CHGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CPhaseGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CRXGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CRYGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CRZGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CSGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CSdgGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CSwapGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CSXGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CUGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CXGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CYGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply CZGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

dcx(qubit1, qubit2)

Apply DCXGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

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

Parameters

• duration (int orfloat orParameterExpression) – duration of the delay.
• qarg (Object) – qubit argument to apply this delay.
• unit (str) – unit of the duration. Supported units: 's', 'ms', 'us', 'ns', 'ps', and 'dt'. Default is 'dt', i.e. integer time unit depending on the target backend.

Returns

handle to the added instructions.

Return type

qiskit.circuit.InstructionSet

Raises

CircuitError – if arguments have bad format.

ecr(qubit1, qubit2)

Apply ECRGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

h(qubit)

Apply HGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

id(qubit)

Apply IGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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 class to prepare the qubits in a specified state. Both these steps are included in the Initialize instruction.

Parameters

• params (Statevector | Sequence[complex] | str |int) –

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

  • Statevector or vector of complex amplitudes to initialize to.
  • Labels of basis states of the Pauli eigenstates Z, X, Y. See Statevector.from_label(). Notice the order of the labels is reversed with respect to the qubit index to be applied to. Example label '01' initializes the qubit zero to $|1\rangle$ and the qubit one to $|0\rangle$.
  • An integer that is used as a bitmap indicating which qubits to initialize to $|1\rangle$. Example: setting params to 5 would initialize qubit 0 and qubit 2 to $|1\rangle$ and qubit 1 to $|0\rangle$.

• qubits (Sequence[QubitSpecifier] | None) – Qubits to initialize. If None the initialization is applied to all qubits in the circuit.

• normalize (bool) – Whether to normalize an input array to a unit vector.

Returns

A handle to the instructions created.

Examples

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

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

output:

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

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

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

output:

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

Initialize two qubits from an array of complex amplitudes.

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

output:

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

iswap(qubit1, qubit2)

Apply iSwapGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Apply Multiple-Controlled X rotation gate

Parameters

• self (QuantumCircuit) – The QuantumCircuit object to apply the mcrx gate on.
• theta (float) – angle theta
• q_controls (QuantumRegister orlist(Qubit)) – The list of control qubits
• q_target (Qubit) – The target qubit
• use_basis_gates (bool) – use p, u, cx

Raises

QiskitError – parameter errors

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

Apply Multiple-Controlled Y rotation gate

Parameters

• self (QuantumCircuit) – The QuantumCircuit object to apply the mcry gate on.
• theta (float) – angle theta
• q_controls (list(Qubit)) – The list of control qubits
• q_target (Qubit) – The target qubit
• q_ancillae (QuantumRegister ortuple(QuantumRegister, int)) – The list of ancillary qubits.
• mode (string) – The implementation mode to use
• use_basis_gates (bool) – use p, u, cx

Raises

QiskitError – parameter errors

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

Apply Multiple-Controlled Z rotation gate

Parameters

• self (QuantumCircuit) – The QuantumCircuit object to apply the mcrz gate on.
• lam (float) – angle lambda
• q_controls (list(Qubit)) – The list of control qubits
• q_target (Qubit) – The target qubit
• use_basis_gates (bool) – use p, u, cx

Raises

QiskitError – parameter errors

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

Apply MCXGate.

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

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

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

Parameters

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

Returns

A handle to the instructions created.

Raises

• ValueError – if the given mode is not known, or if too few ancilla qubits are passed.
• AttributeError – if no ancilla qubits are passed, but some are needed.

Return type

InstructionSet

measure(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 |QuantumRegister |int |slice |Sequence[Qubit |int]) – qubit(s) to measure.
• cbit (Clbit |ClassicalRegister |int |slice |Sequence[Clbit |int]) – classical bit(s) to place the measurement result(s) in.

Returns

handle to the added instructions.

Return type

qiskit.circuit.InstructionSet

Raises

CircuitError – if arguments have bad format.

Examples

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

from qiskit import QuantumCircuit
circuit = QuantumCircuit(1, 1)
circuit.h(0)
circuit.measure(0, 0)
circuit.draw()

     ┌───┐┌─┐
  q: ┤ H ├┤M├
     └───┘└╥┘
c: 1/══════╩═
           0

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

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

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

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

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

This is equivalent to:

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

ms(theta, qubits)

Apply MSGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

p(theta, qubit)

Apply PhaseGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

pauli(pauli_string, qubits)

Apply PauliGate.

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

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

Prepare qubits in a specific state.

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

Parameters

• state (Statevector | Sequence[complex] | str |int) –

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

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

• qubits (Sequence[QubitSpecifier] | None) – Qubits to initialize. If None the initialization is applied to all qubits in the circuit.

• label (str | None) – An optional label for the gate

• normalize (bool) – Whether to normalize an input array to a unit vector.

Returns

A handle to the instruction that was just initialized

Return type

InstructionSet

Examples

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

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

output:

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

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

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

output:

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

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

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

output:

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

r(theta, phi, qubit)

Apply RGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

rcccx(control_qubit1, control_qubit2, control_qubit3, target_qubit)

Apply RC3XGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

rccx(control_qubit1, control_qubit2, target_qubit)

Apply RCCXGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

reset(qubit)

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

Parameters

qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – qubit(s) to reset.

Returns

handle to the added instruction.

Return type

qiskit.circuit.InstructionSet

rv(vx, vy, vz, qubit)

Apply RVGate.

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

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

Parameters

• vx (ParameterExpression |float) – x-component of the rotation axis.
• vy (ParameterExpression |float) – y-component of the rotation axis.
• vz (ParameterExpression |float) – z-component of the rotation axis.
• qubit (Qubit |QuantumRegister |int |slice |Sequence[Qubit |int]) – The qubit(s) to apply the gate to.

Returns

A handle to the instructions created.

Return type

InstructionSet

rx(theta, qubit, label=None)

Apply RXGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

rxx(theta, qubit1, qubit2)

Apply RXXGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

ry(theta, qubit, label=None)

Apply RYGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

ryy(theta, qubit1, qubit2)

Apply RYYGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

rz(phi, qubit)

Apply RZGate.

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

Parameters

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

Returns

A handle to the instructions created.

Return type

InstructionSet

rzx(theta, qubit1, qubit2)

Apply RZXGate.

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

Parameters

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