Skip to content

qoolqit.graphs

graphs

Graph creation and manipulation in QoolQit.

Modules:

  • base_graph –
  • data_graph –
  • utils –

Classes:

  • BaseGraph –

    The BaseGraph in QoolQit, directly inheriting from the NetworkX Graph.

  • DataGraph –

    The main graph structure to represent problem data.

Functions:

  • all_node_pairs –

    Return all pairs of nodes (u, v) where u < v.

  • distances –

    Return a dictionary of edge distances.

  • random_coords –

    Generate a random set of node coordinates on a square of side L.

  • random_edge_list –

    Generates a random set of k edges linkings items from a set of nodes.

  • scale_coords –

    Scale the coordinates by a given value.

  • space_coords –

    Spaces the coordinates so the minimum distance is equal to a set spacing.

BaseGraph(edges: Iterable = [])

The BaseGraph in QoolQit, directly inheriting from the NetworkX Graph.

Defines basic functionalities for graphs within the Rydberg Analog, such as instantiating from a set of node coordinates, directly accessing node distances, and checking if the graph is unit-disk.

Parameters:

  • edges

    (Iterable, default: [] ) –

    set of edge tuples (i, j)

Methods:

  • distances –

    Returns a dictionary of distances for a given set of edges.

  • draw –

    Draw the graph.

  • from_coordinates –

    Construct a base graph from a set of coordinates.

  • from_nodes –

    Construct a base graph from a set of nodes.

  • from_nx –

    Convert a NetworkX Graph object into a QoolQit graph instance.

  • interactions –

    Rydberg model interaction 1/r^6 between pair of nodes.

  • is_ud_graph –

    Check if the graph is unit-disk.

  • max_distance –

    Returns the maximum distance in the graph.

  • min_distance –

    Returns the minimum distance in the graph.

  • rescale_coords –

    Rescales the node coordinates by a factor.

  • set_ud_edges –

    Reset the set of edges to be equal to the set of unit-disk edges.

  • ud_edges –

    Returns the set of edges given by the intersection of circles of a given radius.

  • ud_radius_range –

    Return the range (R_min, R_max) where the graph is unit-disk.

Attributes:

  • all_node_pairs (set) –

    Return a list of all possible node pairs in the graph.

  • coords (dict) –

    Return the dictionary of node coordinates.

  • has_coords (bool) –

    Check if the graph has coordinates.

  • has_edge_weights (bool) –

    Check if the graph has edge weights.

  • has_edges (bool) –

    Check if the graph has edges.

  • has_node_weights (bool) –

    Check if the graph has node weights.

  • sorted_edges (set) –

    Returns the set of edges (u, v) such that (u < v).

Source code in qoolqit/graphs/base_graph.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def __init__(self, edges: Iterable = []) -> None:
    """
    Default constructor for the BaseGraph.

    Arguments:
        edges: set of edge tuples (i, j)
    """
    if edges and not isinstance(edges, Iterable):
        raise TypeError("Input is not a valid edge list.")

    super().__init__()
    self.add_edges_from(edges)
    self._coords = {i: None for i in self.nodes}
    self._reset_dicts()

all_node_pairs: set property

Return a list of all possible node pairs in the graph.

coords: dict property writable

Return the dictionary of node coordinates.

has_coords: bool property

Check if the graph has coordinates.

Requires all nodes to have coordinates.

has_edge_weights: bool property

Check if the graph has edge weights.

Requires all edges to have a weight.

has_edges: bool property

Check if the graph has edges.

has_node_weights: bool property

Check if the graph has node weights.

Requires all nodes to have a weight.

sorted_edges: set property

Returns the set of edges (u, v) such that (u < v).

distances(edge_list: Iterable | None = None) -> dict

Returns a dictionary of distances for a given set of edges.

Distances are calculated directly from the coordinates. Raises an error if there are no coordinates on the graph.

Parameters:

  • edge_list
    (Iterable | None, default: None ) –

    set of edges.

Source code in qoolqit/graphs/base_graph.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
def distances(self, edge_list: Iterable | None = None) -> dict:
    """Returns a dictionary of distances for a given set of edges.

    Distances are calculated directly from the coordinates. Raises an error
    if there are no coordinates on the graph.

    Arguments:
        edge_list: set of edges.
    """
    if self.has_coords:
        if edge_list is None:
            edge_list = self.all_node_pairs
        elif len(edge_list) == 0:  # type: ignore [arg-type]
            raise ValueError("Trying to compute distances for an empty edge list.")
        return distances(self.coords, edge_list)
    else:
        raise AttributeError("Trying to compute distances for a graph without coordinates.")

draw(ax: Axes | None = None, **kwargs: Any) -> None

Draw the graph.

Uses the draw_networkx function from NetworkX.

Parameters:

  • ax
    (Axes | None, default: None ) –

    Axes object to draw on. If None, uses the current Axes.

  • **kwargs
    (Any, default: {} ) –

    keyword-arguments to pass to draw_networkx.

Source code in qoolqit/graphs/base_graph.py 
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
def draw(self, ax: Axes | None = None, **kwargs: Any) -> None:
    """Draw the graph.

    Uses the draw_networkx function from NetworkX.

    Args:
        ax: Axes object to draw on. If None, uses the current Axes.
        **kwargs: keyword-arguments to pass to draw_networkx.
    """
    if self.has_coords:
        if "hide_ticks" not in kwargs:
            kwargs["hide_ticks"] = False

        nx.draw_networkx(self, pos=self.coords, ax=ax, **kwargs)

        if ax is None:
            ax = plt.gca()
        ax.set_xlabel("x")
        ax.set_ylabel("y")
        ax.grid(True, color="lightgray", linestyle="--", linewidth=0.7)

        # minimum ybox
        ylim = ax.get_ylim()
        if (ylim[1] - ylim[0]) < 2:
            y_center = (ylim[0] + ylim[1]) / 2
            ax.set_ylim(y_center - 1, y_center + 1)
        plt.tight_layout()
    else:
        nx.draw_networkx(self, ax=ax, **kwargs)

from_coordinates(coords: list | dict) -> BaseGraph classmethod

Construct a base graph from a set of coordinates.

Parameters:

  • coords
    (list | dict) –

    list or dictionary of coordinate pairs.

Source code in qoolqit/graphs/base_graph.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@classmethod
def from_coordinates(cls, coords: list | dict) -> BaseGraph:
    """Construct a base graph from a set of coordinates.

    Arguments:
        coords: list or dictionary of coordinate pairs.
    """
    if isinstance(coords, list):
        nodes = list(range(len(coords)))
        coords_dict = {i: pos for i, pos in enumerate(coords)}
    elif isinstance(coords, dict):
        nodes = list(coords.keys())
        coords_dict = coords
    graph = cls.from_nodes(nodes)
    graph._coords = coords_dict
    graph._reset_dicts()
    return graph

from_nodes(nodes: Iterable) -> BaseGraph classmethod

Construct a base graph from a set of nodes.

Parameters:

  • nodes
    (Iterable) –

    set of nodes.

Source code in qoolqit/graphs/base_graph.py 
48
49
50
51
52
53
54
55
56
57
58
59
@classmethod
def from_nodes(cls, nodes: Iterable) -> BaseGraph:
    """Construct a base graph from a set of nodes.

    Arguments:
        nodes: set of nodes.
    """
    graph = cls()
    graph.add_nodes_from(nodes)
    graph._coords = {i: None for i in graph.nodes}
    graph._reset_dicts()
    return graph

from_nx(g: nx.Graph) -> BaseGraph classmethod

Convert a NetworkX Graph object into a QoolQit graph instance.

The input networkx.Graph graph must be defined only with the following allowed

Node attributes

pos (tuple): represents the node 2D position. Must be a list/tuple of real numbers. weight: represents the node weight. Must be a real number.

Edge attributes: weight: represents the edge weight. Must be a real number.

Returns an instance of the class with following attributes
  • _node_weights : dict[node, float or None]
  • _edge_weights : dict[(u,v), float or None]
  • _coords : dict[node, (float,float) or None]
