neuralqx.hilbert.abstract_hilbert_core module¶

Core Hilbert-space implementation.

This module defines AbstractHilbertSpace, the implementation-level base class for Hilbert spaces in neuraLQX.

The core is responsible for:

defining the local quantum-number domain (cutoff/step and the resulting discrete set),
storing graph/layout metadata for flattened configurations with multiple gauge copies,
constructing and exposing a NetKet Hilbert instance for sampling and state representation,
providing indexing helpers between graph edges and flattened NetKet site indices,
defining abstract state-generation and move-proposal hooks that concrete cores implement.

The user-facing interface class wraps a concrete core instance and provides a stable public API.

class AbstractHilbertSpace(graph, cutoff, *, step, gauge_dimensions, positive_qn=False, qn_start=None)¶

Bases: ABC

Core Hilbert-space base class.

This class represents the implementation-level Hilbert space (as opposed to the user-facing interface). It owns:

the graph and local quantum-number domain (cutoff/step, allowed basis states),
metadata needed by move/state operations (dtype, q-range),
a NetKet Hilbert instance (self._hilbert),
the total dimension (or an estimate) of the represented space (self._dimensions).

Subclasses are responsible for constructing self._hilbert and setting self._dimensions. This base class provides:

consistent bookkeeping for local degrees of freedom,
abstract contracts for layout/mapping/state-move operations that concrete cores implement.

No public attributes are intended, access all state via properties.

Parameters:

graph (AbstractGraph) – Graph defining the degrees of freedom (edges) and mappings (edge_to_index/index_to_edge).
cutoff (Union[int, float]) – Cutoff controlling the local quantum number range (interpretation is model-specific).
step (Union[int, float]) – Step size between allowed local quantum numbers.
gauge_dimensions (int) – Number of gauge copies stored in block layout, must be >= 1.
positive_qn (bool) – If True, restrict the local quantum numbers to non-negative values starting at qn_start (or 0 if qn_start is None).
qn_start (Optional[int]) – Starting quantum number when positive_qn=True. Defaults to 0 if omitted.

Raises:

ValueError – If gauge_dimensions < 1.

property graph: AbstractGraph¶

Underlying graph defining the degrees of freedom and index mappings.

The graph supplies a bijection between user-facing edge tokens and integer indices, which are then embedded into the flattened configuration layout.

Returns:: The associated AbstractGraph.

property index: HilbertStateEnumerator[AbstractHilbertSpace]¶

State enumerator associated with this core.

Concrete cores must assign self._index to a concrete subclass of HilbertStateEnumerator.

property cutoff: int | float¶

Cutoff controlling the local quantum-number range.

The precise physical meaning is model-dependent, but the cutoff always participates in defining the discrete set of allowed local values (together with step and the positive_qn flag used during construction).

Returns:: The cutoff value.

property step: int | float¶

Step size between allowed local quantum numbers.

Returns:: The step size.

property gauge_dimensions: int¶

Number of gauge copies stored in the flattened configuration.

If each gauge copy contains \(E\) edge sites, the flattened configuration length is

\[N = E \, G,\]

where \(G =\) gauge_dimensions.

Returns:: Number of gauge copies (G), always >= 1.

property dtype: Any¶

Dtype used to represent configurations.

This is selected during construction from the types of cutoff and step (integer-like parameters lead to an integer dtype, otherwise a floating dtype).

Returns:: A JAX dtype (for example jnp.int64 or jnp.float64).

property allowed_basis_states: StaticRange¶

Allowed local basis values as a NetKet netket.utils.StaticRange.

This object compactly represents the discrete local domain (start, step, number of values) and can be used to obtain the explicit array of allowed local states.

Returns:: A netket.utils.StaticRange describing the local basis.

property q_min: float¶

Minimum allowed local quantum number.

Returns:: The minimum local value as a float.

property q_max: float¶

Maximum allowed local quantum number.

Returns:: The maximum local value as a float.

property q_step: float¶

Step size between allowed local quantum numbers (as a float).

Returns:: The local step size.

property tiny_size: int¶

Number of edge degrees of freedom in a single gauge copy.

In the neuraLQX layout, a single gauge copy typically corresponds to the set of edges in the chosen edge representation (often the dual graph’s vertices).

Returns:: Number of sites per gauge copy (E).

property size: int¶

Total number of sites in the flattened configuration.

This is the length N of a single basis state sigma in NetKet layout. With \(E =\) tiny_size and \(G =\) gauge_dimensions:

\[N = E \, G.\]

Returns:: Total configuration length (N).

property local_size: int¶

Number of local basis states per site.

Returns:: Local Hilbert dimension per site.

property dimensions: int¶

