438 lines
15 KiB
Plaintext
438 lines
15 KiB
Plaintext
---
|
||
title: CouplingMap
|
||
description: API reference for qiskit.transpiler.CouplingMap
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.transpiler.CouplingMap
|
||
---
|
||
|
||
# CouplingMap
|
||
|
||
<Class id="qiskit.transpiler.CouplingMap" isDedicatedPage={true} github="https://github.com/qiskit/qiskit/tree/stable/0.24/qiskit/transpiler/coupling.py" signature="CouplingMap(couplinglist=None, description=None)" modifiers="class">
|
||
Bases: `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 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*) – A string to describe the coupling map.
|
||
|
||
## Methods
|
||
|
||
<span id="qiskit-transpiler-couplingmap-add-edge" />
|
||
|
||
### add\_edge
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.add_edge" signature="CouplingMap.add_edge(src, dst)">
|
||
Add directed edge to coupling graph.
|
||
|
||
src (int): source physical qubit dst (int): destination physical qubit
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-add-physical-qubit" />
|
||
|
||
### add\_physical\_qubit
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.add_physical_qubit" signature="CouplingMap.add_physical_qubit(physical_qubit)">
|
||
Add a physical qubit to the coupling graph as a node.
|
||
|
||
physical\_qubit (int): An integer representing a physical qubit.
|
||
|
||
**Raises**
|
||
|
||
**CouplingError** – if trying to add duplicate qubit
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-compute-distance-matrix" />
|
||
|
||
### compute\_distance\_matrix
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.compute_distance_matrix" signature="CouplingMap.compute_distance_matrix()">
|
||
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.
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-connected-components" />
|
||
|
||
### connected\_components
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.connected_components" signature="CouplingMap.connected_components()">
|
||
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 enables 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
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-distance" />
|
||
|
||
### distance
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.distance" signature="CouplingMap.distance(physical_qubit1, physical_qubit2)">
|
||
Returns the undirected distance between physical\_qubit1 and physical\_qubit2.
|
||
|
||
**Parameters**
|
||
|
||
* **physical\_qubit1** (*int*) – A physical qubit
|
||
* **physical\_qubit2** (*int*) – Another physical qubit
|
||
|
||
**Returns**
|
||
|
||
The undirected distance
|
||
|
||
**Return type**
|
||
|
||
int
|
||
|
||
**Raises**
|
||
|
||
**CouplingError** – if the qubits do not exist in the CouplingMap
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-draw" />
|
||
|
||
### draw
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.draw" signature="CouplingMap.draw()">
|
||
Draws the coupling map.
|
||
|
||
This function calls the [`graphviz_draw()`](https://qiskit.org/ecosystem/rustworkx/apiref/rustworkx.visualization.graphviz_draw.html#rustworkx.visualization.graphviz_draw "(in rustworkx v0.13.1)") function from the `rustworkx` package to draw the [`CouplingMap`](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap") object.
|
||
|
||
**Returns**
|
||
|
||
Drawn coupling map.
|
||
|
||
**Return type**
|
||
|
||
PIL.Image
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-from-full" />
|
||
|
||
### from\_full
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.from_full" signature="CouplingMap.from_full(num_qubits, bidirectional=True)" modifiers="classmethod">
|
||
Return a fully connected coupling map on n qubits.
|
||
|
||
**Return type**
|
||
|
||
[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap")
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-from-grid" />
|
||
|
||
### from\_grid
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.from_grid" signature="CouplingMap.from_grid(num_rows, num_columns, bidirectional=True)" modifiers="classmethod">
|
||
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")
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-from-heavy-hex" />
|
||
|
||
### from\_heavy\_hex
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.from_heavy_hex" signature="CouplingMap.from_heavy_hex(distance, bidirectional=True)" modifiers="classmethod">
|
||
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*) – 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*) – 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")
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-from-heavy-square" />
|
||
|
||
### from\_heavy\_square
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.from_heavy_square" signature="CouplingMap.from_heavy_square(distance, bidirectional=True)" modifiers="classmethod">
|
||
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*) – 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*) – 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")
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-from-hexagonal-lattice" />
|
||
|
||
### from\_hexagonal\_lattice
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.from_hexagonal_lattice" signature="CouplingMap.from_hexagonal_lattice(rows, cols, bidirectional=True)" modifiers="classmethod">
|
||
Return a hexagonal lattice graph coupling map.
|
||
|
||
**Parameters**
|
||
|
||
* **rows** (*int*) – The number of rows to generate the graph with.
|
||
* **cols** (*int*) – The number of columns to generate the graph with.
|
||
* **bidirectional** (*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")
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-from-line" />
|
||
|
||
### from\_line
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.from_line" signature="CouplingMap.from_line(num_qubits, bidirectional=True)" modifiers="classmethod">
|
||
Return a coupling map of n qubits connected in a line.
|
||
|
||
**Return type**
|
||
|
||
[*CouplingMap*](qiskit.transpiler.CouplingMap "qiskit.transpiler.coupling.CouplingMap")
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-from-ring" />
|
||
|
||
### from\_ring
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.from_ring" signature="CouplingMap.from_ring(num_qubits, bidirectional=True)" modifiers="classmethod">
|
||
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")
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-get-edges" />
|
||
|
||
### get\_edges
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.get_edges" signature="CouplingMap.get_edges()">
|
||
Gets the list of edges in the coupling graph.
|
||
|
||
**Returns**
|
||
|
||
Each edge is a pair of physical qubits.
|
||
|
||
**Return type**
|
||
|
||
Tuple(int,int)
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-is-connected" />
|
||
|
||
### is\_connected
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.is_connected" signature="CouplingMap.is_connected()">
|
||
Test if the graph is connected.
|
||
|
||
Return True if connected, False otherwise
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-largest-connected-component" />
|
||
|
||
### largest\_connected\_component
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.largest_connected_component" signature="CouplingMap.largest_connected_component()">
|
||
Return a set of qubits in the largest connected component.
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-make-symmetric" />
|
||
|
||
### make\_symmetric
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.make_symmetric" signature="CouplingMap.make_symmetric()">
|
||
Convert uni-directional edges into bi-directional.
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-neighbors" />
|
||
|
||
### neighbors
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.neighbors" signature="CouplingMap.neighbors(physical_qubit)">
|
||
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.
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-reduce" />
|
||
|
||
### reduce
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.reduce" signature="CouplingMap.reduce(mapping)">
|
||
Returns a reduced coupling map that corresponds to the subgraph of qubits selected in the mapping.
|
||
|
||
**Parameters**
|
||
|
||
**mapping** (*list*) – A mapping of reduced qubits to device qubits.
|
||
|
||
**Returns**
|
||
|
||
A reduced coupling\_map for the selected qubits.
|
||
|
||
**Return type**
|
||
|
||
[CouplingMap](qiskit.transpiler.CouplingMap "qiskit.transpiler.CouplingMap")
|
||
|
||
**Raises**
|
||
|
||
**CouplingError** – Reduced coupling map must be connected.
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-shortest-undirected-path" />
|
||
|
||
### shortest\_undirected\_path
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.shortest_undirected_path" signature="CouplingMap.shortest_undirected_path(physical_qubit1, physical_qubit2)">
|
||
Returns the shortest undirected path between physical\_qubit1 and physical\_qubit2.
|
||
|
||
**Parameters**
|
||
|
||
* **physical\_qubit1** (*int*) – A physical qubit
|
||
* **physical\_qubit2** (*int*) – Another physical qubit
|
||
|
||
**Returns**
|
||
|
||
The shortest undirected path
|
||
|
||
**Return type**
|
||
|
||
List
|
||
|
||
**Raises**
|
||
|
||
**CouplingError** – When there is no path between physical\_qubit1, physical\_qubit2.
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-size" />
|
||
|
||
### size
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.size" signature="CouplingMap.size()">
|
||
Return the number of physical qubits in this graph.
|
||
</Function>
|
||
|
||
<span id="qiskit-transpiler-couplingmap-subgraph" />
|
||
|
||
### subgraph
|
||
|
||
<Function id="qiskit.transpiler.CouplingMap.subgraph" signature="CouplingMap.subgraph(nodelist)">
|
||
Return a CouplingMap object for a subgraph of self.
|
||
|
||
nodelist (list): list of integer node labels
|
||
|
||
<Admonition title="Deprecated since version 0.20.0" type="danger">
|
||
The method `qiskit.transpiler.coupling.CouplingMap.subgraph()` is deprecated as of qiskit-terra 0.20.0. It will be removed no earlier than 3 months after the release date. Instead, use [`reduce()`](qiskit.transpiler.CouplingMap#reduce "qiskit.transpiler.CouplingMap.reduce"). It does the same thing, but preserves nodelist order.
|
||
</Admonition>
|
||
</Function>
|
||
|
||
## Attributes
|
||
|
||
### description
|
||
|
||
<Attribute id="qiskit.transpiler.CouplingMap.description" />
|
||
|
||
### graph
|
||
|
||
<Attribute id="qiskit.transpiler.CouplingMap.graph" />
|
||
|
||
### distance\_matrix
|
||
|
||
<Attribute id="qiskit.transpiler.CouplingMap.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`.
|
||
</Attribute>
|
||
|
||
### is\_symmetric
|
||
|
||
<Attribute id="qiskit.transpiler.CouplingMap.is_symmetric">
|
||
Test if the graph is symmetric.
|
||
|
||
Return True if symmetric, False otherwise
|
||
</Attribute>
|
||
|
||
### physical\_qubits
|
||
|
||
<Attribute id="qiskit.transpiler.CouplingMap.physical_qubits">
|
||
Returns a sorted list of physical\_qubits
|
||
</Attribute>
|
||
</Class>
|
||
|