API

collect_compatible(ptbm::ParameterizedTightBindingModel{D}; multiplicities_kws...)

Determine a decomposition of the bands associated with ptbm into a set of SymmetryVectors, with each symmetry vector corresponding to a set of compatibility-respecting (i.e., energy separable along high-symmetry k-lines) bands.

Keyword arguments

• multiplicities_kws...: keyword arguments passed to Crystalline.collect_compatible used in determining the multiplicities of irreps across high-symmetry k-points.

Example

julia> using Crystalline, SymmetricTightBinding

julia> brs = calc_bandreps(221);

julia> cbr = @composite brs[1] + brs[2]
40-irrep CompositeBandRep{3}:
 (3d|A₁g) + (3d|A₁ᵤ) (6 bands)

julia> tbm = tb_hamiltonian(cbr); # a 4-term, 6-band model

julia> ptbm = tbm([1.0, 0.1, -1.0, 0.1]); # fix free coefficients

julia> collect_compatible(ptbm)
2-element Vector{SymmetryVector{3}}:
 [M₅⁺+M₁⁻, X₃⁺+X₁⁻+X₂⁻, Γ₁⁻+Γ₃⁻, R₄⁺] (3 bands)
 [M₁⁺+M₅⁻, X₁⁺+X₂⁺+X₃⁻, Γ₁⁺+Γ₃⁺, R₄⁻] (3 bands)

In the above example, the bands separate into two symmetry vectors, one for each of the original EBRs in cbr.

collect_irrep_annotations(ptbm::ParameterizedTightBindingModel; kws...)

Collect the irrep labels across the high-symmetry k-points referenced by the underlying composite band representation of ptbm, across the bands of the model.

Useful for annotating irrep labels in band structure plots (via the Makie extension call plot(ks, energies; annotations=collect_irrep_annotations(ptbm)))

berrycurvature(
    ptbm::ParameterizedTightBindingModel{D},
    k::ReciprocalPointLike{D},
    n::Integer,
    [∇Hs::NTuple{D, Matrix{ComplexF64}}]
)  --> Ω

Compute the Berry curvature Ω of the nth band of the coefficient-parameterized tight-binding model ptbm at the k-point k. If D == 3, Ω is a 3-element vector, representing, the three components of the Berry curvature pseudovector $[Ω₁, Ω₂, Ω₃] = [Ω₂₃, Ω₃₁, Ω₁₂]$. If D == 2, Ω is a scalar, representing the Berry curvature pseudoscalar $Ω₃ = Ω₁₂$.

The optional ∇Hs argument is a tuple of work-matrices used to store the momentum gradient of the Hamiltonian.

Implementation

The Berry curvature is evaluated using the Kubo-like or "sum-over-states" formula ^[1]:

\[\Omega_{ij}^n = \sum_{n' \neq n} \frac{\langle n |\partial H/\partial k_i|n'\rangle \langle n'|\partial H/\partial k_j|n\rangle - (j \leftrightarrow i)} {(E_n - E_{n'})^2} = -2\mathrm{Im} \sum_{n' \neq n} \frac{\langle n |\partial H/\partial k_i|n'\rangle \langle n'|\partial H/\partial k_j|n\rangle} {(E_n - E_{n'})^2},\]

with $\Omega_{ij}^n$ denoting the Berry curvature tensor component of the nth band and $E_n$ denoting the energy of the nth band. The Berry curvature pseudovector and (antisymmetric) tensor components are related by $\Omega_1 = \Omega_{23}$, $\Omega_2 = \Omega_{31}$, and $\Omega_3 = \Omega_{12}$.

Example

Consider the following model in plane group p2, without time-reversal symmetry:

julia> brs = calc_bandreps(2, Val(2); timereversal=false);

julia> cbr = @composite brs[1] + brs[3]
8-irrep CompositeBandRep{2}:
 (1d|A) + (1c|A) (2 bands)

