TranspileLayout
class qiskit.transpiler.TranspileLayout(initial_layout, input_qubit_mapping, final_layout=None, _input_qubit_count=None, _output_qubit_list=None)
Bases: object
Layout attributes for the output circuit from transpiler.
The 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. The final layout permutation is caused by SwapGate insertion during the Routing Stage. 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:
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")
Suppose that during the layout stage the transpiler reorders the qubits to be:
from qiskit import QuantumCircuit
qc = QuantumCircuit(3)
qc.h(2)
qc.cx(2, 1)
qc.cx(2, 0)
qc.draw("mpl")
Then the output of the initial_virtual_layout() method is equivalent to:
Layout({
qr[0]: 2,
qr[1]: 1,
qr[2]: 0,
})(it is also this attribute in the QuantumCircuit.draw() and 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:
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")
Then the output of the routing_permutation() method is:
[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- This attribute is used to model the permutation caused by the Layout Stage. It is aLayoutobject that maps the inputQuantumCircuitsQubitobjects to the position in the outputQuantumCircuit.qubitslist.input_qubit_mapping- This attribute is used to retain input ordering of the originalQuantumCircuitobject. It maps the virtualQubitobject from the original circuit (andinitial_layout) to its corresponding position inQuantumCircuit.qubitsin the original circuit. This is needed when computing the permutation of theOperatorof the circuit (and used byOperator.from_circuit()).final_layout- This attribute is used to model the permutation caused by the Routing Stage. It is aLayoutobject that maps the output circuit’s qubits fromQuantumCircuit.qubitsin the output circuit to their final positions after routing. Importantly, this only represents the permutation caused by insertingSwapGates into theQuantumCircuitduring the Routing Stage. 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 thefinal_index_layout()to generate this. Iffinal_layoutis set toNone, this indicates that routing was not run, and can be considered equivalent to a trivial layout with the qubits from the output circuit’squbitslist.
Attributes
Parameters
- initial_layout (Layout) –
- input_qubit_mapping (dict[circuit.Qubit, int]) –
- final_layout (Layout | None) –
- _input_qubit_count (int | None) –
- _output_qubit_list (List[Qubit] | None) –
final_layout
Type: Layout | None
Default value: None
initial_layout
Type: Layout
input_qubit_mapping
Type: dict[circuit.Qubit, int]
Methods
final_index_layout
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 input circuit. For example, if you had an input circuit like:
qc = QuantumCircuit(3)
qc.h(0)
qc.cx(0, 1)
qc.cx(0, 2)and the output from the transpiler was:
tqc = QuantumCircuit(3)
tqc.h(2)
tqc.cx(2, 1)
tqc.swap(0, 1)
tqc.cx(2, 1)then the final_index_layout() method returns:
[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) – 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
final_virtual_layout
final_virtual_layout(filter_ancillas=True)
Generate the final layout as a 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:
qc = QuantumCircuit(3)
qc.h(0)
qc.cx(0, 1)
qc.cx(0, 2)and the output from the transpiler was:
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:
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) – 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
initial_index_layout
initial_index_layout(filter_ancillas=False)
Generate an initial layout as an array of integers.
Parameters
filter_ancillas (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
initial_virtual_layout
initial_virtual_layout(filter_ancillas=False)
Return a Layout object for the initial layout.
This returns a mapping of virtual Qubit objects in the input circuit to the positions of the physical qubits selected during layout. This is analogous to the initial_layout attribute.
Parameters
filter_ancillas (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 objects to the positions of the selected physical qubits.
Return type
routing_permutation
routing_permutation()
Generate a final layout as an array of integers.
If there is no 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