neuralqx.hilbert.u1.interface module

U(1) Hilbert-space interface.

This module defines HilbertU1, the user-facing entry point for constructing Hilbert spaces with local \(U(1)\) degrees of freedom on a graph.

A basis configuration is represented as a 1D array sigma whose entries encode edge charges (selected from a discrete set determined by cutoff and step). When gauge_dimensions = G, the configuration is stored in a block (strided) layout with \(G\) consecutive copies of the same edge set. Writing \(E\) for the number of edge sites in one copy, the flattened state has length \(N = G E\) and can be viewed as a tensor \(q_{g,e}\) with shape \((G, E)\).

The interface delegates all implementation details to a concrete core:

  • An unconstrained core for kinematical spaces (independent edge degrees of freedom).

  • A constrained core for gauge-invariant spaces, where gauge fixing is imposed and non-free edge variables are reconstructed deterministically.

class HilbertU1(graph, cutoff=inf, *, step=1, gauge_dimensions=1, is_gauge_invariant=False, gauge_fixing=None, auto_constraint=False, positive_qn=False, qn_start=None, **kwargs)

Bases: AbstractHilbertInterface[ConstrainedHilbertU1Core | UnconstrainedHilbertU1Core]

Concrete \(U(1)\) Hilbert-space interface.

This class provides a stable, user-facing API for constructing Hilbert spaces on a given graph with local \(U(1)\) edge degrees of freedom (integer or real-valued charges depending on cutoff/step). It is intentionally thin: it validates high-level configuration and then selects an appropriate core implementation which owns the NetKet Hilbert object, indexing logic, and move/state operations.

Core selection:

  • If is_gauge_invariant=False (default), UnconstrainedHilbertU1Core is used. The space is kinematical: each edge carries an independent local variable.

  • If is_gauge_invariant=True, ConstrainedHilbertU1Core is used. A gauge-fixing specification must be provided via gauge_fixing or generated via auto_constraint=True. The constrained core typically treats a subset of edge variables as free and reconstructs the remaining slave variables to satisfy the constraint.

Gauge copies:

If gauge_dimensions = G, a configuration is stored as \(G\) consecutive blocks, each of length \(E\) (the number of edge sites in one copy). Equivalently, the flattened state sigma can be reshaped to \(q_{g,e}\) with shape \((G, E)\).

Parameters:

  • graph (AbstractGraph) – Graph on which the Hilbert space is defined (edges provide the sites).

  • cutoff (Union[int, float]) – Cut-off controlling the local quantum-number domain (model-specific semantics).

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

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

  • is_gauge_invariant (bool) – If True, construct a gauge-invariant (constrained) space.

  • gauge_fixing (List[List[List[Union[int, str]]]]) – Gauge-fixing specification used when is_gauge_invariant=True. The expected structure is core-defined; for the U(1) constrained core it is typically a list describing which edges are fixed or how constraints are imposed.

  • auto_constraint (Optional[bool]) – If True and is_gauge_invariant=True, attempt to auto-generate a gauge fixing from the graph.

  • positive_qn (bool) – If True, restrict allowed local quantum numbers to be non-negative.

  • qn_start (Optional[int]) – Starting quantum number when positive_qn=True (defaults to 0 if omitted).

  • kwargs – Additional backend-specific options forwarded to the core builder.

Returns:

None.

Raises:
edge_charges(sigma, edge)

Return the charge values carried by a given graph edge in one or more configurations.

A U(1) configuration can be viewed (via the underlying core layout) as a tensor \(q_{g,e}\) with shape \((G, E)\), where \(G\) is the number of gauge copies and \(E\) is the number of edge sites per copy. For a fixed edge (site) index \(e\), this method extracts the vector

\[\bigl(q_{0,e}, q_{1,e}, \dots, q_{G-1,e}\bigr)\]

for each configuration in the input batch.

Input handling:

  • If sigma is a single state of shape (N,), it is treated as a batch of size 1.

  • If sigma has three or more dimensions, the leading dimensions are collapsed so that the last axis is interpreted as the flattened site axis.

Output shape:

The returned array is flattened to 1D. For a batch size \(B\) and gauge dimensions \(G\), the output has shape (B * G,). For a single input state, the output has shape (G,).

Parameters:

  • sigma (Array) – Basis state or batch of states. The final axis must represent the flattened site layout of length \(N = G E\).

  • edge (Union[tuple, list]) – Edge token in graph notation (for example (u, v, key)) accepted by neuralqx.hilbert.AbstractHilbertInterface.edge_to_site().

Return type:

Array

Returns:

A 1D array containing the extracted charge values across gauge copies (and batches), in the stable order [state0 copy0..copyG-1 | state1 copy0..copyG-1 | ...].

Raises:

ValueError – If edge cannot be mapped to a valid site index for this Hilbert space.