neuralqx.hilbert.u1.operations.flip module

Plum dispatch overload for flip_state on U(1) constrained Hilbert spaces.

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

Generic flip proposal for unconstrained Hilbert spaces.

scope is accepted for API compatibility but ignored.

flip_state(space: neuralqx.hilbert.u1.unconstrained_core.UnconstrainedHilbertU1Core, sigma: jax.jaxlib._jax.Array, key: jax.jaxlib._jax.Array, *, number_of_edges: int = 1, adjacency: bool = False, scope: str = 'single') → jax.jaxlib._jax.Array

Flip proposal for unconstrained U(1) Hilbert spaces.

scope is accepted for API compatibility but ignored.

flip_state(space: neuralqx.hilbert.u1.constrained_core.ConstrainedHilbertU1Core, sigma: jax.jaxlib._jax.Array, key: jax.jaxlib._jax.Array, *, number_of_edges: int = 1, adjacency: bool = False, scope: str = 'single') → jax.jaxlib._jax.Array

Gauge-invariant flip move for neuralqx.hilbert.u1.constrained_core.ConstrainedHilbertU1Core.

This overload plugs into the global flip_state multimethod (via Plum dispatch). It performs a proposal move inside the gauge-invariant subspace by:

  1. Reshaping the input state(s) into v = space.view(sigma) with shape (B, G, E).

  2. Modifying only free edges (independent degrees of freedom) according to scope.

  3. Flattening back to (B, G*E) and calling space._reimpose_gauge_fixing to deterministically recompute all slave edges in topological order, ensuring gauge invariance after the flip.

Two scopes are supported:

  • scope="single": Flips number_of_edges many free-edge sites chosen from the union of all gauge copies.

  • scope="all_copies": Flips one free edge per gauge copy (so number_of_edges must be 1).

Parameters:

  • space (AbstractHilbertSpace) – The constrained U(1) Hilbert core.

  • sigma (Array) – State or batch of states to be modified. Shape (N,) or (B,N).

  • key (Array) – JAX PRNGKey. One independent subkey is used per batch element.

  • number_of_edges (int) – Number of free-edge sites to modify.

  • adjacency (bool) – If True, apply a ± step move modulo the allowed range; otherwise assign a new random allowed value.

  • scope (str) – Either "single" or "all_copies".

Return type:

Array

Returns:

Gauge-invariant state(s) after the flip, with the same batching as the input.

Raises:

ValueError – If scope="all_copies" and number_of_edges != 1.