neuralqx.graph.core.utils.build module¶

Graph construction helpers for the GraphHandler.

This module builds derived graph objects used by neuraLQX, in particular the dual graph defined as the line graph. For a graph \(G=(V,E)\), the line graph \(L(G)\) has vertex set \(E\), and two vertices in \(L(G)\) are connected when the corresponding edges in \(G\) share an endpoint.

The helpers also provide relabelling utilities for NetworkX graphs and a labelling scheme that maps integer vertices to fixed length 3 tuples for non planar embeddings.

map_distinct_vertices(connections_list)¶

Build a stable index mapping for the distinct vertices of a dual graph edge list.

The dual graph is represented by edges whose endpoints are original graph edges, for example edge keys like (u, v, k). This function collects all distinct such endpoints, sorts them deterministically, and assigns an integer index to each.

Parameters:: connections_list (list) – List of dual graph edges, where each element contains two endpoints that represent original graph edges.
Return type:: tuple[list[tuple], dict]
Returns:: A pair (sorted_vertices, distinct_vertices_map) where sorted_vertices is the sorted list of distinct endpoints and distinct_vertices_map maps each endpoint to its integer index.

map_edges(connections_list, mapping)¶

Map a list of dual graph edges onto integer vertex indices.

Given a list of edges expressed in terms of endpoint keys and a mapping from those keys to integers, this function returns the same edge list but with endpoints replaced by their mapped indices.

Parameters:

connections_list (list) – List of edges as pairs of endpoint keys.
mapping (dict) – Mapping from endpoint key to integer index.

Return type:

list[list]

Returns:

List of mapped edges as pairs of integers.

create_dual_nk_graph(handler, g=0, *, is_nonplanar=False)¶

Create the dual NetKet graph and an associated mapping.

The dual graph is constructed as the line graph \(L(G)\) of a NetworkX graph \(G\). Vertices of \(L(G)\) correspond to edges of \(G\), and adjacency corresponds to sharing an endpoint in \(G\).

By default, the input graph is taken from the handler. If is_nonplanar is True, the returned mapping is inverted so it maps dual vertex indices back to the original edge keys, which is convenient for non planar workflows.

Parameters:

handler (GraphHandler) – GraphHandler instance providing the base NetworkX graph.
g (int) – Optional NetworkX graph to dualise. If set to 0, the handler graph is used.
is_nonplanar (bool) – If True, invert the mapping to return index to key.

Return type:

tuple[Graph, dict]

Returns:

A pair (dual_nk_graph, mapping) where dual_nk_graph is a netket.graph.Graph for the line graph and mapping converts between the original edge key representation and the dual vertex indices, possibly inverted.

create_dressed_nx_graph(handler)¶

Add orientation metadata to the handler NetworkX multigraph edges.

Each edge is dressed with two attributes

s the start vertex of the directed edge
e the end vertex of the directed edge

These attributes are used later to classify edges along oriented cycles.

Parameters:: handler – GraphHandler instance providing nx_graph and the edge list.
Return type:: None
Returns:: None.

create_dual_nx_edges(handler)¶

Populate a handler side list of dual NetworkX edges expressed in dual vertex indices.

This walks the edges of handler.dual_nx_graph and maps each endpoint, which is an original graph edge key, to an integer dual vertex label using the handler mapping.

Parameters:: handler – GraphHandler instance providing dual_nx_graph and a mapping method.
Return type:: None
Returns:: None.

find_connected_edges(handler, graph_vertex)¶

Collect incoming and outgoing edges incident to a given vertex.

Edges are considered directed according to the dressed attributes s and e stored on the handler NetworkX multigraph. An edge is outgoing if its s equals the queried vertex, and incoming if its e equals the queried vertex.

Parameters:

handler (GraphHandler) – GraphHandler instance providing the dressed NetworkX multigraph.
graph_vertex (int) – Vertex index for which to collect incident edges.

Return type:

dict[str, list[tuple[int, int, int]]]

Returns:

Dictionary with keys "outgoing" and "incoming" each containing a list of edges represented as (u, v, key) tuples.

init_node_connectivity(handler)¶

Initialise per vertex connectivity lists for the handler.

For each vertex in the handler NetworkX graph, this computes the incoming and outgoing incident edges and stores them under handler.list_of_node_connectivity.

Parameters:: handler – GraphHandler instance providing nx_graph and storage fields.
Return type:: None
Returns:: None.

dress_minimal_cycles_edges(handler)¶

Dress edges of minimal cycles with creation and annihilation types.

For each minimal cycle, each directed edge is compared against the dressed NetworkX edge attributes to decide whether it matches the stored start direction. If it does, the edge is labelled as "creation", otherwise it is labelled as "annihilation". If the edge cannot be matched, it is labelled as "unknown".

The dressed cycles are appended to handler.minimal_cycles.

Parameters:: handler (GraphHandler) – GraphHandler instance providing minimal cycles and the dressed NetworkX graph.
Returns:: None.

index_to_label(i)¶

Map an integer vertex index to a fixed length 3 tuple label.

The mapping is defined by splitting the integer into a group index and a two bit suffix. Let \(i\) be the input, then

\[g = \lfloor i / 4 \rfloor, \qquad r = i \bmod 4, \qquad r = 2 b_1 + b_2\]

The output label is \((g, b_1, b_2)\).

Parameters:: i (int) – Integer vertex label.
Return type:: tuple[int, int, int]
Returns:: Tuple (group, y, z) where group is the quotient and (y, z) are the two bits of the remainder in binary.

relabel_edges_to_nonplanar(edges)¶

Relabel MultiGraph style edges to fixed length 3 tuple vertex labels.

This maps the set of unique endpoints to a contiguous index range and then applies index_to_label to obtain 3 tuple labels. Edge keys are preserved.

Parameters:: edges (list[tuple[int, int, int]]) – List of edges in the form (u, v, key).
Return type:: tuple[list[tuple[tuple[int, int, int], tuple[int, int, int], int]], dict[int, tuple[int, int, int]]]
Returns:: A pair (new_edges, vertex_mapping) where new_edges is a list of ((x1, y1, z1), (x2, y2, z2), key) edges and vertex_mapping maps each original vertex to its new 3 tuple label.

relabel_nx_edges(g)¶

Relabel NetworkX edges to a contiguous integer labelling scheme.

Vertices are mapped to integers in the order provided by g.nodes. The returned edge list contains the relabelled endpoints.

Parameters:: g (Graph) – NetworkX graph whose edges are to be relabelled.
Return type:: list
Returns:: List of edges with integer endpoints.

canonical_rotate(loop)¶

Choose a canonical cyclic rotation of an oriented loop.

A loop is represented as a list of edges (tail, head, key). A rotation is considered valid if it forms a closed oriented chain, meaning

\[\mathrm{head}(e_j) = \mathrm{tail}(e_{j+1})\]

with indices taken modulo the loop length. Among all valid cyclic rotations, this function returns the one whose first tail vertex is minimal under the default ordering.

Parameters:: loop (List[Tuple[Any, Any, int]]) – List of directed edges representing a loop.
Return type:: List[Tuple[Any, Any, int]]
Returns:: Canonically rotated loop as a list of directed edges. If no valid rotation exists, the input loop is returned unchanged.