neuralqx.hilbert.u1 package

U(1) Hilbert-space subpackage.

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:

Subpackages

Submodules