Coordinate systems API

AbstractCoordinate{D}

Abstract supertype for lattice coordinate representations. Concrete subtypes describe the same lattice point in different spaces:

• RealSpace — Cartesian coordinates
• LatticeCoord — unit cell index + geometric sublattice
• HigherDimCoord — higher-dimensional projection (for cut-and-project quasicrystals)

D is the physical dimension (the dimension of the real space the lattice lives in), which is the same for every concrete subtype that describes a given lattice point.

Conversions between coordinate systems are performed by to_real, to_lattice, and to_hyper. These functions dispatch on the concrete lattice type because the conversion depends on the lattice basis and any higher-dimensional projection the lattice uses.

RealSpace{D, T}(x::SVector{D, T})
RealSpace(x::NTuple{D, T})

Real-space Cartesian coordinate in D dimensions with element type T.

LatticeCoord{D}(cell::NTuple{D, Int}, sublattice::Int = 1)

Lattice coordinate: per-axis unit cell index plus the (1-based) geometric sublattice id within the cell.

The sublattice field refers strictly to the geometric sublattice (the honeycomb A/B positions, the Kagome A/B/C, ...), not to the physical AbstractSiteType living on the site. Site types live on a separate axis and are designed in the site-type chapter of the architecture notes.

HigherDimCoord{DPhys, DHyper, T}(hyper::SVector{DHyper, T})

Higher-dimensional coordinate used by cut-and-project quasicrystals. DPhys is the physical dimension (the target of the projection) and DHyper is the host dimension (DHyper > DPhys). The lattice's projection matrix maps hyper back into DPhys-dimensional real space.

to_real(lat::AbstractLattice, coord::AbstractCoordinate) → RealSpace

Convert coord into a real-space Cartesian coordinate on lat. Concrete lattices should implement at least to_real(lat, ::LatticeCoord) (and, for quasicrystals, to_real(lat, ::HigherDimCoord)).

to_lattice(lat::AbstractLattice, coord::AbstractCoordinate) → LatticeCoord

Convert coord into a lattice coordinate on lat. Concrete lattices should implement at least to_lattice(lat, ::RealSpace).

to_hyper(lat::AbstractLattice, coord::AbstractCoordinate) → HigherDimCoord

Convert coord into a higher-dimensional hyper coordinate. Only meaningful for cut-and-project quasicrystals; other lattices may leave this unimplemented.