FiniteLattices.jl

 abstract type AbstractLattice

Abstract supertype of all lattices.

 abstract type EmbeddedLattice{D} <: AbstractLattice

Abstract type of those lattices can be embedded into an Euclidean space ℝ^D. Therefore each point in the lattice has a coordinate, and the distance between two points is induced by the Euclidean metric.

Interfaces should be implemented

 size(Latt::EmbeddedLattice) -> ::Int64

Return the size of the lattice, i.e. the number of sites.

 coordinate(Latt::EmbeddedLattice{D}, idx) -> ::NTuple{D, Float64}

Return the coordinate of a given site.

 equiVec(Latt::EmbeddedLattice{D}) -> ::Vector{NTuple{D,Float64}}

Return the equivalent vectors around the origin point due to the boundary condition. For example, for a square lattice on a torus, there are 9 equivalent vectors (0.0, 0.0), (0.0, ±1.0), (±1.0, 0.0), (±1.0, ±1.0).

 abstract type NonEmbeddedLattice <: AbstractLattice

Abstract type of those lattices cannot be embedded into an Euclidean space.

 abstract type SimpleLattice{D, T<:AbstractBoundaryCondition} <: EmbeddedLattice{D}

Abstract type of D-dimensional simple lattices.

Fields must be implemented

 e::NTuple{D, NTuple{D, Float64}}

Primitive vectors (e₁, e₂, ...).

 sites::Vector{NTuple{D, Int64}}

Sites of the finite lattice, each site is represented by the coefficients of primitive vectors. For example, site (a, b) has coordinate a*e₁ + b*e₂.

 BC::AbstractBoundaryCondition

Boundary condition, used when computing the distance between two sites.

 struct CompositeLattice{D, N, T} <: EmbeddedLattice{D}
      subLatts::T
      shift::NTuple{N, NTuple{D, Float64}}
      sites::Vector{NTuple{2, Int64}}
 end

Wrapper type of composite lattices.

Fields

 subLatts::NTuple{N, SimpleLattice}

List of the sublattices of the composite lattice.

 shift::NTuple{N, NTuple{D, Float64}}

Shift of each sublattice, used when computing the coordinates.

 sites::Vector{NTuple{2, Int64}}

Lazily collect the sites. The first index denotes the sublattice and the second index denotes the site in it.

Constructors

 CompositeLattice{D}(subLatts::NTuple{N, SimpleLattice},
      shift::NTuple{N, NTuple{D, Float64}} = Tuple(fill(Tuple(zeros(D)), N)))

Finally used constructor. Generating a higher dimensional lattice is supported by given a larger D manually.

 CompositeLattice(subLatts::NTuple{N, SimpleLattice{D}},
      shift::NTuple{N, NTuple{D, Float64}} = Tuple(fill(Tuple(zeros(D)), N))) 
 CompositeLattice(Latt1, Latt2, ..., shift)

Deduce D from the sublattices or shift. Each sublattice must have the same dimension in this usage.

 abstract type AbstractBoundaryCondition

 struct OpenBoundaryCondition <: AbstractBoundaryCondition

 struct PeriodicBoundaryCondition{D} <: AbstractBoundaryCondition 
      V::NTuple{D,Int64}
 end

Periodic boundary condition in D dimensions. V denotes the vector of the periodicity. For example, V = (0, W) means the site (a, b) is equivalent to (a, b+W) and thus forms a YC boundary condition.

 struct TwistBoundaryCondition{D} <: AbstractBoundaryCondition 
      V::NTuple{D,Int64}
      θ::Float64
 end

Twist boundary condition in D dimensions. V denotes the vector of the periodicity. θ ∈ (0, 2π) is the twist angle, means c_{r+V} = e^{-iθ}c_{r}. Note θ = 0 results in a periodic boundary condition and thus is not allowed.

 struct CompositeBoundaryCondition{N, T} <: AbstractBoundaryCondition
      BC::T
 end

Wrapper of multiple boundary conditions. BC is a tuple of boundary conditions.

 struct SquareLattice{D,T<:AbstractBoundaryCondition} <: SimpleLattice{D, T}
      e::NTuple{D,NTuple{D,Float64}}
      sites::Vector{NTuple{D,Int64}}
      BC::T
 end

Concrete type of D-dimensional square lattices.

 OpenSqua(L::Int64, W::Int64) -> ::SquareLattice

Construct an open L × W square lattice.

 YCSqua(L::Int64, W::Int64, θ::Real = 0.0) -> ::SquareLattice

