neuralqx.graph.graph module

Concrete generic graph implementation.

This module defines Graph, the default concrete implementation of the AbstractGraph interface.

Design The Graph class is intentionally thin. It delegates almost all combinatorial and geometric work to the internal GraphHandler instance stored as handler.

In particular, the handler is responsible for

• building primal and dual graphs

• maintaining the bijection between keyed edges and integer indices

• extracting minimal cycles and dressing them with creation or annihilation metadata

• computing local sign factors used by volume type constructions

As a result, this class provides a stable public API while keeping implementation details contained in the handler.

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

Bases: AbstractGraph

A concrete directed multigraph wrapper used throughout neuraLQX.

The Graph class provides a user facing graph object that is compatible with neuraLQX Hilbert spaces, operators, and drivers. It exposes a small set of convenience methods and properties that forward to the underlying GraphHandler.

• Minimal loops

Let \(G\) be the underlying undirected graph obtained from the oriented edge set by forgetting direction and keys. A minimal loop in neuraLQX refers to a cycle in a minimum cycle basis of \(G\) together with a consistent oriented, keyed edge representation.

• Dual graph

The dual graph used here is the line graph \(L(G)\). Its vertices correspond to (keyed) primal edges and its edges encode incidence in the primal graph.

minimal_loops()

Return the minimal loops of the primal graph.

In neuraLQX, a minimal loop is represented as an ordered list of keyed oriented edges

\[\ell = \bigl[(u_0, u_1, k_0), (u_1, u_2, k_1), \dots, (u_{m-1}, u_0, k_{m-1})\bigr]\]

such that successive edges share endpoints and the sequence closes.

• How loops are chosen

The underlying handler constructs an undirected simple graph by ignoring keys and orientations and then extracts a minimum cycle basis. In addition, it explicitly accounts for two edge cycles that arise from parallel edges in a multigraph.

• Stability

Each loop is canonically rotated so that the representation is stable under cyclic permutations. This improves reproducibility in logs and doctests.

Returns:

A list of minimal loops. Each loop is a list of keyed oriented edges (u, v, key).

property n_minimal_loops

Return the number of minimal loops in the primal graph.

This is a convenience property equivalent to len(self.minimal_loops()). The value is computed from the handler data and therefore reflects the current graph structure.

Returns:

The number of minimal loops.

minimal_dual_loops(edge_rep=False)

Return the minimal loops of the dual graph.

The dual graph is the line graph \(L(G)\). A dual loop can be represented either

• as a list of keyed primal edges that form a closed walk in \(L(G)\) when interpreted as dual vertices, or

• as a list of dual vertex labels obtained via the mapping \(\mu\) from keyed primal edges to integers

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

where \(E(G)\) denotes the keyed oriented edge set.

Parameters:

edge_rep (bool) – If True, return loops in keyed edge representation (u, v, key). If False, return loops in the dual integer vertex representation.

Returns:

Minimal loops of the dual graph in the requested representation.

Raises:

NotImplementedError – If the underlying handler does not provide dual loop extraction for the current model.

dressed_minimal_loops()

Return dressed minimal loops of the primal graph.

A dressed loop augments each edge in a minimal loop with metadata describing its operator type with respect to the loop orientation. Conceptually, this corresponds to choosing an orientation of the loop and assigning, for each traversed edge, whether the associated edge operator acts as a creation or annihilation along that traversal.

Returns:

The list of dressed minimal loops stored by the handler.

dressed_minimal_dual_loops()

Return dressed minimal loops of the dual graph.

This is the dual analogue of dressed_minimal_loops(). Each loop is represented in the handler chosen dual convention and each segment carries dressing metadata.

Depending on the model, the dressing may encode how dual edge traversals map back to primal edge operators, for example when implementing dual plaquette moves or dual holonomy constructions.

Returns:

The list of dressed minimal dual loops stored by the handler.

property nk_graph

Return the NetKet graph of the primal graph.

This is the NetKet representation used by samplers, Hilbert spaces, and operators that expect netket.graph.Graph.

Returns:

The primal NetKet graph.

property dual_nk_graph

Return the NetKet graph of the dual graph.

The dual is constructed as the line graph of the primal NetworkX multigraph and then converted to a NetKet graph. Dual vertices correspond to keyed primal edges.

Returns:

The dual NetKet graph.

property nx_graph

Return the NetworkX multigraph of the primal graph.

The NetworkX graph is used for connectivity queries, extracting cycle bases, and for attaching edge attributes used in loop dressing and sign computations.

Returns:

The primal NetworkX multigraph.

property dual_nx_graph

Return the NetworkX graph of the dual graph.

The dual NetworkX graph is the line graph of the primal multigraph. It is primarily used for diagnostics and for algorithms that naturally live on the dual, such as dual loop enumeration.

Returns:

The dual NetworkX graph.