neuralqx.hilbert.utils.index package

class HilbertStateEnumerator

Bases: ABC, Generic[CoreT]

Abstract base for Hilbert index/enumerator objects.

A state enumerator is an index object that assigns a canonical integer label to every basis state and can recover the state from its label. This forms the basis for NetKet-compatible indexing and for the plum-based dispatch of states_to_numbers() / numbers_to_states().

Concrete subclasses

These classes implement ranking/unranking, metadata capabilities, and explainability hooks, and are bound to core instances through core.index.

abstractmethod states_to_numbers(core, states, *, validate=False, **kwargs)

Convert basis states to sequential integer labels.

Parameters:

  • core (TypeVar(CoreT)) – Hilbert-space core owning this enumerator.

  • states (Any) – State array of shape (N,) or (B, N).

  • validate (bool) – If True, perform extra validity checks.

  • kwargs (Any) – Additional keyword arguments forwarded to the concrete implementation (e.g. backend, return_dtype for U(1) spaces).

Return type:

Any

Returns:

Integer label(s) with shape matching the batch dimensions of states.

abstractmethod numbers_to_states(core, numbers, *, validate=False, **kwargs)

Convert sequential integer labels back to basis states.

Parameters:

  • core (TypeVar(CoreT)) – Hilbert-space core owning this enumerator.

  • numbers (Any) – Integer scalar or array of integers.

  • validate (bool) – If True, check that numbers are within range.

  • kwargs (Any) – Additional keyword arguments forwarded to the concrete implementation.

Return type:

Any

Returns:

State array of shape (N,) or (B, N).

states_to_numbers(space, states, **kwargs)

Public wrapper: dispatch via space.index.

This overload intentionally avoids importing any concrete/abstract core classes to keep the dispatch layer independent of core module import order.

states_to_numbers(index: neuralqx.hilbert.utils.index._abstract.HilbertStateEnumerator, space: object, states: Any, *args, **kwargs: Any) → Any

Abstract fallback for (index, core, states) dispatch.

states_to_numbers(index: neuralqx.hilbert.u1.index.enumerator.U1UnconstrainedStateEnumerator, space: neuralqx.hilbert.u1.unconstrained_core.UnconstrainedHilbertU1Core, states: Any, *args, **kwargs: Any) → Any

Dispatch overload: unconstrained U(1) states -> numbers.

states_to_numbers(index: neuralqx.hilbert.u1.index.enumerator.U1ConstrainedStateEnumerator, space: neuralqx.hilbert.u1.constrained_core.ConstrainedHilbertU1Core, states: Any, *args, **kwargs: Any) → Any

Dispatch overload: constrained U(1) states -> numbers.

Return type:

Any

numbers_to_states(space, numbers, **kwargs)

Public wrapper: dispatch via space.index.

This overload intentionally avoids importing any concrete/abstract core classes to keep the dispatch layer independent of core module import order.

numbers_to_states(index: neuralqx.hilbert.utils.index._abstract.HilbertStateEnumerator, space: object, numbers: Any, *args, **kwargs: Any) → Any

Abstract fallback for (index, core, numbers) dispatch.

numbers_to_states(index: neuralqx.hilbert.u1.index.enumerator.U1UnconstrainedStateEnumerator, space: neuralqx.hilbert.u1.unconstrained_core.UnconstrainedHilbertU1Core, numbers: Any, *args, **kwargs: Any) → Any

Dispatch overload: unconstrained U(1) numbers -> states.

numbers_to_states(index: neuralqx.hilbert.u1.index.enumerator.U1ConstrainedStateEnumerator, space: neuralqx.hilbert.u1.constrained_core.ConstrainedHilbertU1Core, numbers: Any, *args, **kwargs: Any) → Any

Dispatch overload: constrained U(1) numbers -> states.

Return type:

Any

Submodules