julia> tbm = tb_hamiltonian(cbr, [[0,0], [1,0]]);

tbm is an 8-term model, whose 6th and 8th terms break time-reversal symmetry, but which retains inversion symmetry. We can build a parameterized instance of this model and compute its Berry curvature at some k-point to verify that its evenness under inversion (k → -k):

julia> ptbm = tbm([0, .1, -0, 0, .2, 0, 0, .3]);

julia> k = [0.1, 0.2];

julia> C₁_k₊ = berrycurvature(ptbm, k, 1)  # Berry curvature of band 1 at `k`
-0.2529580943483421

julia> C₁_k₋ = berrycurvature(ptbm, -k, 1) # Berry curvature of band 1 at `-k`
-0.2529580943483421

julia> C₁_k₊ ≈ C₁_k₋
true

julia> C₁_k₊ ≈ -berrycurvature(ptbm, k, 2) # opposite Berry curvatures in bands 1 and 2
true

The model also happens to have a nonzero Chern number, as can be verified by integrating the Berry curvature over the Brillouin zone using chern, or manually by summation:

julia> chern(ptbm, 1, 51)
-1.000000071894951

Extended help

As elsewhere in SymmetricTightBinding.jl, this function operates in reduced coordinates, with the momentum k = (k₁, k₂, k₃) indicating coefficients relative to the primitive reciprocal lattice vectors $\mathbf{b}_i$, i.e., $\mathbf{k} = k_1\mathbf{b}_1 + k_2\mathbf{b}_2 + \ldots$. Importantly, this also implies that returned Berry curvature components are not the Cartesian components, but components relative to the primitive reciprocal basis.

In 3D, this implies that the returned vector Ω = [Ω₁, Ω₂, Ω₃] relates to the Berry curvature pseudovector $\boldsymbol{\Omega}$ via

\[\boldsymbol{\Omega} = V_{\text{BZ}}^{-1} (\Omega_1 \mathbf{b}_1 + \Omega_2 \mathbf{b}_2 + \Omega_3 \mathbf{b}_3) = V_{\text{BZ}}^{-1} (\Omega_{23} \mathbf{b}_1 + \Omega_{31} \mathbf{b}_2 + \Omega_{12} \mathbf{b}_3),\]

with $V_{\text{BZ}} = \mathbf{b}_1 \cdot (\mathbf{b}_2 \times \mathbf{b}_3)$ denoting the (signed) volume of the 3D Brillouin zone. Here, the tensor components $\Omega_{12}$ etc. correspond to momentum derivatives in the reduced coordinates, i.e., the derivatives $\partial/\partial k_{1,2}$ are taken with respect to reduced (dimensionless) coordinates $k_{1,2}$ rather than Cartesian ones.

As a result, the returned Berry curvature pseudovector components $[Ω₁, Ω₂, Ω₃]$ are related to the Cartesian pseudovector components $[Ω_x, Ω_y, Ω_z]$ by the primitive reciprocal lattice matrix $\mathbf{B} = [\mathbf{b}_1 \mathbf{b}_2 \mathbf{b}_3]$:

\[[Ω_x, Ω_y, Ω_z]^{\text{T}} = V_{\text{BZ}}^{-1} \mathbf{B} [Ω₁, Ω₂, Ω₃]^{\text{T}}\]

Equivalently, the antisymmetric Berry curvature tensors $\Omega_{ij}$ ($i,j \in \{1, 2, 3\}$, i.e., reduced coordinate basis) and $\Omega_{\mu\nu} ($\mu, \nu = {x, y, z}``, i.e. Cartesian basis) relates via

\[\Omega_{ij} = \sum_{\mu\nu} B^T_{i\mu} \Omega_{\mu\nu} B_{\nu j}\ \Omega_{\mu\nu} = \sum_{ij} B^{-T}_{\mu i} \Omega_{ij} B^{-1}_{j\nu}.\]