Total Hilbert-space dimension.

For indexable spaces this is exact; otherwise subclasses may provide an estimate appropriate for the represented configuration space.

Returns:: The Hilbert-space dimension (or an estimate), as an integer.

property hilbert: AbstractHilbert | DiscreteHilbert¶

NetKet Hilbert space instance representing the full space.

Subclasses are responsible for constructing this object. It is the canonical Hilbert instance used for sampling and state representation within NetKet.

Returns:: A netket.hilbert.AbstractHilbert instance.

abstract property layout: AbstractBasisLayout[Any]¶

Basis-layout descriptor for the flattened configuration.

Every concrete Hilbert core must provide a layout object implementing the AbstractBasisLayout contract. This keeps the base core agnostic to U(1), SU(2), or future coordinate conventions.

Returns:: Basis-layout object implementing flat/structured coordinate conversion.

property tiny_hilbert: AbstractHilbert¶

Single-copy NetKet Hilbert space.

This returns a homogeneous Hilbert space of length tiny_size with local states given by allowed_basis_states. It is primarily intended for internal helpers and compatibility with code paths that operate on a single gauge copy.

Returns:: A netket.hilbert.HomogeneousHilbert instance.

abstractmethod edge_to_site(edge, gauge_copy=0)¶

Map a graph edge token to a flattened site index.

Concrete cores must define how graph-edge tokens map into their flat site layout for the selected gauge copy.

Parameters:

edge (Any) – Edge token accepted by graph.edge_to_index.
gauge_copy (int) – Gauge-copy index g with 0 <= g < gauge_dimensions.

Return type:

int

Returns:

Flattened site index in [0, size).

abstractmethod site_to_edge(site)¶

Inverse map from a flattened site index to (gauge_copy, edge_token).

Concrete cores must define how a flat site index is decoded into gauge copy and graph-edge identity.

Parameters:: site (int) – Flattened site index in [0, size).
Return type:: tuple[int, Any]
Returns:: A pair (gauge_copy, edge_token) where edge_token is produced by graph.index_to_edge.

abstractmethod view(sigma)¶

Reshape a flattened configuration into an explicit gauge-block view.

Concrete cores define the structured shape associated with their layout (for example U(1): (G, E)).

Parameters:: sigma (Array) – A single configuration or batch in flattened layout.
Return type:: Array
Returns:: Reshaped structured view.

abstractmethod flatten(sigma_view)¶

Flatten a gauge-block view back to the standard NetKet layout.

This is the inverse of view().

Parameters:: sigma_view (Array) – Structured state view.
Return type:: Array
Returns:: Flattened array in NetKet site order.

abstractmethod random_state(key, size=1)¶

Generate random basis state(s).

Concrete cores must provide their own random-state generation logic.

Parameters:

key (Array) – JAX PRNGKey.
size (int) – Number of states to generate.

Return type:

Array

Returns:

A state of shape (N,) or a batch of shape (B, N).

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

Propose a new configuration by updating one or more local degrees of freedom.

Concrete cores must provide their own proposal dynamics implementation.

Parameters:

sigma (Array) – A state of shape (N,) or a batch of shape (B, N).
key (Array) – JAX PRNGKey.
number_of_edges (int) – Number of sites/edges to modify (interpretation depends on the dispatched implementation and may depend on scope).
adjacency (bool) – If True, propose adjacent updates (for example \(q \to q \pm \Delta q\)); if False, propose values by resampling within the local domain.
scope (str) – Move-scope hint interpreted by the dispatched implementation.

Return type:

Array

Returns:

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

states_to_numbers(states, *, backend='auto', return_dtype='auto', validate=False)¶

Convert basis states to sequential numbers with NetKet-compatible ordering.

Dispatch is resolved through this core’s index enumerator object.

Parameters:

states (Any) – A single state (N,) or a batch (B, N).
backend (Literal['auto', 'netket', 'python']) – Conversion backend selector: "auto", "netket", or "python".
return_dtype (str) – Output dtype selector (implementation-defined; "auto" chooses a sensible default).
validate (bool) – If True, validate that inputs are legal basis states before conversion.

Return type:

Any

Returns:

Integer label(s) corresponding to the provided basis state(s).

numbers_to_states(numbers, *, backend='auto', validate=False)¶

Convert sequential numbers to basis states with NetKet-compatible ordering.

Dispatch is resolved through this core’s index enumerator object.

Parameters:

numbers (Any) – Integer label or array of labels.
backend (Literal['auto', 'netket', 'python']) – Conversion backend selector: "auto", "netket", or "python".
validate (bool) – If True, validate that inputs are within the representable range.

Return type:

Array

Returns:

Basis state(s) corresponding to the provided label(s).