Source code in qoolqit/graphs/base_graph.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
@classmethod
def from_nx(cls, g: nx.Graph) -> BaseGraph:
    """Convert a NetworkX Graph object into a QoolQit graph instance.

    The input `networkx.Graph` graph must be defined only with the following allowed

    Node attributes:
        pos (tuple): represents the node 2D position. Must be a list/tuple of real numbers.
        weight: represents the node weight. Must be a real number.
    Edge attributes:
        weight: represents the edge weight. Must be a real number.

    Returns an instance of the class with following attributes:
        - _node_weights : dict[node, float or None]
        - _edge_weights : dict[(u,v), float or None]
        - _coords       : dict[node, (float,float) or None]
    """
    if not isinstance(g, nx.Graph):
        raise TypeError("Input must be a networkx.Graph instance.")

    g = nx.convert_node_labels_to_integers(g)
    num_nodes = len(g.nodes)
    num_edges = len(g.edges)

    # validate node attributes
    for name, data in g.nodes.data():
        unexpected_keys = set(data) - {"weight", "pos"}
        if unexpected_keys:
            raise ValueError(f"{unexpected_keys} not allowed in node attributes.")

    node_pos = nx.get_node_attributes(g, "pos")
    if node_pos:
        if len(node_pos) != num_nodes:
            raise ValueError("Node attribute `pos` must be defined for all nodes")
        for name, pos in node_pos.items():
            is_2D = isinstance(pos, (tuple, list)) & (len(pos) == 2)
            is_real = all(isinstance(p, (float, int)) for p in pos)
            if not (is_2D & is_real):
                raise TypeError(
                    f"In node {name} the `pos` attribute must be a 2D tuple/list"
                    f" of real numbers, got {pos} instead."
                )
    node_weights = nx.get_node_attributes(g, "weight")
    if node_weights:
        if len(node_weights) != num_nodes:
            raise ValueError("Node attribute `weight` must be defined for all nodes")
        for name, weight in node_weights.items():
            if not isinstance(weight, (float, int)):
                raise TypeError(
                    f"In node {name} the `weight` attribute must be a real number, "
                    f"got {type(weight)} instead."
                    ""
                )

    # validate edge attributes
    for u, v, data in g.edges.data():
        unexpected_keys = set(data) - {"weight"}
        if unexpected_keys:
            raise ValueError(f"{unexpected_keys} not allowed in edge attributes.")
    edge_weights = nx.get_edge_attributes(g, "weight")
    if edge_weights:
        if len(edge_weights) != num_edges:
            raise ValueError("Edge attribute `weight` must be defined for all edges")
        for name, weight in edge_weights.items():
            if not isinstance(weight, (float, int)):
                raise TypeError(
                    f"In edge {name}, the attribute `weight` must be a real number, "
                    f"got {type(weight)} instead."
                )

    # build the instance of the graph
    graph = cls()
    graph.add_nodes_from(g.nodes)
    graph.add_edges_from(g.edges)
    graph._node_weights = nx.get_node_attributes(g, "weight", default=None)
    graph._coords = nx.get_node_attributes(g, "pos", default=None)
    graph._edge_weights = nx.get_edge_attributes(g, "weight", default=None)

    return graph

interactions() -> dict

Rydberg model interaction 1/r^6 between pair of nodes.

Source code in qoolqit/graphs/base_graph.py 
245
246
247
def interactions(self) -> dict:
    """Rydberg model interaction 1/r^6 between pair of nodes."""
    return {p: 1.0 / (r**6) for p, r in self.distances().items()}

is_ud_graph() -> bool

Check if the graph is unit-disk.

Source code in qoolqit/graphs/base_graph.py 
303
304
305
306
307
308
309
def is_ud_graph(self) -> bool:
    """Check if the graph is unit-disk."""
    try:
        self.ud_radius_range()
        return True
    except ValueError:
        return False

max_distance(connected: bool | None = None) -> float

Returns the maximum distance in the graph.

Parameters:

  • connected
    (bool | None, default: None ) –

    if True/False, computes only over connected/disconnected nodes.

Source code in qoolqit/graphs/base_graph.py 
264
265
266
267
268
269
270
271
272
273
274
275
276
277
def max_distance(self, connected: bool | None = None) -> float:
    """Returns the maximum distance in the graph.

    Arguments:
        connected: if True/False, computes only over connected/disconnected nodes.
    """
    distance: float
    if connected is None:
        distance = max(self.distances(self.all_node_pairs).values())
    elif connected:
        distance = max(self.distances(self.sorted_edges).values())
    else:
        distance = max(self.distances(self.all_node_pairs - self.sorted_edges).values())
    return distance

min_distance(connected: bool | None = None) -> float

Returns the minimum distance in the graph.

Parameters:

  • connected
    (bool | None, default: None ) –

    if True/False, computes only over connected/disconnected nodes.

Source code in qoolqit/graphs/base_graph.py 
249
250
251
252
253
254
255
256
257
258
259
260
261
262
def min_distance(self, connected: bool | None = None) -> float:
    """Returns the minimum distance in the graph.

    Arguments:
        connected: if True/False, computes only over connected/disconnected nodes.
    """
    distance: float
    if connected is None:
        distance = min(self.distances(self.all_node_pairs).values())
    elif connected:
        distance = min(self.distances(self.sorted_edges).values())
    else:
        distance = min(self.distances(self.all_node_pairs - self.sorted_edges).values())
    return distance

rescale_coords(*args: Any, scaling: float | None = None, spacing: float | None = None) -> None

Rescales the node coordinates by a factor.

Accepts either a scaling or a spacing factor.

Parameters:

  • scaling
    (float | None, default: None ) –

    value to scale by.

  • spacing
    (float | None, default: None ) –

    value to set as the minimum distance in the graph.

Source code in qoolqit/graphs/base_graph.py 
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
def rescale_coords(
    self,
    *args: Any,
    scaling: float | None = None,
    spacing: float | None = None,
) -> None:
    """Rescales the node coordinates by a factor.

    Accepts either a scaling or a spacing factor.

    Arguments:
        scaling: value to scale by.
        spacing: value to set as the minimum distance in the graph.
    """
    if self.has_coords:
        msg = "Please pass either a `scaling` or a `spacing` value as a keyword argument."
        if (len(args) > 0) or (scaling is None and spacing is None):
            raise TypeError(msg)
        if scaling is None and spacing is not None:
            self._coords = space_coords(self._coords, spacing)
        elif spacing is None and scaling is not None:
            self._coords = scale_coords(self._coords, scaling)
        else:
            raise TypeError(msg)
    else:
        raise AttributeError("Trying to rescale coordinates on a graph without coordinates.")

set_ud_edges(radius: float) -> None

Reset the set of edges to be equal to the set of unit-disk edges.

Parameters:

  • radius
    (float) –

    the radius to use in determining the set of unit-disk edges.

Source code in qoolqit/graphs/base_graph.py 
349
350
351
352
353
354
355
356
def set_ud_edges(self, radius: float) -> None:
    """Reset the set of edges to be equal to the set of unit-disk edges.

    Arguments:
        radius: the radius to use in determining the set of unit-disk edges.
    """
    self.remove_edges_from(list(self.edges))
    self.add_edges_from(self.ud_edges(radius))

ud_edges(radius: float) -> set

Returns the set of edges given by the intersection of circles of a given radius.

Parameters:

  • radius
    (float) –

    the value

Source code in qoolqit/graphs/base_graph.py 
311
312
313
314
315
316
317
318
319
320
def ud_edges(self, radius: float) -> set:
    """Returns the set of edges given by the intersection of circles of a given radius.

    Arguments:
        radius: the value
    """
    if self.has_coords:
        return set(e for e, d in self.distances().items() if less_or_equal(d, radius))
    else:
        raise AttributeError("Getting unit disk edges is not valid without coordinates.")

ud_radius_range() -> tuple

