Translation-cell / orbit API

CellSite{D}(cell::SVector{D, Int}, basis::Int)

A single site of a translationally invariant lattice, addressed by its unit-cell coordinate cell ∈ ℤ^D and its basis index basis within the cell. This is the site identity used by the lazy accessors (neighbors_at, cell_position) — an infinite lattice has no linear 1:num_sites index, so sites are named by coordinate instead.

CellBond{D}(src::Int, dst::Int, offset::SVector{D, Int}, type::Symbol)

A bond of the unit-cell motif. It connects basis site src in the home cell to basis site dst in the cell displaced by offset (target cell = home cell + offset). type is a dispatch tag (e.g. :nearest).

By convention, each undirected bond of the lattice should appear exactly once in the motif returned by cell_bonds — this is the implementer's responsibility and is not validated. Listing a bond twice (e.g. both (1, 1, (1, 0)) and (1, 1, (-1, 0))) would double-count neighbours. The lazy accessor incident_cell_bonds re-anchors motif bonds to a requested site, orienting them outward from that site.

translation_vectors(lat::AbstractLattice{D, T}) → SMatrix{D, D, T}

The Bravais translation vectors of lat, as the columns of a D×D matrix. A unit-cell coordinate cell ∈ ℤ^D maps to the real-space cell origin translation_vectors(lat) * cell.

Concrete translationally invariant lattices must implement this. It has no universal default because the geometry is lattice-specific.

num_basis_sites(lat::AbstractLattice) → Int

Number of sites in one unit cell (the size of the site motif). Defaults to num_sublattices, which is 1 unless the lattice is sublattice-aware.

basis_position(lat::AbstractLattice{D, T}, b::Int) → SVector{D, T}

Real-space offset of basis site b relative to its cell origin. The default places a single basis site at the origin; multi-basis lattices (honeycomb, kagome, ...) must override.

cell_bonds(lat::AbstractLattice) → iterator of CellBond{D}

The bond motif: a finite iterator of CellBond, which by convention lists each undirected bond of the lattice exactly once (see CellBond for the double-counting caveat). This is the bond analogue of the site basis and the key object for placing bond tensors in the thermodynamic limit.

Concrete translationally invariant lattices must implement this.

site_orbits(lat::AbstractLattice) → iterator

Representatives of the site orbits under the translation group — i.e. the basis sites 1:num_basis_sites(lat). A TN builder places one site tensor per element of this iterator regardless of the lattice's size or boundary condition.

bond_orbits(lat::AbstractLattice) → iterator of CellBond{D}

Representatives of the bond orbits under the translation group. Defaults to cell_bonds. A TN builder places one bond tensor per element of this iterator.

plaquette_orbits(lat::AbstractLattice) → iterator of PlaquetteRule

Representatives of the plaquette (face) orbits under the translation group — the unit cell's PlaquetteRules. Defaults to () (lattices with no plaquette notion). The bond / site analogues are bond_orbits / site_orbits.

element_orbits(lat::AbstractLattice, e::AbstractLatticeElement)

Representatives of the orbits of centring e under the translation group: site_orbits for VertexCenter, bond_orbits for BondCenter, and plaquette_orbits for PlaquetteCenter. A finite fundamental domain — defined for infinite lattices, where the enumeration elements is not.

cell_position(lat::AbstractLattice{D, T}, cell, b::Int=1) → SVector{D, T}

Real-space position of basis site b in unit cell cell (an NTuple{D,Int}, SVector{D,Int}, or CellSite), computed as translation_vectors(lat) * cell + basis_position(lat, b). Works for any cell coordinate — including cells far outside any finite sample — without materialising the lattice.

incident_cell_bonds(lat::AbstractLattice, s::CellSite) → Vector{CellBond}

The bonds incident to site s, each re-anchored so that src is s.basis and offset points from s.cell toward the neighbour's cell. Every motif bond contributes in both orientations (once where s plays the motif src, once where it plays the motif dst), so a site sees its full coordination shell. Computed lazily from cell_bonds; no global bond list is built.

neighbors_at(lat::AbstractLattice, s::CellSite) → Vector{CellSite}

The neighbouring sites of s, computed on demand from the bond motif. This is the infinite-lattice analogue of neighbors: it works for any cell coordinate and never requires the lattice to be finite or materialised.

element_orbit_position(lat, e::AbstractLatticeElement, rep) → SVector{D,T}

Real-space position of an orbit representative rep of centring e, evaluated on the home unit cell via cell_position:

• VertexCenter, rep::Int (basis index) → the basis-site position;
• BondCenter, rep::CellBond → the midpoint of the bond's two endpoints;
• PlaquetteCenter, rep::PlaquetteRule → the centroid of its corner sites.

Consistent with bond_center / plaquette_center, but evaluated on the fundamental domain: it needs no boundary wrapping (the motif carries unwrapped cell offsets) and works for infinite lattices.