qat.experimental.system_data.topology module

Topology view assembled from canonical system data.

class ScipyTopologyView(adjacency_matrix, gate_fidelity_matrices)

Bases: object

Topology view derived from canonical data as SciPy CSR matrices, as well as further allowing for return to a NetworkX graph representation.

The derived view stores binary logical connectivity and per-gate fidelity matrices.

Variables:

  • adjacency_matrix – Binary directed adjacency matrix (1 if logically connected, no entry otherwise).

  • gate_fidelity_matrices – Mapping from gate name to directed fidelity matrix. Each matrix uses per-gate sparsity and only stores directed edges where that gate is available.

adjacency_matrix: csr_matrix
classmethod from_derived(canonical_graph)

Constructs a ScipyTopologyView from canonical graph data.

Parameters:

canonical_graph (TopologyView) – Topology view to convert.

Return type:

ScipyTopologyView

Returns:

Derived view with binary adjacency and per-gate fidelity matrices.

gate_fidelity_matrices: Mapping[str, csr_matrix]
property networkx_graph: DiGraph

Return a deep copy of the cached NetworkX graph.

The internal graph is computed once on first access and cached. Each call returns a new deep copy so the caller may freely mutate the returned graph without affecting the cached original.

Node labels are integer row indices. Edge metadata includes per-gate fidelity attributes for available gates.

Returns:

Mutable deep copy of the directed graph.

class TopologyView(indptr, indices, node_ids, node_index, edge_couplings_data, edge_metadata)

Bases: DerivedViewInterface

Minimal canonical topology view encoded in a CSR-like graph structure.

Connectivity is stored structurally by indptr and indices. Here, n_rows == n_qubits (one row per source qubit), and the implied adjacency/fidelity matrix is square with shape (n_qubits, n_qubits). For a source row row, the destination rows for outgoing directed couplings are indices[indptr[row]:indptr[row + 1]]. These entries indicate logical qubit connectivity.

For example, with node rows 0 -> q0, 1 -> q1, 2 -> q2 and directed couplings q0 -> q1, q0 -> q2, q1 -> q2:

  • indptr = [0, 2, 3, 3]

  • indices = [1, 2, 2]

This means:

  • row 0 spans indices[indptr[0]:indptr[1]] == indices[0:2] == [1, 2]

    -> q0 connects to q1 and q2

  • row 1 spans indices[indptr[1]:indptr[2]] == indices[2:3] == [2]

    -> q1 connects to q2

  • row 2 spans indices[indptr[2]:indptr[3]] == indices[3:3] == []

    -> q2 has no outgoing couplings

This representation intentionally keeps only topology-relevant canonical content.

Variables:

  • indptr – CSR row pointer array of length n_qubits + 1.

  • indices – CSR destination-row indices for each structural non-zero entry.

  • edge_couplings_data – Per-edge fidelity values in CSR edge order.

  • edge_metadata – Per-edge gate-label entries aligned with edge_couplings_data and CSR edge order.

  • node_ids – Node identifiers in row order.

  • node_index – Device qubit indices in row order.

  • row_by_node_id – Read-only map from node identifier to row index. Derived from node_ids and computed once on first access. Not accepted as a constructor argument, preventing inconsistent manual construction.

are_coupled(source_qubit_id, target_qubit_id)

Checks whether a directed edge exists from source to target qubit.

Parameters:

  • source_qubit_id (str) – Source qubit identifier.

  • target_qubit_id (str) – Target qubit identifier.

Return type:

bool

Returns:

True if the directed coupling exists, otherwise False.

coupled_qubit_indices(qubit_id)

Returns outgoing neighbour qubit indices for a qubit.

Parameters:

qubit_id (str) – Qubit identifier.

Return type:

tuple[int, ...]

Returns:

Tuple of neighbour qubit indices reachable by outgoing edges.

edge_couplings_data: tuple[tuple[float, ...], ...]
edge_metadata: tuple[tuple[str, ...], ...]
classmethod from_canonical(canonical)

Constructs a TopologyView from a CanonicalSystemData object, for topology relevant data. This is a lightweight representation of the system connectivity, stored as a custom CSR matrix form.

Parameters:

canonical (CanonicalSystemData) – The CanonicalSystemData object to convert.

Return type:

TopologyView

Returns:

Topology view with CSR connectivity and aligned fidelity data with associated metadata.

Raises:

ValueError – If qubit or coupling information is missing.

gate_fidelities_by_type(gate_names=None)

Returns grouped gate fidelities, optionally filtered to selected gate names.

When gate_names is provided, only matching gate types are grouped and sorted, avoiding work for unrelated gate types.

Parameters:

gate_names (Union[set[str], tuple[str, ...], None]) – Optional gate names to include. If None, all gate types are returned.

Return type:

tuple[tuple[str, tuple[tuple[float, tuple[str, str]], ...]], ...]

Returns:

Grouped gate fidelities sorted by gate name and fidelity.

indices: ndarray[tuple[int, ...], dtype[int64]]
indptr: ndarray[tuple[int, ...], dtype[int64]]
property nnz: int

Returns number of non-zero (nnz) entries in this CSR view.

In this topology representation, this equals the number of directed edges.

Returns:

Number of non-zero CSR entries.

node_ids: tuple[str, ...]
node_index: ndarray[tuple[int, ...], dtype[uint32]]
property row_by_node_id: Mapping[str, int]

Read-only map from node identifier to row index, derived from node_ids.

Computed once on first access and cached. Not accepted as a constructor argument to prevent mismatched manual construction such as supplying node ids that contradict the mapping.

Returns:

Immutable mapping from node id to row index.

property sorted_gate_fidelities: tuple[tuple[float, tuple[str, str], str], ...]

Returns all gate fidelities sorted from best to worst.

Each entry is (fidelity, (source_qubit_id, target_qubit_id), gate_name). Sorted in descending order by fidelity (best first).

Returns:

Tuple of (fidelity, qubits, gate_name) entries sorted best to worst, or empty tuple if no gate fidelities exist.

property sorted_gate_fidelities_by_type: tuple[tuple[str, tuple[tuple[float, tuple[str, str]], ...]], ...]

Returns gate fidelities grouped by gate type.

The returned structure is ((gate_name, gate_entries), ...) where each gate_entries is a tuple of (fidelity, (source_qubit_id, target_qubit_id)). Gate groups are sorted alphabetically by gate name, and entries within each gate are sorted in descending fidelity order.

Returns:

Grouped gate fidelities sorted by gate name and fidelity.