API reference

Place Rin (Cartesian) in the Wigner–Seitz cell around the origin; return the equivalent integer lattice shifts (multiples of mp_grid) and their degeneracy.

Interpolated k-space data shared by all Fermi levels at one k: E, U, A, Ω̄, rotated velocity.

Canonical b-slot map: slot[b,q] = index b₀ with bvec(:,b₀,1) == bvec(:,b,q) (tol 1e-7).

Detect the higher-order structure of the k=1 b-vector list, independent of ordering: each b is assigned the integer multiple m of the shortest vector parallel to it in the list. Returns (N, mult) where mult[b] is that multiple and N = maximum(mult); a standard mesh gives N = 1. Errors if the multiples are not a complete 1..N per direction (not a Lihm mesh).

Read one record's payload, verifying the int32 length markers.

ws-aware operator interpolation O(k) from O(R) (shared by all SHC operators).

Centres and spread from the weighted half-set matrices (wannomegagamma). Returns (rave, spreadsn, omd, omod, omtot); om_i is the frozen first-pass invariant.

One Jacobi sweep over all (nw1 < nw2) pairs (internalnewuandm_gamma, ported verbatim).

tildeΩ(ω) for band n: −Σ{m≠n} 2 Im[Aα(n,m)Aβ(m,n)]·Re[wmn²/(w_mn²−ω²)] (TAS17 Eq. 12).

Central-difference weight factor for the m-th multiple in an order-N scheme.

Occupied-manifold curvature (J0+J1+J2, Ų) at one Fermi level from shared k-data.

Per-k LVTS12 trace triple (imf, img, imh), each the J0+J1+J2 sum per axial component.

Interpolate everything the imfgh traces need at one k (shared across occupation choices).

True iff fractional k is inside any (centre_frac, radius) sphere (2π reciprocal metric).

Levenshtein edit distance (for did-you-mean suggestions).

Little-group symmetry indices of irreducible point ir (those fixing its representative k).

_localize_gamma(U0, Mrot0, bv; num_iter, conv_tol, conv_window) -> WannieriseResult

wannier90's gamma_only localiser: real-orthogonal Jacobi sweeps on the half b-set. U0 must be real-valued (the Löwdin projection of real Γ data is); Mrot0 is the expanded closed set, of which the first half is the file half. The returned gauge is real.

Per-k morb integrand: img + imh − 2E_F·imf (J0+J1+J2 summed), Wannier-gauge traces.

Löwdin orthonormalisation of a square matrix: U = W·V† from the SVD A = W·Σ·V†.

Parse a unit_cell_cart block into a 3×3 matrix whose columns are the lattice vectors (Å).

Parse a kpoints block (fractional coordinates, one k-point per row).

Split the raw text of a .win file into scalar key/value pairs and named blocks.

P-matrix contraction: 4 corrected corner values (mutable, since the kernels sort in place).

Subset of sym whose Cartesian rotations S satisfy Ω(Sk)=det(S)·S·Ω(k) for the axial field.

Expanded (pw90) R-set: the union of all per-pair minimal-image vectors R+T from a ws_translate_dist table (reference irvec_pw90). Falls back to the plain WS set when wsdist === nothing.

postw90's kuboeigvalmax default: the frozen-window top + 2/3, else max eigenvalue + 2/3.

The postw90 Fermi-level list: fermienergy, or fermienergy_min/max(/step).

kubo/gyrotropic-style frequency list from <prefix>_freq_min/max/step.

Parse key = n or key = n1 n2 n3 into an NTuple{3,Int} k-mesh.

Read a Fortran-unformatted .uHu (sequential records, 4-byte length markers).

Scatter O(R)/(ndegen·ndeg) onto the expanded R-set (reference operator_wigner_setup). The result is interpolated with a plain phase sum — no further degeneracy handling.

js (Qiao/QZYZ18 Eq. 23): B = ∂εm·S + εm·K − L (column m), js = (B + B†)/2.

js (Ryoo/RPS19 Eqs. 21, 26, 37–40): ½{σ,v} from S, SAA, SBB and the full bar velocity.

Band-resolved SHC k-term ωn = Ω^{spin γ}{n,αβ}(k) (Ų, no occupation factor) and energies.

Common per-k SHC data: kd, band energies/velocities, Dh, AAβ, and the js matrix.

Build an SLWF from the .win keywords (slwfnum/slwfconstrain/slwflambda/slwfcentres), or nothing.

Pauli expectation matrices Sh[j] = U†Sj(k)U (full matrices, j = x,y,z).

Diagonal ⟨σ·n̂⟩ in the eigenbasis U at k (spin axis from polar/azimuth angles in degrees).

k-averaged diagonal overlaps M̄nn(b) in the uniform b-order (numwann × nntot).

Symmetrise the disentanglement subspace embeddings (uniform window) using the band representation dband and the Wannier representation dwann of a Sitesym.

Validate parsed keys/blocks against the reference catalogue; error on typos.

Gaussian delta representation: w0gauss(x, 0) = e^{−x²}/√π.

gfortran-style date/time pair, e.g. (" 4Jul2026", "19:40:52").

Write a Wannier-centres-and-spreads block (used for both Initial and Final State).

Write the b-vector shell / weight report block.

Fold a fractional k-point into [0,1)³ (numerical tolerance tol).

Write one record with framing.

