Skip to main contentIBM Quantum Documentation
You are viewing the API reference for an old version of Qiskit SDK. Switch to latest version

CouplingMap

CouplingMap(couplinglist=None, description=None) GitHub(opens in a new tab)

Bases: object

Directed graph specifying fixed coupling.

Nodes correspond to physical qubits (integers) and directed edges correspond to permitted CNOT gates

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

add_edge

CouplingMap.add_edge(src, dst)

Add directed edge to coupling graph.

src (int): source physical qubit dst (int): destination physical qubit

add_physical_qubit

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

compute_distance_matrix

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 attribute or the distance() method but can be called if you’re accessing the distance matrix outside of those or want to pre-generate it.

distance

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

draw

CouplingMap.draw()

Draws the coupling map.

This function needs pydot(opens in a new tab), which in turn needs Graphviz(opens in a new tab) to be installed. Additionally, pillow(opens in a new tab) will need to be installed.

Returns

Drawn coupling map.

Return type

PIL.Image

Raises

MissingOptionalLibraryError – when pydot or pillow are not installed.

from_full

classmethod CouplingMap.from_full(num_qubits, bidirectional=True)

Return a fully connected coupling map on n qubits.

Return type

CouplingMap

from_grid

classmethod CouplingMap.from_grid(num_rows, num_columns, bidirectional=True)

Return a coupling map of qubits connected on a grid of num_rows x num_columns.

Return type

CouplingMap

from_heavy_hex

classmethod CouplingMap.from_heavy_hex(distance, bidirectional=True)

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(opens in a new tab)

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=5d22d12n = \frac{5d^2 - 2d - 1}{2} where nn is the number of qubits and dd 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

from_heavy_square

classmethod CouplingMap.from_heavy_square(distance, bidirectional=True)

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(opens in a new tab)

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=3d22dn = 3d^2 - 2d where nn is the number of qubits and dd 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

from_hexagonal_lattice

classmethod CouplingMap.from_hexagonal_lattice(rows, cols, bidirectional=True)

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

from_line

classmethod CouplingMap.from_line(num_qubits, bidirectional=True)

Return a coupling map of n qubits connected in a line.

Return type

CouplingMap

from_ring

classmethod CouplingMap.from_ring(num_qubits, bidirectional=True)

Return a coupling map of n qubits connected to each of their neighbors in a ring.

Return type

CouplingMap

get_edges

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)

is_connected

CouplingMap.is_connected()

Test if the graph is connected.

Return True if connected, False otherwise

largest_connected_component

CouplingMap.largest_connected_component()

Return a set of qubits in the largest connected component.

make_symmetric

CouplingMap.make_symmetric()

Convert uni-directional edges into bi-directional.

neighbors

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.

reduce

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

Raises

CouplingError – Reduced coupling map must be connected.

shortest_undirected_path

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.

size

CouplingMap.size()

Return the number of physical qubits in this graph.

subgraph

CouplingMap.subgraph(nodelist)

Return a CouplingMap object for a subgraph of self.

nodelist (list): list of integer node labels


Attributes

description

distance_matrix

Return the distance matrix for the coupling map.

graph

is_symmetric

Test if the graph is symmetric.

Return True if symmetric, False otherwise

physical_qubits

Returns a sorted list of physical_qubits

Was this page helpful?