In 2D, the returned Berry curvature is a (pseudo)scalar $Ω₃ = Ω₁₂$. Again, this value represents the component of the Berry curvature in the reduced coordinate system. It is related to the Cartesian pseudoscalar $\Omega_{xy}$ by the (signed) area of the Brillouin zone $A_{\text{BZ}} = (\mathbf{b}_1 \times \mathbf{b}_2) \cdot \hat{\mathbf{z}}$:

\[\Omega_z = \Omega_{xy} = \Omega_{12} / A_{\text{BZ}}.\]

Implications for surface integrals and flux

When using the returned 3D Berry curvature pseudovector [Ω₁, Ω₂, Ω₃] to calculate physical observables like the Chern number of a slice or the flux through a surface, it's crucial to integrate the correct physical quantity. The assumed goal is always to compute a flux integral:

\[\Phi = \int_S \boldsymbol{\Omega} \cdot \,\mathrm{d}\mathbf{S}.\]

While this function returns the components [Ω₁, Ω₂, Ω₃] in the reduced basis, the flux integrand requires the full dot product between the physical vector $\boldsymbol{\Omega} = \Omega_1 \mathbf{b}_1 + \Omega_2 \mathbf{b}_2 + \Omega_3 \mathbf{b}_3$ and the physical area element $\mathrm{d}\mathbf{S}$.

The implications of this statement can be appreciated if we consider e.g., calculating the Chern number on a planar slice of the BZ, for example the plane spanned by $\mathbf{b}_1$ and $\mathbf{b}_2$. The physical area element is $\mathrm{d}\mathbf{S} = (\mathbf{b}_1 \times \mathbf{b}_2) \, \mathrm{d}k_1 \mathrm{d}k_2$, so that the flux integrand is:

\[\mathrm{d}\Phi = \boldsymbol{\Omega} \cdot d\mathbf{S} = V_{\text{BZ}}^{-1} (\Omega_1 \mathbf{b}_1 + \Omega_2 \mathbf{b}_2 + \Omega_3 \mathbf{b}_3) \cdot (\mathbf{b}_1 \times \mathbf{b}_2) \, \mathrm{d}k_1 \mathrm{d}k_2.\]

By the properties of the triple product, the terms proportional to $\Omega_{1,2}$ vanish, leaving:

\[\mathrm{d}\Phi = V_{\text{BZ}}^{-1} \Omega_3 (\mathbf{b}_3 \cdot (\mathbf{b}_1 \times \mathbf{b}_2)) \, \mathrm{d}k_1 \mathrm{d}k_2.\]

The term $\mathbf{b}_3 \cdot (\mathbf{b}_1 \times \mathbf{b}_2)$ is the volume of the 3D Brillouin zone, $V_{\text{BZ}}$, cancelling the $V_{\text{BZ}}^{-1}$ prefactor. Thus, the flux integral simplifies to:

\[\mathrm{d}\Phi = \Omega_3 \, \mathrm{d}k_1 \mathrm{d}k_2.\]

In other words: while the distinction between e.g., $\Omega_{xy}$ and $\Omega_{12}$ is important for interpreting the curvature at an individual k-point, it can be ignored when calculating the Chern number as an integral over the reduced coordinates (e.g., $k_{1,2} \in (-1/2, 1/2]$ above), since the transformation factors in the curvature and the area element $\mathrm{d}\mathbf{S}$ cancel out.

chern(
    ptbm::ParameterizedTightBindingModel{2},
    n::Integer,
    Nk::Integer,
) --> Float64

Evaluate the Chern number of the nth band of the 2D model ptbm, by grid-based integration of the Berry curvature (using berrycurvature) over the reduced-coordinate Brillouin zone $(-1/2, 1/2]×(-1/2, 1/2]$ using Nk×Nk sample points.

Note that, unlike the Fukui et al. method (chern_fukui), this approach does not guarantee integer results for finite Nk, but will converge smoothly to the correct integer Chern number with increasing Nk.

Definition