Column-major 6F12.6 block writer (the reference's (6F12.6) format).

ahc_fermiscan(bm; fermi_energies, kmesh, adpt_kmesh=1, adpt_thresh=100.0) -> Matrix

AHC (S/cm) for a list of Fermi energies (3 × nf matrix), with postw90's adaptive k-mesh refinement: any coarse point whose curvature norm exceeds adpt_thresh (Ų) at some Fermi level is re-evaluated on an adpt_kmesh³ sub-mesh centred on it (replacing the coarse value for the triggered levels only). adpt_kmesh = 1 disables refinement.

anomalous_hall(bm; fermi_energy, kmesh) -> SVector{3,Float64}

Intrinsic anomalous Hall conductivity (S/cm, axial components x/y/z) as the Berry-curvature average over a uniform kmesh (postw90's berry_task = ahc with no adaptive refinement).

anomalous_hall_sym(bm, sym; fermi_energy, kmesh) -> (ahc, ninfo)

Anomalous Hall conductivity (S/cm, axial x/y/z) computed on the irreducible wedge of kmesh under sym and symmetrised — the Berry curvature is a pseudovector, so each irreducible point contributes w · (1/|G|) Σ_s det(R_s)·R_s·Ω(k). Equal to the full-BZ [anomalous_hall] but evaluates only the irreducible k-points. ninfo = (n_irreducible, n_full).

Apply gauge rotation R[:,:,k] in place: U ← U·R and M̃{k,b} ← Rk† M̃{k,b} R{k+b}.

bands(H::TBOperator, kpts) -> energies

Interpolated eigenvalues (num_wann × npts, ascending per column) of a 1-component operator.

berry_curvature_k(bm, kfrac, fermi_energy) -> SVector{3,Float64}

Occupied-manifold Berry curvature −2 Im f(k) (Ų, axial components yz/zx/xy) at one fractional k-point, as the J0+J1+J2 sum.

boltzwann(bm; kmesh, relax_time, mus, temps, tdf_energy_step=0.001,
          tdf_smr_width=0.0, win=nothing, elec_per_state=2) -> BoltzWannResult

Transport distribution function and RTA transport tensors. relax_time in fs; win is the (emin, emax) band-energy window (defaults to the eigenvalue range of H(R)'s source bands as postw90 uses the disentanglement window — pass it explicitly for parity).

build_bvectors(kgrid, lattice, kpb, gpb; kmesh_tol) -> BVectors

Compute Cartesian b-vectors for the given neighbour connectivity and solve the B1 relation for the per-shell finite-difference weights. Verifies completeness and errors if it is not met. Higher-order (higher_order_n) meshes are detected from the block structure of the b-list.

build_hr(U, eig, kgrid, irvec) -> (Hr, Hk)

Wannier-gauge Hamiltonian in reciprocal space Hk[:,:,k] = U_k† diag(ε_k) U_k and its Fourier transform to real space Hr[:,:,R] (undivided by ndegen). U is (numwann × numwann × nkpt), eig is (numbands × nkpt) with numbands == num_wann for the isolated case.

build_nnlist(kfrac, lattice, cells, dnn, shell_list, multi; tol)
    -> (nnlist, nncell, nntot)

Per-k neighbour list in the reference's exact deterministic order (shell-major, then distance-sorted supercell cells, then k₂ ascending; early exit per filled shell). Port of kmesh.F90:423-450. nnlist[k, nn] is the neighbour k-index, nncell[:, k, nn] the reciprocal-lattice fold G.

Unit-cell volume (Ų·Å = ų).

cubic_point_group() -> SymmetryOps

The 48 operations of the cubic point group Oₕ as Cartesian 3×3 matrices (all signed 3×3 permutation matrices), with zero translation. Useful as a symmetry source for cubic crystals when no .sym file is available; the magnetic subgroup of a given quantity can be filtered from it numerically.

density_of_states(bm; energies, kmesh, adaptive=true, adpt_fac=√2, adpt_max=1.0,
                  smr_width=0.0, spin=nothing, project=nothing, polar=0.0, azimuth=0.0,
                  elec_per_state=2) -> (energies, dos[, dos_up, dos_dn])

DOS on the energy grid (eV). With spin (a SpinModel), also returns the spin-decomposed DOS (pass elec_per_state = 1 for spinor calculations, as postw90 enforces). With project (WF indices), the DOS is projected onto those Wannier functions.

density_of_states_sym(bm, sym; energies, kmesh=(25,25,25), kwargs...) -> (es, dos, ninfo)

DOS over the irreducible wedge: the integrand is a scalar, so the representatives only carry their star weights. Accepts the same smearing options as [density_of_states].

dis_extract_symmetry!(U, Z, s, ik, n) -> λ

Constrained ΩI step at irreducible representative ik (the reference's `sitesymdisextractsymmetry): steepest-descent on the subspace embeddingU(n × num_wann) alongΔU = Z·U − U·λwithλ = U†ZU, maximising the Rayleigh quotient band-by-band in the 2-dimensional span {u_i, Δu_i} (generalized 2×2 eigenproblem, larger eigenvalue), then re-projecting onto the symmetric manifold each sweep. Returns the finalλ` — its real trace is the k-point's Z-eigenvalue-sum surrogate for the Ω_I bookkeeping.

Lock frozen bands into U_opt (SMV Eq. 27): project the trial subspace onto the non-frozen space.

dis_project(Awin, wd) -> U_opt

Initial optimal-subspace embedding per k from the trial projections (SMV Sec. III.D), then lock the frozen states (SMV Eq. 27) when a frozen window is present.

dis_windows(eig, num_wann; win_min=-Inf, win_max=Inf, froz_min=-Inf, froz_max=nothing)
    -> WindowData

Select the outer (win_min/win_max) and frozen (froz_min/froz_max) energy windows per k-point (all in eV). A frozen window exists iff froz_max !== nothing. Assumes eig[:,k] ascending.

dis_windows_proj(eig, A, num_wann; win_min, win_max, froz_min=-Inf, froz_max=nothing,
                 proj_min, proj_max) -> WindowData

PDWF (projectability-disentangled) window selection (Qiao–Pizzi–Marzari 2023): partition the bands inside the outer energy window by projectability p_nk = Σ_w |A_nw(k)|². States with p ≥ proj_max (or in the energy frozen window, if given) are frozen; proj_min ≤ p < proj_max are the disentanglement pool; p < proj_min are discarded from the window entirely (so the window is generally non-contiguous). Expects (quasi-)orthonormal .amn columns (0 ≤ p ≤ 1).

Compat method: pull the windows and iteration controls from a parsed .win.

disentangle(model; win_min=-Inf, win_max=Inf, froz_min=-Inf, froz_max=nothing,
            num_iter=200, mix_ratio=0.5, conv_tol=1e-10, conv_window=3,
            verbose=false) -> DisentangleResult

Full SMV disentanglement: window selection, projection + frozen locking, Z-matrix subspace iteration, subspace-Hamiltonian diagonalisation, and handoff to the localiser. Windows are in eV; a frozen window exists iff froz_max is given. The defaults (no windows) disentangle over all num_bands states.

The disentangle(model, win::WinInput) method pulls all of these from a parsed .win instead.

Light per-k interpolation: eigenvalues and (optionally) their Cartesian derivatives (eV·Å).

As eig_deleig, additionally returning the eigenvector matrix U (WF row, band column).

Per-k anti-Hermitian generators → per-k unitary rotations.

exp of an anti-Hermitian matrix X, via the Hermitian eigendecomposition of i·X.

fortran_g(x, w, d) -> String

Fortran Gw.d edit descriptor: numbers with 0.1 ≤ |x| < 10^d (after rounding to d significant digits) print as F(w-4).(d-n) followed by four blanks (n = digits before the point, 0 for |x| < 1); everything else falls back to Ew.d.

O(R) = (1/Nq) Σq e^{−i2πq·R} O(q) on a given R-set (one nw×nw×nk operator stack).

fourier_to_R(Ok, kgrid, irvec) -> OR

Generic k→R transform of a matrix-valued operator: OR[:,:,ir,c] = (1/N_k) Σ_k e^{-i2πk·R} Ok[:,:,k,c]. Ok is (nw × nw × nkpt × ncomp).

gauge_v_windows(chk, nb) -> (vs, winidx)

Per-q windowed gauge matrices v(q) = U_opt·U (ndimwin(q) × nw rows of the window) and the window band indices, shared by every postw90-style operator assembly (A/B/C, spin, sHu/sIu). For non-disentangled runs v = U on all nb bands.

generate_kpath(win, lattice; bands_num_points=100) -> (kpts, xvals, labels, label_idx)

Sample the kpoint_path block of a .win in segment mode: each segment gets a point count proportional to its length (the first segment gets bands_num_points), linearly interpolated in fractional coordinates. xvals is the cumulative Cartesian path length (Å⁻¹). labels/label_idx mark the special points for axis ticks.

write_nnkp(seedname_or_win; out=...) — the `-pp` mode

Generate the k-mesh from seedname.win alone (shell search + B1 weights + neighbour list, no .mmn required) and write seedname.nnkp for the DFT interface. Returns the output path.

geninterp(bm, seedname; alsofirstder=true) -> path

Run generalised interpolation: read seedname_geninterp.kpt, interpolate En(k) (and dE/dk when alsofirstder), write `seednamegeninterp.dat` in the postw90 format.

gyrotropic(m; tasks, fermi_energies, freqs=[0.0], kmesh, smr_width,
           box=I, box_corner=zeros(3), smr_max_arg=5.0, degen_thresh=0.0,
           band_list=nothing, eigval_max=Inf, spin=nothing) -> NamedTuple

Gyrotropic responses on a uniform grid over the fractional box spanned by the rows of box from box_corner. tasks ⊆ (:D0, :Dw, :C, :K, :NOA, :dos); :K needs a MorbModel (.uHu), the others a BerryModel; a SpinModel in spin adds the spin parts of K and NOA. Frequencies are broadened internally as ω + i·smr_width (the same η that smears the Fermi-surface delta — Gaussian, as postw90's default smearing type). Returns (; fermi_energies, freqs, D, Dw, C, K_orb, K_spn, NOA_orb, NOA_spn, dos) in the reference units (D/tildeD dimensionless, C A/cm, K A, NOA Å, DOS eV⁻¹Å⁻³); tensors are indexed [velocity_dir, quantity_dir, ifermi(, ifreq)], NOA as [ab_axial, c, ifermi, ifreq].

hamiltonian_operator(model, result) -> TBOperator

The interpolable Hamiltonian H(R) from a wannierisation result (isolated or disentangled).

hr_diagonal(Hr, irvec, ndegen) -> Vector{Float64}

The on-site Hamiltonian matrix elements ⟨0n|H|0n⟩ (eV) = real diagonal of H(R = 0) / ndegen.

initial_gauge(A) -> U

Per-k Löwdin gauge for the whole model. A is (numbands × numwann × num_kpts); returns U of the same shape.

initial_spread(model) -> SpreadResult

Wannier centres and spread of the initial (Löwdin-projected) gauge — the "Initial State" that Wannier90 reports before any localisation iteration.

injection_current(bm; freqs, fermi_energy, kmesh, smr_width=0.1) -> Array{Float64,4}

Circular injection-current tensor ηabc(ω) (3×3×3 × nfreq), on a Γ-centred kmesh, matching the WannierBerri InjectionCurrent calculator (Gaussian smearing `smrwidth). Needs aBerryModelwith the Berry connection A(R) (from.mmnor a_tb.dat`).

install_cli(; dir = joinpath(first(DEPOT_PATH), "bin"), julia_flags = String[]) -> Vector{String}

Write launcher scripts wannier90.jl, postw90.jl, and w90chk2chk.jl into dir (created if needed; default ~/.julia/bin) so the drop-in binaries are available to pkg> add-installed copies of the package, where the repository's bin/ directory is not at hand. Returns the paths written.

Each launcher runs julia --project=<current active project>, i.e. the environment install_cli was called from — the one that has WannierFunctions installed. Re-run after moving that environment. Extra flags for the julia invocation (e.g. ["-t", "auto"]) can be baked in via julia_flags.

Add dir to your PATH if it is not already on it; the function prints a hint when needed. On Windows, .cmd wrappers are written alongside the Unix ones.

interpolate(model, result, kpts; use_ws_distance=false) -> energies

Interpolate band energies (numwann × npts) at fractional k-points kpts, using the wannierised gauge and (subspace) eigenvalues in result. Requires `result.eiginterp !== nothing. Withusewsdistance=true` the per-Wannier-pair minimal-image improvement (the reference default) is applied — slightly more accurate near cell boundaries.

interpolate_bands(Hr, irvec, ndegen, kpts) -> eigs

Interpolated band energies (num_wann × npts, ascending per column) at fractional k-points kpts.

interpolate_bands_ws(Hr, irvec, ndegen, centres, lattice, mp_grid, kpts) -> eigs

Band interpolation with the use_ws_distance=.true. minimal-image improvement (the reference default). centres are the (3 × num_wann) Cartesian Wannier centres.

interpolate_hk(Hr, irvec, ndegen, kfrac) -> H

Interpolated Wannier-gauge Hamiltonian at a single fractional k-point kfrac (numwann × numwann, Hermitian).

Interpolated H(k') with the per-pair minimal-image (ws_distance) weighting.

kdotp(bm; kpoint=[0,0,0], bands) -> (; T0, T1, T2)

k·p coefficient matrices around fractional kpoint for the interpolated-band indices bands. T0 is nA×nA (eV), T1[a] nA×nA (eV·Å), T2[a,b] nA×nA (eV·Å²), all in the H(k) eigenbasis.

Largest reciprocal-mesh spacing maxi |bi|/Ni (postw90's kmeshspacing).

kpath(m; segments, num_points=100, tasks=(:bands,), bands_colour=:none, fermi_energy=nothing,
      curv_unit=:ang2, polar=0.0, azimuth=0.0, spin=nothing,
      γ=3, α=1, β=2, smr_width=0.0, eigval_max=Inf) -> NamedTuple

Quantities along a high-symmetry path. m is the model matching the most demanding task: a BerryModel (bands, curv), MorbModel (morb + curv), or ShcModel (shc / shc colouring); spin supplies a SpinModel for bands_colour = :spin. Returns (; kpts, xvals, bands, colour, curv, morb, shc) with postw90's conventions: curv is the negative Berry curvature (Ų, or bohr² with curv_unit = :bohr2), morb the LVTS12 integrand −(G + H − 2EF·F)/2 in eV·Ų (never unit-converted), shc the k-resolved Ω^{spin γ}{αβ} Fermi sum. SHC quantities use fixed smearing smr_width (as the reference requires along a path).

kpath_points(segments, lattice; num_points=100) -> (kpts, xvals)

Reference path construction: segment 1 gets num_points samples, segment p gets nint(num_points·len_p/len_1); each segment is sampled at fractions (i−1)/n_p (interior vertices appear once, as the next segment's first point) and one final point closes the path. xvals reproduce postw90's accumulation: the increment is always the current segment's step, and only the final value is forced to the exact total length (so interior-vertex x-coordinates differ slightly from the cumulative segment lengths — this matches the reference files).

Parse the kpoint_path block of a .win into (start, end) fractional segment tuples.

kslice(m; corner, b1, b2, mesh=(50,50), fermi_energy=nothing, tasks=(:bands,),
       curv_unit=:ang2, γ=3, α=1, β=2, smr_width=0.0, eigval_max=Inf, curvature=false)
    -> (; kpts, coords, bands, curv, morb, shc)

Grid k(i,j) = corner + (i/N1)·b1 + (j/N2)·b2 (fractional; i = 0..N1 fastest). coords are the 2-D Cartesian coordinates in the slice plane (Å⁻¹). m is a BerryModel (bands, curv), MorbModel (morb), or ShcModel (shc). Conventions match postw90's kslice files: curv is −(J0+J1+J2), morb the LVTS12 integrand −(G + H − 2EF·F)/2 in eV·Ų, shc the fermi-summed Ω^{spin γ}{αβ} with fixed smearing smr_width. curvature=true is a legacy alias for adding :curv to tasks.

σA(i,j,ω) = Re[(AHij−AHji)/2] + i·Im[(Hij−H_ji)/2] — the antisymmetric combination.

σS(i,j,ω) = Re[(Hij+Hji)/2] + i·Im[(AHij+AH_ji)/2] — the symmetric output combination.

localize(U0, Mrot0, bv; num_iter=100, algorithm=:rcg, kwargs...) -> WannieriseResult

Run the spread minimisation from an initial square gauge U0 (numwann × numwann × nkpt) and its gauge-rotated overlaps Mrot0. Shared by the isolated-bands path (wannierise) and the post-disentanglement handoff. Ω_I is invariant under this step.

algorithm:

• :rcg — Riemannian Polak–Ribière+ conjugate gradient on the product-of-unitaries manifold, parabolic-model line search with Armijo backtracking safeguard, convergence when |ΔΩ| stays below conv_tol (default 1e-10 Ų) for conv_window (default 3) iterations. Modern default.
• :w90 — the reference Wannier90 minimiser, reproduced exactly (Fletcher–Reeves CG, parabolic line search, fixed sweep count with convergence checking off unless conv_window > 1). Use for bit-faithful parity with wannier90.x.

lowdin(A) -> U

Löwdin-orthonormalised gauge from an (numbands × numwann) projection block: the closest isometry to A in Frobenius norm, U = V W† where A = V Σ W†.

main(seedname; pp=false, write_files=true, verbose=true) -> (model, win, result)

Run wannierisation for seedname and write .wout plus, when requested in the .win, _hr.dat (write_hr/hr_plot), _tb.dat (write_tb), and the band-structure files (bands_plot). Returns the model, parsed input, and result.

With pp=true (the -pp flag, or postproc_setup = .true. in the .win) only the post-processing setup runs: the k-mesh is generated from the .win alone and seedname.nnkp is written for the DFT interface. No .amn/.mmn needed.

−∂f/∂ε of the Fermi function (1/eV), with the reference's overflow cutoff.

omega_gradient(Mrot, bv, centres) -> G

Analytic gradient dΩ/dW as the anti-Hermitian matrix G[:,:,k], following wann_domega: G = (4/N_k) Σ_{k,b} w_b ( A[R] − S[T] ) with R_{mn}=M_{mn}·conj(M_nn), R̃_{mn}=M_{mn}/M_nn, q_n = Im ln M_nn + b·r_n.

ΩI of the current subspaces: (1/Nk) Σk Σb wb (numwann − Σ{mn}|⟨wm,k|w_n,k+b⟩|²).

optical_conductivity(bm; fermi_energy, kmesh, freqs=0.0:0.01:..., eigval_max=Inf,
                     adaptive=true, adpt_fac=√2, adpt_max=1.0, smr_width=0.0,
                     ) -> KuboResult

Interband optical conductivity σ(ħω) and JDOS on a uniform k-mesh, with postw90's defaults (Gaussian broadening; per-pair adaptive width from the band-velocity difference).

orbital_magnetisation(mm; fermi_energy, kmesh) -> SVector{3,Float64}

Orbital magnetisation (μ_B per cell, x/y/z) from the LVTS12 trace formulas on a uniform k-mesh (no adaptive refinement, matching postw90).

orbital_magnetisation_sym(mm, sym; fermi_energy, kmesh=(25,25,25)) -> (M, ninfo)

Orbital magnetisation over the irreducible wedge: the LVTS12 integrand is a pseudovector like the Berry curvature, so each irreducible representative contributes w · (1/|G|) Σ_s det(R_s)·R_s·m(k). Equal to the full-BZ [orbital_magnetisation] but evaluates only the irreducible k-points. ninfo = (n_irreducible, n_full).

Parse the atomsfrac / atomscart block into (species, fractional site) pairs.

parse_exclude_bands(win) -> Vector{Int}

Parse the exclude_bands range list (exclude_bands = 1-4,10) into a sorted index list.

Parse a Fortran-style float, tolerating d/D exponent markers (e.g. "17.0d0").

parse_projections(win) -> Vector{Projection}

Parse the projections block: Species:orb[;orb2...], f=x,y,z:orb, or c=x,y,z:orb sites (a species expands to every atom of that species, in atoms-block order). Default z-axis (0,0,1), x-axis (1,0,0), zona 1.0, radial 1 — the reference defaults.

Parse a Wannier90 range-vector string ("1-4,6") into a sorted index list.

plot_wannier_functions(model, win, result; seedname, dir) -> paths

Assemble and write seedname_0000n.xsf for each WF in wannier_plot_list (default: all). Honours wannier_plot_supercell. Only the formatted-UNK, xsf, crystal-mode path is implemented (wannier_plot_format = cube is not yet supported).

position_operator(model, result) -> TBOperator

The position operator ⟨0m|r|Rn⟩ (3 Cartesian components, Å) from the final-gauge overlap matrices, using the finite-difference Berry-connection formula the reference uses in _tb.dat: off-diagonal i w_b b M̃_mn (Wang–Yates–Souza–Vanderbilt PRB 74, 195118 (2006), Eq. 44) and diagonal −w_b b Im ln M̃_nn (Marzari–Vanderbilt PRB 56, 12847 (1997), Eq. 32), then Fourier k→R.

postw90_main(seedname; verbose=true)

Drop-in postw90.x: dispatch every module requested in seedname.win (berry tasks ahc/morb/kubo/sc/shc/kdotp, gyrotropic, dos, kpath, kslice, geninterp, boltzwann, spin_moment) and write the reference-named output files.

read_amn(path) -> (A, num_bands, num_kpts, num_wann)

A[m,n,k] is (numbands × numwann × numkpts) complex. File layout: comment line; `numbands numkpts numwann; then num_bands·num_wann·num_kpts recordsm n k Re Im`.

read_chk(path) -> Checkpoint

Read a Wannier90 binary checkpoint (seedname.chk).

read_chk_fmt(path) -> Checkpoint

Read a formatted checkpoint (seedname.chk.fmt, as produced by w90chk2chk.x -u2f).

read_dmn(path, num_bands, num_wann) -> Sitesym

Read a seedname.dmn (formatted, list-directed). Line 2 is num_bands nsym nkptirr num_kpts; then ik2ir (numkpts), ir2ik (nkptirr), kptsym (nsym×nkptirr, isym fastest), `dwann(nw²×nsym×nkptirr, complex, i fastest),d_band` (nb²×nsym×nkptirr, complex).

read_eig(path) -> eig

eig[m,k] (numbands × numkpts), eV. Each line: band_index kpt_index energy.

read_geninterp_kpt(path) -> (comment, idx, kpts)

Read a seedname_geninterp.kpt file: comment line, coordinate flag (crystal/frac), count, then index kx ky kz per line.

read_hr(path) -> (num_wann, irvec, ndegen, Hr)

Inverse of write_hr. Parses by tokenizing (never by column slicing): header line skipped, then num_wann, nrpts, the (15I5) ndegen block, then the matrix rows. Returns Hr[j,i,irpt] = Re + im*Im (undivided by ndegen).

read_ht(path) -> (H00, H01)  — read a `seedname_htB.dat`.

read_mmn(path) -> (M, kpb, gpb, num_bands, num_kpts, nntot)

M[m,n,b,k] is (numbands × numbands × nntot × numkpts). kpb[b,k] is the neighbour k-index and gpb[:,b,k] its reciprocal-lattice fold. File layout: comment line; `numbands numkpts nntot`; then numkpts·nntot blocks, each a line k kb g1 g2 g3 followed by num_bands² records Re Im with the row index m varying fastest.

read_model(seedname) -> Model

Load a full wannierisation problem from seedname.win, seedname.amn, seedname.mmn, and (if present) seedname.eig. Builds the lattice, k-grid, and B1 neighbour weights.

read_shu(path; num_bands, num_kpts, nntot) -> X

Read a Fortran-unformatted .sHu or .sIu (identical layout): X[m, n, s, b, ik] = ⟨u_mk|σ_s H_k|u_n,k+b⟩ (.sHu) or ⟨u_mk|σ_s|u_n,k+b⟩ (.sIu), with b running in .mmn neighbour order. On disk each record is a ket-fastest nb×nb matrix that must be transposed (pw2wannier90 convention, as postw90 does on read).

read_spn(path; num_bands, num_kpts) -> spn

Read a formatted .spn: spn[n, m, ik, s] = ⟨ψ_n|σ_s|ψ_m⟩ (s = x,y,z), stored lower-triangular (n ≤ m) with Hermitian completion.

read_sym(path) -> SymmetryOps

Read a seedname.sym: line 1 = number of operations; then, per operation, three rows of the 3×3 rotation matrix followed by one row of the 3-vector fractional translation (blank lines between blocks are ignored).

read_tb(path) -> (lattice, num_wann, irvec, ndegen, Hr, pos)

Read a seedname_tb.dat: the lattice vectors (Å), the Wannier Hamiltonian Hr[j,i,ir] = ⟨0j|H|R i⟩, and the position operator pos[j,i,ir,α] = ⟨0j|rα|R i⟩ (Å). Inverse of [`writetb`](@ref).

read_uhu(path; num_bands, num_kpts, nntot) -> uHu

Read a .uHu file: uHu[m, n, b1, b2, q] = <u_{m,q+b1}|H_q|u_{n,q+b2}> (the transpose applied on read, as the reference does for pw2wannier90's ordering). Formatted and Fortran-unformatted files are distinguished automatically.

read_unk(path) -> (ng, ik, u)

Read a formatted UNK file: ng = (ngx, ngy, ngz), the k-index ik, and u[npoint, band] with the x-fastest linear index npoint = nx + (ny−1)ngx + (nz−1)ngx·ngy.

read_win(path; strict=true) -> WinInput

Parse a Wannier90 .win input file. Only the parameters needed for wannierisation and interpolation are promoted to typed fields; the remainder stay in raw/blocks.

Unknown keywords (not in the reference wannier90 parser's catalogue) are an error with a did-you-mean suggestion — a silently ignored typo like num_itre is worse than a hard stop. Recognised-but-unsupported keywords warn once and are ignored. Pass strict=false to downgrade unknown-keyword errors to warnings.

Real orthonormal basis of the column span of a (numerically conjugation-closed) complex embedding; errors if the span is not real. Used to realify the Γ disentangled subspace.

After disentanglement the gauge is square (numwann): the band representation is replaced by the Wannier one for the localisation phase (the reference's `sitesymreplacedmatrix_band`).

rotate_overlaps(M, U, kpb) -> Mrot

Rotate the band-space overlaps into the Wannier gauge: Mrot[:,:,b,k] = U_k† · M[:,:,b,k] · U_{k+b}, shape (numwann × numwann × nntot × num_kpts).

run_transport(model, win, res; seedname) -> (energies, qc, dos)

The .win-driven transport_mode = bulk flow: build H(R) from the wannierised result, translate the WF centres home, assemble the principal layers and scan the energy window, writing _qc.dat / _dos.dat (and _htB.dat with tran_write_ht).

run_wannier(seedname; verbose=false) -> (model, WinInput, WannierResult)

Convenience: read seedname.{win,amn,mmn,eig} and run the full pipeline.

Compat method: drive the pipeline from a parsed .win (reference-faithful :w90 optimiser).

run_wannier(model; win_min=-Inf, win_max=Inf, froz_min=-Inf, froz_max=nothing,
            dis_num_iter=200, dis_mix_ratio=0.5, num_iter=100,
            algorithm=:rcg, verbose=false) -> WannierResult

Keyword-first full pipeline. Disentangles first when num_bands > num_wann (using the given energy windows, eV), then localises. algorithm selects the spread minimiser: :rcg (Riemannian conjugate gradient with a true convergence criterion — the native default) or :w90 (the reference-faithful Wannier90 optimiser, fixed num_iter sweeps).

The run_wannier(model, win::WinInput) / run_wannier(seedname) methods drive everything from a parsed .win instead and default to :w90 for drop-in parity with wannier90.x.

scdm_amn(getu, ng, kfrac, num_bands, num_wann;
         eig=nothing, mode=:isolated, mu=0.0, sigma=1.0) -> A

Array-level SCDM core: getu(k) returns the periodic parts u_mk(r) on the ng real-space grid as an (npts × ≥num_bands) matrix with x fastest (the UNK layout; vec of an ng₁×ng₂×ng₃ array). Used by scdm_projections (UNK files) and by the DFTK extension (in-memory wavefunctions).

scdm_auto(proj, eig; sigma_factor=3.0) -> (; mu, sigma, mu_fit, sigma_fit, rms)
scdm_auto(A,    eig; sigma_factor=3.0) -> (; mu, sigma, mu_fit, sigma_fit, rms)

Fit the SCDM erfc smearing parameters from a projectability-vs-energy curve (Vitale et al., npj Comput. Mater. 6, 66 (2020)), removing the last hand-set numbers from an SCDM-erfc wannierisation.

The first form takes a projectability matrix proj and band energies eig, both num_bands × nkpt (energies in eV). The second computes the projectability itself from an .amn array A (num_bands × num_wann × nkpt) as the diagonal of the orthogonal projector onto each k-point's trial columns, so it works for non-orthonormal trial orbitals.

Returns a named tuple: mu/sigma are the SCDM parameters ready to pass to scdm_projections / wannier_model (mu = mu_fit − sigma_factor·sigma_fit), mu_fit/sigma_fit are the raw erfc fit, and rms is the fit residual (a large value warns that the projectability is not erfc-like — e.g. a manifold not separable in energy).

The fit is only as clean as the projectability. It is designed for pseudo-atomic-orbital projectabilities — the ones Quantum ESPRESSO's atomic_proj/projwfc produce, and what the Vitale protocol assumes — where P(ε) drops monotonically from ≈1 to ≈0. Crude trial orbitals (e.g. a hydrogenic guess that misses the true radial shape, or a valence shell an n ≤ 3 hydrogenic cannot represent) can give a non-erfc cloud and a degenerate fit with a large rms; treat that rms as the honest signal that this projectability is not a good basis for the fit, not as a value to feed onward.

scdm_projections(model; dir, mode=:isolated, mu=0.0, sigma=1.0) -> A

Compute SCDM initial projections from the UNK files in dir. Returns A (numbands × numwann × nkpt), ready to replace model.A (or write with write_amn).

mode:

• :isolated — f ≡ 1 (numbands == numwann or a clean isolated group).
• :erfc — f(ε) = erfc((ε − μ)/σ)/2, for entangled valence-like manifolds.
• :gaussian — f(ε) = exp(−(ε − μ)²/σ²), for selecting bands around μ.

The pivot points are chosen at the k-point closest to Γ (the k-list must contain one). :erfc/:gaussian require band energies (model.eig).

select_shells(kcart, lattice, cells, dnn, multi; kmesh_tol) -> (shell_list, weights)

Automatic shell selection satisfying the B1 relation (kmeshshellautomatic): add shells in distance order, skipping shells parallel to accepted ones (|cosine| within 1e-6 of 1) and rejecting additions that make the design matrix singular (singular value < 1e-5), until Σs ws Σb b⊗b = 1 holds within `kmeshtol`.

shc_fermiscan(sm; fermi_energies, kmesh, γ=3, α=1, β=2, adaptive=true,
              adpt_fac=√2, adpt_max=1.0, smr_width=0.0, eigval_max=Inf)
    -> Vector (per Fermi energy, (ħ/e)·S/cm)

Fermi-scan spin Hall conductivity σ^{spin γ}_{αβ} (QZYZ18 Berry-curvature-like term).

shc_freqscan(sm; freqs, fermi_energy, kmesh, γ=3, α=1, β=2, adaptive=true,
             adpt_fac=√2, adpt_max=1.0, smr_width=0.0, eigval_max=Inf)
    -> Vector{ComplexF64} (per frequency, (ħ/e)·S/cm)

ac spin Hall conductivity σ^{spin γ}{αβ}(ω) on a frequency list (eV), with T = 0 occupations at the single `fermienergy.smis anShcModel(Qiao) orShcRyooModel`.

shc_imjv(sm, kf; γ=3, α=1, β=2) -> (E, imjv)

Band energies and the raw SHC integrand matrix imjv[n,m] = Im[j^{spin γ}_{α,nm}·v_{β,mn}] (no energy denominator, no smearing) at one k — the quantity the tetrahedron method integrates. Equals the per-pair numerator of the Gaussian shc_fermiscan.

shc_tetra(sm; kmesh, fermi_energies=nothing, freqs=nothing, fermi_energy=nothing,
          γ=3, α=1, β=2, cutoff=1e-4, avoid_deg=3e-4) -> Vector

Tetrahedron-method spin Hall conductivity in (ħ/e)·S/cm. Pass fermi_energies for a Fermi scan (ω = 0, real output) or freqs + fermi_energy for a frequency scan (complex output). cutoff = tetrahedron_cutoff, avoid_deg = tetrahedron_avoid_degeneracy.

b-vectors of one shell around k-point 1, in reference discovery order (kmeshgetbvectors).

shell_distances(kcart, lattice, cells; search_shells, tol) -> (dnn, multi)

Distances of the first search_shells neighbour shells of k-point 1 (over all k+G images) and their multiplicities. Port of kmesh.F90:172-199.

shift_current(seedname; kwargs...) -> (; freqs, sc)

Convenience: assemble the BerryModel and centres from seedname.{win,mmn,eig,chk}.

shift_current(bm, centres; fermi_energy, freqs, kmesh, phase_conv=1, sc_eta=0.04,
              w_thr=5.0, eta_corr=true, adaptive=true, adpt_fac=√2, adpt_max=1.0,
              smr_width=0.0, eigval_max=Inf) -> (; freqs, sc)

Shift-current tensor on a uniform frequency grid (freqs must be uniformly spaced, as the reference assumes). centres is the 3×nw matrix of Wannier centres (Å, from the checkpoint) — used by the tight-binding phase convention (phase_conv = 1); phase_conv = 2 is the plain Wannier90 convention. sc is 3×6×nfreq: sc[a, bc, :] = σ_abc with a the current direction and bc packing (xx, yy, zz, xy, xz, yz), in A/V².

Window-slim the eigenvalues, projections A, and overlaps M to window-local indices.

slwf_gradient(Mrot, bv, slwf) -> G

The SLWF+C gradient field (same convention as omega_gradient, ×4/Nk), a verbatim port of wanndomega's selective_loc branch: the standard MV gradient restricted to the selected WF block plus the λ centre-constraint terms. Only elements with m ≤ slwfnum or n ≤ slwfnum are nonzero (the non-selected block is free).

slwf_omega(Mrot, bv, slwf) -> (; ΩC, centres)

The SLWF+C objective Ω_C and the (standard) Wannier centres, from the gauge-rotated overlaps.

spin_expectation(sm, kfrac; polar=0.0, azimuth=0.0) -> (E, spn)

Band energies and per-band ⟨σ·n̂⟩_nk ∈ [−1, 1] at one k-point.

spin_moment(sm; fermi_energy, kmesh=(25,25,25)) -> (; moment, theta, phi)

Total spin magnetic moment (Bohr magnetons per cell) and its polar/azimuthal angles in degrees (postw90 convention: θ = acos(mz/|m|), φ = atan(my/mx) — plain atan, as in pwscf). Occupations are the T = 0 step with strict ε < EF.

Build the uniform-order index maps from the b-vector table.

ss_gradient(Mrot, bv, ss) -> G

Gradient of ΩSS in the reference's cdodq convention (drop-in for `omegagradient`): four M̄-weighted terms over the ±b pairs, divided by N_k.

ss_spread(Mrot, bv, ss) -> SpreadResult

The SS objective and single-point centres. Only Ω (the objective) and centres are meaningful during minimisation; the ΩI/OD/D fields are zeroed — the standard MV decomposition is recomputed at the converged gauge for reporting.

Strip a trailing !/# comment and surrounding whitespace.

supercell_cells(B) -> Vector{NTuple{3,Int}}

The (2·NSUPCELL+1)³ reciprocal-superlattice cells, ordered exactly as the reference: (0,0,0) first, then ascending by |l·b₁+m·b₂+n·b₃|, ties resolved by the reference's extract-max / lowest-index rule (kmeshsupercellsort + internal_maxloc).

SVD/polar orthonormalisation of a rectangular projection block: U = Z·V† (drop singular values).

symmetrize_gradient!(G, s)

Project the numwann gradient field onto the symmetric-gauge tangent space (localisation phase, d = dwann): mode 1 accumulates the star into each representative and zeroes the rest; mode 2 averages over the little group. Applied mode 1 then mode 2, matching the reference.

symmetrize_rotation!(d, s)

Propagate the CG rotation generator from each irreducible representative to its star, d(Rk) = D(R)·d(k)·D(R)†, so applying exp(d) keeps U symmetry-adapted (the representative-k gradient is the only nonzero one after mode-1 gradient symmetrisation).

symmetrize_u!(U, s, dband, dwann; n=size(U,1))

Symmetrise a full gauge stack in place: at each irreducible representative project onto the symmetric subspace, then reconstruct the star via U(Rk) = d(R)·U(k)·D(R)†. U is ndim × num_wann × num_kpts (ndim = n).

symmetrize_ukirr(U0, s, ir, dband, dwann, n) -> U

Project the (leading n×n block of the) gauge U0 at irreducible point ir onto the symmetric subspace: iterate ũ = (1/|G_k|) Σ_{R'∈G_k} d(R')† · U · D(R') then Löwdin-orthonormalise, until convergence. dband/dwann select the representation (numbands / numwann).

symmetrize_zmatrix!(Z, s)

Symmetrise the disentanglement Z matrices across each k-star and little group, Z(k) ← (1/|G_k|) Σ_{R'∈G_k∪1} d†(R') [Σ_star d†(R) Z(Rk) d(R)] d(R'), updating only the irreducible representatives (non-representative entries are never used afterwards). Each distinct star member contributes once, through the first symmetry that reaches it.

tabulate_3d(bm; mesh, colour=nothing) -> (energies, colours)

Tabulate interpolated band energies on a regular (Γ-inclusive, no boundary doubling) 3-D grid k = ((i1-1)/n1, (i2-1)/n2, (i3-1)/n3). energies is nband × n1 × n2 × n3. If colour is a function (bm, kf, E, U) -> Vector{Float64} (one scalar per band), its values are tabulated in the same layout and returned as colours (else nothing). Useful for FermiSurfer surfaces coloured by velocity, spin, or Berry curvature.

tb_model(path; lattice=nothing) -> BerryModel

Load a tight-binding model as a BerryModel. A _tb.dat supplies the lattice and r(R) automatically; a _hr.dat needs the lattice (a Lattice) passed explicitly and yields an H(R)-only model.

tran_green(tot, tott, H00, H01, e; igreen) -> g

Green function at real energy e from the transfer matrices (port of tran_green): igreen = 0 bulk g_nn, 1 surface g00 (right lead), -1 dual surface ḡ00 (left lead).

tran_transfer(H00, H01, ecmp) -> (T, T̄)

López-Sancho/Rubio decimation for the lead transfer matrices at complex energy ecmp (port of tran_transfer; converges quadratically, errors after 50 iterations).

translate_centres_home(centres, lattice, atoms_frac_mean) -> centres

Translate Cartesian WF centres into the home cell centred on the mean atomic position (the reference's internal_translate_centres with automatic_translation): fractional coordinates are shifted into [c̄ − 0.5, c̄ + 0.5).

Translate a Cartesian vector into the home unit cell [0,1)³ (reference utilitytranslatehome).

transport_bulk(H00, H01; win_min=-3.0, win_max=3.0, energy_step=0.01)
    -> (energies, qc, dos)

Landauer conductance T(E) (in units of 2e²/h) and Green-function DOS of the periodic chain with principal-layer blocks H00/H01 (Fermi level already subtracted from H00's diagonal), scanned over win_min:energy_step:win_max — the reference's tran_bulk.

transport_from_tb(lattice, irvec, Hr, centres, mp_grid;
                  one_dim_axis=:z, fermi_energy, dist_cutoff=1500.0,
                  dist_cutoff_mode="one_dim", hr_cutoff=0.0) -> (H00, H01, num_pl)

Assemble the principal-layer blocks from a real-space Wannier Hamiltonian (the reference's tran_reduce_hr + tran_cut_hr_one_dim + tran_get_ht): keep H(R) with R purely along the 1D axis, zero elements beyond dist_cutoff (WF-centre distances, one_dim or full 3D mode), choose the principal-layer size from hr_cutoff decay, and tile H00/H01. The Fermi energy is subtracted from the H00 diagonal.

wannier_function_grid(model, win, result; list, supercell=(2,2,2), dir=".")
    -> (w, ng, los)

Assemble the plotted Wannier functions on the supercell grid. Returns the complex 4-D array w[ix, iy, iz, n] (axes are the supercell grid offsets los[d]:los[d]+ngs[d]*ng[d]-1), the home-cell grid dims ng, and the lower bounds los. UNK files are read from dir.

wannier_model(; unit_cell, kpoints, mp_grid, num_wann, M, A, kpb, gpb, eig=nothing,
              kmesh_tol=1e-6, seedname="model") -> Model

Construct a wannierisation Model from in-memory arrays (the same content as the .win/.mmn/.amn/.eig files, but passed directly):

• unit_cell — 3×3 real lattice, columns = a₁,a₂,a₃ (Å).
• kpoints — vector of fractional k-points; mp_grid — the Monkhorst–Pack dimensions.
• M[b,b′,nn,k] — the .mmn overlaps ⟨u_{b,k}|u_{b′,k+nn}⟩; kpb[nn,k] the neighbour k-index and gpb[:,nn,k] the reciprocal-lattice shift folding k+b back into the list.
• A[b,w,k] — the .amn projections; num_wann the target count.
• eig[b,k] — band energies (eV); nothing for the isolated case with no interpolation.

Feeds run_wannier(model) exactly as a file-read model would.

wannierise(model; num_iter=100, algorithm=:rcg, ...) -> WannieriseResult

Minimise the Wannier spread starting from the Löwdin-projected gauge (isolated-bands case, numbands == numwann). algorithm = :rcg (default) uses Riemannian conjugate gradient with a true convergence criterion (num_iter is a maximum); algorithm = :w90 reproduces the reference Wannier90 optimiser exactly (fixed num_iter sweeps unless conv_window > 1).

wigner_seitz(lattice, mp_grid; ws_search_size=2, tol=1e-5) -> (irvec, ndegen)

Wigner–Seitz lattice vectors (columns of irvec, integer) inside the superlattice cell defined by mp_grid, with degeneracy ndegen for boundary points. Enforces the sum rule ΣR 1/ndegen(R) = ∏ mpgrid.

write_amn(path, A; header)

Write projections in the .amn format (m n k Re Im, band index fastest).

write_band_dat(path, xvals, energies)

Write seedname_band.dat. energies is (nb × nk). For each band b, for each k-point, a line (2E16.8) = xval energy. The reference emits write(*,*) ' ' after every band (including the last), so a trailing blank line is written after each band's block (verified against the reference _band.dat).

write_band_kpt(path, kpts; weight=1.0)

Write seedname_band.kpt: first line the count, then (3f12.6,3x,a) = k1 k2 k3 weight (weight rendered as "1.0" by default, matching the reference).

Write _boltzdos.dat (fixed-width / unsmeared variant; boltzwann.F90:1180).

Write the BoltzWann output set (_tdf/_elcond/_sigmas/_seebeck/_kappa.dat, boltzwann.F90 headers and G18.10 rows). Component order xx xy yy xz yz zz; Seebeck is the full 3×3.

write_bxsf(seedname, lattice, Hr, irvec, ndegen; fermi_energy=0.0, num_points=50) -> path

Write seedname.bxsf (XCrySDen Fermi-surface grid): all interpolated bands on the inclusive (num_points+1)³ fractional grid (x outer, z fastest), reference layout.

write_chk(path, chk::Checkpoint)

Write a Wannier90 binary checkpoint readable by wannier90.x (restart = plot/wannierise) and postw90.x.

write_chk_fmt(path, chk::Checkpoint)

Write a formatted checkpoint readable by w90chk2chk.x -f2u (and any Wannier90 build).

write_cube(seedname, index, lattice, ng, w, los, centre, atoms_cart;
           radius=3.5, scale=1.0, mode=:crystal, supercell=(2,2,2)) -> path

Write seedname_<index>.cube for one Wannier function: w is its complex supercell grid (from wannier_function_grid, offsets los, UNK grid ng), centre its Cartesian centre (Å), atoms_cart a vector of (symbol, position) pairs (Å). Crystal mode keeps every periodic atom image within scale·radius of the WF centre; the data box spans radius around the centre along each lattice direction (reference geometry, everything written in bohr).

Write seedname-dos.dat in the postw90 format (energy, dos[, up, down]).

Write -ahc-fermiscan.dat or -morb-fermiscan.dat rows (4(F12.6,1x)) (berry.F90).

write_frmsf(path, lattice, energies; fermi_energy=0.0, colours=nothing) -> path

Write a FermiSurfer .frmsf file: grid dims, shift flag 1, band count, the three reciprocal vectors (Å⁻¹), then band-outer / i3-fastest energies (shifted by fermi_energy so the surface lands at 0), and optionally a colour block in the same order. energies/colours are the nband × n1 × n2 × n3 arrays from tabulate_3d.

write_gyrotropic(seedname, res; tasks=...) -> seedname

Write the postw90 seedname-gyrotropic-*.dat files for the quantities in res (from gyrotropic): symmetrised 11-column blocks for D/tildeD/C/K, raw γ_abc columns for NOA, and the 2-column DOS — exact reference headers and E15.6 formats.

write_hr(path, num_wann, irvec, ndegen, Hr; header)

Write seedname_hr.dat. Layout:

• line 1: header string (list-directed, leading space)
• line 2: num_wann (list-directed)
• line 3: nrpts (list-directed)
• ndegen block: (15I5) — 15 ints per line, width 5, wrapping
• matrix rows, nested irpt{ i{ j }}: (5I5,2F12.6) = Rx Ry Rz j i Re Im, value Hr[j,i,irpt] (j fast/row).

Hr is (numwann × numwann × nrpts), stored undivided by ndegen.

write_hr_diag(io, Hr, irvec, ndegen)

Write the postw90 write_hr_diag on-site Hamiltonian table (⟨0n|H|0n⟩ in eV) to io (default stdout), matching the reference stdout format.

write_ht(path, H00, H01; header) — write a `seedname_htB.dat` (reference format).

write_kdotp(seedname, res) -> seedname

Write seedname-kdotp_{0,1,2}.dat in the postw90 layout: one complex value per line in (2E18.8E3), column-major within each block; order-1 has three blocks (a = x,y,z), order-2 nine blocks (a,b) with b fastest.

write_kpath(seedname, res) -> seedname

Write the postw90 kpath output files for whichever quantities res (from kpath) contains: -path.kpt + -bands.dat (band-major, colour column when present), -curv.dat, -morb.dat, and -shc.dat.

write_kslice(seedname, coords, bands; curv=nothing, morb=nothing, shc=nothing)

Write the postw90 kslice output files: -kslice-coord.dat, -kslice-bands.dat, and (when given) -kslice-curv.dat, -kslice-morb.dat, -kslice-shc.dat.

Write -kubo_S_ab.dat / -kubo_A_ab.dat / -jdos.dat (3E16.8 / 2E16.8, berry.F90).

write_labelinfo(path, labels, idxs, xvals, kpts)

Write seedname_band.labelinfo.dat. One line per special point, format (a,3x,I10,3x,4f18.10) = label, point-index, xval, k1 k2 k3. The reference label variable is character(len=20), so the label field is left-justified in a 20-char field (matches the reference byte spacing).

write_nnkp(path, lattice, kfrac, projs, nnlist, nncell; exclude_bands=Int[], calc_only_A=false)

Write a .nnkp file in the reference format (drop-in for wannier90.x -pp output).

write_rmn(seedname, model, Mrot) -> path

Write seedname_r.dat: the position matrix elements ⟨0n|r|Rm⟩ (Å) on the Wigner–Seitz R-set, from the final-gauge overlaps Mrot — linear WYSV06 form off the diagonal, −Σ wb b Im ln M̃nn on the diagonal (all R). Reference record layout (5I5,6F12.6), n varying fastest.

write_shc(path, x, shc; freq_scan=false) -> path

Write a postw90 -shc-fermiscan.dat (real shc) or -shc-freqscan.dat (freq_scan = true, complex shc) file with the exact reference formats.

write_shift_current(seedname, freqs, sc) -> seedname

Write the 18 seedname-sc_<abc>.dat files (a = current direction, bc the symmetric pair), (2E18.8E3) rows of ω [eV] and σ_abc [A/V²].

write_tb(path, lattice, num_wann, irvec, ndegen, Hr; header)

Write seedname_tb.dat: lattice + <0n|H|Rm> + <0n|r|Rm>.

• line 1: header (list-directed)
• lines 2-4: a1,a2,a3 in Å (list-directed) — rows are lattice vectors
• num_wann, nrpts (list-directed)
• ndegen (15I5)
• H part: per R, a blank line then (3I5) irvec, then rows (2I5,3x,2(E15.8,1x)) = j i Re(H) Im(H), value Hr[j,i,irpt]
• r part: same block structure with 6 reals per row (3 complex Cartesian components); pass pos (nw × nw × nrpts × 3, from position_operator) or zeros are written.

lattice.A has lattice vectors as COLUMNS (Å); the reference stores real_lattice(k,:) = a_k (rows), so we emit the columns of lattice.A.

write_transport(seedname, energies, qc, dos) — write `_qc.dat` / `_dos.dat` (reference format).

write_wout(path, model, win, result; dis=nothing, omega_trace=nothing)

Write the .wout log. result::WannierResult supplies the final spread; dis::DisentangleResult (optional) adds the disentanglement Ω_I convergence table.

write_xsf(path, lattice, atoms, w, ng, los, supercell)

Write one WF's real part as an XCrySDen .xsf (crystal mode, Å): CRYSTAL/PRIMVEC/CONVVEC/ PRIMCOORD blocks, then a general 3-D datagrid over the whole plotting supercell.

write_xyz(path, centres, atoms_cart; translate_home_cell=false, lattice=nothing) -> path

Write seedname_centres.xyz: Wannier centres as pseudo-atoms X, then the real atoms. centres is a 3×nw matrix (Å), atoms_cart a vector of (symbol, position) pairs (Å). With translate_home_cell, centres are rationalised into the home cell (needs lattice).

ws_translate_dist(irvec, centres, lattice, mp_grid; ws_search_size=2, tol=1e-5) -> irdist

For each Wannier pair (i,j) and each R (column of irvec), the minimal-image-equivalent integer R-vectors. irdist[i,j,ir] is a Vector{NTuple{3,Int}} of length ndeg(i,j,ir). centres is the (3 × num_wann) Cartesian Wannier centres.

Z-matrix (SMV Eq. 21) restricted to the non-frozen rows, for a single k.

BVectors

Finite-difference neighbour geometry. For each k-point, nntot neighbours are recorded:

• kpb[b,k] : index of the neighbour k-point k+b (in the k list)
• gpb[:,b,k] : integer reciprocal-lattice shift G folding k+b back into the list
• bvec[:,b,k] : Cartesian b-vector (Å⁻¹), = B·(kfrac[kpb] + G − kfrac[k])
• wb[b,k] : finite-difference weight for that b (Ų)

The weights satisfy the B1 completeness relation Σb wb bα bβ = δ_αβ (PRB 56, 12847).

BerryModel

Everything the Berry-curvature interpolation needs, built once from a checkpoint (or a completed run): H(R), the Berry-connection matrix A(R) (postw90 convention: linear finite-difference for ALL elements, Hermitised at each q), the Wigner–Seitz R-set, and the lattice.

BerryModel(seedname) -> BerryModel

Convenience: assemble from seedname.{win,mmn,eig,chk} (a completed Wannier90 or WannierFunctions run).

BerryModel(chk::Checkpoint, eig, bv::BVectors, kgrid::KGrid, lattice) -> BerryModel

Assemble H(R) and A(R) from a Wannier90 checkpoint plus the band energies and the b-vector geometry (from the .mmn connectivity, so slot order matches chk.m_matrix).

• H(q) = v† diag(ε_window) v with v = U_opt·U (window rows) for disentangled runs, U† diag(ε) U otherwise.
• A_α(q) = Σ_b i w_b b_α M̃(q,b) for all elements (postw90 default, transl_inv=F — NB this differs from the _tb.dat convention which uses −wb b Im ln M̃nn on the diagonal), then Hermitised: A ← (A + A†)/2.
• Both transformed with O(R) = (1/N_q) Σ_q e^{−i2πq·R} O(q) on the Wigner–Seitz R-set.

BerryModel(lattice, irvec, ndegen, Hr; pos=nothing) -> BerryModel

Build an interpolation model directly from a Wannier Hamiltonian H(R) (and, optionally, the position operator r(R) as pos[j,i,ir,α]). With pos, the full Berry-connection stack (AHC, Kubo, curvature, kpath curv/morb) is available; without it, only H(R)-derived quantities (bands, DOS, velocities, BoltzWann, geninterp) work. This is the TB-model entry point — the R list carries its own Wigner–Seitz degeneracies, so no k-mesh or checkpoint is needed.

BoltzWannResult

TDF energy grid + tensor (6 × nE), and per (μ, T): electrical conductivity σ (1/Ω/m), σ·S (A/m/K), Seebeck S (V/K), and K (W/m/K), each 3×3 stored as [iμ, iT] matrices.

Everything a Wannier90 checkpoint stores.

Checkpoint(model, win, result) -> Checkpoint

Assemble a checkpoint from a completed run_wannier result, in the state wannier90.x labels "postwann". For disentangled runs the window bookkeeping and the rectangular U_opt are reconstructed from the result's DisentangleResult.

Result of disentanglement, ready for MV localisation and interpolation.

KGrid

The Monkhorst–Pack k-point grid: frac holds fractional coordinates (length nkpt), mp_grid the grid subdivisions.

KuboResult

Frequency grid (eV), Hermitian and anti-Hermitian conductivity tensors (3×3×nfreq, S/cm), and the joint density of states (states/eV, unscaled).

Lattice(A)

Real- and reciprocal-space lattice. A has the three real-space lattice vectors as its columns (Ångström). The reciprocal lattice B (columns b₁,b₂,b₃, units Å⁻¹) satisfies the crystallographic convention aᵢ·bⱼ = 2π δᵢⱼ, i.e. B = 2π (A⁻¹)ᵀ.

Model

Everything needed to Wannierise a set of bands: geometry, k-mesh, neighbour weights, the overlap matrices M, the projection matrices A, and (optionally) the band energies.

• M[m,n,b,k] = ⟨u{m,k} | u{n,k+b}⟩ (numbands × numbands × nntot × nkpt)
• A[m,n,k] = ⟨ψ{m,k} | gn⟩ (numbands × numwann × nkpt), trial-projection overlaps
• eig[m,k] = ε{m,k} in eV (numbands × nkpt), optional (disentanglement/interp)

MorbModel

BerryModel plus the two H-weighted position operators B(R) (3 components) and C(R) (3×3 components) needed for the orbital magnetisation.

MorbModel(seedname; transl_inv_full=false) -> MorbModel

Assemble from seedname.{win,mmn,eig,chk,uHu} (formatted .uHu). With transl_inv_full = true, A(R), B(R) and C(R) use the one-shell translation-invariant scheme (e^{ib·r₀} phases, canonical b-slots on the expanded minimal-image R-set with e^{−ib·R̃/2}, plus the H-weighted correction terms of get_oper.F90; C(R) is then NOT Hermitian-paired).

One projection: site (fractional), angular character (l, mr), radial node count, axes; for spinor projections s = ±1 selects the spin component along s_qaxis (s = 0 ⇒ spatial).

SLWF

Selective-localisation controls: minimise the spread of Wannier functions 1..num, with an optional centre constraint (constrain) of strength lambda toward the Cartesian sites centres (3×num).

SSData

Uniform b-vector order maps for the Stengel–Spaldin functional: nnord[nn, k] is the index at k of the b-vector equal to bvec[:, nn, 1], nnrev[nn, k] the index of its negative (the reference's kmesh_info%nnord / %nnrev).

ShcModel

BerryModel plus the QZYZ operators: SS(R) (σ, 3 comps), SH(R) (σH), SR(R) (σ(r−R)α) and SHR(R) (σH(r−R)α), each for the chosen spin component γ built on demand — here all three γ are stored (γ, α indices: [.,.,R,γ] and [.,.,R,γ,α]).

ShcModel(seedname; scissors_shift=0.0, num_valence_bands=0) -> ShcModel

Assemble from seedname.{win,mmn,eig,chk,spn} (Qiao method: no .uHu needed). A nonzero scissors_shift (eV) rigidly shifts the ab-initio bands above num_valence_bands before H(R) and σH are built (postw90's scissors correction — Qiao method only).

ShcRyooModel

BerryModel plus the Ryoo–Park–Souza operators (RPS19, PRB 99, 235113): S(R) (from .spn), SAA(R) = ⟨0|σγ(r−R)α|R⟩ (from .sIu) and SBB(R) = ⟨0|σγ H(r−R)α|R⟩ (from .sHu).

ShcRyooModel(seedname; transl_inv_full=false) -> ShcRyooModel

Assemble from seedname.{win,mmn,eig,chk,spn,sHu,sIu}. With transl_inv_full = true the one-shell translation-invariant scheme is used for A(R), SAA(R) and SBB(R) (phases e^{ib·r₀} and e^{−ib·R/2} with r₀ = (r̄i+r̄j)/2, plus the (r₀−R/2)·S / ·σH diagonal corrections).

NB: the reference implementation accumulates the windowed σ-rotation across the three spin components (get_oper.F90:2680), so its SAA/SBB for γ = y hold σx+σy and for γ = z hold σx+σy+σz. We compute the clean per-component operators; results agree for γ = x (which is what the shipped oracle tests use) and differ — deliberately — for γ = y, z.

Sitesym

Site-symmetry data from a .dmn: ik2ir[ik] (irreducible index of k), ir2ik[ir] (representative k of irreducible index ir), kptsym[isym, ir] (the k reached by applying isym to irreducible point ir), and the band/Wannier representation matrices d_band[:,:,isym,ir] (numbands²) and `dwann[:,:,isym,ir]` (num_wann²).

SpinModel

BerryModel plus the Wannier-gauge Pauli matrices S(R) (3 components) from a .spn file.

SpinModel(seedname) -> SpinModel

Assemble from seedname.{win,eig,chk,spn} (plus .mmn for the Berry connection when present — not needed for the spin quantities themselves).

SpinModel(bm, chk, spn, kgrid) -> SpinModel

Assemble S(R) from raw .spn matrices: S(q) = v† σ(win_q, win_q) v on the disentanglement window, then Fourier to the Wigner–Seitz R-set of bm.

Container for the results of a spread evaluation.

SymmetryOps

Space-group operations from a .sym file: rot[s] is the 3×3 rotation of symmetry s (fractional/crystal basis, acting on fractional coordinates) and trans[s] its fractional translation. nsym operations in total.

TBOperator

A tight-binding (Wannier-gauge) operator: data[m, n, ir, c] is the (m,n) matrix element of component c at lattice vector irvec[ir], stored undivided by ndegen (the Wannier90 convention). Component count is 1 for the Hamiltonian, 3 (x,y,z) for the position operator.

Evaluate at a fractional k-point by calling it: op(k) returns a num_wann × num_wann matrix (1 component) or a 3-vector of matrices.

Evaluate the operator at fractional k: Σ_R e^{+i2πk·R} O(R)/ndegen(R).

WannierResult

Outcome of a full wannierisation. U is the final square gauge (numwann × numwann × nkpt); eig_interp are the per-k energies to Fourier-interpolate (the DFT eigenvalues for the isolated case, or the disentangled subspace eigenvalues), both num_wann × nkpt.

Result of a wannierisation run.

WinInput

Parsed .win input. Scalar parameters not promoted to typed fields are kept in raw (lower-cased keys), and block bodies (raw lines, comments stripped) in blocks.

Per-k energy-window bookkeeping (all indices window-local unless noted).

@maybe_threads cond for ... end

Thread the loop only when cond is true (and more than one thread is available). Threading a 64-iteration loop of microsecond bodies costs more in scheduling than it saves — every threaded k/R loop in this package is gated on a problem-size condition.

Bohr radius in Ångström. The reference Wannier90 defaults to CODATA2006 (compile flags select 2010/2018/2022); we match the default so bohr-specified cells reproduce reference output exactly.

Symmetric-tensor packing order used by BoltzWann files: xx, xy, yy, xz, yz, zz.

Default minimum loop length before a k/R loop is worth threading.

2π.