Lattice2D.jl

Tuple listing every topology shipped by Lattice2D.

AbstractTopology{D}

Abstract supertype for 2D lattice topologies (Square, Triangular, Honeycomb, ...). Each concrete subtype is a singleton that acts as a dispatch key for get_unit_cell, and, through TopologyTrait in LatticeCore, as the topology(lat) value of the resulting PeriodicLattice2D.

Connection(src_sub, dst_sub, dx, dy, type)

A unit-cell-level connection rule — the description of an edge between sublattices inside a single unit cell, or between a sublattice in one cell and a sublattice in a neighbouring cell.

This is distinct from LatticeCore.Bond:

• A Connection is a template on the unit cell (src_sub, dst_sub are sublattice ids, dx, dy are relative cell offsets). It is topology data, known statically from get_unit_cell.
• A LatticeCore.Bond is an instantiated edge on a concrete Lx × Ly sample, with absolute site indices and a wrapped displacement vector. It is the per-sample output of build_lattice.

Fields

• src_sub::Int — 1-based sublattice id of the source site
• dst_sub::Int — 1-based sublattice id of the destination site
• dx::Int — x-axis cell offset (0 = same unit cell)
• dy::Int — y-axis cell offset
• type::Int — bond type tag. Currently stored as an Int on the Connection side for backward compatibility; build_lattice converts this to a Symbol (:type_N) when it emits LatticeCore.Bond.

Dice <: AbstractTopology{2}

Dice (T3) lattice: bipartite triangular-based structure with a single 6-coordinated hub site and two 3-coordinated rim sites per unit cell.

Honeycomb <: AbstractTopology{2}

Honeycomb lattice: two-sublattice (A/B) bipartite triangular Bravais lattice, three nearest neighbours per site.

Kagome <: AbstractTopology{2}

Kagome lattice: three-sublattice (A/B/C) structure on a triangular Bravais lattice, four nearest neighbours per site.

Lieb <: AbstractTopology{2}

Lieb (line-centred square) lattice: three-sublattice structure on a square Bravais lattice. Used for flat-band physics.

PeriodicLattice2D{Topo, T, B, I, L}

Finite 2D periodic lattice built from a topology (get_unit_cell) and a LatticeCore.LatticeBoundary. Subtype of LatticeCore.AbstractLattice{2, T}; every LatticeCore-side method (num_sites, position, neighbors, boundary, size_trait, site_layout, reciprocal_lattice, ...) is implemented below.

Type parameters

• Topo<:AbstractTopology{2} — singleton topology marker
• T<:AbstractFloat — numeric type for positions
• B<:LatticeCore.LatticeBoundary — composite boundary condition
• I<:LatticeCore.AbstractIndexing — linearisation strategy
• L<:LatticeCore.AbstractSiteLayout — site-type layout

Fields

• Lx, Ly, N — per-axis cell counts and total site count
• positions — cached real-space positions, indexed by site id
• nearest_neighbors — adjacency lists (one Vector{Int} per site)
• bonds — list of LatticeCore.Bond{2, T} with wrapped vectors
• basis_matrix — the 2 × 2 real-space basis (columns are primitive vectors)
• sublattice_ids — geometric sublattice id (1-based) of each site
• is_bipartite_flag — cached result of a BFS 2-colouring
• site_map — Lx × Ly matrix of the base site id of each cell
• topology — topology singleton
• boundary — composite boundary
• indexing — RowMajor, ColMajor, or Snake
• layout — site-type layout

Prefer constructing via build_lattice rather than the inner constructor.

ShastrySutherland <: AbstractTopology{2}

Shastry–Sutherland lattice: square Bravais lattice with four sites per unit cell, both nearest-neighbour (square) bonds and dimer (J′) bonds.

Square <: AbstractTopology{2}

Standard square lattice: one sublattice, orthonormal primitive vectors, four nearest neighbours per site.

Triangular <: AbstractTopology{2}

Triangular lattice: one sublattice, 60° primitive vectors, six nearest neighbours per site.

UnionJack <: AbstractTopology{2}

Union Jack (centred square) lattice: square primitive cell with two sublattices — a corner site and a body-centred site — and eight-coordinated corner sites, four-coordinated body sites.

UnitCell{D, T}

Static topology description for a D-dimensional Bravais lattice with an arbitrary basis. Contains

• basis::Vector{Vector{T}} — the D primitive vectors
• sublattice_positions::Vector{Vector{T}} — one offset per geometric sublattice inside the unit cell
• connections::Vector{Connection} — the full list of intra- and inter-cell connection rules for this topology

Produced by get_unit_cell on an AbstractTopology singleton.

Lattice2D.Lattice(Topology, Lx, Ly; kwargs...)

Alias for build_lattice. Kept for readability; returns a PeriodicLattice2D.

_resolve_boundary(axis::LatticeCore.AbstractAxisBC)
_resolve_boundary(boundary::LatticeCore.LatticeBoundary)

Normalise the user-facing boundary argument of build_lattice to a LatticeBoundary{2}. A single axis BC is broadcast to both axes with a NoModifier; an explicit LatticeBoundary is returned as-is.

build_lattice(Topology, Lx, Ly;
              boundary = PeriodicAxis(),
              indexing = RowMajor(),
              layout   = UniformLayout(IsingSite())) → PeriodicLattice2D

Construct a finite 2D lattice of topology Topology on an Lx × Ly sample. The boundary argument accepts either a single LatticeCore.AbstractAxisBC (broadcast to both axes) or an explicit LatticeCore.LatticeBoundary for mixed-axis setups such as cylinders.

Examples

# 4 × 4 periodic square lattice, row-major linearisation, Ising sites
lat = build_lattice(Square, 4, 4)

# Open honeycomb 6 × 6
open_hc = build_lattice(Honeycomb, 6, 6; boundary = OpenAxis())

# Cylinder: square lattice with PBC in x, OBC in y
cyl = build_lattice(Square, 4, 4;
    boundary = LatticeBoundary((PeriodicAxis(), OpenAxis())))

# Kagome with XY sites
xy_kg = build_lattice(Kagome, 4, 4; layout = UniformLayout(XYSite()))

calc_reciprocal_vectors(basis::Vector{<:Vector}) → Vector{Vector{Float64}}

Return the reciprocal-lattice basis associated with a real-space basis expressed as a vector of vectors. Uses $B = 2\pi (A^{-\top})$ where the columns of $A$ are the primitive real-space vectors. Provided for parity with the old public API; new code should prefer LatticeCore.reciprocal_lattice(lat).

check_bipartite_bfs(N::Int, neighbors::Vector{Vector{Int}}) → Bool

BFS two-colouring of an adjacency list. Returns true iff the graph is bipartite.

get_unit_cell(::Type{T}) where {T <: AbstractTopology}

Return the UnitCell describing topology T. Concrete topology types (Square, Triangular, ...) specialise this method. The fallback throws.

basis_vectors(lat::PeriodicLattice2D) → SMatrix{2, 2, T}

Real-space primitive basis. Columns are the two primitive vectors a₁, a₂ of the underlying topology.