---
title: TranspileLayout (latest version)
description: API reference for qiskit.transpiler.TranspileLayout in the latest version of qiskit
source: https://quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.transpiler.TranspileLayout
---

# TranspileLayout

*class* `qiskit.transpiler.TranspileLayout(initial_layout, input_qubit_mapping, final_layout=None, _input_qubit_count=None, _output_qubit_list=None)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/layout.py#L447-L975)

Bases: [`object`](https://docs.python.org/3/library/functions.html#object)

Layout attributes for the output circuit from transpiler.

The [`transpiler`](/docs/api/qiskit/transpiler#module-qiskit.transpiler "qiskit.transpiler") is unitary-preserving up to the “initial layout” and “final layout” permutations. The initial layout permutation is caused by setting and applying the initial layout during the [Layout stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-layout). The final layout permutation is caused by [`SwapGate`](/docs/api/qiskit/qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate") insertion during the [Routing stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-routing). This class provides an interface to reason about these permutations using a variety of helper methods.

During the layout stage, the transpiler can potentially remap the order of the qubits in the circuit as it fits the circuit to the target backend. For example, let the input circuit be:

```python
from qiskit.circuit import QuantumCircuit, QuantumRegister

qr = QuantumRegister(3, name="MyReg")
qc = QuantumCircuit(qr)
qc.h(0)
qc.cx(0, 1)
qc.cx(0, 2)
qc.draw("mpl")
```

![Circuit diagram output by the previous code.](https://quantum.cloud.ibm.com/docs/images/api/qiskit/qiskit-transpiler-TranspileLayout-1.avif)

Suppose that during the layout stage the transpiler reorders the qubits to be:

```python
from qiskit import QuantumCircuit

qc = QuantumCircuit(3)
qc.h(2)
qc.cx(2, 1)
qc.cx(2, 0)
qc.draw("mpl")
```

![Circuit diagram output by the previous code.](https://quantum.cloud.ibm.com/docs/images/api/qiskit/qiskit-transpiler-TranspileLayout-2.avif)

Then the output of the [`initial_virtual_layout()`](#qiskit.transpiler.TranspileLayout.initial_virtual_layout "qiskit.transpiler.TranspileLayout.initial_virtual_layout") method is equivalent to:

```python
Layout({
    qr[0]: 2,
    qr[1]: 1,
    qr[2]: 0,
})
```

(it is also this attribute in the [`QuantumCircuit.draw()`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#draw "qiskit.circuit.QuantumCircuit.draw") and [`circuit_drawer()`](/docs/api/qiskit/qiskit.visualization.circuit_drawer "qiskit.visualization.circuit_drawer") which is used to display the mapping of qubits to positions in circuit visualizations post-transpilation).

Building on the above example, suppose that during the routing stage the transpiler needs to insert swap gates, and the output circuit becomes:

```python
from qiskit import QuantumCircuit