Construct a YC L × W square lattice, where θ is the twist angle, e.g. θ = 0 means PBC and θ = π means APBC.

 struct TriangularLattice{D, T<:AbstractBoundaryCondition} <: SimpleLattice{D, T}
      e::NTuple{D,NTuple{D,Float64}}
      sites::Vector{NTuple{D,Int64}}
      BC::T
 end

Concrete type of triangular lattices. Note we only assume each layer is a triangular lattice if D > 2.

 YCTria(L::Int64, W::Int64, θ::Real = 0.0;
      reflect::Bool = false,
      scale::Real = 1.0) -> ::TriangularLattice

Construct a YC L × W triangular lattice, where θ is the twist angle, e.g. θ = 0 means PBC and θ = π means APBC.

kwargs

 reflect::Bool = false

If reflect = true, reflect the lattice along the x axis from the default convention.

 scale::Real = 1.0

The scale factor of the lattice. scale = 1.0 means the length of the primitive vectors equals to 1.0.

 XCTria(L::Int64, W::Int64,  θ::Real = 0.0;
      reflect::Bool = false,
      scale::Real = 1.0) -> ::TriangularLattice

Construct a XC L × W triangular lattice, where θ is the twist angle, e.g. θ = 0 means PBC and θ = π means APBC.

kwargs

 reflect::Bool = false

If reflect = true, reflect the lattice along the y axis from the default convention.

 scale::Real = 1.0

The scale factor of the lattice. scale = 1.0 means the length of the primitive vectors equals to 1.0.

 OHTria(L::Int64) -> ::TriangularLattice

Construct a triangular lattice in an open hexagon with L sites in a side.

 YCHoneycomb(L::Int64, W::Int64, θ::Real = 0.0; scale::Real = 1.0) -> ::CompositeLattice

Construct a YC L × W honeycomb lattice, where θ is the twist angle. Note YC honeycomb lattice is a XC triangular lattice with 2 sites per unit cell.

kwargs

 scale::Real = 1.0

The scale factor of the lattice, which equals to the distance between the nearest neighbor unit cells. Thus, use scale = sqrt(3) to make the length of the NN bond equals to 1.0.

 XCHoneycomb(L::Int64, W::Int64, θ::Real = 0.0; kwargs...) -> ::CompositeLattice

Construct a XC L × W honeycomb lattice, where θ is the twist angle. Note XC honeycomb lattice is a YC triangular lattice with 2 sites per unit cell.

kwargs

 scale::Real = 1.0

The scale factor of the lattice, which equals to the distance between the nearest neighbor unit cells. Thus, use scale = sqrt(3) to make the length of the NN bond equals to 1.0.

 coordinate(Latt::EmbeddedLattice{D}, idx) -> ::NTuple{D, Float64}

Return the coordinate of a given site.

 distance(Latt::EmbeddedLattice, idx1::Ind64, idx2::Int64) -> ::Float64

Return the distance between two sites.

 Zigzag!(Latt::EmbeddedLattice) -> Latt

Sort sites according to zigzag path, i.e. lexicographic order where last dimension first.

 Snake!(Latt::SimpleLattice{2}) -> Latt

Sort sites according to snake path, i.e. lexicographic order up to an even-odd modulation.

 neighbor(Latt::EmbeddedLattice, i::Int64; kwargs...) -> ::Vector{Int64}

Return all the neighbor sites of a given site.

 neighbor(Latt::EmbeddedLattice; kwargs...) -> ::Vector{NTuple{2, Int64}}

Return all neighbor pairs of a given lattice.

Kwargs

 d::Union{Missing, Real} = missing

The distance between the two sites of the neighbor pair.

 level::Int64 = 1

The neighbor level, e.g. level = 1 means the nearest neighbor, level = 2 means the next nearest neighbor, etc. Note it is defined by the total lattice, instead of the given site i. Note the priority is d > level.

 ordered::Bool = false

View (i,j) as an ordered pair if true, i.e. (i,j) ≠ (j,i).

 equiVec(Latt::EmbeddedLattice{D}) -> ::Vector{NTuple{D,Float64}}

Return the equivalent vectors around the origin point due to the boundary condition. For example, for a square lattice on a torus, there are 9 equivalent vectors (0.0, 0.0), (0.0, ±1.0), (±1.0, 0.0), (±1.0, ±1.0).

 relaVec(Latt::EmbeddedLattice, idx1::Int64, idx2::Int64) -> ::NTuple{D, Float64}

Return the nearest relative vector between the two sites. Note PBC is considered.

 intrapair(Latt::CompositeLattice, idx::Int64; kwargs...) -> ::Vector{NTuple{2, Int64}}

Similar to neighbor, but only return the intra-sublattice pairs of the idx sublattice.

 intrapair(Latt::CompositeLattice,
      lsidx::AbstractVector{Int64} = 1:N;
      kwargs...) -> ::Vector{NTuple{2, Int64}}

