Band representations

bandreps(
    sgnum::Integer,
    ::Val{D}=Val(3);
    spinful::Union{Bool, Val{true}, Val{false}}=Val(false),
    timereversal::Bool=true,
    allpaths::Bool=false,
    explicitly_real::Bool=timereversal
) --> Collection{BandRep{D}}

bandreps( # type-unstable convenience accessor
    sgnum::Integer,
    D::Integer;
    kws...
) --> Collection{BandRep{D}}

Compute the band representations of space group sgnum in dimension D.

If spinful is Val(true) (or true), the spinful band representations are computed instead, induced from the double-valued site symmetry irreps (see siteirreps) and subduced onto the double-valued little group irreps (currently available in 3D only). As for D, the Val spelling keeps the return type inferrable and the Bool spelling does not.

Keyword arguments

• timereversal (default, true): whether the irreps used to induce the band representations are assumed to be time-reversal invariant (i.e., are coreps, see realify).
• allpaths (default, false): whether the band representations are projected to all distinct k-points returned by lgirreps (allpaths = false), including high-symmetry k-lines and -plane, or only to the maximal k-points (allpaths = true), i.e., just to high-symmetry points.
• explicitly_real (default, timereversal): whether, if timereversal = true, to ensure that the site symmetry irreps accompanying the band representations are chosen in the canonical form associated with time reversal (see physical_realify), i.e., explicitly real for spinless irreps and J*conj(D)*J' = D for spinful ones. This can be helpful for subsequent analysis involving the action of time-reversal symmetry.
• include_nonmaximal (default, false): whether to include band representations induced from site symmetry irreps of non-maximal Wyckoff positions. Passing as true will include band representations induced from all Wyckoff positions, regardless of maximality.

Notes

All band representations associated with maximal Wyckoff positions are returned, irregardless of whether they are elementary (i.e., no regard is made to whether the band representation is "composite"). As such, the returned band representations generally are a superset of the set of elementary band representations (and so contain all elementary band representations).

Implementation

The implementation is based on Cano, Bradlyn, Wang, Elcoro, et al., Phys. Rev. B 97, 035139 (2018), Sections II.C-D.

indicator_group(F::Smith) -> Any

Return the symmetry indicator group $X^{\text{BS}}$ associated with an input set of band representations brs (or Smith decomposition thereof, F), i.e., return the the nontrivial (i.e., ≠ {0,1}) elementary factors of the Smith normal form of the band representation matrix. The return value is a Vector{Int} containing the nontrivial factors. If no nontrivial factors exists, the return value is an empty Vector{Int}.

See also indicator_group_as_string for a formatted string version.

Understanding

The symmetry indicator group answers the question "what direct product of $\mathbb{Z}_n$ groups is the the quotient group $X^{\text{BS}} = \{\text{BS}\}/\{\text{AI}\}$ isomorphic to?" (see e.g., Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017) for more information).

Example

julia> brs = bandreps(2, Val(3));

julia> indicator_group(brs)
4-element Vector{Int64}:
 2
 2
 2
 4

indicator_group_as_string(
    nontriv_Λ::AbstractVector{<:Integer}
) -> String

Return the symmetry indicator group $X^{\text{BS}}$ as a formatted string (i.e., as "Zᵢ×Zⱼ×…"). See also indicator_group for a vector representation.

Example

julia> brs = bandreps(2, Val(3));

julia> indicator_group_as_string(brs)
"Z₂×Z₂×Z₂×Z₄"

basisdim(brs::Collection{<:BandRep})   --> Int
basisdim(B::AbstractMatrix{<:Integer}) --> Int
basisdim(F::Smith)                     --> Int

Return the dimension of the (linearly independent parts) of a band representation basis. This is $d^{\text{bs}} = d^{\text{ai}}$ in the notation of Po, Watanabe, & Vishwanath, Nature Commun. 8, 50 (2017), or equivalently, the rank of stack(brs) over the ring of integers. This is the number of linearly independent basis vectors that span the expansions of a band structure viewed as symmetry data.

smith_column_bases(brs::Collection{<:BandRep})   --> @NamedTuple{S̃, Λ, S̃⁻¹}
smith_column_bases(B::AbstractMatrix{<:Integer}) --> @NamedTuple{S̃, Λ, S̃⁻¹}
smith_column_bases(F::Smith)                     --> @NamedTuple{S̃, Λ, S̃⁻¹}

Return the parts of the Smith normal decomposition of a set of band representations brs (or of its matrix B, or of a Smith decomposition F thereof) that pertain to the column space of the band representation matrix, i.e. the parts associated with the $d^{\text{bs}} =$ basisdim(brs) nonzero elementary factors of $\boldsymbol{\Lambda}$:

• S̃: the first $d^{\text{bs}}$ columns of $\mathbf{S}$; an integer-coefficient basis for all gapped band structures {BS}.
• Λ: the first $d^{\text{bs}}$ elements of $\boldsymbol{\Lambda}$, i.e. its nonzero elementary factors $\lambda_1, \ldots, \lambda_{d^{\text{bs}}}$.
• S̃⁻¹: the first $d^{\text{bs}}$ rows of $\mathbf{S}^{-1}$; these take a symmetry vector n to its coefficients in S̃, i.e. S̃⁻¹*n.

Note that S̃⁻¹ is a slice of $\mathbf{S}^{-1}$, not the inverse of the (generally nonsquare) S̃; the two nevertheless satisfy S̃⁻¹*S̃ == I. All three returned quantities are views into F, so nothing is allocated.

A basis for the atomic insulators {AI} — the bands induced by localized orbitals at the Wyckoff positions — is S̃*Diagonal(Λ). A symmetry vector that can be expanded on that basis with positive integer coefficients is a trivial insulator (i.e., deformable to an atomic limit); one that cannot is topological, either fragilely (some negative coefficients) or strongly (fractional coefficients). calc_topology distinguishes the strong case from Λ and S̃⁻¹ alone.

Implementation

For an n×m integer matrix $\mathbf{B}$, the Smith normal form gives integer matrices $\mathbf{S}$, $\mathrm{diagm}(\boldsymbol{\Lambda})$ and $\mathbf{T}$ (of size n×n, n×m and m×m, respectively) with $\mathbf{B} = \mathbf{S}\mathrm{diagm}(\boldsymbol{\Lambda})\mathbf{T}$, where $\boldsymbol{\Lambda} = [\lambda_1, \ldots, \lambda_r, 0, \ldots, 0]$ with $\lambda_{j+1}$ divisible by $\lambda_j$ and $r = d^{\text{bs}} \leq \min(n,m)$; $\mathbf{S}$ and $\mathbf{T}$ have integer-valued inverses.

Applying S̃⁻¹ to integer symmetry data $\mathbf{n}$ gives the integer factors $q_i C_i$ ($C_i = \lambda_i$ here) of Tang, Po, Vishwanath, & Wan, Nature Physics 15, 470 (2019).