Momentum space API

AbstractMomentumLattice{D, T} <: AbstractLattice{D, T}

Abstract supertype for k-space lattices. A momentum lattice is itself an AbstractLattice — its "sites" are k-points, its "positions" are k-vectors in the reciprocal basis — so 02's lattice interface (num_sites, position, traits, test suite) can be re-used for k-space work. See dev/note/04_architecture/05_momentum_space.

Required interface for concrete subtypes

• num_k_points(ml)::Int
• k_point(ml, i::Int)::SVector{D, T}
• reciprocal_basis(ml)::SMatrix{D, D, T}

The graph-neighbour side of AbstractLattice (neighbors, bonds) is deliberately vacuous for momentum lattices: k-space is not a graph in the same sense. Concrete momentum lattices return an empty neighbour list; MC code should never walk them as a graph.

PeriodicMomentumLattice{D, T}

Concrete momentum lattice for a Bravais periodic lattice. Stores the reciprocal basis, the mesh dimensions, the Γ-offset, and an explicit list of k-points (eager construction).

Construct via monkhorst_pack or gamma_centered rather than calling the struct directly.

num_k_points(ml::AbstractMomentumLattice) → Int

Number of k-points stored in the lattice.

k_point(ml::AbstractMomentumLattice, i::Int) → SVector{D, T}

The i-th k-vector in real (Cartesian) units — i.e. already multiplied through the reciprocal basis.

reciprocal_basis(ml::AbstractMomentumLattice) → SMatrix{D, D, T}

Reciprocal-space basis matrix. Columns are the primitive reciprocal lattice vectors.

monkhorst_pack(basis::SMatrix{D, D, T}, mesh::NTuple{D, Int})
    → PeriodicMomentumLattice{D, T}

Construct a Monkhorst–Pack half-shifted mesh over the Brillouin zone spanned by basis. For each axis the fractional k-coordinates are

frac_i ∈ { (n + 0.5) / N - 0.5 | n = 0, …, N - 1 }

so the mesh is centred at Γ and avoids the BZ edges.

gamma_centered(basis::SMatrix{D, D, T}, mesh::NTuple{D, Int})
    → PeriodicMomentumLattice{D, T}

Construct a Γ-centred regular mesh. Fractional k-coordinates are n / N with n = 0, …, N - 1, so the mesh includes Γ and walks to but not through the BZ edge.

reciprocal_lattice(lat::AbstractLattice) → PeriodicMomentumLattice

Construct the reciprocal lattice for a Bravais-like lat.

Trait contract

This method is a required override for any concrete lattice whose reciprocal_support(lat) returns HasReciprocal. The fallback deliberately throws a MethodError so missing implementations surface immediately at the trait dispatch site (see momentum_lattice, which routes HasReciprocal lattices through reciprocal_lattice).

Lattices with reciprocal_support(lat) == NoReciprocal() MUST NOT override this method — they have no Bravais reciprocal structure and momentum_lattice will refuse to call them. Lattices with HasFourierModule() should implement fourier_module instead.

The returned object is expected to satisfy the AbstractMomentumLattice interface (num_k_points, k_point, reciprocal_basis); the canonical concrete return type is PeriodicMomentumLattice.

fourier_module(lat::AbstractLattice) → AbstractMomentumLattice

Quasicrystal-side entry point: construct the discrete Fourier module (Bragg peak set) for a cut-and-project lattice.

Trait contract

This method is a required override for any concrete lattice whose reciprocal_support(lat) returns HasFourierModule. Concrete quasicrystal lattices implement it in their own package (typically QuasiCrystal.jl); the fallback throws a MethodError so the trait/method mismatch is visible at the call site through momentum_lattice.

Lattices with HasReciprocal should implement reciprocal_lattice instead, and lattices with NoReciprocal should not override either.

The returned object is expected to be an AbstractMomentumLattice — typically a BraggPeakSet — so observers like structure_factor treat periodic and quasiperiodic lattices uniformly.

momentum_lattice(lat::AbstractLattice) → AbstractMomentumLattice

Unified trait-dispatched entry point. Returns the reciprocal lattice for Bravais-like structures, the Fourier module for quasicrystals, and throws for lattices without any k-space representation.

structure_factor(lat, state, k::SVector) → Float64

Scalar structure factor at a single k-point:

S(k) = (1/N) |⟨ Σ_i s_i exp(-i k · r_i) ⟩|²

computed on a single snapshot (no thermal averaging). The default implementation is naive O(N) per k-point; FFT- and NUFFT-based specialisations on regular meshes are provided in the optional LatticeCoreFFTWExt / LatticeCoreNFFTExt extensions and dispatch on reciprocal_support(lat).

structure_factor(lat, state, ml::AbstractMomentumLattice) → Vector{Float64}

Evaluate the structure factor at every k-point of ml.

Dispatch is driven by reciprocal_support(lat):

• HasReciprocal() (Bravais periodic lattices): uses an FFT-based fast path when LatticeCoreFFTWExt is loaded (using FFTW), otherwise falls back to the naive O(N · M) loop.
• HasFourierModule() (cut-and-project quasicrystals): uses a NUFFT fast path when LatticeCoreNFFTExt is loaded (using NFFT), otherwise falls back to naive.
• NoReciprocal() and any unhandled case: naive.

Extensions hook into the _structure_factor_fast indirection below; the default fallback simply runs the naive loop.

AcceptanceWindow

Abstract supertype for acceptance windows in the internal (perp) space of a cut-and-project quasicrystal. Concrete windows (PolygonalWindow, IntervalWindow, etc.) live in QuasiCrystal.jl.

HyperReciprocalLattice{DPhys, DHyper, T}

Infinite-abstract representation of a quasicrystal's reciprocal structure: the higher-dimensional reciprocal basis, the parallel and perpendicular projections, and the acceptance window used to decide peak intensities.

Concrete construction (building the projections, sampling peaks) lives in QuasiCrystal.jl.

BraggPeakSet{DPhys, T}

Finite materialisation of a HyperReciprocalLattice up to a cutoff radius: a list of physical-space k-positions with intensities and a back-pointer to the higher-dimensional indices that generated them.

Being a subtype of AbstractMomentumLattice, a BraggPeakSet can be passed straight to structure_factor or to a StructureFactorObserver so the same code paths work for periodic and quasiperiodic lattices.