neuralqx.hilbert.constraints.u1_constraint module

NetKet discrete constraint for U(1) gauge-fixing checks.

This module provides U1Constraint, a netket.hilbert.constraint.DiscreteHilbertConstraint implementation used by constrained (gauge-fixed) U(1) Hilbert-space cores.

NetKet requires constrained discrete Hilbert spaces to supply a constraint object that can be called on batches of states. This constraint:

  • stores a gauge-fixing specification that has been preprocessed into a JAX-friendly format,

  • evaluates gauge-fixing satisfaction for each state in a batch using a JIT-compatible routine,

  • implements stable hashing/equality so NetKet can cache/compare constraint instances.

The actual per-state gauge-fixing check is delegated to check_one_state_jax() from ..utils; hashing uses make_hashable() to transform nested Python/JAX structures into a comparable, hashable representation.

class U1Constraint(gauge_fixing, cutoff, q_min, q_max, q_step)

Bases: DiscreteHilbertConstraint

Discrete Hilbert-space constraint enforcing a U(1) gauge fixing.

This class implements NetKet’s netket.hilbert.constraint.DiscreteHilbertConstraint API for the constrained U(1) Hilbert-space backend. It is constructed with:

  • gauge_fixing: a gauge-fixing specification already preprocessed into the internal JAX-friendly representation expected by check_one_state_jax(),

  • q_min, q_max, q_step: range metadata used to perform modular arithmetic consistent with the Hilbert space’s allowed local basis values,

  • cutoff: stored primarily for identity/hashing and for traceability/debugging.

Batch semantics

NetKet calls the constraint with an array x of shape (B, N) (batch size B, Hilbert size N). The constraint must return a boolean array of shape (B,) indicating whether each state satisfies the gauge fixing.

JAX / JIT friendliness

The implementation must be compatible with JAX transformations and JIT compilation. The per-state check is performed by check_one_state_jax() and vectorized over the batch using jax.vmap().

PyTree notes

NetKet expects constraint objects to be PyTrees. All stored fields are marked with struct.field(pytree_node=False) so they are treated as static (non-PyTree) metadata.

Parameters:

  • gauge_fixing (Union[Array, list]) – Gauge-fixing specification in the internal JAX-friendly format consumed by check_one_state_jax().

  • cutoff (Union[float, int]) – Cutoff associated with the Hilbert space using this constraint.

  • q_min (Union[float, int]) – Minimum allowed local quantum number/value.

  • q_max (Union[float, int]) – Maximum allowed local quantum number/value.

  • q_step (Union[float, int]) – Step between consecutive allowed local quantum numbers/values.

Returns:

None.

Raises:

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