The returned Chern number is defined with the sign-convention:

\[C = \frac{1}{2\pi} \int_{\text{BZ}} \nabla_{\mathbf{k}} \times \mathrm{i} \langle u_{n\mathbf{k}} | \nabla_{\mathbf{k}} | u_{n\mathbf{k}} \rangle \, \mathrm{d}^2 \mathbf{k}.\]

chern_fukui(
    ptbm::ParameterizedTightBindingModel{2},
    bands::Union{T, AbstractVector{T}, AbstractVector{<:AbstractVector{T}}} where T<:Integer,
    Nk::Integer,
) --> C where C <: Union{Int, Vector{Int}}

Evaluate the Chern number of the specified bands of the 2D model ptbm, using the link-variable integration approach of Fukui et al. ^[1] and Nk linear sample points per k-space dimension.

The bands argument can specify either:

1. a single band index n, returning then the Abelian Chern number of the nth band, or
2. an abstract vector of band indices ns, returning then the non-Abelian Chern number of the corresponding band multiplet, or
3. an abstract vector of abstract vectors nsv, returning then a vector of non-Abelian Chern numbers, one for each band multiplet specified in nsv.

The returned value is guaranteed to be an integer (but will only converge to the correct Chern number for sufficiently high Nk).

See also chern for an alternative approach (applicable to the Abelian case) based on direct integration of the Berry curvature, evaluated from a sum-over-states formula. The Fukui approach is usually more performant for Chern number evaluation.

Definition

The returned Chern number is defined with the sign-convention:

\[C = \frac{1}{2\pi} \int_{\text{BZ}} \nabla_{\mathbf{k}} \times \mathrm{i} \langle u_{n\mathbf{k}} | \nabla_{\mathbf{k}} | u_{n\mathbf{k}} \rangle \, \mathrm{d}^2 \mathbf{k}.\]

energy_gradient_wrt_hopping(
    ptbm::ParameterizedTightBindingModel{D},
    k::ReciprocalPointLike{D}
    (Es, us) = solve(ptbm, k; bloch_phase=Val(false));
    degen_rtol::Float64 = 1e-12,
    degen_atol::Float64 = 1e-12
) where D

Return the hopping gradient of the energy of each band in ptbm evaluated at momentum k.

The gradient is computed using the Feynman-Hellmann theorem. For degenerate bands (assessed energetically using relative and absolute tolerances degen_rtol and degen_atol), a degenerate variant is used, equivalent to degenerate perturbation theory.

The gradient is returned as column vectors, one for each band, with each column containing the gradient of the corresponding energy with respect to the hopping coefficients of ptbm.

gradient_wrt_hopping(tbm :: TightBindingModel)
gradient_wrt_hopping(ptbm :: ParameterizedTightBindingModel)

Return a structure that encodes the gradient of a tight-binding model tbm or ptbm with respect to the hopping coefficients.

To evaluate the gradient at a particular momentum k, use the returned structure as a functor at k. I.e., gradient(tbm)(k) returns the gradient of the tight-binding Hamiltonian with respect to all hoppping coefficients at momentum k. This gradient is a vector of matrices.

gradient_wrt_momentum(ptbm :: ParameterizedTightBindingModel)

Return a structure that encodes the gradient of a parameterized tight-binding model ptbm with respect to its momentum coordinates (in the basis of the primitive reciprocal lattice vectors)

To evaluate the gradient at a particular momentum k, use the returned structure as a functor at k. I.e., gradient_wrt_momentum(ptbm)(k)[i] returns the ith component of the momentum derivative of ptbm with respect to the momentum at k. The return value is a D-dimensional tuple of matrices (see also TightBindingModelMomentumGradient).

obtain_symmetry_related_hoppings(
    Rs::AbstractVector{V}, 
    brₐ::NewBandRep{D}, 
    brᵦ::NewBandRep{D};
    diagonal_block::Bool = true,
) --> Vector{HoppingOrbit{D}}