Return the range (R_min, R_max) where the graph is unit-disk.

The graph is unit-disk if the maximum distance between all connected nodes is smaller than the minimum distance between disconnected nodes. This means that for any value R in that interval, the following condition is true:

graph.ud_edges(radius = R) == graph.sorted edges

Source code in qoolqit/graphs/base_graph.py 
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
def ud_radius_range(self) -> tuple:
    """Return the range (R_min, R_max) where the graph is unit-disk.

    The graph is unit-disk if the maximum distance between all connected nodes is
    smaller than the minimum distance between disconnected nodes. This means that
    for any value R in that interval, the following condition is true:

    graph.ud_edges(radius = R) == graph.sorted edges
    """
    if self.has_coords:
        n_edges = len(self.sorted_edges)
        if n_edges == 0:
            # If the graph is empty and has coordinates
            return (0.0, self.min_distance(connected=False))
        elif n_edges == len(self.all_node_pairs):
            # If the graph is fully connected
            return (self.max_distance(connected=True), float("inf"))
        elif self.max_distance(connected=True) < self.min_distance(connected=False):
            return (self.max_distance(connected=True), self.min_distance(connected=False))
        else:
            raise ValueError("Graph is not unit disk.")
    else:
        raise AttributeError("Checking if graph is unit disk is not valid without coordinates.")

DataGraph(edges: Iterable = [])

The main graph structure to represent problem data.

Parameters:

  • edges

    (Iterable, default: [] ) –

    set of edge tuples (i, j)

Returned by: Used by:

Methods:

  • circle –

    Constructs a circle graph, with the respective coordinates.

  • distances –

    Returns a dictionary of distances for a given set of edges.

  • draw –

    Draw the graph.

  • from_coordinates –

    Construct a base graph from a set of coordinates.

  • from_matrix –

    Constructs a graph from a symmetric square matrix.

  • from_nodes –

    Construct a base graph from a set of nodes.

  • from_nx –

    Convert a NetworkX Graph object into a QoolQit graph instance.

  • from_pyg –

    Convert a PyTorch Geometric Data object into a DataGraph instance.

  • heavy_hexagonal –

    Constructs a heavy-hexagonal lattice graph, with respective coordinates.

  • hexagonal –

    Constructs a hexagonal lattice graph, with respective coordinates.

  • interactions –

    Rydberg model interaction 1/r^6 between pair of nodes.

  • is_ud_graph –

    Check if the graph is unit-disk.

  • line –

    Constructs a line graph, with the respective coordinates.

  • max_distance –

    Returns the maximum distance in the graph.

  • min_distance –

    Returns the minimum distance in the graph.

  • random_er –

    Constructs an Erdős–Rényi random graph.

  • random_ud –

    Constructs a random unit-disk graph.

  • rescale_coords –

    Rescales the node coordinates by a factor.

  • set_ud_edges –

    Reset the set of edges to be equal to the set of unit-disk edges.

  • square –

    Constructs a square lattice graph, with respective coordinates.

  • to_pyg –

    Convert the DataGraph to a PyTorch Geometric Data object.

  • triangular –

    Constructs a triangular lattice graph, with respective coordinates.

  • ud_edges –

    Returns the set of edges given by the intersection of circles of a given radius.

  • ud_radius_range –

    Return the range (R_min, R_max) where the graph is unit-disk.

Attributes:

  • all_node_pairs (set) –

    Return a list of all possible node pairs in the graph.

  • coords (dict) –

    Return the dictionary of node coordinates.

  • edge_weights (dict) –

    Return the dictionary of edge weights.

  • has_coords (bool) –

    Check if the graph has coordinates.

  • has_edge_weights (bool) –

    Check if the graph has edge weights.

  • has_edges (bool) –

    Check if the graph has edges.

  • has_node_weights (bool) –

    Check if the graph has node weights.

  • node_weights (dict) –

    Return the dictionary of node weights.

  • sorted_edges (set) –

    Returns the set of edges (u, v) such that (u < v).

Source code in qoolqit/graphs/data_graph.py 
28
29
30
31
32
33
34
35
def __init__(self, edges: Iterable = []) -> None:
    """
    Default constructor for the BaseGraph.

    Arguments:
        edges: set of edge tuples (i, j)
    """
    super().__init__(edges)

all_node_pairs: set property

Return a list of all possible node pairs in the graph.

coords: dict property writable

Return the dictionary of node coordinates.

edge_weights: dict property writable

Return the dictionary of edge weights.

has_coords: bool property

Check if the graph has coordinates.

Requires all nodes to have coordinates.

has_edge_weights: bool property

Check if the graph has edge weights.

Requires all edges to have a weight.

has_edges: bool property

Check if the graph has edges.

has_node_weights: bool property

Check if the graph has node weights.

Requires all nodes to have a weight.

node_weights: dict property writable

Return the dictionary of node weights.

sorted_edges: set property

Returns the set of edges (u, v) such that (u < v).

circle(n: int, spacing: float = 1.0, center: tuple = (0.0, 0.0)) -> DataGraph classmethod

Constructs a circle graph, with the respective coordinates.

Parameters:

  • n
    (int) –

    number of nodes.

  • spacing
    (float, default: 1.0 ) –

    distance between each node.

  • center
    (tuple, default: (0.0, 0.0) ) –

    point (x, y) to set as the center of the graph.

Source code in qoolqit/graphs/data_graph.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@classmethod
def circle(
    cls,
    n: int,
    spacing: float = 1.0,
    center: tuple = (0.0, 0.0),
) -> DataGraph:
    """Constructs a circle graph, with the respective coordinates.

    Arguments:
        n: number of nodes.
        spacing: distance between each node.
        center: point (x, y) to set as the center of the graph.
    """

    d_theta = (2.0 * np.pi) / n
    r = spacing / (2.0 * np.sin(np.pi / n))
    theta = np.linspace(0.0, 2.0 * np.pi - d_theta, n)
    coords = [
        (x + center[0], y + center[1]) for x, y in zip(r * np.cos(theta), r * np.sin(theta))
    ]
    edges = [(i, i + 1) for i in range(n - 1)] + [(n - 1, 0)]
    graph = cls.from_coordinates(coords)
    graph.add_edges_from(edges)
    graph._reset_dicts()
    return graph

distances(edge_list: Iterable | None = None) -> dict

Returns a dictionary of distances for a given set of edges.

Distances are calculated directly from the coordinates. Raises an error if there are no coordinates on the graph.

Parameters:

  • edge_list
    (Iterable | None, default: None ) –

    set of edges.

Source code in qoolqit/graphs/base_graph.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
def distances(self, edge_list: Iterable | None = None) -> dict:
    """Returns a dictionary of distances for a given set of edges.

    Distances are calculated directly from the coordinates. Raises an error
    if there are no coordinates on the graph.

    Arguments:
        edge_list: set of edges.
    """
    if self.has_coords:
        if edge_list is None:
            edge_list = self.all_node_pairs
        elif len(edge_list) == 0:  # type: ignore [arg-type]
            raise ValueError("Trying to compute distances for an empty edge list.")
        return distances(self.coords, edge_list)
    else:
        raise AttributeError("Trying to compute distances for a graph without coordinates.")

draw(ax: Axes | None = None, **kwargs: Any) -> None

Draw the graph.

Uses the draw_networkx function from NetworkX.

Parameters:

  • ax
    (Axes | None, default: None ) –

    Axes object to draw on. If None, uses the current Axes.

  • **kwargs
    (Any, default: {} ) –

    keyword-arguments to pass to draw_networkx.

