Indexing API

AbstractIndexing

Abstract supertype for strategies that linearise a LatticeCoord into a 1-based site index. Concrete subtypes determine the ordering of sites along axes and the placement of sublattices within each cell.

The indexing method is deliberately decoupled from the coordinate system: a lattice may switch its AbstractIndexing without changing how it describes positions. See dev/note/04_architecture/03_boundary_and_coordinates/README.md for the design rationale.

Required interface (per concrete indexing / dimension)

• site_index(indexing, dims::NTuple{D, Int}, nsub::Int, coord::LatticeCoord{D})::Int
• lattice_coord(indexing, dims::NTuple{D, Int}, nsub::Int, i::Int)::LatticeCoord{D}

These two methods must round-trip: site_index ∘ lattice_coord is the identity on 1:prod(dims) * nsub.

Sublattice convention

The sublattice is the innermost (fastest) index: sites within a single cell are contiguous. For nsub == 1 this reduces to the usual single-sublattice formulas and can be read at a glance.

Row-major (C-style): x is the fastest axis within a row.

Column-major (Fortran-style): y is the fastest axis.

Snake

Boustrophedon (snake) indexing: row-major layout with alternating row direction. Useful when physical adjacency between neighbouring indices matters (e.g. for certain serialisation layouts).

site_index(indexing, dims, nsub, coord) → Int

Linearise coord into a 1-based site index. See AbstractIndexing for the required contract.

lattice_coord(indexing, dims, nsub, i) → LatticeCoord

Inverse of site_index.