neuralqx.hilbert.abstract_hilbert_interface module

User-facing Hilbert-space interface.

This module defines AbstractHilbertInterface, a thin wrapper around a concrete core implementation (AbstractHilbertSpace).

The interface exists to provide a stable public API (validation, configuration, convenience methods) while allowing the internal core to evolve independently. Most numerical logic and all backend-specific details (NetKet Hilbert construction, constraints, move proposals, indexing) live in the core and are exposed here via delegation.

class AbstractHilbertInterface(graph, cutoff=inf, *, step=1, gauge_dimensions=1, is_gauge_invariant=False, **kwargs)

Bases: ABC, Generic[CoreT]

User-facing interface around a concrete Hilbert-space core implementation.

This interface is intentionally thin: it owns a core object (an neuralqx.hilbert._abstract_hilbert_core.AbstractHilbertSpace) and exposes a stable, user-friendly API while allowing the internal core to evolve.

The key design goal is separation of concerns:

  • The interface handles user-facing validation, configuration, and a clean attribute surface.

  • The core implements the actual physics/constraints, NetKet Hilbert construction, moves, etc.

Core construction: Subclasses must implement _build_core() and return a fully-initialised core instance. All properties and convenience methods delegate to that core.

Parameters:

  • graph (AbstractGraph) – The graph on which the Hilbert space is defined.

  • cutoff (Union[int, float]) – Cutoff used by the underlying core (semantics depend on the concrete core).

  • step (Union[int, float]) – Step size between allowed local quantum numbers (semantics depend on the core).

  • gauge_dimensions (int) – Number of gauge copies (blocks) stored in the flattened configuration.

  • is_gauge_invariant (bool) – If True, construct a gauge-invariant (constrained) Hilbert space.

  • kwargs – Forwarded to _build_core() for backend-specific options. Concrete interfaces define and validate any group-specific constructor arguments.

property hilbert: CoreT

Underlying core Hilbert-space implementation.

This object owns the NetKet Hilbert instance, constraint logic, move proposals, and all indexing utilities. The interface delegates most functionality to this core.

Returns:

The concrete core instance.

property hilbert_netket: AbstractHilbert | DiscreteHilbert

NetKet Hilbert object used for sampling and operator construction.

Returns:

A NetKet Hilbert instance.

property is_gauge_invariant: bool

Whether this interface represents a gauge-invariant (constrained) Hilbert space.

Returns:

True if the Hilbert space is constrained by gauge invariance, otherwise False.

property graph: AbstractGraph

Graph on which the Hilbert space is defined.

This is delegated to the underlying core and is guaranteed to be an AbstractGraph.

Returns:

The associated graph.

property tiny_hilbert: AbstractHilbert

A smaller/base NetKet Hilbert object used internally by some cores.

Typically this corresponds to a single “gauge copy” (one block of edge degrees of freedom) and is used to build or reason about the full Hilbert space.

Returns:

A NetKet Hilbert instance.

property tiny_size: int

Number of sites (edge degrees of freedom) in a single gauge copy.

If the configuration is stored as gauge_dimensions consecutive blocks, then

\[\text{size} = \text{gauge\_dimensions} \times \text{tiny\_size}.\]
Returns:

Number of sites in one gauge copy.

property size: int

Total number of sites in the flattened configuration.

This is the length N of a single basis state sigma (shape (N,)), including all gauge copies.

Returns:

Total configuration length.

property local_size: int

Number of local basis states per site.

Returns:

Local Hilbert dimension per site.

property dimensions: int

Total Hilbert-space dimension (or an estimate if the space is not indexable).

Returns:

The dimension (exact for finite indexable spaces, otherwise core-defined).

property gauge_dimensions: int

Number of gauge copies (blocks) stored in the flattened configuration.

Returns:

Gauge dimension as defined by the core.

property is_indexable: bool

Whether the underlying NetKet Hilbert space supports indexing.

Returns:

True if indexable, otherwise False.

property is_finite: bool

Whether the underlying NetKet Hilbert space is finite.

Returns:

True if finite, otherwise False.

random_state(key, size=1)

Generate random basis state(s) via the core implementation.

Parameters:

  • key (Array) – JAX PRNGKey.

  • size (int) – Number of states to generate (batch size).

Return type:

Array

Returns:

A single state of shape (N,) or a batch of states of shape (B, N), depending on the core and size.

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

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

This is a user-facing wrapper over the core’s move proposal logic. The precise semantics of number_of_edges, adjacency, and scope are core-dependent (and may differ between constrained and unconstrained implementations).

Parameters:

  • sigma (Array) – A state of shape (N,) or a batch of states of shape (B, N).

  • key (Array) – JAX PRNGKey.

  • number_of_edges (int) – Number of sites/edges to modify (core-dependent).

  • adjacency (bool) – If True, propose adjacent updates (for example, \(q \to q \pm \Delta\)) rather than resampling.

  • scope (str) – Optional selector used by some constrained cores (for example, "single" vs "all"). Ignored by cores that do not support it.

Return type:

Array

Returns:

A proposed state (or batch) with the same shape as sigma.

edge_to_site(edge, gauge_copy=0)

Map a graph edge token to a flattened site index.

Conceptually, this addresses an edge degree of freedom inside a chosen gauge copy.

Parameters:

  • edge (Any) – Edge identifier accepted by the graph/core (for example a keyed edge tuple).

  • gauge_copy (int) – Index of the gauge copy/block to address (0-based).

Return type:

int

Returns:

Flattened site index in [0, size).

site_to_edge(site)

Inverse mapping from a flattened site index to a structured edge representation.

Parameters:

site (int) – Flattened site index in [0, size).

Return type:

tuple[int, Any]

Returns:

A core-defined representation identifying the gauge copy and the underlying graph edge.

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

Convert basis states to sequential integers using NetKet-compatible ordering.

Depending on backend, this conversion may be delegated to NetKet, performed in pure Python, or chosen automatically by the core. For large batches, the backend choice can materially affect performance and memory use.

Parameters:

  • states (Any) – A single state (N,) or a batch (B, N).

  • backend (Literal['auto', 'netket', 'python']) – Conversion backend: "auto", "netket", or "python".

  • return_dtype (str) – Output dtype selector (core-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 integers to basis states using NetKet-compatible ordering.

Depending on backend, this conversion may be delegated to NetKet, performed in pure Python, or chosen automatically by the core.

Parameters:

  • numbers (Any) – Integer label or array of labels.

  • backend (Literal['auto', 'netket', 'python']) – Conversion backend: "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).