Source code in qoolqit/graphs/base_graph.py 
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
def draw(self, ax: Axes | None = None, **kwargs: Any) -> None:
    """Draw the graph.

    Uses the draw_networkx function from NetworkX.

    Args:
        ax: Axes object to draw on. If None, uses the current Axes.
        **kwargs: keyword-arguments to pass to draw_networkx.
    """
    if self.has_coords:
        if "hide_ticks" not in kwargs:
            kwargs["hide_ticks"] = False

        nx.draw_networkx(self, pos=self.coords, ax=ax, **kwargs)

        if ax is None:
            ax = plt.gca()
        ax.set_xlabel("x")
        ax.set_ylabel("y")
        ax.grid(True, color="lightgray", linestyle="--", linewidth=0.7)

        # minimum ybox
        ylim = ax.get_ylim()
        if (ylim[1] - ylim[0]) < 2:
            y_center = (ylim[0] + ylim[1]) / 2
            ax.set_ylim(y_center - 1, y_center + 1)
        plt.tight_layout()
    else:
        nx.draw_networkx(self, ax=ax, **kwargs)

from_coordinates(coords: list | dict) -> BaseGraph classmethod

Construct a base graph from a set of coordinates.

Parameters:

  • coords
    (list | dict) –

    list or dictionary of coordinate pairs.

Source code in qoolqit/graphs/base_graph.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@classmethod
def from_coordinates(cls, coords: list | dict) -> BaseGraph:
    """Construct a base graph from a set of coordinates.

    Arguments:
        coords: list or dictionary of coordinate pairs.
    """
    if isinstance(coords, list):
        nodes = list(range(len(coords)))
        coords_dict = {i: pos for i, pos in enumerate(coords)}
    elif isinstance(coords, dict):
        nodes = list(coords.keys())
        coords_dict = coords
    graph = cls.from_nodes(nodes)
    graph._coords = coords_dict
    graph._reset_dicts()
    return graph

from_matrix(data: ArrayLike) -> DataGraph classmethod

Constructs a graph from a symmetric square matrix.

The diagonal values are set as the node weights. For each entry (i, j) where M[i, j] != 0 an edge (i, j) is added to the graph and the value M[i, j] is set as its weight.

Parameters:

  • data
    (ArrayLike) –

    symmetric square matrix.

Source code in qoolqit/graphs/data_graph.py 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
@classmethod
def from_matrix(cls, data: ArrayLike) -> DataGraph:
    """Constructs a graph from a symmetric square matrix.

    The diagonal values are set as the node weights. For each entry (i, j)
    where M[i, j] != 0 an edge (i, j) is added to the graph and the value
    M[i, j] is set as its weight.

    Arguments:
        data: symmetric square matrix.
    """
    if data.ndim != 2:
        raise ValueError("2D Matrix required.")
    if not np.allclose(data, data.T, rtol=0.0, atol=ATOL_32):
        raise ValueError("Matrix must be symmetric.")

    diag = np.diag(data)
    n_nodes = len(diag)
    node_weights = {i: diag[i] for i in range(n_nodes)}
    if np.allclose(diag, np.zeros(n_nodes), rtol=0.0, atol=ATOL_32):
        node_weights = {i: None for i in range(n_nodes)}
    else:
        node_weights = {i: diag[i].item() for i in range(n_nodes)}

    data[data <= ATOL_32] = 0.0
    non_zero = data.nonzero()
    i_list = non_zero[0].tolist()
    j_list = non_zero[1].tolist()

    edge_list = [(i, j) for i, j in zip(i_list, j_list) if i < j]
    edge_weights = {(i, j): data[i, j].item() for i, j in edge_list}

    graph = cls.from_nodes(range(n_nodes))
    graph.add_edges_from(edge_list)
    graph.node_weights = node_weights
    graph.edge_weights = edge_weights
    return graph

from_nodes(nodes: Iterable) -> BaseGraph classmethod

Construct a base graph from a set of nodes.

Parameters:

  • nodes
    (Iterable) –

    set of nodes.

Source code in qoolqit/graphs/base_graph.py 
48
49
50
51
52
53
54
55
56
57
58
59
@classmethod
def from_nodes(cls, nodes: Iterable) -> BaseGraph:
    """Construct a base graph from a set of nodes.

    Arguments:
        nodes: set of nodes.
    """
    graph = cls()
    graph.add_nodes_from(nodes)
    graph._coords = {i: None for i in graph.nodes}
    graph._reset_dicts()
    return graph

from_nx(g: nx.Graph) -> BaseGraph classmethod

Convert a NetworkX Graph object into a QoolQit graph instance.

The input networkx.Graph graph must be defined only with the following allowed

Node attributes

pos (tuple): represents the node 2D position. Must be a list/tuple of real numbers. weight: represents the node weight. Must be a real number.

Edge attributes: weight: represents the edge weight. Must be a real number.

Returns an instance of the class with following attributes
  • _node_weights : dict[node, float or None]
  • _edge_weights : dict[(u,v), float or None]
  • _coords : dict[node, (float,float) or None]
Source code in qoolqit/graphs/base_graph.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
@classmethod
def from_nx(cls, g: nx.Graph) -> BaseGraph:
    """Convert a NetworkX Graph object into a QoolQit graph instance.

    The input `networkx.Graph` graph must be defined only with the following allowed

    Node attributes:
        pos (tuple): represents the node 2D position. Must be a list/tuple of real numbers.
        weight: represents the node weight. Must be a real number.
    Edge attributes:
        weight: represents the edge weight. Must be a real number.

    Returns an instance of the class with following attributes:
        - _node_weights : dict[node, float or None]
        - _edge_weights : dict[(u,v), float or None]
        - _coords       : dict[node, (float,float) or None]
    """
    if not isinstance(g, nx.Graph):
        raise TypeError("Input must be a networkx.Graph instance.")

    g = nx.convert_node_labels_to_integers(g)
    num_nodes = len(g.nodes)
    num_edges = len(g.edges)

    # validate node attributes
    for name, data in g.nodes.data():
        unexpected_keys = set(data) - {"weight", "pos"}
        if unexpected_keys:
            raise ValueError(f"{unexpected_keys} not allowed in node attributes.")

    node_pos = nx.get_node_attributes(g, "pos")
    if node_pos:
        if len(node_pos) != num_nodes:
            raise ValueError("Node attribute `pos` must be defined for all nodes")
        for name, pos in node_pos.items():
            is_2D = isinstance(pos, (tuple, list)) & (len(pos) == 2)
            is_real = all(isinstance(p, (float, int)) for p in pos)
            if not (is_2D & is_real):
                raise TypeError(
                    f"In node {name} the `pos` attribute must be a 2D tuple/list"
                    f" of real numbers, got {pos} instead."
                )
    node_weights = nx.get_node_attributes(g, "weight")
    if node_weights:
        if len(node_weights) != num_nodes:
            raise ValueError("Node attribute `weight` must be defined for all nodes")
        for name, weight in node_weights.items():
            if not isinstance(weight, (float, int)):
                raise TypeError(
                    f"In node {name} the `weight` attribute must be a real number, "
                    f"got {type(weight)} instead."
                    ""
                )

    # validate edge attributes
    for u, v, data in g.edges.data():
        unexpected_keys = set(data) - {"weight"}
        if unexpected_keys:
            raise ValueError(f"{unexpected_keys} not allowed in edge attributes.")
    edge_weights = nx.get_edge_attributes(g, "weight")
    if edge_weights:
        if len(edge_weights) != num_edges:
            raise ValueError("Edge attribute `weight` must be defined for all edges")
        for name, weight in edge_weights.items():
            if not isinstance(weight, (float, int)):
                raise TypeError(
                    f"In edge {name}, the attribute `weight` must be a real number, "
                    f"got {type(weight)} instead."
                )

    # build the instance of the graph
    graph = cls()
    graph.add_nodes_from(g.nodes)
    graph.add_edges_from(g.edges)
    graph._node_weights = nx.get_node_attributes(g, "weight", default=None)
    graph._coords = nx.get_node_attributes(g, "pos", default=None)
    graph._edge_weights = nx.get_edge_attributes(g, "weight", default=None)

    return graph

from_pyg(data: torch_geometric.data.Data, node_attrs: Iterable[str] | None = None, edge_attrs: Iterable[str] | None = None, graph_attrs: Iterable[str] | None = None, node_weights_attr: str | None = None, edge_weights_attr: str | None = None) -> DataGraph classmethod

