Coupling Maps

What a Coupling Map Is

A coupling map represents the physical qubit connectivity of a quantum hardware device as a graph. Each node is a physical qubit and each edge represents a connection between two qubits. If an edge exists between qubit 0 and qubit 1, a two-qubit gate can be applied between them in either direction.

Tessera uses coupling maps in two places. DenseLayoutPass uses distances between qubits to decide where to place logical qubits, and BasicSwapRouter uses adjacency to determine where SWAP gates need to be inserted.

TesseraCouplingMap

from tessera.hardware.coupling_map import TesseraCouplingMap

Constructor

TesseraCouplingMap(num_qubits, edges=None)

Parameter	Type	Description
`num_qubits`	`int`	Total number of physical qubits in the coupling map
`edges`	`list[tuple[int, int]] \| None`	List of edges as `(start, end)` tuples. If `None`, the graph has no connections.

Example

from tessera.hardware.coupling_map import TesseraCouplingMap

# 4-qubit linear chain: 0 <-> 1 <-> 2 <-> 3
cm = TesseraCouplingMap(4, [
    (0, 1), (1, 0),
    (1, 2), (2, 1),
    (2, 3), (3, 2)
])

Methods

Method	Description
`add_edge(start, end)`	Add a connection between two qubits
`are_connected(start, end)`	Returns `True` if a connection exists between `start` and `end`
`neighbors(q)`	Returns a list of qubits directly connected to `q`
`shortest_path(start, end)`	Returns the shortest hop path between two qubits as a list of qubit indices
`distance(start, end)`	Returns the number of hops between two qubits
`is_valid_qubit(q)`	Returns `True` if qubit index `q` exists in the coupling map
`edges`	Property that returns all edges as a list of `(start, end)` tuples
`len(cm)`	Returns the number of qubits in the coupling map

Raises: ValueError on shortest_path() and distance() if no path exists between the two qubits or if either qubit index does not exist in the map.

Built-in Coupling Maps

Tessera ships with seven pre-built coupling maps covering all supported backends. These are available as named keys in the coupling map registry and as importable instances.

Full registry

Key	Device	Qubits	Topology
`IBM_DEFAULT`	FakeNairobiV2	7	Heavy-hex
`IBM_BRISBANE`	FakeBrisbane	127	Heavy-hex
`IBM_SHERBROOKE`	FakeSherbrooke	127	Heavy-hex
`IONQ_ARIA`	IonQ Aria	25	All-to-all
`IONQ_FORTE`	IonQ Forte	36	All-to-all
`RIGETTI_ANKAA`	Rigetti Ankaa-2	84	7×12 rectangular grid
`RIGETTI_ANKAA_9Q`	Rigetti Ankaa-9Q-3	9	3×3 rectangular grid

IBM coupling maps are derived from real hardware topologies via Qiskit's fake provider backends. IonQ maps are constructed as complete graphs where every qubit is connected to every other qubit. Rigetti maps are constructed as rectangular grids with horizontal and vertical connections between adjacent qubits.

Using a named key

transpile(qc, backend="IBM", coupling_map="IBM_BRISBANE")

Importing directly

from tessera.backends.coupling_maps import IBM_BRISBANE_COUPLING_MAP, IONQ_ARIA_COUPLING_MAP

Building a Custom Coupling Map

Pass a TesseraCouplingMap instance directly to transpile() to use a topology not covered by the built-in maps. All built-in coupling maps follow the convention of including both (a, b) and (b, a) for every connection so that qubits are reachable from either side. You should follow the same convention when building custom maps.

from tessera.hardware.coupling_map import TesseraCouplingMap
from tessera.api.transpile import transpile

# 3-qubit ring topology
cm = TesseraCouplingMap(3, [
    (0, 1), (1, 0),
    (1, 2), (2, 1),
    (2, 0), (0, 2)
])

transpiled = transpile(qc, backend="IBM", coupling_map=cm)

Note

If your circuit has more qubits than the coupling map supports, transpile() will raise a ValueError before any passes run.

Adding a New Coupling Map to the Registry

If you want a custom coupling map to be referenceable by string key, add it to the registry in tessera/backends/coupling_maps.py and the COUPLING_MAP_REGISTRY dict. See the Adding a Backend guide for a full walkthrough because adding a coupling map follows the same pattern.