qoolqit.graphs

package

qoolqit.graphs

Classes

• DataGraph — The main graph structure to represent problem data.

• BaseGraph — The BaseGraph in QoolQit, direclty inheriting from the NetworkX Graph.

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.

class

DataGraph (edges: Iterable = [])

Bases : BaseGraph

The main graph structure to represent problem data.

Default constructor for the BaseGraph.

Parameters

• edges : Iterable — set of edge tuples (i, j)

Attributes

• adj — Graph adjacency object holding the neighbors of each node.

• name — String identifier of the graph.

• nodes — A NodeView of the Graph as G.nodes or G.nodes().

• edges — An EdgeView of the Graph as G.edges or G.edges().

• degree — A DegreeView for the Graph as G.degree or G.degree().

• sorted_edges : set — Returns the set of edges (u, v) such that (u < v).

• all_node_pairs : set — Return a list of all possible node pairs in the graph.

• has_coords : bool — Check if the graph has coordinates.

• has_edges : bool — Check if the graph has edges.

• coords : dict — Return the dictionary of node coordinates.

• node_weights : dict — Return the dictionary of node weights.

• edge_weights : dict — Return the dictionary of edge weights.

• has_node_weights : bool — Check if the graph has node weights.

• has_edge_weights : bool — Check if the graph has edge weights.

Methods

• line — Constructs a line graph, with the respective coordinates.

• circle — Constructs a circle graph, with the respective coordinates.

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

• triangular — Constructs a triangular lattice graph, with respective coordinates.

• hexagonal — Constructs a hexagonal lattice graph, with respective coordinates.

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

• random_ud — Constructs a random unit-disk graph.

• from_matrix — Constructs a graph from a symmetric square matrix.

• from_pyg — Create a graph from a pyg data object.

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

classmethod

line (n: int, spacing: float = 1.0) → DataGraph

Constructs a line graph, with the respective coordinates.

Parameters

• n : int — number of nodes.

• spacing : float — distance between each node.

classmethod

circle (n: int, spacing: float = 1.0, center: tuple = (0.0, 0.0)) → DataGraph

Constructs a circle graph, with the respective coordinates.

Parameters

• n : int — number of nodes.

• spacing : float — distance between each node.

• center : tuple — point (x, y) to set as the center of the graph.

classmethod

random_er (n: int, p: float, seed: int | None = None) → DataGraph

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 — random seed.

classmethod

triangular (m: int, n: int, spacing: float = 1.0) → DataGraph

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 — The distance between adjacent nodes on the final lattice.

classmethod

hexagonal (m: int, n: int, spacing: float = 1.0) → DataGraph

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 — The distance between adjacent nodes on the final lattice.

classmethod

heavy_hexagonal (m: int, n: int, spacing: float = 1.0) → DataGraph

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 — 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.

classmethod

random_ud (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).

Parameters

• n : int — number of nodes.

• radius : float — radius to use for defining the unit-disk edges.

• L : float | None — size of the square on which to sample the node coordinates.

classmethod

from_matrix (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.

Parameters

• data : ArrayLike — symmetric square matrix.

Raises

• ValueError

classmethod

from_pyg (data) → DataGraph

Create a graph from a pyg data object.

Raises

• NotImplementedError

property

node_weights : dict

Return the dictionary of node weights.

property

edge_weights : dict

Return the dictionary of edge weights.

property

has_node_weights : bool

Check if the graph has node weights.

Requires all nodes to have a weight.

property

has_edge_weights : bool

Check if the graph has edge weights.

Requires all edges to have a weight.

method

set_ud_edges (radius: float) → None

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

class

BaseGraph (edges: Iterable = [])

Bases : nx.Graph

The BaseGraph in QoolQit, direclty 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.

Default constructor for the BaseGraph.

Parameters

• edges : Iterable — set of edge tuples (i, j)

Attributes

• adj — Graph adjacency object holding the neighbors of each node.

• name — String identifier of the graph.

• nodes — A NodeView of the Graph as G.nodes or G.nodes().

• edges — An EdgeView of the Graph as G.edges or G.edges().

• degree — A DegreeView for the Graph as G.degree or G.degree().

• sorted_edges : set — Returns the set of edges (u, v) such that (u < v).

• all_node_pairs : set — Return a list of all possible node pairs in the graph.

• has_coords : bool — Check if the graph has coordinates.

• has_edges : bool — Check if the graph has edges.

• coords : dict — Return the dictionary of node coordinates.

Methods

• from_nodes — Construct a base graph from a set of nodes.

• from_coordinates — Construct a base graph from a set of coordinates.

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

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

• min_distance — Returns the minimum distance in the graph.

• max_distance — Returns the maximum distance in the graph.

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

• is_ud_graph — Check if the graph is unit-disk.

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

• 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.

• draw — Draw the graph.

classmethod

from_nodes (nodes: Iterable) → BaseGraph

Construct a base graph from a set of nodes.

Parameters

• nodes : Iterable — set of nodes.

classmethod

from_coordinates (coords: list | dict) → BaseGraph

Construct a base graph from a set of coordinates.

Parameters

• coords : list | dict — list or dictionary of coordinate pairs.

property

sorted_edges : set

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

property

all_node_pairs : set

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

property

has_coords : bool

Check if the graph has coordinates.

Requires all nodes to have coordinates.

property

has_edges : bool

Check if the graph has edges.

property

coords : dict

Return the dictionary of node coordinates.

method

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 — set of edges.

Raises

• AttributeError

• ValueError

method

interactions () → dict

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

method

min_distance (connected: bool | None = None) → float

Returns the minimum distance in the graph.

Parameters

• connected : bool | None — if True/False, computes only over connected/disconnected nodes.

method

max_distance (connected: bool | None = None) → float

Returns the maximum distance in the graph.

Parameters

• connected : bool | None — if True/False, computes only over connected/disconnected nodes.

method

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

Raises

• AttributeError

• ValueError

method

is_ud_graph () → bool

Check if the graph is unit-disk.

method

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

Raises

• AttributeError

method

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 — value to scale by.

• spacing : float | None — value to set as the minimum distance in the graph.

Raises

• AttributeError

• TypeError

method

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.

method

draw (return_fig: bool = False, *args: Any, **kwargs: Any) → plt.Figure | None

Draw the graph.

Uses the draw_networkx function from NetworkX.

Parameters

• *args : Any — arguments to pass to draw_networkx.

• **kwargs : Any — keyword-arguments to pass to draw_networkx.

all_node_pairs (nodes: Iterable) → set

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

Parameters

• nodes : Iterable — set of node indices.

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.

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 — side of the square.

random_edge_list (nodes: Iterable, k: int) → list

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

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.

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.