Convert a PyTorch Geometric Data object into a DataGraph instance.

Requires torch_geometric. Uses to_networkx internally.

Default attributes copied (if present on data ):

  • Node: x, pos (pos is also stored in _coords)
  • Edge: edge_attr
  • Graph: y

Use node_attrs, edge_attrs, graph_attrs for extras.

QoolQit weights (_node_weights, _edge_weights) are not populated automatically — use the explicit parameters:

  • node_weights_attr: real-valued tensor of shape (N,) or (N, 1). Defaults to None.
  • edge_weights_attr: real-valued tensor of shape (E,) or (E, 1) where E = edge_index.shape[1] (directed count). Defaults to None.

The weight attribute is also stored as a regular node/edge attribute.

Parameters:

  • data
    (Data) –

    PyTorch Geometric Data object to convert.

  • node_attrs
    (Iterable[str] | None, default: None ) –

    extra node attributes to copy (beyond x and pos).

  • edge_attrs
    (Iterable[str] | None, default: None ) –

    extra edge attributes to copy (beyond edge_attr).

  • graph_attrs
    (Iterable[str] | None, default: None ) –

    extra graph-level attributes to copy (beyond y).

  • node_weights_attr
    (str | None, default: None ) –

    Data attribute to use as node weights.

  • edge_weights_attr
    (str | None, default: None ) –

    Data attribute to use as edge weights.

Returns:

  • DataGraph –

    DataGraph with _coords, _node_weights, _edge_weights

  • DataGraph –

    populated where applicable.

Raises:

  • ImportError –

    if torch_geometric is not installed.

  • TypeError –

    if data is not a torch_geometric.data.Data instance, or if a weight attribute is not a torch.Tensor.

  • AttributeError –

    if a specified weight attribute is missing.

  • ValueError –

    if a weight tensor has an incompatible shape or size.

Source code in qoolqit/graphs/data_graph.py 
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
@classmethod
def from_pyg(
    cls,
    data: torch_geometric.data.Data,
    node_attrs: Iterable[str] | None = None,
    edge_attrs: Iterable[str] | None = None,
    graph_attrs: Iterable[str] | None = None,
    node_weights_attr: str | None = None,
    edge_weights_attr: str | None = None,
) -> DataGraph:
    """Convert a PyTorch Geometric Data object into a DataGraph instance.

    Requires ``torch_geometric``. Uses ``to_networkx`` internally.

    **Default attributes copied (if present on** ``data`` **):**

    - Node: ``x``, ``pos`` (``pos`` is also stored in ``_coords``)
    - Edge: ``edge_attr``
    - Graph: ``y``

    Use ``node_attrs``, ``edge_attrs``, ``graph_attrs`` for extras.

    **QoolQit weights** (``_node_weights``, ``_edge_weights``) are not
    populated automatically — use the explicit parameters:

    - ``node_weights_attr``: real-valued tensor of shape ``(N,)`` or
      ``(N, 1)``. Defaults to ``None``.
    - ``edge_weights_attr``: real-valued tensor of shape ``(E,)`` or
      ``(E, 1)`` where ``E = edge_index.shape[1]`` (directed count).
      Defaults to ``None``.

    The weight attribute is also stored as a regular node/edge attribute.

    Arguments:
        data: PyTorch Geometric Data object to convert.
        node_attrs: extra node attributes to copy (beyond x and pos).
        edge_attrs: extra edge attributes to copy (beyond edge_attr).
        graph_attrs: extra graph-level attributes to copy (beyond y).
        node_weights_attr: Data attribute to use as node weights.
        edge_weights_attr: Data attribute to use as edge weights.

    Returns:
        DataGraph with ``_coords``, ``_node_weights``, ``_edge_weights``
        populated where applicable.

    Raises:
        ImportError: if ``torch_geometric`` is not installed.
        TypeError: if ``data`` is not a ``torch_geometric.data.Data``
            instance, or if a weight attribute is not a ``torch.Tensor``.
        AttributeError: if a specified weight attribute is missing.
        ValueError: if a weight tensor has an incompatible shape or size.
    """
    try:
        from torch_geometric.data import Data
        from torch_geometric.utils import to_networkx
    except ImportError as e:
        raise ImportError("Please, install the `torch_geometric` package.") from e

    if not isinstance(data, Data):
        raise TypeError("Input must be a torch_geometric.data.Data object.")

    # Validate weight attrs early and keep the squeezed tensors
    node_tensor = (
        cls._validate_weights_attr(data, node_weights_attr, data.num_nodes, "node")
        if node_weights_attr is not None
        else None
    )
    edge_tensor = (
        cls._validate_weights_attr(data, edge_weights_attr, data.num_edges, "edge")
        if edge_weights_attr is not None
        else None
    )

    # Select unique attributes and add default ones only if present in the data
    node_attrs_set = {k for k in {"x", "pos"} if k in data}
    if node_attrs is not None:
        node_attrs_set |= set(node_attrs)
    if node_weights_attr is not None:
        node_attrs_set.add(node_weights_attr)

    edge_attrs_set = {k for k in {"edge_attr"} if k in data}
    if edge_attrs is not None:
        edge_attrs_set |= set(edge_attrs)
    if edge_weights_attr is not None:
        edge_attrs_set.add(edge_weights_attr)

    graph_attrs_set = {k for k in {"y"} if k in data}
    if graph_attrs is not None:
        graph_attrs_set |= set(graph_attrs)

    # Convert to NetworkX (undirected, no self-loops)
    nx_graph = to_networkx(
        data,
        node_attrs=list(node_attrs_set),
        edge_attrs=list(edge_attrs_set),
        graph_attrs=list(graph_attrs_set),
        to_undirected=True,
        remove_self_loops=True,
    )

    # Build the DataGraph: edges carry their data, nodes carry their data
    graph = cls(nx_graph.edges(data=True))
    graph.add_nodes_from(nx_graph.nodes(data=True))
    graph.graph = nx_graph.graph

    # Re-initialize QoolQit internal dicts for all nodes/edges
    graph._coords = {n: None for n in graph.nodes}
    graph._reset_dicts()

    # pos → _coords (stored as list [x, y] by to_networkx)
    for node, node_data in nx_graph.nodes(data=True):
        if "pos" in node_data:
            graph._coords[node] = tuple(node_data["pos"])  # type: ignore[assignment]

    # node_weights_attr → _node_weights
    if node_tensor is not None:
        for i in range(data.num_nodes):
            graph._node_weights[i] = node_tensor[i].item()

    # edge_weights_attr → _edge_weights
    if edge_tensor is not None:
        seen: set = set()
        for idx in range(data.edge_index.shape[1]):
            u = int(data.edge_index[0, idx].item())
            v = int(data.edge_index[1, idx].item())
            key = (min(u, v), max(u, v))
            if key not in seen:
                graph._edge_weights[key] = edge_tensor[idx].item()
                seen.add(key)

    return graph

heavy_hexagonal(m: int, n: int, spacing: float = 1.0) -> DataGraph classmethod

Constructs a heavy-hexagonal lattice graph, with respective coordinates.

Parameters:

  • m
    (int) –

    Number of rows of hexagons.

  • n
    (int) –

    Number of columns of hexagons.

  • spacing
    (float, default: 1.0 ) –

    The distance between adjacent nodes on the final lattice.

Notes

The heavy-hexagonal lattice is a regular hexagonal lattice where each edge is decorated with an additional lattice site.

