neuralqx.hilbert.u1.index.mapping module

U(1) state indexing: states_to_numbers and numbers_to_states.

Concrete implementation for AbstractHilbertSpace (U(1) spaces). This module is the canonical implementation location; the plum dispatch overloads are registered in neuralqx.hilbert.u1.index (__init__.py).

states_to_numbers(space, states, *, backend='auto', return_dtype='auto', validate=False, netket_order=None)

Convert basis states to sequential numbers, matching NetKet’s convention.

Works even when NetKet cannot index the space, by using a purely arithmetic rank/unrank on:

  • the full state (unconstrained direct-product spaces), or

  • the reduced “free-variable” parameterization (gauge-fixed constrained spaces).

Parameters:

  • space (AbstractHilbertSpace) – A core Hilbert space (AbstractHilbertSpace) or compatible object.

  • states (Any) – Array-like of shape (N,) or (…, N) containing local basis values.

  • backend (Literal['auto', 'netket', 'python', 'jax']) – “auto” | “netket” | “python”. - “netket”: call space.hilbert.states_to_numbers directly. - “python”: always use arithmetic ranking (works when not indexable). - “auto”: use “netket” when it works, else fallback to “python”.

  • return_dtype (Union[str, dtype, None]) – “auto” | “int64” | “object” (python big-int). “auto” returns int64 when safe, else object.

  • validate (bool) – If True, perform extra checks (may be slow): - unconstrained: validates values are in local basis. - gauge-fixed: also validates gauge invariance (space.check_states if present).

  • netket_order (Optional[Literal['C', 'F']]) – Optional override for site-order (“C” or “F”). If None, inferred from NetKet using a tiny N=2 reference Hilbert.

Return type:

Any

Returns:

numbers with shape (…) matching the batch shape of states (without trailing N).

numbers_to_states(space, numbers, *, backend='auto', validate=False, netket_order=None)

Convert sequential numbers to basis states, matching NetKet’s convention.

Works even when NetKet cannot index the space, by using arithmetic unranking.

Parameters:

  • space (AbstractHilbertSpace) – A core Hilbert space (AbstractHilbertSpace) or compatible object.

  • numbers (Any) – Scalar or array-like of integers.

  • backend (Literal['auto', 'netket', 'python', 'jax']) – “auto” | “netket” | “python” (see states_to_numbers).

  • validate (bool) – If True, check that numbers are in range for the chosen mapping.

  • netket_order (Optional[Literal['C', 'F']]) – Optional override for site-order (“C” or “F”). If None, inferred.

Return type:

Array

Returns:

JAX array of states with shape (…, N) and dtype=space.dtype.