215 lines
12 KiB
Plaintext
215 lines
12 KiB
Plaintext
---
|
||
title: TranspileLayout
|
||
description: API reference for qiskit.transpiler.TranspileLayout
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.transpiler.TranspileLayout
|
||
---
|
||
|
||
# TranspileLayout
|
||
|
||
<Class id="qiskit.transpiler.TranspileLayout" isDedicatedPage={true} github="https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/transpiler/layout.py" signature="qiskit.transpiler.TranspileLayout(initial_layout, input_qubit_mapping, final_layout=None, _input_qubit_count=None, _output_qubit_list=None)" modifiers="class">
|
||
Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.12)")
|
||
|
||
Layout attributes from output circuit from transpiler.
|
||
|
||
The transpiler in general is unitary-perserving up to permutations caused by setting and applying initial layout during the [Layout Stage](transpiler#layout-stage) and [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate") insertion during the [Routing Stage](transpiler#routing-stage). To provide an interface to reason about these permutations caused by the [`transpiler`](transpiler#module-qiskit.transpiler "qiskit.transpiler"). In general the normal interface to access and reason about the layout transformations made by the transpiler is to use the helper methods defined on this class.
|
||
|
||
For example, looking at the initial layout, the transpiler can potentially remap the order of the qubits in your circuit as it fits the circuit to the target backend. If the input circuit was:
|
||
|
||
Then during the layout stage the transpiler reorders the qubits to be:
|
||
|
||
then the output of the [`initial_virtual_layout()`](#qiskit.transpiler.TranspileLayout.initial_virtual_layout "qiskit.transpiler.TranspileLayout.initial_virtual_layout") would be equivalent to:
|
||
|
||
```python
|
||
Layout({
|
||
qr[0]: 2,
|
||
qr[1]: 1,
|
||
qr[2]: 0,
|
||
})
|
||
```
|
||
|
||
(it is also this attribute in the [`QuantumCircuit.draw()`](qiskit.circuit.QuantumCircuit#draw "qiskit.circuit.QuantumCircuit.draw") and [`circuit_drawer()`](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 this above example for final layout, if the transpiler needed to insert swap gates during routing so the output circuit became:
|
||
|
||
then the output of the [`routing_permutation()`](#qiskit.transpiler.TranspileLayout.routing_permutation "qiskit.transpiler.TranspileLayout.routing_permutation") method would be:
|
||
|
||
```python
|
||
[1, 0, 2]
|
||
```
|
||
|
||
which maps the qubits at each position to their final position after any swap insertions caused by 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](transpiler#layout-stage) it contains a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object that maps the input [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit")s [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects to the position in the output `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`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") object. It maps the virtual [`Qubit`](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`](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()`](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 is a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object used to model the output permutation caused ny any [`SwapGate`](qiskit.circuit.library.SwapGate "qiskit.circuit.library.SwapGate")s inserted into the [`QuantumCircuit`](qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") during the [Routing Stage](transpiler#routing-stage). It maps the output circuit’s qubits from `QuantumCircuit.qubits` in the output circuit to the final position after 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 this is set to `None` this indicates that routing was not run and it can be considered equivalent to a trivial layout with the qubits from the output circuit’s [`qubits`](qiskit.circuit.QuantumCircuit#qubits "qiskit.circuit.QuantumCircuit.qubits") list.
|
||
|
||
## Attributes
|
||
|
||
### final\_layout
|
||
|
||
<Attribute id="qiskit.transpiler.TranspileLayout.final_layout" attributeTypeHint="Layout | None" attributeValue="None" />
|
||
|
||
### initial\_layout
|
||
|
||
<Attribute id="qiskit.transpiler.TranspileLayout.initial_layout" attributeTypeHint="Layout" />
|
||
|
||
### input\_qubit\_mapping
|
||
|
||
<Attribute id="qiskit.transpiler.TranspileLayout.input_qubit_mapping" attributeTypeHint="dict[Qubit, int]" />
|
||
|
||
## Methods
|
||
|
||
### final\_index\_layout
|
||
|
||
<Function id="qiskit.transpiler.TranspileLayout.final_index_layout" signature="final_index_layout(filter_ancillas=True)">
|
||
Generate the final layout as an array of integers
|
||
|
||
This method will generate an array of final positions for each qubit in the output 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)
|
||
qc.h(2)
|
||
qc.cx(2, 1)
|
||
qc.swap(0, 1)
|
||
qc.cx(2, 1)
|
||
```
|
||
|
||
then the return from this function would be a list of:
|
||
|
||
```python
|
||
[2, 0, 1]
|
||
```
|
||
|
||
because qubit 0 in the original circuit’s final state is on qubit 3 in the output circuit, qubit 1 in the original circuit’s final state is on qubit 0, and qubit 2’s final state is on qubit. 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 "(in Python v3.12)")) – 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/typing.html#typing.List "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]
|
||
</Function>
|
||
|
||
### final\_virtual\_layout
|
||
|
||
<Function id="qiskit.transpiler.TranspileLayout.final_virtual_layout" signature="final_virtual_layout(filter_ancillas=True)">
|
||
Generate the final layout as a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object
|
||
|
||
This method will generate an array of final positions for each qubit in the output 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)
|
||
qc.h(2)
|
||
qc.cx(2, 1)
|
||
qc.swap(0, 1)
|
||
qc.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,
|
||
})
|
||
```
|
||
|
||
because qubit 0 in the original circuit’s final state is on qubit 3 in the output circuit, qubit 1 in the original circuit’s final state is on qubit 0, and qubit 2’s final state is on qubit. 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 "(in Python v3.12)")) – 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*](qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout")
|
||
</Function>
|
||
|
||
### initial\_index\_layout
|
||
|
||
<Function id="qiskit.transpiler.TranspileLayout.initial_index_layout" signature="initial_index_layout(filter_ancillas=False)">
|
||
Generate an initial layout as an array of integers
|
||
|
||
**Parameters**
|
||
|
||
**filter\_ancillas** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.12)")) – 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/typing.html#typing.List "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]
|
||
</Function>
|
||
|
||
### initial\_virtual\_layout
|
||
|
||
<Function id="qiskit.transpiler.TranspileLayout.initial_virtual_layout" signature="initial_virtual_layout(filter_ancillas=False)">
|
||
Return a [`Layout`](qiskit.transpiler.Layout "qiskit.transpiler.Layout") object for the initial layout.
|
||
|
||
This returns a mapping of virtual [`Qubit`](qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects in the input circuit to the physical qubit 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 "(in Python v3.12)")) – 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`](qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects to the selected physical qubits.
|
||
|
||
**Return type**
|
||
|
||
[*Layout*](qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout")
|
||
</Function>
|
||
|
||
### routing\_permutation
|
||
|
||
<Function id="qiskit.transpiler.TranspileLayout.routing_permutation" signature="routing_permutation()">
|
||
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]` to indicate this
|
||
|
||
**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/typing.html#typing.List "(in Python v3.12)")\[[int](https://docs.python.org/3/library/functions.html#int "(in Python v3.12)")]
|
||
</Function>
|
||
</Class>
|
||
|