neuralqx.hilbert.u1.unconstrained_core module

Unconstrained \(U(1)\) Hilbert-space core.

This module implements UnconstrainedHilbertU1Core, the concrete core backend for the kinematical (unconstrained) Hilbert space of \(U(1)\)-valued edge degrees of freedom on a given graph.

A configuration (basis state) is represented as a 1D array sigma of length

\[N = G\,E,\]

where \(E\) is the number of edge sites in a single gauge copy and \(G\) is the number of gauge copies (gauge_dimensions). The layout is block-strided:

\[\sigma = \bigl[q_{0,0}, \ldots, q_{0,E-1} \;\big|\; q_{1,0}, \ldots, q_{1,E-1} \;\big|\; \cdots \bigr],\]

so that copy g occupies indices [g*E, (g+1)*E).

No gauge-fixing or Gauss constraints are imposed in this core: all tensor-product basis configurations built from the local domain are admissible. The local domain itself is defined by the base class neuralqx.hilbert._abstract_hilbert_core.AbstractHilbertSpace from the parameters cutoff, step, positive_qn, and qn_start.

class UnconstrainedHilbertU1Core(graph, cutoff, *, step=1, gauge_dimensions=1, positive_qn=False, qn_start=None)

Bases: AbstractHilbertSpace

Unconstrained \(U(1)\) Hilbert-space core.

This core represents the full tensor-product Hilbert space for \(U(1)\) edge variables on a graph, without imposing gauge invariance or gauge fixing. It is the implementation backend used by neuralqx.hilbert.u1.HilbertU1 when is_gauge_invariant=False.

Degrees of freedom and layout

Let \(E\) be the number of edge sites in a single gauge copy (in neuraLQX this is typically the number of dual-graph vertices, i.e. one site per primal edge degree of freedom), and let \(G\) be gauge_dimensions. A basis configuration is stored as a flat vector \(\sigma \in \mathbb{R}^{N}\) (or \(\mathbb{Z}^{N}\)) with

\[N = G\,E.\]

Conceptually, the same data may be viewed as a rank-2 array \(q_{g,e}\) of shape \((G, E)\) (gauge copy \(g\), edge site \(e\)), using the block layout

\[\sigma_{gE + e} = q_{g,e}.\]
Local basis (single-site domain)

The allowed local values are constructed by the base class neuralqx.hilbert._abstract_hilbert_core.AbstractHilbertSpace as a netket.utils.StaticRange. In the common symmetric case (positive_qn=False), the domain is

\[\mathcal{Q} = \{-c,\,-c+s,\,\ldots,\,c-s,\,c\},\]

where \(c\) is cutoff and \(s\) is step. When positive_qn=True, the domain is restricted to a non-negative range starting at qn_start (defaulting to 0 if omitted); the exact endpoint is determined by the base-class construction.

NetKet representation

This core builds a flat NetKet netket.hilbert.HomogeneousHilbert with:

  • N = E * G sites,

  • the local states given by self.allowed_basis_states.

Dimension bookkeeping

If the NetKet Hilbert is indexable (self.hilbert.is_indexable), the total number of basis states is taken from self.hilbert.n_states. Otherwise, the core stores the formal tensor size

\[\dim(\mathcal{H}) = |\mathcal{Q}|^{N},\]

which grows exponentially in \(N\) and may be extremely large. A scientific-notation string is cached for readable representations.

Parameters:

  • graph (AbstractGraph) – Graph defining the edge degrees of freedom and edge-index mappings.

  • cutoff (Union[int, float]) – Cutoff controlling the extent of the local \(U(1)\) basis.

  • step (Union[int, float]) – Step size between consecutive allowed local values.

  • gauge_dimensions (int) – Number of gauge copies \(G\) in the flattened block layout.

  • positive_qn (bool) – If True, restrict the local domain to non-negative values.

  • qn_start (Optional[int]) – Starting value for the local domain when positive_qn=True (defaults to 0 if omitted).

Returns:

None.

Raises:

ValueError – If gauge_dimensions < 1 (validated by the base class).

property layout: StridedGaugeCopyLayout

U(1) contiguous strided layout over gauge-copy blocks.

edge_to_site(edge, gauge_copy=0)

Map a graph edge token to a flattened U(1) site index.

Return type:

int

site_to_edge(site)

Inverse map from flat site index to (gauge_copy, edge_token).

Return type:

tuple[int, object]

view(sigma)

Reshape flat state(s) into (G, E) or (B, G, E) view.

Return type:

Array

flatten(sigma_view)

Flatten (G, E) or (B, G, E) view back to NetKet layout.

Return type:

Array

random_state(key, size=1)

Generate random U(1) unconstrained basis state(s).

Return type:

Array

flip_state(sigma, key, number_of_edges=1, *, adjacency=False, scope='single')

Propose U(1) unconstrained updates using dispatched U(1) move logic.

Return type:

Array