neuralqx.graph.core.graph_handler module

Internal construction utilities for neuraLQX graphs.

This module provides GraphHandler, the implementation behind the public AbstractGraph interface. The handler owns the concrete graph data structures and is responsible for turning a user supplied edge list into

  • a NetKet graph \(G\) used by samplers and Hilbert spaces

  • a NetworkX multigraph used for connectivity queries and cycle computations

  • the dual graph, defined as the line graph \(L(G)\)

  • a bijection between oriented edges and integer indices, used to index edge degrees of freedom in array based configurations

  • local sign tables used by volume like and grasping constructions

Planar versus non planar A planar graph uses integer vertex labels. A non planar graph uses vertices that are coordinate tuples \((x,y,z)\in\mathbb R^3\). For non planar input, the handler relabels the coordinate tuples to contiguous integers for efficient indexing, while preserving an inverse map to recover the original coordinates.

Dual graph Let \(G=(V,E)\) be the (multi)graph. The dual graph used here is the line graph \(L(G)\), whose vertex set is \(V(L(G))=E(G)\) and where two dual vertices are adjacent whenever their corresponding primal edges share an endpoint. The handler stores a mapping

\[\mu : E(G) \to \{0,1,\dots,|E(G)|-1\}\]

which identifies each (keyed) primal edge with an integer label for the corresponding dual vertex.

Local sign data Depending on planarity, sign data is computed using different geometric conventions

  • Non planar, triple edge sign at a vertex \(v\) using tangents \(t_i\in\mathbb R^3\)

    \[\varepsilon(e_1,e_2,e_3) = \operatorname{sgn}\bigl(\det[t_1\ t_2\ t_3]\bigr)\]

  • Planar, ordered edge pair sign at a vertex using a 2D orientation convention, for tangents \(t_1,t_2\in\mathbb R^2\)

    \[\operatorname{sgn}(e_1,e_2) = \operatorname{sgn}(t_{1x}t_{2y}-t_{1y}t_{2x})\]

The handler computes and stores these signs for both the primal graph and, when needed, the dual graph.

class GraphHandler(edges, coordinates=None, plot=False)

Bases: object

Concrete graph construction and bookkeeping.

The GraphHandler class is the workhorse that builds all graph representations needed by neuraLQX. It is created with a list of oriented edges and optionally a coordinate map for non planar graphs. After initialisation it provides

  • edges and vertices in internal integer labelling

  • nk_graph as a netket.graph.Graph

  • nx_graph as a networkx.MultiGraph with dressed edge attributes

  • dual_nk_graph and dual_nx_graph as dual representations

  • mapping, a bijection between (keyed) edges and integer indices

  • graph_signs and dual_graph_signs, local sign tables

  • minimal_cycles, a collection of dressed minimal loops

Input edge format

Edges may be given as (u, v) or (u, v, key). If any parallel edges exist between the same endpoints, keys must be provided for all edges to disambiguate them. If no keys are provided and no duplicates exist, the handler inserts the default key 0 for every edge.

Non planar relabelling

For non planar input, vertex labels are coordinate tuples. The handler constructs a relabelling map

\[\pi : V_{\mathrm{orig}} \to \{0,1,\dots,|V|-1\}\]

and rewrites all edges in terms of these integer labels while preserving

  • _nonplanar_int2orig_map mapping integers back to coordinates

  • _nonplanar_orig2int_map mapping coordinates to integers

Minimal loops

Minimal loops are extracted from a minimum cycle basis of the underlying undirected simple graph, with special handling for two edge cycles arising from parallel edges. Loop edges are returned as keyed triples (u, v, key) and then canonically rotated to a stable representative.

type edges:

List[List[int]]

param edges:

Oriented edge list. Each edge is (u, v) or (u, v, key).

type coordinates:

Optional[Dict]

param coordinates:

Optional mapping used for random embeddings, typically keyed by integer labels.

type plot:

bool

param plot:

If True, compute layout positions and display plots for diagnostics.

raises TypeError:

If keyed and unkeyed edges are mixed.

raises ValueError:

If duplicate unkeyed edges are supplied.

map_edge_to_dual_vertex(edge)

Map a keyed primal edge to the corresponding dual vertex label.