Compute the symmetry-related hopping terms from the points in the WP of brₐ to the WP of brᵦ, displaced by a set of primitive lattice-vector representatives Rs.

Implementation

1. Take a point a in the WP of brₐ and a point b in the WP of brᵦ. Compute the displacement vector δ = b + R - a, where R ∈ Rs.
2. If δ ∈ representatives, add δ => (a, b, R) to the list of hoppings for that representative and continue. Otherwise, search all representatives for one whose list of hoppings contains δ => (a, b, R). If none is found, add δ as a new representative and add δ => (a, b, R) to its list of hoppings.
3. Take g ∈ generators, compute δ' = g δ and (a', b', R') = (g a, g b, g R), and repeat step 2.
4. Repeat steps 1–3 for all pairs of points in the WPs of brₐ and brᵦ.

Additionally, if we are considering a diagonal block (which must be Hermitian or anti-Hermitian), we check whether orbits that relate δ and -δ are present; if not, we add them.

pin_free!(
    brs::Collection{NewBandRep{D}},
    idx2αβγ::Pair{Int, <:AbstractVector{<:Real}}
)

pin_free!(
    brs::Collection{NewBandRep{D}},
    idx2αβγs::AbstractVector{<:Pair{Int, <:AbstractVector{<:Real}}}
)

For idx2αβγ = idx => αβγ, update brs[idx] such that the free parameters of its associated Wyckoff positions are pinned to αβγ.

A vector of pairs idx2αβγs can also be provided, to pin multiple distinct band representations.

See also pin_free for non-mutated input.

sgrep_induced_by_siteir(
    br::Union{NewBandRep, CompositeBandRep},
    op::SymOperation, [positions::Vector{<:DirectPoint}]
)
sgrep_induced_by_siteir(
    tbm::Union{TightBindingModel,ParameterizedTightBindingModel}, op::SymOperation
)
    --> SiteInducedSGRepElement

Computes the representation matrix of a symmetry operation op induced by the site symmetry group associated with an elementary or composite band representation br , including the global momentum-dependent phase factor, returning a SiteInducedSGRepElement, which is a functor over momentum inputs.

A (possibly parameterized) tight-binding model tbm can be specified instead of a band representation, in which case the latter is inferred from the former.

spectrum(ptbm::ParameterizedTightBindingModel, ks; transform = identity)

Evaluate the spectrum, i.e., energies, of the tight-binding model ptbm over an iterable of input momenta ks.

Energies are returned as a matrix, with rows running over momenta and columns over distinct bands.

Keyword arguments

• transform: a function to apply to the resulting matrix of energies, defaulting to the identity function. This can be used to e.g., convert the energies to a different scaling.

Example

As an example, we evaluating the band structure of graphene. Below, we first construct and parameterize a tight-binding model for the the (2b|A₁) EBR in plane group 17, corresponding to the highest-lying orbitals in graphene. Next, we construct a path along high-symmetry directions of the Brillouin zone using Brillouin.jl, calculate the spectrum across this path; and finally, plot the band structure using Brillouin and GLMakie (or PlotlyJS):

julia> using Crystalline, SymmetricTightBinding

julia> brs = calc_bandreps(17, Val(2));

julia> cbr = @composite brs[5]
13-irrep CompositeBandRep{2}:
 (2b|A₁) (2 bands)

julia> ptbm = tb_hamiltonian(cbr, [zeros(Int, dim(cbr))])([0.0, 1.0]);

julia> using Brillouin, GLMakie

julia> kpi = interpolate(irrfbz_path(17, directbasis(17, Val(2))), 100);

julia> plot(kpi, spectrum(ptbm, kpi))

spectrum(ptbm::ParameterizedTightBindingModel, k::AbstractVector{<:Real})

Evaluate the spectrum, i.e., energies, of the tight-binding model ptbm at a single momentum k, across all the bands of ptbm.

