split spectrum into two functions: spectrum and spectrum_single_k for multiple/single **k**-points

- `spectrum_single_k` now handles case where a *single* **k**-point is provided and `spectrum` is strictly for *multiple* of **k**-points
- by splitting up like this, we also enable the introduction of convenience method for 1D models, using `spectrum(..., ks)`  with a plain (abstract) vector of real numbers; this is just much nicer in day-to-day use.

Author: thchr

src/SymmetricTightBinding.jl

@@ -41,7 +41,7 @@ export pin_free!
 include("symmetry_analysis.jl")
 export symmetry_eigenvalues
 include("spectrum.jl")
-export spectrum
+export spectrum, spectrum_single_k
 include("gradients.jl")
 export gradient_wrt_hopping
 export TightBindingModelHoppingGradient

src/spectrum.jl

@@ -1,11 +1,18 @@
 """
-    spectrum(ptbm::ParameterizedTightBindingModel, ks; transform = identity)
+    spectrum(ptbm::ParameterizedTightBindingModel{D, S}, 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.
+bands. If `S == HERMITIAN`, the element types (energies) are `Float64`, and otherwise
+`ComplexF64`.
+
+## Arguments
+- `ptbm`: a [`ParameterizedTightBindingModel`](@ref) to evaluate the spectrum of.
+- `ks`: An iterable of momenta. Each such momentum `ks[i]` must evaluate to a real
+  `D`-dimensional abstract vector. If `D = 1` (1D models), `ks` can also be any abstract
+  vector of real numbers.
 
 ## Keyword arguments
 
@@ -50,19 +57,30 @@ function spectrum(
     ResultType = S === HERMITIAN ? Float64 : ComplexF64
     Es = Matrix{ResultType}(undef, length(ks), ptbm.tbm.N)
     for (i, k) in enumerate(ks)
-        es = spectrum(ptbm, k; transform)
+        es = spectrum_single_k(ptbm, k; transform)
         @inbounds Es[i, :] .= es
     end
     return Es
 end
 
+# if the model is 1D (D==1), we also provide a convenience method that allows passing a
+# any abstract vector of real numbers, each an interpreted as independent momentum point
+function spectrum(
+    ptbm::ParameterizedTightBindingModel{1, S},
+    ks::AbstractVector{<:Real},
+    transform::F = nothing
+) where {S, F}
+    ks = [[k] for k in ks]
+    return spectrum(ptbm, ks; transform)
+end
+
 """
-    spectrum(ptbm::ParameterizedTightBindingModel, k::AbstractVector{<:Real})
+    spectrum_single_k(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`.
 """
-function spectrum(
+function spectrum_single_k(
     ptbm::ParameterizedTightBindingModel{D, S},
     k::AbstractVector{<:Real};
     transform::F = nothing

test/gradients.jl

@@ -74,12 +74,12 @@ using LinearAlgebra
 
         # verify via finite differences: ∂Eₙ/∂cᵢ ≈ [Eₙ(c+εeᵢ) - Eₙ(c-εeᵢ)] / 2ε
         ε = 1e-8
-        Es_ref = spectrum(ptbm, k)
+        Es_ref = spectrum_single_k(ptbm, k)
         for i in 1:length(cs)
             cs₊ = copy(cs); cs₊[i] += ε
             cs₋ = copy(cs); cs₋[i] -= ε
-            Es₊ = spectrum(tbm(cs₊), k)
-            Es₋ = spectrum(tbm(cs₋), k)
+            Es₊ = spectrum_single_k(tbm(cs₊), k)
+            Es₋ = spectrum_single_k(tbm(cs₋), k)
             dEs_fd = (Es₊ .- Es₋) ./ (2ε)
             dEs_analytic = [∇Es[n][i] for n in 1:tbm.N]
             @test dEs_analytic ≈ dEs_fd  atol=1e-5

test/pg_tb_hamiltonian.jl

@@ -69,8 +69,8 @@ using LinearAlgebra
         # C₄ symmetry: H(k₁,k₂) and H(k₂,-k₁) should have same spectrum
         k = [0.1, 0.3]
         k_rot = [0.3, -0.1] # C₄ rotation in reciprocal space
-        es = spectrum(ptbm, k)
-        es_rot = spectrum(ptbm, k_rot)
+        es = spectrum_single_k(ptbm, k)
+        es_rot = spectrum_single_k(ptbm, k_rot)
         @test es ≈ es_rot  atol=1e-10
     end
 

test/spectrum.jl

@@ -13,7 +13,7 @@ using LinearAlgebra
 
     @testset "Single k-point" begin
         k = [0.2, -0.1]
-        es = spectrum(ptbm, k)
+        es = spectrum_single_k(ptbm, k)
         @test length(es) == 2  # 2 bands
         @test issorted(es)     # eigenvalues sorted
 
@@ -30,14 +30,14 @@ using LinearAlgebra
 
         # verify consistency with single-k method
         for (i, k) in enumerate(ks)
-            @test Es[i, :] ≈ spectrum(ptbm, k)
+            @test Es[i, :] ≈ spectrum_single_k(ptbm, k)
         end
     end
 
     @testset "Transform keyword" begin
         k = [0.0, 0.0]
-        es = spectrum(ptbm, k)
-        es_sq = spectrum(ptbm, k; transform=x->x^2)
+        es = spectrum_single_k(ptbm, k)
+        es_sq = spectrum_single_k(ptbm, k; transform=x->x^2)
         @test es_sq ≈ es.^2
 
         ks = [[0.0, 0.0], [0.5, 0.0]]
@@ -47,11 +47,30 @@ using LinearAlgebra
 
     @testset "Graphene Dirac point" begin
         # at K = (1/3, 1/3), graphene should have a degeneracy
-        es_K = spectrum(ptbm, [1/3, 1/3])
+        es_K = spectrum_single_k(ptbm, [1/3, 1/3])
         @test es_K[1] ≈ es_K[2] atol=1e-10
 
         # at Gamma, bands should be split
-        es_Γ = spectrum(ptbm, [0.0, 0.0])
+        es_Γ = spectrum_single_k(ptbm, [0.0, 0.0])
         @test abs(es_Γ[2] - es_Γ[1]) > 1e-1
     end
+
+    @testset "D = 1 convenience method" begin
+        brs_1D = calc_bandreps(2, Val(1))
+        cbr_1D = @composite brs_1D[1]+brs_1D[3] # 2 bands
+        tbm_1D = tb_hamiltonian(cbr_1D, [[0], [1]])
+        ptbm_1D = tbm_1D([0.1, 0.2, -0.3, 0.4, -0.5])
+        # for 1D models, we allow passing a vector of real numbers, each interpreted as
+        # independent momentum points
+        ks_numbers = [0.0, 0.25, 0.5, 0.75]     # ::Vector 
+        ks_points  = [[k] for k in ks_numbers]
+        @test spectrum(ptbm_1D, ks_numbers) ≈ spectrum(ptbm_1D, ks_points)
+
+        ks_numbers_range = range(0, 1/2, 10)    # ::StepRange (an `AbstractVector`)
+        ks_points_range  = [[k] for k in ks_numbers_range]
+        @test spectrum(ptbm_1D, ks_numbers_range) ≈ spectrum(ptbm_1D, ks_points_range)
+
+        # we should still throw an informative error if we try to do this with a D≠1 model
+        @test_throws ErrorException spectrum(ptbm, ks_numbers)
+    end
 end