The dual graph is the line graph, so every primal edge becomes a dual vertex. The handler stores a mapping \(\mu\) from keyed edges (u, v, key) to an integer label. If the exact oriented edge is not found, the reversed orientation is also tried while keeping the key fixed.

Parameters:

edge (tuple[int, int]) – A keyed edge triple (u, v, key).

Return type:

Optional[int]

Returns:

The integer label of the corresponding dual vertex, or None if not found.

inverse_mapping(vertex)

Invert the edge to index mapping for one dual vertex.

Given a dual vertex label \(w\in V(L(G))\), this returns the primal edge (u, v, key) satisfying \(\mu(u,v,key)=w\) if it exists.

This is a convenience method for diagnostics and for algorithms that traverse the dual graph and need to recover the associated primal edge.

Parameters:

vertex (int) – Integer label of the dual vertex.

Return type:

Optional[tuple[int, int]]

Returns:

The corresponding keyed edge triple, or None if not found.

convert_vertex_to_int(v)

Convert a non planar coordinate vertex to its internal integer label.

For non planar graphs, vertices are originally supplied as coordinate tuples \((x,y,z)\in\mathbb R^3\). The handler relabels them to integers for indexing. This method performs the inverse lookup, returning the integer label associated with the given coordinate triple.

Parameters:

v (tuple[int, int, int]) – Vertex coordinate tuple (x, y, z).

Return type:

Optional[int]

Returns:

Integer label if present, otherwise None.

Raises:

NotImplementedError – If called on a planar graph.

get_smallest_loops()

Return all smallest-length loops (shortest simple cycles) as keyed oriented edges (u, v, key).

Return type:

List[List[Tuple[Any, Any, int]]]

What “smallest-length” means here:

  • If the multigraph has parallel edges between the same unordered endpoints {u,v}, then there exist 2-edge cycles. Those are the shortest possible, so we return all such 2-edge cycles and stop.

  • Otherwise, we compute the girth (length of the shortest cycle) of the underlying simple undirected graph (keys + orientations ignored), and return all simple cycles of that length, converted back to keyed oriented edges using a deterministic key choice (the minimum key on each undirected segment).

Notes

  • This avoids nx.minimum_cycle_basis() because that returns only a basis, not all shortest cycles.

  • We deduplicate cycles via canonical rotation.

get_smallest_dual_loops(edge_rep=False)

Return all smallest-length loops (shortest simple cycles) as keyed oriented edges (u, v, key) in the dual loop. By default, the vertices in the dual graph are labelled by the primal edges. If the edge_rep is truthy, the minimal loops are returned such that the vertices are labelled as dual vertices and not primal edges.

Return type:

Union[list[list[tuple[int, int, int]]], list[list]]

What “smallest-length” means here:

  • If the multigraph has parallel edges between the same unordered endpoints {u,v}, then there exist 2-edge cycles. Those are the shortest possible, so we return all such 2-edge cycles and stop.

  • Otherwise, we compute the girth (length of the shortest cycle) of the underlying simple undirected graph (keys + orientations ignored), and return all simple cycles of that length, converted back to keyed oriented edges using a deterministic key choice (the minimum key on each undirected segment).

Notes

  • This avoids nx.minimum_cycle_basis() because that returns only a basis, not all shortest cycles.

  • We deduplicate cycles via canonical rotation.

print_signs(dual_signs=False)

Pretty print stored sign tables.

This is a diagnostic helper that prints the sign tables stored in graph_signs or dual_graph_signs. For planar graphs the printed entries correspond to ordered edge pairs, while for non planar graphs they correspond to ordered edge triples.

Parameters:

dual_signs (bool) – If True, print signs for the dual graph, otherwise print primal signs.

Return type:

None

Returns:

None.

export(filename, *, dpi=300)

Export a static visualisation of the graph to an image file.

This method creates a figure without requiring interactive plotting and writes it to filename. The renderer depends on planarity

  • Planar graphs use the 2D directed multigraph drawing routine, optionally with dual data

  • Non planar graphs use the 3D renderer based on stored coordinate maps

Parameters:

  • filename (str) – Output image path.

  • dpi (int) – Resolution used when saving the figure.

Return type:

None

Returns:

None.

Raises:

RuntimeError – If no figure could be produced for export.