subduced_complement(tbm::TightBindingModel{D}, sgnumᴴ::Int; timereversal)
                                                    --> TightBindingModel{D}

Given a model tbm associated with a space group $G$, determine the new, independent tight-binding terms (i.e., the the orthogonal complement of terms) that become symmetry-allowed when the model's space group is reduced to a subgroup $H ≤ G$ with space group number sgnumᴴ and time-reversal symmetry timereversal.

Practically, the function answers the question: which new tight-binding terms become allowed if the symmetry of the model is reduced from space group $G$ to subgroup $H$?

Implementation

The function computes a basis of allowed tight-binding terms in the subgroup setting $H$ by simply restricting the constraints in $G$ to generators in $H$. This gives a basis for the tight-binding terms in the subduced $G ↓ H$ setting. The space spanned by this basis is compared to the space spanned in the original model; in particular new terms are identified as the orthogonal complement of the spaces associated with $G ↓ H$ relative to $G$.

Keywords

• timereversal::Bool: Specifies whether time-reversal symmetry is present in the subgroup $H$. By default, the presence or absence is inherited from the original model tbm. Note that timereversal must be "lower or equal to" the time-reversal of the original model.

Example

It is well-known that the Dirac point of graphene is gapped under mirror and time-reversal symmetry breaking. We can see this by constructing a tight-binding model first for a model of graphene (plane group ⋕17) and then subducing it to a setting without mirror symmetry (plane group ⋕16) and without time-reversal symmetry (timereversal = false). First, we construct the tight-binding model for graphene (via the (2a|A₁) band representation):

julia> using SymmetricTightBinding, Crystalline

julia> brs = calc_bandreps(17, Val(2); timereversal = true);

julia> cbr = @composite brs[5]

julia> tbm = tb_hamiltonian(cbr, [[0,0], [1,0]])

Each of the 4 terms in this model is proportional to an identity matrix at K = (1/3, 1/3). Using subduced_complement, we can find the new terms that appear if we imagine lowering the symmetry from plane group ⋕17 to ⋕16 (which has no mirror symmetry) while also removing time-reversal symmetry.

julia> Δtbm = subduced_complement(tbm, 16; timereversal = false)
2-term 2×2 TightBindingModel{2} over (2b|A₁):
┌─
1. ⎡ i𝕖(δ₁)+i𝕖(δ₂)+i𝕖(δ₃)-i𝕖(δ₄)-i𝕖(δ₅)-i𝕖(δ₆)  0                                          ⎤
│  ⎣ 0                                          -i𝕖(δ₁)-i𝕖(δ₂)-i𝕖(δ₃)+i𝕖(δ₄)+i𝕖(δ₅)+i𝕖(δ₆) ⎦
└─ (2b|A₁) self-term:  δ₁=[1,0], δ₂=[0,1], δ₃=[-1,-1], δ₄=-δ₁, δ₅=-δ₂, δ₆=-δ₃
┌─
2. ⎡ 0                                       𝕖(δ₁)+𝕖(δ₂)+𝕖(δ₃)-𝕖(δ₇)-𝕖(δ₈)-𝕖(δ₉) ⎤
│  ⎣ 𝕖(δ₄)+𝕖(δ₅)+𝕖(δ₆)-𝕖(δ₁₀)-𝕖(δ₁₁)-𝕖(δ₁₂)  0                                   ⎦
└─ (2b|A₁) self-term:  δ₁=[4/3,-1/3], δ₂=[1/3,5/3], δ₃=[-5/3,-4/3], δ₄=-δ₁, δ₅=-δ₂, δ₆=-δ₃, δ₇=[1/3,-4/3], δ₈=[-5/3,-1/3], δ₉=[4/3,5/3], δ₁₀=-δ₇, δ₁₁=-δ₈, δ₁₂=-δ₉

The first of the of these terms is not diagonal at K and so opens a gap at the Dirac point:

