qiskit-documentation/docs/api/qiskit/1.2/qiskit.transpiler.Layout.mdx

---
title: Layout (v1.2)
description: API reference for qiskit.transpiler.Layout in qiskit v1.2
in_page_toc_min_heading_level: 1
python_api_type: class
python_api_name: qiskit.transpiler.Layout
---

# Layout

<Class id="qiskit.transpiler.Layout" isDedicatedPage={true} github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L30-L439" signature="qiskit.transpiler.Layout(input_dict=None)" modifiers="class">
  Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.13)")

  Two-ways dict to represent a Layout.

  construct a Layout from a bijective dictionary, mapping virtual qubits to physical qubits

  ## Methods

  ### add

  <Function id="qiskit.transpiler.Layout.add" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L161-L184" signature="add(virtual_bit, physical_bit=None)">
    Adds a map element between bit and physical\_bit. If physical\_bit is not defined, bit will be mapped to a new physical bit.

    **Parameters**

    *   **virtual\_bit** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")) – A (qu)bit. For example, (QuantumRegister(3, ‘qr’), 2).
    *   **physical\_bit** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – A physical bit. For example, 3.
  </Function>

  ### add\_register

  <Function id="qiskit.transpiler.Layout.add_register" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L186-L195" signature="add_register(reg)">
    Adds at the end physical\_qubits that map each bit in reg.

    **Parameters**

    **reg** ([*Register*](circuit#qiskit.circuit.Register "qiskit.circuit.Register")) – A (qu)bit Register. For example, QuantumRegister(3, ‘qr’).
  </Function>

  ### combine\_into\_edge\_map

  <Function id="qiskit.transpiler.Layout.combine_into_edge_map" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L234-L264" signature="combine_into_edge_map(another_layout)">
    Combines self and another\_layout into an “edge map”.

    For example:

    ```python
       self       another_layout  resulting edge map
    qr_1 -> 0        0 <- q_2         qr_1 -> q_2
    qr_2 -> 2        2 <- q_1         qr_2 -> q_1
    qr_3 -> 3        3 <- q_0         qr_3 -> q_0
    ```

    The edge map is used to compose dags via, for example, compose.

    **Parameters**

    **another\_layout** ([*Layout*](#qiskit.transpiler.Layout "qiskit.transpiler.Layout")) – The other layout to combine.

    **Returns**

    A “edge map”.

    **Return type**

    [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")

    **Raises**

    [**LayoutError**](transpiler#qiskit.transpiler.LayoutError "qiskit.transpiler.LayoutError") – another\_layout can be bigger than self, but not smaller. Otherwise, raises.
  </Function>

  ### compose

  <Function id="qiskit.transpiler.Layout.compose" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L371-L389" signature="compose(other, qubits)">
    Compose this layout with another layout.

    If this layout represents a mapping from the P-qubits to the positions of the Q-qubits, and the other layout represents a mapping from the Q-qubits to the positions of the R-qubits, then the composed layout represents a mapping from the P-qubits to the positions of the R-qubits.

    **Parameters**

    *   **other** ([*Layout*](#qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout")) – The existing [`Layout`](#qiskit.transpiler.Layout "qiskit.transpiler.Layout") to compose this [`Layout`](#qiskit.transpiler.Layout "qiskit.transpiler.Layout") with.
    *   **qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit")*]*) – A list of [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects over which `other` is defined, used to establish the correspondence between the positions of the `other` qubits and the actual qubits.

    **Returns**

    A new layout object the represents this layout composed with the `other` layout.

    **Return type**

    [*Layout*](#qiskit.transpiler.Layout "qiskit.transpiler.layout.Layout")
  </Function>

  ### copy

  <Function id="qiskit.transpiler.Layout.copy" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L151-L159" signature="copy()">
    Returns a copy of a Layout instance.
  </Function>

  ### from\_dict

  <Function id="qiskit.transpiler.Layout.from_dict" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L55-L88" signature="from_dict(input_dict)">
    Populates a Layout from a dictionary.

    The dictionary must be a bijective mapping between virtual qubits (tuple) and physical qubits (int).

    **Parameters**

    **input\_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.13)")) –

    e.g.:

    ```python
    {(QuantumRegister(3, 'qr'), 0): 0,
     (QuantumRegister(3, 'qr'), 1): 1,
     (QuantumRegister(3, 'qr'), 2): 2}

    Can be written more concisely as follows:

    * virtual to physical::

        {qr[0]: 0,
         qr[1]: 1,
         qr[2]: 2}

    * physical to virtual::

        {0: qr[0],
         1: qr[1],
         2: qr[2]}
    ```
  </Function>

  ### from\_intlist

  <Function id="qiskit.transpiler.Layout.from_intlist" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L303-L339" signature="from_intlist(int_list, *qregs)" modifiers="static">
    Converts a list of integers to a Layout mapping virtual qubits (index of the list) to physical qubits (the list values).

    **Parameters**

    *   **int\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – A list of integers.
    *   **\*qregs** (*QuantumRegisters*) – The quantum registers to apply the layout to.

    **Returns**

    The corresponding Layout object.

    **Return type**

    [Layout](#qiskit.transpiler.Layout "qiskit.transpiler.Layout")

    **Raises**

    [**LayoutError**](transpiler#qiskit.transpiler.LayoutError "qiskit.transpiler.LayoutError") – Invalid input layout.
  </Function>

  ### from\_qubit\_list

  <Function id="qiskit.transpiler.Layout.from_qubit_list" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L341-L369" signature="from_qubit_list(qubit_list, *qregs)" modifiers="static">
    Populates a Layout from a list containing virtual qubits, Qubit or None.

    **Parameters**

    *   **qubit\_list** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")) – e.g.: \[qr\[0], None, qr\[2], qr\[3]]
    *   **\*qregs** (*QuantumRegisters*) – The quantum registers to apply the layout to.

    **Returns**

    the corresponding Layout object

    **Return type**

    [Layout](#qiskit.transpiler.Layout "qiskit.transpiler.Layout")

    **Raises**

    [**LayoutError**](transpiler#qiskit.transpiler.LayoutError "qiskit.transpiler.LayoutError") – If the elements are not Qubit or None
  </Function>

  ### generate\_trivial\_layout

  <Function id="qiskit.transpiler.Layout.generate_trivial_layout" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L286-L301" signature="generate_trivial_layout(*regs)" modifiers="static">
    Creates a trivial (“one-to-one”) Layout with the registers and qubits in regs.

    **Parameters**

    **\*regs** (*Registers, Qubits*) – registers and qubits to include in the layout.

    **Returns**

    A layout with all the regs in the given order.

    **Return type**

    [Layout](#qiskit.transpiler.Layout "qiskit.transpiler.Layout")
  </Function>

  ### get\_physical\_bits

  <Function id="qiskit.transpiler.Layout.get_physical_bits" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L212-L217" signature="get_physical_bits()">
    Returns the dictionary where the keys are physical (qu)bits and the values are virtual (qu)bits.
  </Function>

  ### get\_registers

  <Function id="qiskit.transpiler.Layout.get_registers" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L197-L203" signature="get_registers()">
    Returns the registers in the layout \[QuantumRegister(2, ‘qr0’), QuantumRegister(3, ‘qr1’)] :returns: A set of Registers in the layout :rtype: Set
  </Function>

  ### get\_virtual\_bits

  <Function id="qiskit.transpiler.Layout.get_virtual_bits" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L205-L210" signature="get_virtual_bits()">
    Returns the dictionary where the keys are virtual (qu)bits and the values are physical (qu)bits.
  </Function>

  ### inverse

  <Function id="qiskit.transpiler.Layout.inverse" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L391-L416" signature="inverse(source_qubits, target_qubits)">
    Finds the inverse of this layout.

    This is possible when the layout is a bijective mapping, however the input and the output qubits may be different (in particular, this layout may be the mapping from the extended-with-ancillas virtual qubits to physical qubits). Thus, if this layout represents a mapping from the P-qubits to the positions of the Q-qubits, the inverse layout represents a mapping from the Q-qubits to the positions of the P-qubits.

    **Parameters**

    *   **source\_qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit")*]*) – A list of [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects representing the domain of the layout.
    *   **target\_qubits** ([*List*](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.13)")*\[*[*Qubit*](circuit#qiskit.circuit.Qubit "qiskit.circuit.quantumregister.Qubit")*]*) – A list of [`Qubit`](circuit#qiskit.circuit.Qubit "qiskit.circuit.Qubit") objects representing the image of the layout.

    **Returns**

    A new layout object the represents the inverse of this layout.
  </Function>

  ### order\_based\_on\_type

  <Function id="qiskit.transpiler.Layout.order_based_on_type" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L90-L104" signature="order_based_on_type(value1, value2)" modifiers="static">
    decides which one is physical/virtual based on the type. Returns (virtual, physical)
  </Function>

  ### reorder\_bits

  <Function id="qiskit.transpiler.Layout.reorder_bits" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L266-L284" signature="reorder_bits(bits)">
    Given an ordered list of bits, reorder them according to this layout.

    The list of bits must exactly match the virtual bits in this layout.

    **Parameters**

    **bits** ([*list*](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.13)")*\[*[*Bit*](circuit#qiskit.circuit.Bit "qiskit.circuit.Bit")*]*) – the bits to reorder.

    **Returns**

    ordered bits.

    **Return type**

    List
  </Function>

  ### swap

  <Function id="qiskit.transpiler.Layout.swap" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L219-L232" signature="swap(left, right)">
    Swaps the map between left and right.

    **Parameters**

    *   **left** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")  *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – Item to swap with right.
    *   **right** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple "(in Python v3.13)")  *or*[*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.13)")) – Item to swap with left.

    **Raises**

    [**LayoutError**](transpiler#qiskit.transpiler.LayoutError "qiskit.transpiler.LayoutError") – If left and right have not the same type.
  </Function>

  ### to\_permutation

  <Function id="qiskit.transpiler.Layout.to_permutation" github="https://github.com/Qiskit/qiskit/tree/stable/1.2/qiskit/transpiler/layout.py#L418-L439" signature="to_permutation(qubits)">
    Creates a permutation corresponding to this layout.

    This is possible when the layout is a bijective mapping with the same source and target qubits (for instance, a “final\_layout” corresponds to a permutation of the physical circuit qubits). If this layout is a mapping from qubits to their new positions, the resulting permutation describes which qubits occupy the positions 0, 1, 2, etc. after applying the permutation.

    For example, suppose that the list of qubits is `[qr_0, qr_1, qr_2]`, and the layout maps `qr_0` to `2`, `qr_1` to `0`, and `qr_2` to `1`. In terms of positions in `qubits`, this maps `0` to `2`, `1` to `0` and `2` to `1`, with the corresponding permutation being `[1, 2, 0]`.
  </Function>
</Class>