VASP band structure unfolding code
When performing VASP calculations on supercells (e.g., for alloys, defects, or doped systems), the band structure gets folded into the smaller supercell Brillouin zone. This tool unfolds the bands back to the primitive cell Brillouin zone, recovering an intuitive effective band structure.
pip install -e .Requirements: Python >= 3.9, numpy, pymatgen
Generate a KPOINTS file for the supercell VASP calculation using the primitive cell POSCAR and the supercell transformation matrix.
vasp-unfold generate-kpoints \
--poscar-pc POSCAR_PC \
--matrix "2 0 0 0 2 0 0 0 2" \
--kpath G-X-M-G \
--npoints 200 \
--output KPOINTS--matrix: Supercell transformation matrix (A_SC = M * A_PC), 9 integers in row-major order--kpath: High-symmetry k-point path (default: auto-generated by pymatgen)--npoints: Number of points along the k-path (default: 100)
Run a VASP non-SCF calculation with the generated KPOINTS file. Make sure WAVECAR output is enabled.
vasp-unfold unfold \
--wavecar WAVECAR \
--poscar-pc POSCAR_PC \
--matrix "2 0 0 0 2 0 0 0 2" \
--kpath G-X-M-G \
--npoints 200 \
--efermi -3.45 \
--output unfold_result--efermi: Fermi energy in eV (default: read from WAVECAR)--tol: K-point matching tolerance (default: 0.01)
Produces a *_wnk.dat file in 3-column ASCII format:
# E_fermi = -3.450000 eV
# High-symmetry points: Gamma 0.000000 X 0.500000 ...
# kpts enk(eV) wnk
0.00000000 -5.123456 0.95431234e+00
0.00000001 -4.987654 0.87654321e+00
...
| Column | Description |
|---|---|
kpts |
Distance along the k-path |
enk |
Energy relative to the Fermi level (eV) |
wnk |
Spectral weight (0 to 1) |
from vasp_unfold import BandUnfolder, WavecarReader
reader = WavecarReader("WAVECAR")
unfolder = BandUnfolder(reader, M)
out_k, out_E, out_W = unfolder.unfold(kpath_frac, k_distances)Computes spectral weights for primitive cell k-points from the supercell plane-wave coefficients C_{K,m}(G):
P(k) = Σ_G |C(G)|², where frac(M^{-T}(K+G)) ≈ k
A weight close to 1 indicates that the band retains strong primitive cell character at that k-point.
V. Popescu and A. Zunger, "Extracting E versus k effective band structure from supercell calculations on alloys and impurities," Physical Review B 85, 085201 (2012).
MIT