qc = QuantumCircuit(3)
qc.h(2)
qc.cx(2, 1)
qc.swap(0, 1)
qc.cx(2, 1)
qc.draw("mpl")
```

![Circuit diagram output by the previous code.](https://quantum.cloud.ibm.com/docs/images/api/qiskit/qiskit-transpiler-TranspileLayout-3.avif)

Then the output of the [`routing_permutation()`](#qiskit.transpiler.TranspileLayout.routing_permutation "qiskit.transpiler.TranspileLayout.routing_permutation") method is:

```python
[1, 0, 2]
```

which maps positions of qubits before routing to their final positions after routing.

There are three public attributes associated with the class, however these are mostly provided for backwards compatibility and represent the internal state from the transpiler. They are defined as:

> - [`initial_layout`](#qiskit.transpiler.TranspileLayout.initial_layout "qiskit.transpiler.TranspileLayout.initial_layout") - This attribute is used to model the permutation caused by the [Layout stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-layout). It is a [`Layout`](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.Layout") object that maps the input [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")s [`Qubit`](/docs/api/qiskit/circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects to the position in the output [`QuantumCircuit.qubits`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#qubits "qiskit.circuit.QuantumCircuit.qubits") list.
> - [`input_qubit_mapping`](#qiskit.transpiler.TranspileLayout.input_qubit_mapping "qiskit.transpiler.TranspileLayout.input_qubit_mapping") - This attribute is used to retain input ordering of the original [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object. It maps the virtual [`Qubit`](/docs/api/qiskit/circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") object from the original circuit (and [`initial_layout`](#qiskit.transpiler.TranspileLayout.initial_layout "qiskit.transpiler.TranspileLayout.initial_layout")) to its corresponding position in [`QuantumCircuit.qubits`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#qubits "qiskit.circuit.QuantumCircuit.qubits") in the original circuit. This is needed when computing the permutation of the `Operator` of the circuit (and used by [`Operator.from_circuit()`](/docs/api/qiskit/qiskit.quantum_info.Operator#from_circuit "qiskit.quantum_info.Operator.from_circuit")).
> - [`final_layout`](#qiskit.transpiler.TranspileLayout.final_layout "qiskit.transpiler.TranspileLayout.final_layout") - This attribute is used to model the permutation caused by the [Routing stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-routing). It is a [`Layout`](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.Layout") object that maps the output circuit’s qubits from [`QuantumCircuit.qubits`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#qubits "qiskit.circuit.QuantumCircuit.qubits") in the output circuit to their final positions after routing. Importantly, this only represents the permutation caused by inserting [`SwapGate`](/docs/api/qiskit/qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s into the [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") during the [Routing stage](/docs/api/qiskit/transpiler#transpiler-preset-stage-routing). It is **not** a mapping from the original input circuit’s position to the final position at the end of the transpiled circuit. If you need this, you can use the [`final_index_layout()`](#qiskit.transpiler.TranspileLayout.final_index_layout "qiskit.transpiler.TranspileLayout.final_index_layout") to generate this. If [`final_layout`](#qiskit.transpiler.TranspileLayout.final_layout "qiskit.transpiler.TranspileLayout.final_layout") is set to `None`, this indicates that routing was not run, and can be considered equivalent to a trivial layout with the qubits from the output circuit’s [`qubits`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit#qubits "qiskit.circuit.QuantumCircuit.qubits") list.

## Attributes

**Parameters**

- **initial\_layout** ([*Layout*](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout"))
- **input\_qubit\_mapping** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*\[*[*Qubit*](/docs/api/qiskit/circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*,* [*int*](https://docs.python.org/3/library/functions.html#int)*]*)
- **final\_layout** ([*Layout*](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout") *| None*)
- **\_input\_qubit\_count** ([*int*](https://docs.python.org/3/library/functions.html#int) *| None*)
- **\_output\_qubit\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)*\[*[*Qubit*](/docs/api/qiskit/circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit")*] | None*)

### final\_layout

Type: `Layout | None`

Default value: `None`

### initial\_layout

Type: `Layout`

### input\_qubit\_mapping

Type: `dict[Qubit, int]`

## Methods

### final\_index\_layout

`final_index_layout(filter_ancillas=True)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/layout.py#L629-L697)

Generate the final layout as an array of integers.

This method will generate an array of final positions for each qubit in the input circuit. For example, if you had an input circuit like:

```python
qc = QuantumCircuit(3)
qc.h(0)
qc.cx(0, 1)
qc.cx(0, 2)
```

and the output from the transpiler was:

```python
tqc = QuantumCircuit(3)
tqc.h(2)
tqc.cx(2, 1)
tqc.swap(0, 1)
tqc.cx(2, 1)
```

