neuralqx.hilbert.u1.constrained_core module¶

Gauge-fixed (constrained) U(1) Hilbert-space core and gauge-fixing utilities.

This module implements a gauge-invariant (but gauge-fixed) Hilbert-space backend for U(1) edge degrees of freedom on a graph. The central class is ConstrainedHilbertU1Core, which:

interprets a user-provided gauge-fixing array (or auto-generates one from the graph),
identifies free (independent) and slave (dependent) edge variables,
provides a deterministic projector ConstrainedHilbertU1Core.reimpose_gauge_fixing() that overwrites slave values to satisfy all gauge-fixing relations,
constructs a NetKet netket.hilbert.HomogeneousHilbert with a U1Constraint enforcing the gauge fixing across all gauge copies,
exposes JAX-friendly move proposals via typed Move objects (free-edge flips and plaquette flips), with dispatch implemented using functools.singledispatchmethod().

The helper functions in this module focus on parsing and normalising edge tokens, mapping them to base edge indices, converting a gauge-fixing array into internal constraint objects, and producing a topological ordering of dependencies so slave edges can be recomputed in a valid order.

class GaugeFixingTopo(free, slave_topo, slave_fixers)¶

Bases: object

Topological gauge-fixing description on base edge indices 0...E-1.

This object stores the structure of a gauge fixing after parsing and dependency analysis:

free: indices of free (independent) edges; these parameterise the constrained space.
slave_topo: slave edges ordered so that each slave’s dependencies have been handled earlier in the sequence.
slave_fixers: RHS dependency lists aligned with slave_topo; the i-th entry contains the fixers needed to compute slave_topo[i].

This ordering is crucial for deterministic reconstruction: when free edges change, slave edges must be recomputed in an order that respects the dependency DAG.

Parameters:

free (Tuple[int, ...]) – Sorted tuple of free base-edge indices.
slave_topo (Tuple[int, ...]) – Tuple of slave indices in a valid topological order.
slave_fixers (Tuple[Tuple[Tuple[int, int], ...], ...]) – Tuple of RHS fixers aligned with slave_topo; each element is a tuple of (idx, sign) pairs.

Returns:

None.

Raises:

None – This dataclass does not intentionally raise exceptions during normal construction.

property n_free: int¶

Number of free (independent) base edges.

Returns:: The length of free.
Raises:: None – This property does not intentionally raise exceptions.

class ConstrainedHilbertU1Core(graph, cutoff, *, step=1, gauge_dimensions=1, constraint=None, auto_constraint=False, positive_qn=False, qn_start=None)¶

Bases: AbstractHilbertSpace

Gauge-invariant (gauge-fixed) \(U(1)\) Hilbert-space core.

This core implements a constrained Hilbert space of \(U(1)\) edge degrees of freedom by enforcing a user-specified (or auto-generated) gauge fixing. In practice, the gauge fixing is a collection of deterministic relations that identify a subset of edges as:

Free edges

Independent degrees of freedom that parameterise the constrained space. Free edges are the only variables that are directly updated by move proposals in this core.

Slave edges

Dependent degrees of freedom that are recomputed deterministically from free edges (and possibly other slaves) via the gauge-fixing relations. Slave edges are never sampled independently.

Configuration layout

The full state sigma is stored as a flat vector of length N = G * E where:

E = tiny_size is the number of base edge sites per gauge copy,
G = gauge_dimensions is the number of gauge copies.

Internally, the core frequently reshapes to (B, G, E) for batch operations.

Gauge-fixing pipeline

During construction, the core:

Validates that cutoff and step are integer-valued for this constrained implementation.
Resolves the gauge-fixing specification: - if auto_constraint=True, it generates a gauge fixing from the graph, - otherwise it parses the provided constraint array.
Converts the gauge fixing to internal _Constraint objects on base indices.
Computes a topological ordering of dependencies via _topological_ordering() to obtain free and a valid slave update order.
Lifts the base-copy constraints across all gauge copies and constructs a NetKet netket.hilbert.HomogeneousHilbert with a U1Constraint enforcing those relations.
Precomputes plaquette (minimal-loop) data in a JAX-safe padded form to support JIT-compiled plaquette moves.

Deterministic projection

The method reimpose_gauge_fixing() overwrites slave edges (in topological order) to satisfy all constraints. This allows the core to:

generate gauge-consistent random states by sampling arbitrary values and then projecting,
apply updates to free edges and then re-project to restore the constraints.

Move proposals

Proposals are expressed via typed Move objects and applied through propose(). Supported move families include:

Free-edge flips (single-gauge selection space or per-gauge-copy updates),
Plaquette flips (single-gauge or all-gauge), implemented as ±step updates around minimal loops.

Dimension reporting

If the underlying NetKet Hilbert is indexable, the exact dimension is taken from hilbert.n_states. Otherwise, an estimate based on the number of free edges is used, and a scientific-notation string is cached for readable printing.

Parameters:

graph (AbstractGraph) – Graph defining edge degrees of freedom and index mappings.
cutoff (int) – Integer cutoff controlling the local basis range for U(1) labels.
step (Union[int, float]) – Integer step size between allowed basis labels.
gauge_dimensions (int) – Number of gauge copies in the flattened layout.
constraint (Optional[List[List[List[Union[int, str]]]]]) – User gauge-fixing array, or None when using auto_constraint=True.
auto_constraint (Optional[bool]) – If True, auto-generate gauge fixing from the graph.
positive_qn (bool) – If True, restrict local labels to a non-negative (or shifted) range.
qn_start (Optional[int]) – Optional starting label when positive_qn=True.

Returns:

None.

Raises:

InvalidCutoffError – If cutoff or step is provided as a float in this constrained implementation.
AutoConstraintGaugeFixingConflictError – If both auto_constraint=True and an explicit constraint array are provided.
IncorrectGaugeFixingArrayError – If the gauge-fixing array is malformed or references unmappable edges.
CyclicGaugeFixingError – If the gauge-fixing dependency graph contains a cycle.

property hilbert: AbstractHilbert¶

Return the underlying NetKet Hilbert space.

The returned object is a flat netket.hilbert.HomogeneousHilbert of size N = tiny_size * gauge_dimensions equipped with a U1Constraint that enforces the lifted gauge-fixing relations.

Returns:: NetKet Hilbert object backing this constrained core.
Raises:: None – This property does not intentionally raise exceptions.

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

property dimensions_pretty: str¶

Return a human-friendly scientific-notation string for the Hilbert-space dimension.

This is intended for logging and representations, since the exact dimension can be extremely large.

Returns:: Dimension formatted in scientific notation.
Raises:: None – This property does not intentionally raise exceptions.

property gauge_fixing: GaugeFixingTopo¶

Return the parsed gauge-fixing topology.

The topology identifies free edges and provides a topological order for updating slave edges, along with the RHS fixer lists required to recompute each slave.

Returns:: GaugeFixingTopo describing free/slave structure and dependency order.
Raises:: None – This property does not intentionally raise exceptions.

property constraints_base: Tuple[_Constraint, ...]¶

Return gauge-fixing constraints in base-edge indexing.

Each returned constraint is a _Constraint with:

lhs: base index of the slave edge,
rhs: tuple of (base_index, sign) dependency pairs.

Returns:: Tuple of _Constraint objects in base-index space.
Raises:: None – This property does not intentionally raise exceptions.

reimpose_gauge_fixing(sigma)¶

Deterministically reimpose gauge fixing by recomputing slave edges.

This method projects an arbitrary state (or batch of states) onto the gauge-fixed subspace by overwriting only slave edges. Free edges are left unchanged.

Algorithm:

Reshape the input into (B, G, E).
Iterate over slave edges in the stored topological order.
For each slave edge, compute a signed modular sum of its fixer edges, and set the slave value to that result across all gauge copies.
Flatten back to (B, N) and restore the input shape convention.

Parameters:: sigma (Array) – State of shape (N,) or batch of shape (B, N).
Return type:: Array
Returns:: Gauge-consistent state(s) with the same shape as the input.
Raises:: None – This method does not intentionally raise exceptions.

check_states(sigma)¶

Check whether state(s) satisfy all base gauge-fixing constraints across all gauge copies.

For each base constraint and each gauge copy, this method verifies that the stored value on the LHS matches the modular signed sum of the RHS fixers.

This is primarily intended for correctness/debugging. Constraint enforcement during sampling is handled by NetKet via the attached U1Constraint, while constructive enforcement is provided by reimpose_gauge_fixing().

Parameters:: sigma (Array) – State of shape (N,) or batch of shape (B, N).
Return type:: Array
Returns:: Boolean (for a single input state) or boolean array of shape (B,) indicating whether each state satisfies all constraints.
Raises:: None – This method does not intentionally raise exceptions.