Collect all the intra-sublattice pairs of the given sublattices.

Kwargs

 d::Union{Missing, Real} = missing

The distance between the two sites of the neighbor pair.

 level::Int64 = 1

The neighbor level, note the inter-sublattice pairs will be ignored when calculating the distance with given level.

 ordered::Bool = false

View (i,j) as an ordered pair if true, i.e. (i,j) ≠ (j,i).

 interpair(Latt::CompositeLattice; kwargs...) -> ::Vector{NTuple{2, Int64}}

Collect all the inter-sublattice pairs.

 interpair(Latt::CompositeLattice, idx1::Int64, idx2::Int64;
      kwargs...) -> ::Vector{NTuple{2, Int64}}

Similar to neighbor, but only return the inter-sublattice pairs (i, j) s.t. i in idx1 and j in idx2 sublattices. Note the kwarg ordered will not affect the result for this usage.

Kwargs

 d::Union{Missing, Real} = missing

The distance between the two sites of the neighbor pair.

 level::Int64 = 1

The neighbor level, note the intra-sublattice pairs will be ignored when calculating the distance with given level.

 ordered::Bool = false

View (i,j) as an ordered pair if true, i.e. (i,j) ≠ (j,i).

 FTCoefs(Latt::EmbeddedLattice{D}, k::NTuple{D,Float64}; kwargs...) -> ::Vector{ComplexF64}
 FTCoefs(Latt::EmbeddedLattice{D}, lsk::AbstractVector{NTuple{D,Float64}}; kwargs...) -> ::Matrix{ComplexF64}

Return the Fourier coefficients corresponding to the given wave vector k, represented by a length N vector where N is the number of sites in the lattice. Note the FT convention is FS(k) = 1/sqrt(N) ∑_r exp(-ik⋅r) S(r).

Note our convention guarantees the FT is orthogonal thus the returned vector is normalized. However, the returned matrix corresponding to multiple k may not be orthogonal since we do not limit the input k list.

kwargs

 dims::Int64/Tuple{Vararg{Int64}} = Tuple(1:D)

The dimensions to perform the partial Fourier transform. For example, dims = (1,) means k = (kₓ, y) will give the coefficients (x, y') -> C e^{-ikₓx}δ(y - y'), where C is a normalization constant. Note it will return NaN if any site in the lattice does not have the same y-coordinate.

 FT(Sr::AbstractMatrix,
      Latt::EmbeddedLattice{D},
      lsk::AbstractVector = _default_lsk(Latt);
      dims::Union{Int64, Tuple{Vararg{Int64}}} = Tuple(1:D)
      ) -> FS::Matrix

Finally used method, apply the Fourier transform Sr(r, n) -> FS(k, n) where n is the column index of the given matrix Sr.

The FT convention please see FTCoefs.

 FT(Sr::AbstractVector,
      Latt::EmbeddedLattice,
      lsk::AbstractVector = _default_lsk(Latt);
      kwargs...
      ) -> ::Vector
 FT(Sr::AbstractMatrix,
      Latt::EmbeddedLattice{D},
      k::NTuple{D,Float64};
      kwargs...
      ) -> ::Vector

Return a vector for single n or k.

 FT(Sr::AbstractVector,
      Latt::EmbeddedLattice{D},
      k::NTuple{D,Float64};
      kwargs...
      ) -> ::ComplexF64

Return the coefficients when both n and k are single.

 FT(Latt::EmbeddedLattice, k; kwargs...) -> f: Sr -> FS

Return the function instead of applying the FT immediately.

 FT2(SS::AbstractMatrix,
      Latt::EmbeddedLattice,
      k::Tuple;
      symmetric::Bool=true,
      dims::Union{Int64, Tuple{Vararg{Int64}}} = Tuple(1:D)
      ) -> ::ComplexF64/Float64

Apply twice Fourier transform with the same k to the input matrix SS. A common use case is to calculate the structure factor from the all to all correlation function.

If symmetric = true, we assume the input matrix is hermitian and thus the result should be real up to a numerical error. In this case, we will automatically complete the matrix if it is a upper/lower triangular matrix.

dims gives the dimensions to perform the partial Fourier transform, details see function FTCoefs.

 FF2(SS::AbstractMatrix,
      Latt::EmbeddedLattice,
      lsk::AbstractVector = _default_lsk(Latt);
      kwargs...) -> ::Vector{ComplexF64/Float64}

Return a vector by simply broadcasting lsk.

 FT2(Latt::EmbeddedLattice, k) -> f: SS -> Sk

Return the function instead of applying the FT immediately.