neuralqx.graph.core.abstract_graph module

Public graph interface built on top of neuralqx.graph._graph_handler.GraphHandler.

This module defines AbstractGraph, a thin, user facing wrapper that exposes a consistent API for graphs used throughout neuraLQX. The underlying GraphHandler is responsible for

• validating and normalising edge data, including multiedge keys

• constructing primal and dual graphs in both NetworkX and NetKet formats

• maintaining embeddings and coordinate maps for non planar graphs

• computing local sign data used in volume like and grasping operators

Planar versus non planar In neuraLQX a planar graph uses integer vertex labels. A non planar graph is represented by edges whose endpoints are 3 tuples \((x,y,z)\) giving an embedding in \(\mathbb R^3\). When requested, a random embedding can be generated by reassigning each vertex coordinate from a normal distribution

\[(x,y,z)\sim \mathcal N(\mu,\sigma^2 I_3)\]

The abstract interface provides hooks for minimal loop extraction and loop dressing, which are used when constructing graph based operators such as plaquette terms and graph changing moves.

class AbstractGraph(edges, plot=False, *, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: ABC

Abstract base class for neuraLQX graphs.

An AbstractGraph owns a GraphHandler instance and delegates all low level construction to it. The class exposes a stable API used by Hilbert spaces, operators, solvers, and callbacks, independent of whether the graph is planar or non planar.

Edges

Edges are treated as oriented multigraph edges. Each edge is represented as a triple (u, v, key) where u is the tail, v is the head, and key distinguishes parallel edges between the same endpoints.

Dual graph

The dual graph is defined as the line graph of the primal graph, so dual vertices correspond to primal edges. The handler maintains a bijection between a primal edge and its dual vertex index.

Minimal loops

Concrete subclasses must implement access to minimal loops and their dressed variants. In this context, minimal loops refer to the shortest cycles in a cycle basis of the underlying undirected graph. Dressing attaches an orientation dependent label to each edge along the loop, which is typically used to select creation or annihilation type actions in operator kernels.

Sign data

The property :pyattr:`signs` exposes local orientation signs used in volume like constructions. For non planar embeddings this is based on the determinant of three tangent vectors, while for planar embeddings this reduces to a 2D oriented area convention.

type edges:

list

param edges:

List of oriented edges. Each edge is (u, v) or (u, v, key).

type plot:

bool

param plot:

If True, the handler may create and display diagnostic plots during construction.

type random_embedding:

bool

param random_embedding:

If True, treat the input as non planar and redraw all vertex coordinates from a Gaussian distribution.

type random_embedding_mean:

float

param random_embedding_mean:

Mean \(\mu\) used when random_embedding is True.

type random_embedding_std:

float

param random_embedding_std:

Standard deviation \(\sigma\) used when random_embedding is True.

type random_embedding_seed:

int

param random_embedding_seed:

Seed controlling the random embedding when random_embedding is True.

raises ValueError:

If the graph cannot be constructed from the provided edges.

abstractmethod minimal_loops()

Return minimal loops of the primal graph.

A minimal loop is a shortest cycle selected from a cycle basis of the underlying undirected graph. Equivalently, if \(\mathcal C\) denotes the cycle space and \(\mathcal B\subset\mathcal C\) a chosen basis, this method returns the subset of cycles in \(\mathcal B\) with minimal length.

Concrete subclasses decide the precise representation, for example a list of edge triples (u, v, key) or a list of vertex sequences.

Returns:

Minimal loops of the primal graph.

Raises:

NotImplementedError – If the concrete graph class does not implement loop extraction.

abstractmethod minimal_dual_loops(edge_rep)

Return minimal loops of the dual graph.

The dual graph is the line graph of the primal graph. Dual vertices correspond to primal edges, so a dual loop corresponds to a sequence of primal edges with consecutive incidence.

Parameters:

edge_rep (Optional[bool]) – If True, return dual loops using primal edge representations. If False, return dual loops using dual vertex indices, depending on the concrete implementation.

Returns:

Minimal loops of the dual graph.

Raises:

NotImplementedError – If the concrete graph class does not implement loop extraction.

abstractmethod dressed_minimal_loops()

Return dressed minimal loops of the primal graph.

Dressing adds orientation dependent structure to each edge in the loop. A common convention is to associate to each oriented edge either a creation like label or an annihilation like label, which in operator language corresponds to selecting actions analogous to \(a^\dagger\) or \(a\) depending on whether the loop traversal agrees with the edge orientation.

Concrete subclasses must specify the exact dressing schema and output format.

Returns:

Dressed minimal loops of the primal graph.

Raises:

NotImplementedError – If the concrete graph class does not implement dressed loop extraction.

abstractmethod dressed_minimal_dual_loops()

Return dressed minimal loops of the dual graph.

This is the dual analogue of dressed_minimal_loops(). Dressing is applied after selecting the minimal loops in the dual graph and may be expressed in terms of primal edge orientation data.

Returns:

Dressed minimal loops of the dual graph.

Raises:

NotImplementedError – If the concrete graph class does not implement dressed dual loops.

abstract property nk_graph

Return the NetKet graph associated with the primal graph.

Concrete subclasses may return a netket.graph.Graph instance constructed from the handler.

Returns:

NetKet primal graph.

Raises:

NotImplementedError – If not implemented by the concrete graph class.

abstract property dual_nk_graph

Return the NetKet dual graph of the primal graph.

The dual graph is typically constructed as the line graph of the primal graph and then converted to a netket.graph.Graph.

Returns:

NetKet dual graph.

Raises:

NotImplementedError – If not implemented by the concrete graph class.

abstract property nx_graph

Return the NetworkX multigraph associated with the primal graph.

Returns:

NetworkX primal graph.

Raises:

NotImplementedError – If not implemented by the concrete graph class.

abstract property dual_nx_graph

Return the NetworkX graph associated with the dual of the primal graph.

Returns:

NetworkX dual graph.

Raises:

NotImplementedError – If not implemented by the concrete graph class.

property signs

Return local sign data for the primal graph.

For a non planar embedding, signs are defined for ordered triples of edges incident at a vertex. Let \(t_1,t_2,t_3\in\mathbb R^3\) be unit tangents of three incident oriented edges at a vertex \(v\). The sign is

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

For a planar embedding, signs reduce to ordered edge pairs using a 2D orientation convention. If \(t_1,t_2\in\mathbb R^2\) are outgoing tangents at the vertex, an equivalent geometric quantity is the oriented area

\[\operatorname{sgn}(t_{1x} t_{2y} - t_{1y} t_{2x})\]

The handler decides which convention is used based on whether the graph is planar.

Returns:

A dictionary of sign tables keyed by vertex.

property is_planar

Return True if the graph is planar under neuraLQX conventions.

A planar graph uses integer vertex labels. A non planar graph uses 3 tuple vertex labels \((x,y,z)\) describing an embedding in \(\mathbb R^3\).

Returns:

True if vertices are integer labelled, otherwise False.

property edges

Return the list of oriented edges forming the graph.

Each edge is represented as (u, v, key) where key distinguishes parallel edges.

Returns:

List of oriented edges.

property vertices

Return the list of vertices of the graph in the handler’s internal representation.

For planar graphs, vertices are integers. For non planar graphs, vertices are integers in the internal representation and the original coordinate tuples are accessible via the non planar mappings.

Returns:

List of vertices.

property nonplanar_edges

Return the oriented edges in their original non planar coordinate representation.

In the non planar case, input vertices may be 3 tuples \((x,y,z)\). The handler stores a copy of the original edge list using these coordinate tuples. This property exposes that representation.

Returns:

List of oriented edges with coordinate tuple endpoints.

Raises:

NonExistentNonPlanarEdgesError – If called on a planar graph.

property mapping

Return the bijective mapping from oriented edges to integer indices.

Each oriented edge (u, v, key) is mapped to an integer index \(k\). This index identifies the position of the edge degree of freedom inside array based basis states, for example a local configuration \(\sigma\in\mathbb Z^N\) where \(\sigma_k\) stores the quantum number on the edge mapped to \(k\).

Returns:

Dictionary mapping edges to indices.

property nonplanar_vertex_mapping

Return the mapping from non planar vertex coordinates to internal integer labels.

For non planar graphs, the user may supply vertices as coordinate tuples \((x,y,z)\). The handler relabels these to integers for efficient indexing. This property returns the forward map from coordinate tuples to integers.

Returns:

Dictionary mapping coordinate tuples to integer labels.

Raises:

NonExistentNonPlanarVerticesError – If called on a planar graph.

property n_edges

Return the number of edges in the primal graph.

Returns:

Number of primal edges.

property n_vertices

Return the number of vertices in the primal graph.

Returns:

Number of primal vertices.

property n_dual_edges

Return the number of edges in the dual graph.

Returns:

Number of dual edges.

property n_dual_vertices

Return the number of vertices in the dual graph.

Returns:

Number of dual vertices.

edge_to_index(edge)

Map an oriented edge to its integer index.

The mapping is defined by the handler as a bijection between edges and indices. If the exact edge is not found, this method also tries the reversed orientation while keeping the same multiedge key. This supports situations where the caller provides an edge with opposite orientation to the stored convention.

Parameters:

edge (Union[list, tuple]) – Edge representation as a list or tuple. Expected form is (u, v, key).

Return type:

int

Returns:

Integer index of the edge degree of freedom.

Raises:

InvalidIndexError – If neither the given edge nor its reversed orientation exists in the mapping.

index_to_edge(index)

Map an integer index back to an oriented edge.

This is the inverse of edge_to_index(). The index refers to the position of an edge degree of freedom in an array based configuration.

Parameters:

index (int) – Integer index to invert.

Return type:

Union[list, tuple]

Returns:

Edge triple (u, v, key) in the handler’s orientation convention.

Raises:

OutOfRangeIndexError – If the index is not present in the mapping.

valence(node)

Return the valence of a vertex.

The valence is the number of edges incident to the vertex in the underlying multigraph. In an oriented setting this counts both incoming and outgoing edges, with multiplicity for parallel edges.

Parameters:

node (Union[int, tuple]) – Vertex label, either an integer (planar) or a coordinate tuple (non planar input).

Return type:

int

Returns:

Valence of the vertex.

nonplanar_vertex_to_index(nonplanar_vertex)

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

Parameters:

nonplanar_vertex (tuple) – Vertex coordinate tuple \((x,y,z)\).

Return type:

int

Returns:

Integer label used internally by the handler.

Raises:

NonExistentNonPlanarVerticesError – If called on a planar graph.

export(filename, *, dpi=300)

Export a visual representation of the graph to an image file.

This delegates to the handler, which chooses an appropriate renderer depending on whether the graph is planar or non planar.

Parameters:

• filename (str) – Output path for the exported image.

• dpi (int) – Resolution in dots per inch used when rendering.

Return type:

None

Returns:

None.

edges_at(vertex)

Return oriented edges whose head equals the specified vertex.

This selects edges (u, v, key) such that v == vertex. For a directed graph, these are the incoming edges at that vertex.

Parameters:

vertex (int) – Integer label of the vertex.

Return type:

list

Returns:

List of incoming oriented edges at vertex.

edges_from(vertex)

Return oriented edges whose tail equals the specified vertex.

This selects edges (u, v, key) such that u == vertex. For a directed graph, these are the outgoing edges from that vertex.

Parameters:

vertex (int) – Integer label of the vertex.

Return type:

list

Returns:

List of outgoing oriented edges from vertex.