fix copilot finds & add docstring for TightBindingTerm

- also a fix for an error in the docs CI (add a docstring for `TightBindingTerm`)

Author: thchr

CLAUDE.md

@@ -22,7 +22,7 @@ hopping ranges, the package:
 ## Key types and API
 
 ### Core pipeline
-- `tb_hamiltonian(cbr, Rs, Val{hermiticity})` — top-level entry point; returns `TightBindingModel`
+- `tb_hamiltonian(cbr, Rs, ::Val{<:Hermiticity})` — top-level entry point; returns `TightBindingModel`
 - `obtain_symmetry_related_hoppings(Rs, br_a, br_b)` — enumerates hopping orbits
 - `sgrep_induced_by_siteir(br, op)` — site-symmetry induced space group representation
 

docs/src/band-symmetry.md

@@ -11,7 +11,7 @@ To explore these tools, we first re-build the graphene model previously explored
     sgnum = 17                         # plane group p6mm
     brs = calc_bandreps(sgnum, Val(2)) # band representations
     cbr = @composite brs[5]            # (2b|A₁) EBR
-    tbm = tb_hamiltonian(cbr)          # tight-binding model (nearest neigbors)
+    tbm = tb_hamiltonian(cbr)          # tight-binding model (nearest neighbors)
     ptbm = tbm([0, 1])                 # zero self-energy, nonzero nearest-neighbor hopping
     Rs = directbasis(sgnum, Val(2))    # (conventional) direct lattice basis
     kp = irrfbz_path(sgnum, Rs)        # high-symmetry k-path

docs/src/nonhermitian.md

@@ -4,14 +4,14 @@ By default, the models returned by `tb_hamiltonian` are Hermitian. In addition t
 
 ## Hatano--Nelson model
 
-The architypical non-Hermitian model is the 1D Hatano--Nelson model, consisting of a single site and nearest-neigbor hoppings, in a setting with only time-reversal symmetry.
+The archetypical non-Hermitian model is the 1D Hatano--Nelson model, consisting of a single site and nearest-neighbor hoppings, in a setting with only time-reversal symmetry.
 It is simple to build this model with SymmetricTightBinding.jl:
 
 ```@example hatano-nelson
 brs = calc_bandreps(1, 1)  # EBRs in plane group 1, with time-reversal symmetry
 pin_free!(brs, [1=>[0]]) # the 1a Wyckoff position in plane group 1 has a free parameter: set to 0 for definiteness
 cbr = @composite brs[1]    # single-site model
-tbm = tb_hamiltonian(cbr, [[1]], NONHERMITIAN) # nearest neigbor hoppings
+tbm = tb_hamiltonian(cbr, [[1]], NONHERMITIAN) # nearest neighbor hoppings
 ```
 
 The model is very simple: two different hopping terms, corresponding to right- and left-directed hopping terms. The absence of hermiticity allows the hopping amplitudes in either direction to differ, contrasting the Hermitian case:
@@ -21,7 +21,7 @@ tb_hamiltonian(cbr, [[1]], HERMITIAN)
 ```
 The non-Hermitian model reduces to the Hermitian model when the left- and right-directed hopping amplitudes are equal. When the two are _not_ equal, the Hatano-Nelson model features exceptional points and spontaneous symmetry breaking of the real spectrum, as we can verify by example (using Brillouin.jl and GLMakie.jl for dispersion plotting):
 
-```@example hatano-nelson¨
+```@example hatano-nelson
 ptbm = tbm([0.9, 1.1]) # a model with 0.9 hopping amplitude to right, 1.1 to the left
 
 using Brillouin, GLMakie
@@ -45,7 +45,7 @@ tbm_notr = tb_hamiltonian((@composite brs_notr[1]), [[0], [1]], NONHERMITIAN) #
 ## A more complicated example: exceptional surfaces in p4
 
 We can also construct more complicated examples where symmetry plays a role. Consider for example the following simple extension of the Hatano-Nelson model to a 2D lattice with p4 symmetry:
-```
+```@example hatano-nelson-p4
 brs = calc_bandreps(10, Val(2))
 cbr = @composite brs[1]
 tbm_H  = tb_hamiltonian(cbr, [[0,0], [1,0]], Val(HERMITIAN))
@@ -54,7 +54,7 @@ tbm_NH = tb_hamiltonian(cbr, [[0,0], [1,0]], Val(NONHERMITIAN))
 
 It is instructive to visualize both the Hermitian and non-Hermitian models and compare the involved hopping terms:
 
-```
+```@example hatano-nelson-p4
 plot(tbm_H)
 plot(tbm_NH)
 ```