then the [`final_index_layout()`](#qiskit.transpiler.TranspileLayout.final_index_layout "qiskit.transpiler.TranspileLayout.final_index_layout") method returns:

```python
[2, 0, 1]
```

This can be seen as follows. Qubit 0 in the original circuit is mapped to qubit 2 in the output circuit during the layout stage, which is mapped to qubit 2 during the routing stage. Qubit 1 in the original circuit is mapped to qubit 1 in the output circuit during the layout stage, which is mapped to qubit 0 during the routing stage. Qubit 2 in the original circuit is mapped to qubit 0 in the output circuit during the layout stage, which is mapped to qubit 1 during the routing stage. The output list length will be as wide as the input circuit’s number of qubits, as the output list from this method is for tracking the permutation of qubits in the original circuit caused by the transpiler.

**Parameters**

**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If set to `False` any ancillas allocated in the output circuit will be included in the layout.

**Returns**

A list of final positions for each input circuit qubit.

**Return type**

[list](https://docs.python.org/3/library/stdtypes.html#list)\[[int](https://docs.python.org/3/library/functions.html#int)]

### final\_virtual\_layout

`final_virtual_layout(filter_ancillas=True)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/layout.py#L699-L745)

Generate the final layout as a [`Layout`](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.Layout") object.

This method will generate an array of final positions for each qubit in the input circuit. For example, if you had an input circuit like:

```python
qc = QuantumCircuit(3)
qc.h(0)
qc.cx(0, 1)
qc.cx(0, 2)
```

and the output from the transpiler was:

```python
tqc = QuantumCircuit(3)
tqc.h(2)
tqc.cx(2, 1)
tqc.swap(0, 1)
tqc.cx(2, 1)
```

then the return from this function would be a layout object:

```python
Layout({
    qc.qubits[0]: 2,
    qc.qubits[1]: 0,
    qc.qubits[2]: 1,
})
```

This can be seen as follows. Qubit 0 in the original circuit is mapped to qubit 2 in the output circuit during the layout stage, which is mapped to qubit 2 during the routing stage. Qubit 1 in the original circuit is mapped to qubit 1 in the output circuit during the layout stage, which is mapped to qubit 0 during the routing stage. Qubit 2 in the original circuit is mapped to qubit 0 in the output circuit during the layout stage, which is mapped to qubit 1 during the routing stage. The output list length will be as wide as the input circuit’s number of qubits, as the output list from this method is for tracking the permutation of qubits in the original circuit caused by the transpiler.

**Parameters**

**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If set to `False` any ancillas allocated in the output circuit will be included in the layout.

**Returns**

A layout object mapping to the final positions for each qubit.

**Return type**

[*Layout*](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout")

### from\_property\_set

*classmethod* `from_property_set(dag, property_set)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/layout.py#L747-L927)

Construct the [`TranspileLayout`](#qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") by reading out the fields from the given [`PropertySet`](/docs/api/qiskit/qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet"). Returns `None` if there are no layout-setting keys present.

This includes combining the different keys of the property set into the full set of initial and final layouts, including virtual permutations.

This does not invalidate or in any way mutate the given property set. In order to “canonicalize” the property set afterwards, call [`write_into_property_set()`](#qiskit.transpiler.TranspileLayout.write_into_property_set "qiskit.transpiler.TranspileLayout.write_into_property_set").

This reads the following property-set keys:

**`layout`**

**Required**. The [`Layout`](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.Layout") object mapping virtual qubits (potentially expanded with ancillas) to physical-qubit indices. This corresponds directly to [`initial_layout`](#qiskit.transpiler.TranspileLayout.initial_layout "qiskit.transpiler.TranspileLayout.initial_layout").

> **Note**
>
> In all standard use, this is a required field. However, if `virtual_permutation_layout` is set, then a “trivial” layout will be inferred, even if the circuit is not actually laid out to hardware. This is an unfortunate limitation of this class’s data model, where it is not possible to specify a final permutation without also having an initial layout. This deficiency will be corrected in Qiskit 3.0.

**`original_qubit_indices`**

**Required** (but automatically set by the [`PassManager`](/docs/api/qiskit/qiskit.transpiler.PassManager "qiskit.transpiler.PassManager")). The mapping `{virtual: index}` that indicates which relative index each incoming virtual qubit was, in the input circuit. This can be expanded with ancillas too (in which case the ancilla indices don’t mean much, since they weren’t in the incoming circuit).

**`num_input_qubits`**

**Required** (but automatically set by the [`PassManager`](/docs/api/qiskit/qiskit.transpiler.PassManager "qiskit.transpiler.PassManager")). The number of explicit virtual qubits in the input circuit (i.e. not including implicit ancillas).

**`final_layout`**

**Optional**. The effective final permutation, in terms of the current qubits of the [`DAGCircuit`](/docs/api/qiskit/qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit"). This corresponds directly to [`final_layout`](#qiskit.transpiler.TranspileLayout.final_layout "qiskit.transpiler.TranspileLayout.final_layout").

**`virtual_permutation_layout`**

**Optional**. This is set by certain optimization passes that run before layout selection, such as [`ElidePermutations`](/docs/api/qiskit/qiskit.transpiler.passes.ElidePermutations "qiskit.transpiler.passes.ElidePermutations"). It is similar in spirit to `final_layout`, but typically only applies to the input virtual qubits.

> **Warning**
>
> This object uses the opposite permutation convention to `final_layout` due to an oversight in Qiskit during its introduction. In other words, `virtual_permutation_layout` maps a [`Qubit`](/docs/api/qiskit/circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") instance at the end of the circuit to its integer index at the start of the circuit.

**Parameters**

- **dag** ([*DAGCircuit*](/docs/api/qiskit/qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit")) – the current state of the [`DAGCircuit`](/docs/api/qiskit/qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit").
- **property\_set** ([*PropertySet*](/docs/api/qiskit/qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet")) – the current transpiler’s property set. This must at least have the `layout` key set.

**Return type**

[TranspileLayout](#qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") | None

### initial\_index\_layout

`initial_index_layout(filter_ancillas=False)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/layout.py#L589-L611)

Generate an initial layout as an array of integers.

**Parameters**

**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If set to `True` any ancilla qubits added to the transpiler will not be included in the output.

**Returns**

A layout array that maps a position in the array to its new position in the output circuit.

**Return type**

[list](https://docs.python.org/3/library/stdtypes.html#list)\[[int](https://docs.python.org/3/library/functions.html#int)]

### initial\_virtual\_layout

`initial_virtual_layout(filter_ancillas=False)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/layout.py#L564-L587)

Return a [`Layout`](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.Layout") object for the initial layout.

This returns a mapping of virtual [`Qubit`](/docs/api/qiskit/circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects in the input circuit to the positions of the physical qubits selected during layout. This is analogous to the [`initial_layout`](#qiskit.transpiler.TranspileLayout.initial_layout "qiskit.transpiler.TranspileLayout.initial_layout") attribute.

**Parameters**

**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – If set to `True` only qubits in the input circuit will be in the returned layout. Any ancilla qubits added to the output circuit will be filtered from the returned object.

**Returns**

A layout object mapping the input circuit’s [`Qubit`](/docs/api/qiskit/circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects to the positions of the selected physical qubits.

**Return type**

[*Layout*](/docs/api/qiskit/qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout")

### routing\_permutation

`routing_permutation()`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/layout.py#L613-L627)

Generate a final layout as an array of integers.

If there is no [`final_layout`](#qiskit.transpiler.TranspileLayout.final_layout "qiskit.transpiler.TranspileLayout.final_layout") attribute present then that indicates there was no output permutation caused by routing or other transpiler transforms. In this case the function will return a list of `[0, 1, 2, .., n]`.

**Returns**

A layout array that maps a position in the array to its new position in the output circuit.

**Return type**

[list](https://docs.python.org/3/library/stdtypes.html#list)\[[int](https://docs.python.org/3/library/functions.html#int)]

### write\_into\_property\_set

`write_into_property_set(property_set)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/layout.py#L929-L975)

‘Unpack’ this layout into the loose-constraints form of the `property_set`.

This is the inverse method of [`from_property_set()`](#qiskit.transpiler.TranspileLayout.from_property_set "qiskit.transpiler.TranspileLayout.from_property_set").

This always writes the follow property-set keys, overwriting them if they were already set:

**`layout`**

Directly corresponds to [`initial_layout`](#qiskit.transpiler.TranspileLayout.initial_layout "qiskit.transpiler.TranspileLayout.initial_layout").

**`original_qubit_indices`**

Directly corresponds to [`input_qubit_mapping`](#qiskit.transpiler.TranspileLayout.input_qubit_mapping "qiskit.transpiler.TranspileLayout.input_qubit_mapping").

**`final_layout`**

Directly corresponds to [`final_layout`](#qiskit.transpiler.TranspileLayout.final_layout "qiskit.transpiler.TranspileLayout.final_layout"). Note that this might not be identical to the `final_layout` from before a call to [`from_property_set()`](#qiskit.transpiler.TranspileLayout.from_property_set "qiskit.transpiler.TranspileLayout.from_property_set"), because the effects of `virtual_permutation_layout` will have been combined into it.

**`virtual_permutation_layout`**

Deleted from the property set; [`TranspileLayout`](#qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") “finalizes” the multiple separate permutations into one single permutation, to retain the canonical form.

In addition, the following keys are updated, if this [`TranspileLayout`](#qiskit.transpiler.TranspileLayout "qiskit.transpiler.TranspileLayout") has a known value for them. They are left as-is if not, to handle cases where this class was manually constructed without setting certain optional fields.

**`num_input_qubits`**

The number of non-ancilla virtual qubits in the input circuit.

**Parameters**

**property\_set** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*\[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*,* [*object*](https://docs.python.org/3/library/functions.html#object)*]*) – the [`PropertySet`](/docs/api/qiskit/qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet") (or general [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)) that the output should be written into. This mutates the input in place.