neuralqx.hilbert package

This module implements the Hilbert space infrastructure of neuraLQX.

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.

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.

Subpackages

Submodules