is_gauge_invariant(sigma)¶

Alias for check_states().

This name is provided for API clarity: in this core, “gauge invariant” means “satisfies the stored gauge fixing relations”.

Parameters:: sigma (Array) – State of shape (N,) or batch of shape (B, N).
Return type:: Array
Returns:: Boolean (single state) or boolean array of shape (B,) indicating gauge invariance.
Raises:: None – This method does not intentionally raise exceptions.

random_state(key, size=1, dtype=None)¶

Generate random gauge-consistent states.

Strategy:

Sample values for all sites from the allowed local basis set.
Apply reimpose_gauge_fixing() to overwrite slave edges deterministically.

The resulting states satisfy the gauge fixing exactly by construction.

Parameters:

key (Array) – JAX PRNG key.
size (int) – Number of states to generate (batch size).
dtype – Optional dtype override for the sampled states. If None, the local basis dtype is used.

Return type:

Array

Returns:

Batch of gauge-consistent states of shape (size, N).

Raises:

None – This method does not intentionally raise exceptions.

propose(sigma, key, move)¶

Propose new state(s) by applying a typed move.

This is the stable entry point for move proposals. Dispatch is performed on the concrete type of the provided Move instance via functools.singledispatchmethod().

Parameters:

sigma (Array) – State of shape (N,) or batch of shape (B, N).
key (Array) – JAX PRNG key.
move (Move) – Move object describing the proposal.

Return type:

Array

Returns:

Proposed state(s) with the same shape as the input.

Raises:

NotImplementedError – If the move type is not supported by this core.
InvalidFreeEdgeSelectionError – If a free-edge flip requests more edges than available.
NotImplementedError – If a plaquette move is requested but the graph provides no plaquettes.

plaquette_flip(sigma, key)¶

Legacy convenience wrapper for plaquette moves.

This method exists for backward compatibility with older APIs that exposed a direct plaquette_flip(sigma, key) entry point. Internally it routes to propose() using a typed plaquette move.

Parameters:

sigma (Array) – State of shape (N,) or batch of shape (B, N).
key (Array) – JAX PRNG key.

Return type:

Array

Returns:

Proposed gauge-consistent state(s) after a plaquette update.

Raises:

NotImplementedError – If no plaquettes are available for the current graph.

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

Backwards-compatible flip API using string-based scope.

This wrapper translates older scope strings into typed move objects and then delegates to propose().

Supported mappings:

Single-gauge selection space (union of all gauge copies): scope in {"single", "sgd", "one", "union"} → FreeEdgeFlipSingleGauge.
Per-gauge-copy updates: scope in {"all", "agd", "all_gd", "per_gauge", "each"} → FreeEdgeFlipAllGauge.

Unrecognised scope strings default to the single-gauge behaviour.

Parameters:

sigma (Array) – State of shape (N,) or batch of shape (B, N).
key (Array) – JAX PRNG key.
number_of_edges (int) – Number of free edges to flip per proposal (interpreted by the chosen move).
adjacency (bool) – If True, use ±step modular updates; otherwise assign random allowed values.
scope (str) – Scope selector determining single-vs-all gauge-copy behaviour.

Return type:

Array

Returns:

Gauge-consistent proposed state(s) with the same shape as the input.

Raises:

InvalidFreeEdgeSelectionError – If the requested number of edges exceeds available free edges for the selected scope.

flip_state_all_gd(sigma, key, number_of_edges=1, *, adjacency=False, scope='all')¶

Backwards-compatible convenience wrapper for flipping in all gauge copies.

This wrapper always constructs a FreeEdgeFlipAllGauge move (independent flips per gauge copy) and delegates to propose(). The scope argument is accepted for compatibility but does not change behaviour.

Parameters:

sigma (Array) – State of shape (N,) or batch of shape (B, N).
key (Array) – JAX PRNG key.
number_of_edges (int) – Number of free edges to flip inside each gauge copy.
adjacency (bool) – If True, use ±step modular updates; otherwise assign random allowed values.
scope (str) – Accepted for API compatibility; ignored.

Return type:

Array

Returns:

Gauge-consistent proposed state(s) with the same shape as the input.

Raises:

InvalidFreeEdgeSelectionError – If the requested number of edges exceeds available free edges in a single gauge copy.