Source code in qoolqit/graphs/data_graph.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
@classmethod
def heavy_hexagonal(
    cls,
    m: int,
    n: int,
    spacing: float = 1.0,
) -> DataGraph:
    """
    Constructs a heavy-hexagonal lattice graph, with respective coordinates.

    Arguments:
        m: Number of rows of hexagons.
        n: Number of columns of hexagons.
        spacing: The distance between adjacent nodes on the final lattice.

    Notes:
        The heavy-hexagonal lattice is a regular hexagonal lattice where
        each edge is decorated with an additional lattice site.
    """
    G_hex = nx.hexagonal_lattice_graph(m, n, with_positions=True)
    pos_unit = nx.get_node_attributes(G_hex, "pos")

    G_heavy = nx.Graph()
    scaling_factor = 2 * spacing

    label_map = {}
    for old_label, (x, y) in pos_unit.items():
        # Relabel to an even-integer grid to make space for midpoint nodes
        new_label = (2 * old_label[0], 2 * old_label[1])
        label_map[old_label] = new_label

        # Scale positions and add the node to the new graph
        new_pos = (x * scaling_factor, y * scaling_factor)
        G_heavy.add_node(new_label, pos=new_pos)

    for u_old, v_old in G_hex.edges():
        u_new, v_new = label_map[u_old], label_map[v_old]

        mid_label = ((u_new[0] + v_new[0]) // 2, (u_new[1] + v_new[1]) // 2)

        pos_u = G_heavy.nodes[u_new]["pos"]
        pos_v = G_heavy.nodes[v_new]["pos"]
        mid_pos = ((pos_u[0] + pos_v[0]) / 2, (pos_u[1] + pos_v[1]) / 2)

        G_heavy.add_node(mid_label, pos=mid_pos)
        G_heavy.add_edge(u_new, mid_label)
        G_heavy.add_edge(mid_label, v_new)

    final_nodes = sorted(list(G_heavy.nodes()))

    final_coords = [G_heavy.nodes[label]["pos"] for label in final_nodes]

    label_to_int = {label: i for i, label in enumerate(final_nodes)}

    final_edges = [(label_to_int[u], label_to_int[v]) for u, v in G_heavy.edges()]

    graph = cls.from_coordinates(final_coords)
    graph.add_edges_from(final_edges)
    graph._reset_dicts()
    return graph

hexagonal(m: int, n: int, spacing: float = 1.0) -> DataGraph classmethod

Constructs a hexagonal lattice graph, with respective coordinates.

Parameters:

  • m
    (int) –

    Number of rows of hexagons.

  • n
    (int) –

    Number of columns of hexagons.

  • spacing
    (float, default: 1.0 ) –

    The distance between adjacent nodes on the final lattice.

Source code in qoolqit/graphs/data_graph.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
@classmethod
def hexagonal(
    cls,
    m: int,
    n: int,
    spacing: float = 1.0,
) -> DataGraph:
    """
    Constructs a hexagonal lattice graph, with respective coordinates.

    Arguments:
        m: Number of rows of hexagons.
        n: Number of columns of hexagons.
        spacing: The distance between adjacent nodes on the final lattice.
    """
    G = nx.hexagonal_lattice_graph(m, n, with_positions=True)
    G = nx.convert_node_labels_to_integers(G)
    pos_unit = nx.get_node_attributes(G, "pos")

    final_pos = {node: (x * spacing, y * spacing) for node, (x, y) in pos_unit.items()}

    graph = cls.from_coordinates(final_pos)
    graph.add_edges_from(G.edges)
    graph._reset_dicts()
    return graph

interactions() -> dict

Rydberg model interaction 1/r^6 between pair of nodes.

Source code in qoolqit/graphs/base_graph.py 
245
246
247
def interactions(self) -> dict:
    """Rydberg model interaction 1/r^6 between pair of nodes."""
    return {p: 1.0 / (r**6) for p, r in self.distances().items()}

is_ud_graph() -> bool

Check if the graph is unit-disk.

Source code in qoolqit/graphs/base_graph.py 
303
304
305
306
307
308
309
def is_ud_graph(self) -> bool:
    """Check if the graph is unit-disk."""
    try:
        self.ud_radius_range()
        return True
    except ValueError:
        return False

line(n: int, spacing: float = 1.0) -> DataGraph classmethod

Constructs a line graph, with the respective coordinates.

Parameters:

  • n
    (int) –

    number of nodes.

  • spacing
    (float, default: 1.0 ) –

    distance between each node.

Source code in qoolqit/graphs/data_graph.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
@classmethod
def line(cls, n: int, spacing: float = 1.0) -> DataGraph:
    """Constructs a line graph, with the respective coordinates.

    Arguments:
        n: number of nodes.
        spacing: distance between each node.
    """
    coords = [(i * spacing, 0.0) for i in range(n)]
    graph = cls.from_coordinates(coords)
    edges = [(i, i + 1) for i in range(0, n - 1)]
    graph.add_edges_from(edges)
    graph._reset_dicts()
    return graph

max_distance(connected: bool | None = None) -> float

Returns the maximum distance in the graph.

Parameters:

  • connected
    (bool | None, default: None ) –

    if True/False, computes only over connected/disconnected nodes.

Source code in qoolqit/graphs/base_graph.py 
264
265
266
267
268
269
270
271
272
273
274
275
276
277
def max_distance(self, connected: bool | None = None) -> float:
    """Returns the maximum distance in the graph.

    Arguments:
        connected: if True/False, computes only over connected/disconnected nodes.
    """
    distance: float
    if connected is None:
        distance = max(self.distances(self.all_node_pairs).values())
    elif connected:
        distance = max(self.distances(self.sorted_edges).values())
    else:
        distance = max(self.distances(self.all_node_pairs - self.sorted_edges).values())
    return distance

min_distance(connected: bool | None = None) -> float

Returns the minimum distance in the graph.

Parameters:

  • connected
    (bool | None, default: None ) –

    if True/False, computes only over connected/disconnected nodes.

Source code in qoolqit/graphs/base_graph.py 
249
250
251
252
253
254
255
256
257
258
259
260
261
262
def min_distance(self, connected: bool | None = None) -> float:
    """Returns the minimum distance in the graph.

    Arguments:
        connected: if True/False, computes only over connected/disconnected nodes.
    """
    distance: float
    if connected is None:
        distance = min(self.distances(self.all_node_pairs).values())
    elif connected:
        distance = min(self.distances(self.sorted_edges).values())
    else:
        distance = min(self.distances(self.all_node_pairs - self.sorted_edges).values())
    return distance

random_er(n: int, p: float, seed: int | None = None) -> DataGraph classmethod

Constructs an Erdős–Rényi random graph.

Parameters:

  • n
    (int) –

    number of nodes.

  • p
    (float) –

    probability that any two nodes connect.

  • seed
    (int | None, default: None ) –

    random seed.

Source code in qoolqit/graphs/data_graph.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@classmethod
def random_er(cls, n: int, p: float, seed: int | None = None) -> DataGraph:
    """Constructs an Erdős–Rényi random graph.

    Arguments:
        n: number of nodes.
        p: probability that any two nodes connect.
        seed: random seed.
    """
    base_graph = nx.erdos_renyi_graph(n, p, seed)
    graph = DataGraph.from_nodes(list(base_graph.nodes))
    graph.add_edges_from(base_graph.edges)
    graph._reset_dicts()
    return graph

random_ud(n: int, radius: float = 1.0, L: float | None = None) -> DataGraph classmethod

Constructs a random unit-disk graph.

The nodes are sampled uniformly from a square of size (L x L). If L is not given, it is estimated based on a rough heuristic that of packing N nodes on a square of side L such that the expected minimum distance is R, leading to L ~ (R / 2) * sqrt(π * n).

Parameters:

  • n
    (int) –

    number of nodes.

  • radius
    (float, default: 1.0 ) –

    radius to use for defining the unit-disk edges.

  • L
    (float | None, default: None ) –

    size of the square on which to sample the node coordinates.

Source code in qoolqit/graphs/data_graph.py 
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
@classmethod
def random_ud(
    cls,
    n: int,
    radius: float = 1.0,
    L: float | None = None,
) -> DataGraph:
    """Constructs a random unit-disk graph.

    The nodes are sampled uniformly from a square of size (L x L).
    If L is not given, it is estimated based on a rough heuristic that
    of packing N nodes on a square of side L such that the expected
    minimum distance is R, leading to L ~ (R / 2) * sqrt(π * n).

    Arguments:
        n: number of nodes.
        radius: radius to use for defining the unit-disk edges.
        L: size of the square on which to sample the node coordinates.
    """
    if L is None:
        L = (radius / 2) * ((np.pi * n) ** 0.5)
    coords = random_coords(n, L)
    graph = cls.from_coordinates(coords)
    edges = graph.ud_edges(radius)
    graph.add_edges_from(edges)
    graph._reset_dicts()
    return graph

rescale_coords(*args: Any, scaling: float | None = None, spacing: float | None = None) -> None

Rescales the node coordinates by a factor.

Accepts either a scaling or a spacing factor.

Parameters:

  • scaling
    (float | None, default: None ) –

    value to scale by.

  • spacing
    (float | None, default: None ) –

    value to set as the minimum distance in the graph.

Source code in qoolqit/graphs/base_graph.py 
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
def rescale_coords(
    self,
    *args: Any,
    scaling: float | None = None,
    spacing: float | None = None,
) -> None:
    """Rescales the node coordinates by a factor.

    Accepts either a scaling or a spacing factor.

    Arguments:
        scaling: value to scale by.
        spacing: value to set as the minimum distance in the graph.
    """
    if self.has_coords:
        msg = "Please pass either a `scaling` or a `spacing` value as a keyword argument."
        if (len(args) > 0) or (scaling is None and spacing is None):
            raise TypeError(msg)
        if scaling is None and spacing is not None:
            self._coords = space_coords(self._coords, spacing)
        elif spacing is None and scaling is not None:
            self._coords = scale_coords(self._coords, scaling)
        else:
            raise TypeError(msg)
    else:
        raise AttributeError("Trying to rescale coordinates on a graph without coordinates.")

set_ud_edges(radius: float) -> None

Reset the set of edges to be equal to the set of unit-disk edges.

Source code in qoolqit/graphs/data_graph.py 
644
645
646
647
def set_ud_edges(self, radius: float) -> None:
    """Reset the set of edges to be equal to the set of unit-disk edges."""
    super().set_ud_edges(radius=radius)
    self._edge_weights = {e: None for e in self.sorted_edges}

square(m: int, n: int, spacing: float = 1.0) -> DataGraph classmethod

Constructs a square lattice graph, with respective coordinates.

Parameters:

  • m
    (int) –

    Number of rows of square.

  • n
    (int) –

    Number of columns of square.

  • spacing
    (float, default: 1.0 ) –

    The distance between adjacent nodes on the final lattice.

Source code in qoolqit/graphs/data_graph.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
@classmethod
def square(
    cls,
    m: int,
    n: int,
    spacing: float = 1.0,
) -> DataGraph:
    """
    Constructs a square lattice graph, with respective coordinates.

    Arguments:
        m: Number of rows of square.
        n: Number of columns of square.
        spacing: The distance between adjacent nodes on the final lattice.
    """
    G = nx.grid_2d_graph(m, n)
    final_coords = [(x * spacing, y * spacing) for (x, y) in list(G.nodes)]
    G = nx.convert_node_labels_to_integers(G)

    graph = DataGraph.from_coordinates(final_coords)
    graph.add_edges_from(G.edges)
    graph._reset_dicts()
    return graph

to_pyg(node_attrs: Iterable[str] | None = None, edge_attrs: Iterable[str] | None = None, graph_attrs: Iterable[str] | None = None, node_weights_attr: str = 'weight', edge_weights_attr: str = 'edge_weight') -> torch_geometric.data.Data

Convert the DataGraph to a PyTorch Geometric Data object.

Requires torch_geometric. Uses from_networkx internally.

Default attributes exported (if present on the graph):

  • Node "x" → data.x; Edge "edge_attr" → data.edge_attr
  • Graph "y" → data.y

Use node_attrs, edge_attrs, graph_attrs for extras.

QoolQit internal dicts exported when populated:

  • _coords → data.pos (float64, shape (N, 2))
  • _node_weights → data.<node_weights_attr> (float64, shape (N,)). Defaults to "weight".
  • _edge_weights → data.<edge_weights_attr> (float64, shape (2*E,)). Defaults to "edge_weight".

Parameters:

  • node_attrs
    (Iterable[str] | None, default: None ) –

    extra node attributes to export (beyond x).

  • edge_attrs
    (Iterable[str] | None, default: None ) –

    extra edge attributes to export (beyond edge_attr).

  • graph_attrs
    (Iterable[str] | None, default: None ) –

    extra graph-level attributes to export (beyond y).

  • node_weights_attr
    (str, default: 'weight' ) –

    Data attribute name for node weights. Defaults to "weight".

  • edge_weights_attr
    (str, default: 'edge_weight' ) –

    Data attribute name for edge weights. Defaults to "edge_weight".

Returns:

  • Data –

    PyTorch Geometric Data object.

Raises:

  • ImportError –

    if torch_geometric is not installed.

Source code in qoolqit/graphs/data_graph.py 
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
def to_pyg(
    self,
    node_attrs: Iterable[str] | None = None,
    edge_attrs: Iterable[str] | None = None,
    graph_attrs: Iterable[str] | None = None,
    node_weights_attr: str = "weight",
    edge_weights_attr: str = "edge_weight",
) -> torch_geometric.data.Data:
    """Convert the DataGraph to a PyTorch Geometric Data object.

    Requires ``torch_geometric``. Uses ``from_networkx`` internally.

    **Default attributes exported (if present on the graph):**

    - Node ``"x"`` → ``data.x``; Edge ``"edge_attr"`` → ``data.edge_attr``
    - Graph ``"y"`` → ``data.y``

    Use ``node_attrs``, ``edge_attrs``, ``graph_attrs`` for extras.

    **QoolQit internal dicts exported when populated:**

    - ``_coords`` → ``data.pos`` (float64, shape ``(N, 2)``)
    - ``_node_weights`` → ``data.<node_weights_attr>`` (float64, shape
      ``(N,)``). Defaults to ``"weight"``.
    - ``_edge_weights`` → ``data.<edge_weights_attr>`` (float64, shape
      ``(2*E,)``). Defaults to ``"edge_weight"``.

    Arguments:
        node_attrs: extra node attributes to export (beyond x).
        edge_attrs: extra edge attributes to export (beyond edge_attr).
        graph_attrs: extra graph-level attributes to export (beyond y).
        node_weights_attr: Data attribute name for node weights.
            Defaults to ``"weight"``.
        edge_weights_attr: Data attribute name for edge weights.
            Defaults to ``"edge_weight"``.

    Returns:
        PyTorch Geometric Data object.

    Raises:
        ImportError: if ``torch_geometric`` is not installed.
    """
    try:
        import torch
        from torch_geometric.utils import from_networkx
    except ImportError as e:
        raise ImportError("Please, install the `torch_geometric` package.") from e

    node_attrs_set = set(node_attrs) if node_attrs else set()
    edge_attrs_set = set(edge_attrs) if edge_attrs else set()
    graph_attrs_list = list(graph_attrs) if graph_attrs else []

    # Add default PyG attributes if present in the graph
    if any("x" in d for _, d in self.nodes(data=True)):
        node_attrs_set.add("x")
    if any("edge_attr" in d for _, _, d in self.edges(data=True)):
        edge_attrs_set.add("edge_attr")
    if "y" in self.graph:
        graph_attrs_list.append("y")

    # Build a filtered copy with only the requested attributes
    filtered_graph = nx.Graph()
    filtered_graph.add_nodes_from(self.nodes())
    filtered_graph.add_edges_from(self.edges())

    for node, node_data in self.nodes(data=True):
        for key, value in node_data.items():
            if key in node_attrs_set:
                filtered_graph.nodes[node][key] = value
    for u, v, edge_data in self.edges(data=True):
        for key, value in edge_data.items():
            if key in edge_attrs_set:
                filtered_graph.edges[u, v][key] = value
    for attr in graph_attrs_list:
        if attr in self.graph:
            filtered_graph.graph[attr] = self.graph[attr]

    data = from_networkx(filtered_graph)

    # Export _coords → pos
    if self.has_coords:
        positions = [self._coords[n] for n in sorted(self.nodes())]
        data.pos = torch.tensor(positions, dtype=torch.float64)

    # Export _node_weights → node_weights_attr
    if self.has_node_weights:
        weights = [self._node_weights[n] for n in sorted(self.nodes())]
        setattr(data, node_weights_attr, torch.tensor(weights, dtype=torch.float64))

    # Export _edge_weights → edge_weights_attr (one value per directed edge in edge_index)
    if self.has_edge_weights:
        edge_weights: list[float] = []
        for i in range(data.edge_index.shape[1]):
            u, v = int(data.edge_index[0, i].item()), int(data.edge_index[1, i].item())
            edge_key = (min(u, v), max(u, v))
            edge_weights.append(float(self._edge_weights[edge_key]))  # type: ignore[arg-type]
        setattr(data, edge_weights_attr, torch.tensor(edge_weights, dtype=torch.float64))

    return data

triangular(m: int, n: int, spacing: float = 1.0) -> DataGraph classmethod

Constructs a triangular lattice graph, with respective coordinates.

Parameters:

  • m
    (int) –

    Number of rows of triangles.

  • n
    (int) –

    Number of columns of triangles.

  • spacing
    (float, default: 1.0 ) –

    The distance between adjacent nodes on the final lattice.

Source code in qoolqit/graphs/data_graph.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
@classmethod
def triangular(
    cls,
    m: int,
    n: int,
    spacing: float = 1.0,
) -> DataGraph:
    """
    Constructs a triangular lattice graph, with respective coordinates.

    Arguments:
        m: Number of rows of triangles.
        n: Number of columns of triangles.
        spacing: The distance between adjacent nodes on the final lattice.
    """
    G = nx.triangular_lattice_graph(m, n, with_positions=True)
    G = nx.convert_node_labels_to_integers(G)
    pos_unit = nx.get_node_attributes(G, "pos")

    final_pos = {node: (x * spacing, y * spacing) for node, (x, y) in pos_unit.items()}

    graph = cls.from_coordinates(final_pos)
    graph.add_edges_from(G.edges)
    graph._reset_dicts()
    return graph

ud_edges(radius: float) -> set

Returns the set of edges given by the intersection of circles of a given radius.

Parameters:

  • radius
    (float) –

    the value

Source code in qoolqit/graphs/base_graph.py 
311
312
313
314
315
316
317
318
319
320
def ud_edges(self, radius: float) -> set:
    """Returns the set of edges given by the intersection of circles of a given radius.

    Arguments:
        radius: the value
    """
    if self.has_coords:
        return set(e for e, d in self.distances().items() if less_or_equal(d, radius))
    else:
        raise AttributeError("Getting unit disk edges is not valid without coordinates.")

ud_radius_range() -> tuple

Return the range (R_min, R_max) where the graph is unit-disk.

The graph is unit-disk if the maximum distance between all connected nodes is smaller than the minimum distance between disconnected nodes. This means that for any value R in that interval, the following condition is true:

graph.ud_edges(radius = R) == graph.sorted edges

Source code in qoolqit/graphs/base_graph.py 
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
def ud_radius_range(self) -> tuple:
    """Return the range (R_min, R_max) where the graph is unit-disk.

    The graph is unit-disk if the maximum distance between all connected nodes is
    smaller than the minimum distance between disconnected nodes. This means that
    for any value R in that interval, the following condition is true:

    graph.ud_edges(radius = R) == graph.sorted edges
    """
    if self.has_coords:
        n_edges = len(self.sorted_edges)
        if n_edges == 0:
            # If the graph is empty and has coordinates
            return (0.0, self.min_distance(connected=False))
        elif n_edges == len(self.all_node_pairs):
            # If the graph is fully connected
            return (self.max_distance(connected=True), float("inf"))
        elif self.max_distance(connected=True) < self.min_distance(connected=False):
            return (self.max_distance(connected=True), self.min_distance(connected=False))
        else:
            raise ValueError("Graph is not unit disk.")
    else:
        raise AttributeError("Checking if graph is unit disk is not valid without coordinates.")

all_node_pairs(nodes: Iterable) -> set

Return all pairs of nodes (u, v) where u < v.

Parameters:

  • nodes

    (Iterable) –

    set of node indices.

Source code in qoolqit/graphs/utils.py 
13
14
15
16
17
18
19
def all_node_pairs(nodes: Iterable) -> set:
    """Return all pairs of nodes (u, v) where u < v.

    Arguments:
        nodes: set of node indices.
    """
    return set(filter(lambda x: x[0] < x[1], product(nodes, nodes)))

distances(coords: dict, edge_list: Iterable) -> dict

Return a dictionary of edge distances.

Parameters:

  • coords

    (dict) –

    dictionary of node coordinates.

  • edge_list

    (Iterable) –

    edge list to compute the distances for.

Source code in qoolqit/graphs/utils.py 
22
23
24
25
26
27
28
29
def distances(coords: dict, edge_list: Iterable) -> dict:
    """Return a dictionary of edge distances.

    Arguments:
        coords: dictionary of node coordinates.
        edge_list: edge list to compute the distances for.
    """
    return {edge: dist(coords[edge[0]], coords[edge[1]]) for edge in edge_list}

random_coords(n: int, L: float = 1.0) -> list

Generate a random set of node coordinates on a square of side L.

Parameters:

  • n

    (int) –

    number of coordinate pairs to generate.

  • L

    (float, default: 1.0 ) –

    side of the square.

Source code in qoolqit/graphs/utils.py 
65
66
67
68
69
70
71
72
73
74
def random_coords(n: int, L: float = 1.0) -> list:
    """Generate a random set of node coordinates on a square of side L.

    Arguments:
        n: number of coordinate pairs to generate.
        L: side of the square.
    """
    x_coords = np.random.uniform(low=-L / 2, high=L / 2, size=(n,)).tolist()
    y_coords = np.random.uniform(low=-L / 2, high=L / 2, size=(n,)).tolist()
    return [(x, y) for x, y in zip(x_coords, y_coords)]

random_edge_list(nodes: Iterable, k: int) -> list

Generates a random set of k edges linkings items from a set of nodes.

Source code in qoolqit/graphs/utils.py 
77
78
79
80
def random_edge_list(nodes: Iterable, k: int) -> list:
    """Generates a random set of k edges linkings items from a set of nodes."""
    all_edges = all_node_pairs(nodes)
    return random.sample(tuple(all_edges), k=k)

scale_coords(coords: dict, scaling: float) -> dict

Scale the coordinates by a given value.

Parameters:

  • coords

    (dict) –

    dictionary of node coordinates.

  • scaling

    (float) –

    value to scale by.

Source code in qoolqit/graphs/utils.py 
41
42
43
44
45
46
47
48
49
def scale_coords(coords: dict, scaling: float) -> dict:
    """Scale the coordinates by a given value.

    Arguments:
        coords: dictionary of node coordinates.
        scaling: value to scale by.
    """
    scaled_coords = {i: (c[0] * scaling, c[1] * scaling) for i, c in coords.items()}
    return scaled_coords

space_coords(coords: dict, spacing: float) -> dict

Spaces the coordinates so the minimum distance is equal to a set spacing.

Parameters:

  • coords

    (dict) –

    dictionary of node coordinates.

  • spacing

    (float) –

    value to set as minimum distance.

Source code in qoolqit/graphs/utils.py 
52
53
54
55
56
57
58
59
60
61
62
def space_coords(coords: dict, spacing: float) -> dict:
    """Spaces the coordinates so the minimum distance is equal to a set spacing.

    Arguments:
        coords: dictionary of node coordinates.
        spacing: value to set as minimum distance.
    """
    pairs = all_node_pairs(list(coords.keys()))
    min_dist = min(distances(coords, pairs).values())
    scale_factor = spacing / min_dist
    return scale_coords(coords, scale_factor)