ext/SymmetricTightBindingMakieExt.jl

@@ -55,7 +55,7 @@ function Makie.plot!(
     t = p.t[]
     offdiag = p.offdiag[] # implies that (anti-)hermiticity requires adding reversed hoppings
     context = p.context[]
-    context = merge(context, default_context_attributes) # TODO: remove manual merging once Makie v0.25+ is out
+    context = merge(default_context_attributes, context) # TODO: remove manual merging once Makie v0.25+ is out
 
     P, V = Point{D, Float32}, Vec{D, Float32}
     Rm = stack(Rs)

src/tightbinding.jl

@@ -29,7 +29,7 @@ function obtain_symmetry_related_hoppings(
     Rs::AbstractVector{V}, # must be specified in the primitive basis
     brₐ::NewBandRep{D},
     brᵦ::NewBandRep{D};
-    diagonal_block::Bool = true, # whether to manually add "reversed" hoppings (if false),
+    diagonal_block::Bool = true, # whether to manually add "reversed" hoppings (if true),
     reverse_hop::Bool = false, # if hopping actually goes from a+R→b rather than a→b+R
                                # (used in NONHERMITIAN case, for lower-triangular blocks)
                                # practically just corresponds to flipping signs of `Rs`
@@ -75,7 +75,7 @@ function obtain_symmetry_related_hoppings(
     # hermiticity/anti-hermiticity could link orbits that spatial symmetries might not have
     # already linked: in particular, if we are in a "diagonal block" of the Hamiltonian,
     # then, for every hopping vector `δ`, we must have a "reversed" counterpart `-δ` in the
-    # presence of hermiticity r anti-hermiticity (always the case in our implementation);
+    # presence of hermiticity or anti-hermiticity (always the case in our implementation);
     # but those two vectors might have fallen in distinct orbits up this point - if so, we
     # now merge them
     if diagonal_block
@@ -849,16 +849,18 @@ end
     tb_hamiltonian(
         cbr::CompositeBandRep{D},
         Rs::AbstractVector{Vector{Int}}
-        [Sᵛ::Val{S} = Val(Hermitian)]
+        [Sᵛ::Val{S} = Val(HERMITIAN)]
     ) -> TightBindingModel{D, S}
 
 Construct the tight-binding Hamiltonian from a given composite band representation `cbr` and
 a set of global translation-representatives `Rs`.
 
-Whether the returned Hamiltonian is Hermitian or anti-Hermitian can be controlled by passing
-the optional argument `Sᵛ` as `Val(HERMITIAN)` (default) or `Val(ANTIHERMITIAN)`.
-This can also be passed as a plain `HERMITIAN` or `ANTIHERMITIAN` (but is then not type
-stable).
+Whether the returned Hamiltonian is Hermitian, anti-Hermitian, or non-Hermitian can be
+controlled by passing the optional argument `Sᵛ :: Val{S}` where `S` is an value of the enum
+type [`Hermiticity`](@ref), i.e., `HERMITIAN`, `ANTIHERMITIAN`, or `NONHERMITIAN` (default,
+`HERMITIAN`).
+This choice can also be passed a plain `S` (without a `Val` wrapper) but the call is then
+not type-stable.
 
 The returned [`TightBindingModel`](@ref) will generally feature several terms (iterating to
 [`TightBindingTerm`](@ref)s), each representing a tight-binding term that is closed under
@@ -903,7 +905,7 @@ function tb_hamiltonian(
     # upper block-diagonals: we do this to get a more natural sorting of the terms in the
     # model, with self-hoppings first, etc. For Hermitian/anti-Hermitian models, we only
     # go over the upper triangular part, with the latter following directly; for
-    # non-Hermitian, we just go over all blocks, going along diagonls 0,1,-1,…,B-1,-(B-1)
+    # non-Hermitian, we just go over all blocks, going along diagonals 0,1,-1,…,B-1,-(B-1)
     for d in _diagonal_indices(B, Sᵛ) # offset from main diagonal (at 0)
         for block_i in _row_indices(B, d, Sᵛ)
             block_j = block_i + d

src/types.jl

@@ -85,9 +85,9 @@ from `br2` to `br1` if `diagonal_block = false` and `S` is not `NONHERMITIAN`).
 - `br2 :: NewBandRep{D}`: second band representation
 - `ordering1 :: OrbitalOrdering{D}`: ordering of the orbitals in `br1`
 - `ordering2 :: OrbitalOrdering{D}`: ordering of the orbitals in `br2`
-- `h_orbit :: Union{Nothing,HoppingOrbit{D}}`: hopping orbit associated to the block
+- `h_orbit :: HoppingOrbit{D}`: hopping orbit associated to the block
 - `Mm :: Array{Int,4}`: matrix codifying Hamiltonian
-- `t :: Vector{Float64}}`: a basis vector, stored in re/im-doubled format
+- `t :: Vector{Float64}`: a basis vector, stored in re/im-doubled format
 - `MmtC :: Array{ComplexF64, 3}`: pre-contracted matrix `Mm` with "complexified" `t`.
 - `diagonal_block :: Bool`: whether this is a diagonal block in the overall Hamiltonian.
 """
@@ -152,6 +152,26 @@ Hermitian conjugation. Values:
     NONHERMITIAN
 end
 
+
+"""
+    TightBindingTerm{D, S}
+
+A single term a tight-binding Hamiltonian, representing a single block or a
+hermiticity-related pair of blocks of the Hamiltonian matrix.
+
+## Fields
+- `axis :: BlockedOneTo{Int, Vector{Int}}`: the blocked axis of the term, encoding the
+  global row/column indices all blocks in the full Hamiltonian matrix.
+- `block_ij :: NTuple{2, Int}`: the indices of considered term in the blocked axes; i.e.,
+  `axis[block_ij...]` gives the global row/column indices of the "key" block represented by
+  the term. If `S` is `NONHERMITIAN` or the term is diagonal, the key block is the only
+  block represented by the term; otherwise, the term also represents the hermiticity-related
+  block, whose global coordinates are `axis[reverse(block_ij)...]`.
+- `block :: TightBindingBlock{D, S}`: the `TightBindingBlock` associated to the key block.
+- `brs :: Vector{NewBandRep{D}}`: the set of band representations involved in the
+  Hamiltonian; each element corresponds to a block-index in `axis`, such that `axis[i, j]`
+  gives the (block of) hopping amplitudes from `brs[j]` to `brs[i]`.
+"""
 struct TightBindingTerm{D, S} <: AbstractBlockMatrix{TightBindingElementString}
     axis::BlockedOneTo{Int, Vector{Int}}
     block_ij::NTuple{2, Int}
@@ -191,10 +211,7 @@ function _getindex(
     i::Int,
     j::Int,
     conjugate::Bool = false
-) where {D, S}
-    # if we are actually getting from a block related to the stored one by antihermiticity
-    antihermitian_get = S === ANTIHERMITIAN && conjugate == true
-    
+) where {D, S}  
     @boundscheck 1 ≤ i ≤ size(tbb.Mm, 3) && 1 ≤ j ≤ size(tbb.Mm, 4) ||
                  error(BoundsError(tbb, (i, j)))