neuralqx.hilbert.utils.layout package

class AbstractBasisLayout

Bases: ABC, Generic[CoordT]

Abstract base class for flattening layouts.

A layout is a bijection between

  • a structured coordinate in some domain-specific coordinate space C, and

  • a flattened integer site index in {0, 1, …, N-1}.

In symbols, a subclass defines an invertible map

\[\phi: C \to \{0, \ldots, N-1\}\]

together with its inverse

\[\phi^{-1}: \{0, \ldots, N-1\} \to C.\]

This abstraction is meant to intentionally separates basis semantics from memory layout.

A large part of neuralqx logic operates on flattened arrays because they are efficient and easy to vectorize. At the same time, many algorithms reason in structured terms such as

  • gauge copy indices,

  • edge indices,

  • irrep labels,

  • magnetic quantum number labels,

  • intertwiner labels,

  • sectors or channels.

Hard-coding the flattening convention in many places makes the code brittle and makes it difficult to support new groups or basis parameterizations.

By centralizing the flattening logic in a BasisLayout, code that manipulates flattened states can remain generic while group-specific logic is expressed through structured coordinates.

Every subclass must implement the following abstract members:

  • size Returns the total number of flattened sites N.

  • site_of() Maps a structured coordinate to a flattened site index.

  • coord_of() Inverse mapping from flattened site index to structured coordinate.

Required invariants

For every valid coordinate c and every valid site s, subclasses must satisfy

  • 0 <= site_of(c) < size

  • coord_of(site_of(c)) == c

  • site_of(coord_of(s)) == s

Error semantics

Subclasses should raise:

  • IndexError when a flattened site index is out of range, and

  • IndexError when coordinate components are out of range.

Use ValueError only for invalid layout construction parameters, such as non-positive dimensions.

Convenience methods

This class provides a few helpers:

  • validate_site() for consistent flat-index validation

  • encode_coord() and decode_coord() as naming aliases

  • __len__() so len(layout) returns size

  • contains_site() to test flat-site validity

Notes on API naming

The canonical abstract methods are site_of(coord) and coord_of(site) because they are explicit and coordinate-type agnostic.

Concrete subclasses may additionally expose convenience methods such as

  • encode(gauge_copy, edge_index) -> int

  • decode(site) -> tuple[…]

when that improves ergonomics for common call sites.