julia> Δtbm[1](ReciprocalPoint(1/3, 1/3))
2×2 Matrix{ComplexF64}:
 5.19615+1.73195e-14im       0.0+0.0im
     0.0+0.0im          -5.19615+1.43774e-14im

Adding symmetry-breaking terms to the original model

To build a "complete" model, with both the original and symmetry-breaking terms, use vcat:

julia> tbm′ = vcat(tbm, Δtbm); length(tbm′) == length(tbm) + length(Δtbm)
true

Limitations

The subgroup $H$ must be a volume-preserving subgroup of the original group $G$. I.e. $H$ must be a translationen-gleiche subgroup of $G$ (or $G$ itself), and there must exist a transformation from $G$ to $H$ that preserves volume (i.e., has det(t.P) == 1 for t denoting an element returned by Crystalline.jl's conjugacy_relations).

symmetry_eigenvalues(
    ptbm::ParameterizedTightBindingModel{D},
    ops::AbstractVector{SymOperation{D}},
    k::ReciprocalPointLike{D},
    [sgreps::AbstractVector{SiteInducedSGRepElement{D}}]
)
symmetry_eigenvalues(
    ptbm::ParameterizedTightBindingModel{D},
    lg::LittleGroup{D},
    [sgreps::AbstractVector{SiteInducedSGRepElement{D}}]
)
    --> Matrix{ComplexF64}

Compute the symmetry eigenvalues of a coefficient-parameterized tight-binding model ptbm at the k-point k for the symmetry operations ops. A LittleGroup can also be provided instead of ops and k.

Representations of the symmetry operations ops as acting on the orbitals of the tight-binding setting can optionally be provided in sgreps (see sgrep_induced_by_siteir) and are otherwise initialized by the function.

The symmetry eigenvalues are returned as a matrix, with rows running over the elements of ops and columns running over the bands of ptbm.

tb_hamiltonian(cbr::CompositeBandRep{D}, Rs::AbstractVector{Vector{Int}}) 
    --> Vector{TightBindingTerm{D}}

Construct the TB Hamiltonian matrix from a given composite band representation cbr and a set of global translation-representatives Rs. The Hamiltonian is constructed block by block according to the symmetry-related hoppings between the band representations in cbr. Several models returned, each representing a term that is closed under the symmetry operations of the underlying space group.

HoppingOrbit{D}

A structure holding information about symmetry-related spatial hopping vectors.

An orbit includes all symmetry related vectors {δ} = {δ₁, δ₂, …} obtained by applying the symmetry operations of the underlying space group to a representative vector δ.

For each element of the orbit δᵢ there may be multiple hopping terms, from site a to site b, possibly related by a lattice translation R. Each such set of possible hopping term (a, b, R) is for each δᵢ is stored elements as the ith element of the vector hoppings.

Fields

• representative :: RVec{D}: the representative hopping vector δ
• orbit :: Vector{RVec{D}}: the δᵢ elements of the orbit generated by δ. Generally orbit[1] == representative, i.e., δ₁ = δ
• hoppings :: Vector{Vector{NTuple{3,RVec{D}}}}: the ith element gives the possible physical hopping terms (a,b,R) associated to orbit[i]. Multiple physical hopping terms may correspond to each element of the orbit. For (a, b, R) = hoppings[i][j], we have orbit[i] = δᵢ = b + R - a

ParameterizedTightBindingModel{D}

A coefficient-parameterized tight-binding model, that can be used as a functor for evaluation at input momenta k.

Fields

• tbm :: TightBindingModel{D}: A tight-binding model, consisting of a set of a list of TightBindingTerm{D}s.
• cs :: Vector{Float64}: A vector of coefficients, each associated to a corresponding element of tbm.
• scratch :: Matrix{ComplexF64}: A scratch space for evaluating the Hamiltonian matrix at at specific momenta. This is a N×N matrix, where N is the number of orbitals in tbm (i.e., tbm.N). The scratch space is instantiated automatically on construction.

Functor over momenta

A ParameterizedTightBindingModel ptbm can be be evaluated at any ´D-dimensional momentumkby usingptbmas a functor. That is,ptbm(k)returns a numerical representation of the Hamiltonian matrix forptbmevaluated at momentumk.

TightBindingElementString

A structure for pretty-printing tight-binding matrix elements.

Fields

• s :: String: the string representing the tight-binding matrix element
• active :: Bool: whether the element belongs to an "active" block - i.e., one we want to highlight (then shown in blue).

TightBindingModel{D}

A structure storing a list of TightBindingTerm{D}s. Each term is assumed to associated with an identical list of EBRs.

To associate a set of coefficients to each term, see ParameterizedTightBindingModel, which also allows evaluation at specific momenta.

Fields

• terms :: Vector{TightBindingTerm{D}}: a vector of TightBindingTerm{D}s, each of which represents a block (or conjugated pairs of blocks) of the Hamiltonian matrix.
• cbr :: CompositeBandRep{D}: the composite band representation associated to the model.
• positions :: Vector{DirectPoint{D}}: a vector of positions, specified in the lattice basis, associated to each orbital of the model.
• N :: Int: the total number of orbitals in the model, i.e., the size of the Hamiltonian matrix associated to each element of terms.

(∇ptbm::TightBindingModelMomentumGradient{D})(
    k::ReciprocalPointLike{D},
    components::NTuple{C, Int},
    [∇Hs::NTuple{C, Matrix{ComplexF64}}]
) --> ∇Hs

Evaluate components of the momentum gradient ∇ptbm at momentum k, writing into the mutated matrix tuple ∇Hs (automatically initialized if not provided).

The momentum components are specified by the components argument. These specifications are assumed relative to the primitive reciprocal lattice vectors $\mathbf{b}_i$ (which k = (k₁, k₂, k₃) is also assumed specified relative to, such that the momentum vector is $\mathbf{k} = k_1 \mathbf{b}_1 + k_2 \mathbf{b}_2 + k_3 \mathbf{b}_3$). E.g., for a 3D model with components = (2, 3), the elements of the returned ∇Hs tuple have the interpretation that ∇Hs[1] is the gradient of the Hamiltonian with respect to k₂, i.e., $\partial H/\partial k_2$, and ∇Hs[2] is the gradient with respect to k₃, $\partial H/\partial k_3$.

Coordinate transformation

Note that because k is specified relative to the primitive reciprocal basis, which is generally neither orthogonal nor unit-normalized, the computed gradient is not the gradient with respect to the Cartesian components of $\mathbf{k}$, nor with respect to the coefficients of unit-normalized primitive reciprocal lattice vectors.

One may readily convert to either of these cases by using the chain rule, however. E.g., the gradient components $\partial H/\partial k̃_i$ for coordinates $k̃_i$ relative to a unit-normalized reciprocal basis specification of the momentum vector $\mathbf{k} = k̃_1\hat{\mathbf{b}}_1 + k̃_2\hat{\mathbf{b}}_2 + k̃_3\hat{\mathbf{b}}_3$ are related to the returned components by $\partial H/\partial k̃_i = |\mathbf{b}_i|^{-1} \partial H/\partial k_i$.

Similarly, the components relative to Cartesian coordinates $kᶜ_i$ of the momentum vector $\mathbf{k} = kᶜ_1\hat{\mathbf{e}}_1 + kᶜ_2\hat{\mathbf{e}}_2 + kᶜ_3\hat{\mathbf{e}}_3$ can be obtained via $\partial H/\partial kᶜ_i = \sum_j (\mathbf{B}^{-\mathrm{T}})_{ij} \partial H/\partial k_j$, where $\mathbf{B} = [\mathbf{b}_1 \mathbf{b}_2 \mathbf{b}_3]$ is a matrix whose columns are the primitive reciprocal lattice vectors and $\mathbf{B}^{-\mathrm{T}}$ is its inverse transpose.