--- title: CouplingMap (latest version) description: API reference for qiskit.transpiler.CouplingMap in the latest version of qiskit source: https://quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.transpiler.CouplingMap --- # CouplingMap *class* `qiskit.transpiler.CouplingMap(couplinglist=None, description=None)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L31-L518) Bases: [`object`](https://docs.python.org/3/library/functions.html#object) Directed graph specifying fixed coupling. Nodes correspond to physical qubits (integers) and directed edges correspond to permitted CNOT gates, with source and destination corresponding to control and target qubits, respectively. Create coupling graph. By default, the generated coupling has no nodes. **Parameters** - **couplinglist** ([*list*](https://docs.python.org/3/library/stdtypes.html#list) *or None*) – An initial coupling graph, specified as an adjacency list containing couplings, e.g. \[\[0,1], \[0,2], \[1,2]]. It is required that nodes are contiguously indexed starting at 0. Missed nodes will be added as isolated nodes in the coupling map. - **description** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – A string to describe the coupling map. ## Attributes ### description ### graph ### distance\_matrix Return the distance matrix for the coupling map. For any qubits where there isn’t a path available between them the value in this position of the distance matrix will be `math.inf`. ### is\_symmetric Test if the graph is symmetric. Return True if symmetric, False otherwise ### physical\_qubits Returns a sorted list of physical\_qubits ## Methods ### add\_edge `add_edge(src, dst)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L117-L133) Add directed edge to coupling graph. src (int): source physical qubit dst (int): destination physical qubit ### add\_physical\_qubit `add_physical_qubit(physical_qubit)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L98-L115) Add a physical qubit to the coupling graph as a node. physical\_qubit (int): An integer representing a physical qubit. **Raises** [**CouplingError**](/docs/api/qiskit/transpiler#qiskit.transpiler.CouplingError "qiskit.transpiler.CouplingError") – if trying to add duplicate qubit ### compute\_distance\_matrix `compute_distance_matrix()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L171-L184) Compute the full distance matrix on pairs of nodes. The distance map self.\_dist\_matrix is computed from the graph using all\_pairs\_shortest\_path\_length. This is normally handled internally by the [`distance_matrix`](#qiskit.transpiler.CouplingMap.distance_matrix "qiskit.transpiler.CouplingMap.distance_matrix") attribute or the [`distance()`](#qiskit.transpiler.CouplingMap.distance "qiskit.transpiler.CouplingMap.distance") method but can be called if you’re accessing the distance matrix outside of those or want to pre-generate it. ### connected\_components `connected_components()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L413-L471) Separate a [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") into subgraph [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") for each connected component. The connected components of a [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") are the subgraphs that are not part of any larger subgraph. For example, if you had a coupling map that looked like: ```python 0 --> 1 4 --> 5 ---> 6 --> 7 | | | | V V 2 --> 3 ``` then the connected components of that graph are the subgraphs: ```python 0 --> 1 | | | | V V 2 --> 3 ``` and: ```python 4 --> 5 ---> 6 --> 7 ``` For a connected [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object there is only a single connected component, the entire [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap"). This method will return a list of [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") objects, one for each connected component in this [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap"). The data payload of each node in the [`graph`](#qiskit.transpiler.CouplingMap.graph "qiskit.transpiler.CouplingMap.graph") attribute will contain the qubit number in the original graph. This will enable mapping the qubit index in a component subgraph to the original qubit in the combined [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap"). For example: ```python from qiskit.transpiler import CouplingMap cmap = CouplingMap([[0, 1], [1, 2], [2, 0], [3, 4], [4, 5], [5, 3]]) component_cmaps = cmap.connected_components() print(component_cmaps[1].graph[0]) ``` will print `3` as index `0` in the second component is qubit 3 in the original cmap. **Returns** **A list of [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") objects for each connected** components. The order of this list is deterministic but implementation specific and shouldn’t be relied upon as part of the API. **Return type** [list](https://docs.python.org/3/library/stdtypes.html#list) ### distance `distance(physical_qubit1, physical_qubit2)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L186-L207) Returns the undirected distance between physical\_qubit1 and physical\_qubit2. **Parameters** - **physical\_qubit1** ([*int*](https://docs.python.org/3/library/functions.html#int)) – A physical qubit - **physical\_qubit2** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Another physical qubit **Returns** The undirected distance **Return type** [int](https://docs.python.org/3/library/functions.html#int) **Raises** [**CouplingError**](/docs/api/qiskit/transpiler#qiskit.transpiler.CouplingError "qiskit.transpiler.CouplingError") – if the qubits do not exist in the CouplingMap ### draw `draw(method='neato')` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L498-L518) Draws the coupling map. This function calls the [`graphviz_draw()`](https://www.rustworkx.org/apiref/rustworkx.visualization.graphviz_draw.html#rustworkx.visualization.graphviz_draw) function from the `rustworkx` package to draw the [`CouplingMap`](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object. > **Warning** > > This function will call the system Graphviz tool on a file involving user-controllable strings (such as qubit objects). It is recommended to only call this function on trusted input. **Parameters** **method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – The layout method to use. See the documentation for [`graphviz_draw()`](https://www.rustworkx.org/apiref/rustworkx.visualization.graphviz_draw.html#rustworkx.visualization.graphviz_draw) for the list of supported methods **Returns** Drawn coupling map. **Return type** PIL.Image ### from\_full *classmethod* `from_full(num_qubits, bidirectional=True)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L303-L315) Return a fully connected coupling map on n qubits. **Return type** [*CouplingMap*](#qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") ### from\_grid *classmethod* `from_grid(num_rows, num_columns, bidirectional=True)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L331-L338) Return a coupling map of qubits connected on a grid of num\_rows x num\_columns. **Return type** [*CouplingMap*](#qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") ### from\_heavy\_hex *classmethod* `from_heavy_hex(distance, bidirectional=True)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L340-L362) Return a heavy hexagon graph coupling map. A heavy hexagon graph is described in: [https://journals.aps.org/prx/abstract/10.1103/PhysRevX.10.011022](https://journals.aps.org/prx/abstract/10.1103/PhysRevX.10.011022) **Parameters** - **distance** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The code distance for the generated heavy hex graph. The value for distance can be any odd positive integer. The distance relates to the number of qubits by: $n = \frac{5d^2 - 2d - 1}{2}$ where $n$ is the number of qubits and $d$ is the `distance` parameter. - **bidirectional** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – Whether the edges in the output coupling graph are bidirectional or not. By default this is set to `True` **Returns** A heavy hex coupling graph **Return type** [CouplingMap](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") ### from\_heavy\_square *classmethod* `from_heavy_square(distance, bidirectional=True)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L364-L388) Return a heavy square graph coupling map. A heavy square graph is described in: [https://journals.aps.org/prx/abstract/10.1103/PhysRevX.10.011022](https://journals.aps.org/prx/abstract/10.1103/PhysRevX.10.011022) **Parameters** - **distance** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The code distance for the generated heavy square graph. The value for distance can be any odd positive integer. The distance relates to the number of qubits by: $n = 3d^2 - 2d$ where $n$ is the number of qubits and $d$ is the `distance` parameter. - **bidirectional** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – Whether the edges in the output coupling graph are bidirectional or not. By default this is set to `True` **Returns** A heavy square coupling graph **Return type** [CouplingMap](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") ### from\_hexagonal\_lattice *classmethod* `from_hexagonal_lattice(rows, cols, bidirectional=True)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L390-L407) Return a hexagonal lattice graph coupling map. **Parameters** - **rows** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The number of rows to generate the graph with. - **cols** ([*int*](https://docs.python.org/3/library/functions.html#int)) – The number of columns to generate the graph with. - **bidirectional** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – Whether the edges in the output coupling graph are bidirectional or not. By default this is set to `True` **Returns** A hexagonal lattice coupling graph **Return type** [CouplingMap](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") ### from\_line *classmethod* `from_line(num_qubits, bidirectional=True)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L317-L322) Return a coupling map of n qubits connected in a line. **Return type** [*CouplingMap*](#qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") ### from\_ring *classmethod* `from_ring(num_qubits, bidirectional=True)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L324-L329) Return a coupling map of n qubits connected to each of their neighbors in a ring. **Return type** [*CouplingMap*](#qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap") ### get\_edges `get_edges()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L86-L93) Gets the list of edges in the coupling graph. **Returns** Each edge is a pair of physical qubits. **Return type** Tuple([int](https://docs.python.org/3/library/functions.html#int),[int](https://docs.python.org/3/library/functions.html#int)) ### is\_connected `is_connected()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L142-L151) Test if the graph is connected. Return True if connected, False otherwise ### largest\_connected\_component `largest_connected_component()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L409-L411) Return a set of qubits in the largest connected component. ### make\_symmetric `make_symmetric()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L240-L252) Convert uni-directional edges into bi-directional. ### neighbors `neighbors(physical_qubit)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L153-L159) Return the nearest neighbors of a physical qubit. Directionality matters, i.e. a neighbor must be reachable by going one hop in the direction of an edge. ### reduce `reduce(mapping, check_if_connected=True)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L263-L301) Returns a reduced coupling map that corresponds to the subgraph of qubits selected in the mapping. **Parameters** - **mapping** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)) – A mapping of reduced qubits to device qubits. - **check\_if\_connected** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – if True, checks that the reduced coupling map is connected. **Returns** A reduced coupling\_map for the selected qubits. **Return type** [CouplingMap](#qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") **Raises** [**CouplingError**](/docs/api/qiskit/transpiler#qiskit.transpiler.CouplingError "qiskit.transpiler.CouplingError") – Reduced coupling map must be connected. ### shortest\_undirected\_path `shortest_undirected_path(physical_qubit1, physical_qubit2)` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L209-L227) Returns the shortest undirected path between physical\_qubit1 and physical\_qubit2. **Parameters** - **physical\_qubit1** ([*int*](https://docs.python.org/3/library/functions.html#int)) – A physical qubit - **physical\_qubit2** ([*int*](https://docs.python.org/3/library/functions.html#int)) – Another physical qubit **Returns** The shortest undirected path **Return type** List **Raises** [**CouplingError**](/docs/api/qiskit/transpiler#qiskit.transpiler.CouplingError "qiskit.transpiler.CouplingError") – When there is no path between physical\_qubit1, physical\_qubit2. ### size `size()` [GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/transpiler/coupling.py#L80-L84) Return the number of physical qubits in this graph.