neuralqx.graph package

This module contains the implementation of the GraphHandler class for neuralqx

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.

class HalfLadderGraph(length, connected=False, *, plot=False, non_planar=False)

Bases: Graph

This Graph is one which represents half a ladder. That is, it looks like this:

5 6 7 8 9 | | | | | 0—1—2—3—4

where the integers represent vertices and the lines represent edges (oriented in incrementing order).

If you specify connected = True, then it will create a loop graph, connected in the example above the vertex 4 to 0.

In this context, the vertices lying on the main graph (0, 1, 2, 3, 4) are called k-vertices and the edges connecting them are called k-edges. The vertices (5, 6, 7, 8, 9) which branch out from the k-vertices are called μ-vertices. In similar fashion, edges connecting the k- and μ- vertices are called μ-edges.

Note

This half ladder implementation contains extra information such as the k- and μ- vertices/edges because it was initially developed for a certain spherically symmetric model.

class SingleVertexGraph(valence, orientation=None, *, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

Star graph with one central vertex and prescribed edge orientations.

This graph has a distinguished central vertex labelled 0 and valence external vertices labelled 1,2,\dots,valence. For each external vertex \(i\), there is exactly one edge connecting \(0\) and \(i\). The orientation of each edge is controlled by an integer direction \(d_i\in\{+1,-1\}\):

  • \(d_i=+1\) gives an edge \(0\to i\),

  • \(d_i=-1\) gives an edge \(i\to 0\).

If orientation is not provided, all edges are oriented outwards (all \(d_i=+1\)).

If non_planar=True, vertices are relabelled to fixed-length 3-tuples and may be given a random spatial embedding.

Parameters:

  • valence (int) – Number of edges incident at the central vertex.

  • orientation (Optional[list]) – Optional list of length valence with entries in {+1, -1}.

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, relabel vertices to 3-tuples to trigger the non-planar pipeline.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

Raises:

OrientationValenceMismatchError – If orientation is provided with the wrong length.

class TriangularLatticeGraph(m, n, periodic=False, *, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

Triangular lattice graph on an \(m\times n\) patch, optionally periodic.

This graph is a two-dimensional lattice obtained from a rectangular grid by adding diagonal connections so that elementary faces become triangles (as in networkx.generators.triangular_lattice_graph()). The periodic flag enables periodic boundary conditions in the NetworkX construction.

NetworkX uses coordinate-labelled vertices for this generator; neuraLQX relabels them to consecutive integers before constructing Graph. If non_planar=True, vertices are relabelled to 3-tuples and may be given a random spatial embedding.

Parameters:

  • m (int) – Lattice size parameter (as interpreted by the NetworkX generator).

  • n (int) – Lattice size parameter (as interpreted by the NetworkX generator).

  • periodic (bool) – If True, impose periodic boundary conditions as supported by NetworkX.

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, relabel vertices to 3-tuples to trigger the non-planar pipeline.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

class HypercubeGraph(N, *, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

\(N\)-dimensional hypercube graph \(Q_N\).

Vertices correspond to bit-strings of length \(N\), i.e. \(\{0,1\}^N\), and two vertices are adjacent iff they differ in exactly one bit (Hamming distance one). Consequently:

\[|V| = 2^N,\qquad |E| = N\,2^{N-1}.\]

The graph is constructed from networkx.generators.hypercube_graph(), then relabelled to consecutive integer vertex labels before being passed to Graph. If non_planar=True, vertices are relabelled to 3-tuples and may be given a random spatial embedding.

Parameters:

  • N (int) – Hypercube dimension.

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, relabel vertices to 3-tuples to trigger the non-planar pipeline.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

class HexagonalLatticeGraph(m, n, periodic=False, *, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

Hexagonal (honeycomb) lattice graph with \(m\) rows and \(n\) columns of hexagons.

This graph is the 1-skeleton of the hexagonal tiling of the plane, arranged such that odd numbered columns are shifted relative to even numbered columns (as in networkx.generators.hexagonal_lattice_graph()). The periodic flag enables periodic boundary conditions in the NetworkX construction.

NetworkX uses coordinate-labelled vertices for this generator; neuraLQX relabels them to consecutive integers before constructing Graph. If non_planar=True, vertices are relabelled to 3-tuples and may be given a random spatial embedding.

Parameters:

  • m (int) – Number of hexagon rows.

  • n (int) – Number of hexagon columns.

  • periodic (bool) – If True, impose periodic boundary conditions as supported by NetworkX.

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, relabel vertices to 3-tuples to trigger the non-planar pipeline.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

class DodecahedralGraph(*, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

Dodecahedral graph.

This is the 1-skeleton of the regular dodecahedron. It is a 3-regular graph with

\[|V| = 20,\qquad |E| = 30.\]

The graph is constructed from networkx.generators.dodecahedral_graph(), then relabelled to consecutive integer vertex labels before being passed to Graph. If non_planar=True, vertices are relabelled to fixed-length 3-tuples and may be given a random spatial embedding.

Parameters:

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, relabel vertices to 3-tuples to trigger the non-planar pipeline.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

class CircularLadderGraph(N, *, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

Circular ladder graph \(C_N \,\square\, K_2\).

This graph consists of two concentric \(N\)-cycles (“rails”) together with \(N\) rungs joining corresponding vertices on the two rails. Equivalently, its vertex set can be written as

\[V = \{0,1,\dots,N-1\} \times \{0,1\},\]

with edges \((i,a)\sim(i\pm1 \!\!\!\pmod N, a)\) (cycle edges) and \((i,0)\sim(i,1)\) (rungs).

Basic counts (for \(N\ge 3\)):

\[|V| = 2N,\qquad |E| = 3N.\]

The underlying NetworkX graph is relabelled to consecutive integer vertex labels before being passed to Graph. If non_planar=True, vertices are instead relabelled to fixed-length 3-tuples and can optionally be given a random spatial embedding.

Parameters:

  • N (int) – Ladder length (number of rungs / cycle length).

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, relabel vertices to 3-tuples to trigger the non-planar pipeline.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

class LadderGraph(N, *, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

Ladder graph \(P_N \,\square\, K_2\).

This graph consists of two path graphs of length \(N-1\) (“rails”) with \(N\) rungs connecting corresponding vertices. A convenient description is

\[V = \{0,1,\dots,N-1\}\times\{0,1\},\]

with edges \((i,a)\sim(i+1,a)\) for \(i=0,\dots,N-2\) and rungs \((i,0)\sim(i,1)\).

Basic counts (for \(N\ge 2\)):

\[|V| = 2N,\qquad |E| = (2N-2) + N = 3N - 2.\]

The underlying NetworkX graph is relabelled to consecutive integer vertex labels before being passed to Graph. If non_planar=True, vertices are relabelled to fixed-length 3-tuples and may be given a random spatial embedding.

Parameters:

  • N (int) – Ladder length (number of rungs).

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, relabel vertices to 3-tuples to trigger the non-planar pipeline.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

class Grid2D(m, n, periodic=False, *, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

Two-dimensional rectangular grid graph \(P_m \,\square\, P_n\), optionally periodic.

For periodic=False, the graph is the Cartesian product of two path graphs, giving the usual \(m\times n\) rectangular lattice. For periodic=True, periodic boundary conditions are applied in both directions, yielding a torus graph \(C_m \,\square\, C_n\).

When non-periodic:

\[|V| = mn,\qquad |E| = m(n-1) + (m-1)n.\]

When periodic:

\[|V| = mn,\qquad |E| = 2mn.\]

The NetworkX generator uses 2D lattice coordinates internally; these are relabelled to consecutive integers before constructing Graph. If non_planar=True, vertices are relabelled to 3-tuples and may be given a random spatial embedding.

Parameters:

  • m (int) – Number of rows.

  • n (int) – Number of columns.

  • periodic (bool) – If True, impose periodic boundary conditions in both directions.

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, relabel vertices to 3-tuples to trigger the non-planar pipeline.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

class K5Graph(*, plot=False, non_planar=False, random_embedding=False, random_embedding_mean=0.0, random_embedding_std=5.0, random_embedding_seed=123)

Bases: Graph

Complete graph on five vertices \(K_5\).

This graph has vertex set \(\{0,1,2,3,4\}\) and an edge between every distinct pair, hence

\[|V| = 5,\qquad |E| = \binom{5}{2} = 10.\]

In neuraLQX this class provides a small, fixed test graph. When non_planar=True, a pre-defined 3-tuple vertex labelling is used so that the non-planar pipeline (including the non-planar sign computation) can be exercised without relying on a planar embedding.

Parameters:

  • plot (bool) – If True, produce a visualisation via the base graph machinery.

  • non_planar (bool) – If True, use the pre-defined 3-tuple vertex labels for the non-planar path.

  • random_embedding (bool) – If True, assign a random 3D embedding to vertices (non-planar only).

  • random_embedding_mean (float) – Mean of the Gaussian used for the random embedding.

  • random_embedding_std (float) – Standard deviation of the Gaussian used for the random embedding.

  • random_embedding_seed (int) – Seed controlling the random embedding.

Subpackages

Submodules