Easyunfold

easyunfold is intended for obtaining the effective band structure of a supercell for a certain k-point path of the primitive cell. It was originally based on PyVaspwfc for reading VASP wavefunction outputs, with a notable improvement being that symmetry-breaking is properly accounted for by sampling necessary additional k-points and averaging accordingly. Documentation site here!

Our goal is to implement the band structure unfolding workflow in a robust and user-friendly software package. Typical applications of band structure unfolding are the electronic structure analysis of defects, disorder, alloys, surfaces (and more), as illustrated in the example outputs below and docs examples.

For the methodology of supercell band unfolding, see here.

Example Outputs

Cs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite Alloys | Oxygen Vacancy (Vₒ⁰) in MgO :-------------------------:|:------------------------------------: <img src="docs/img/CSTB_easyunfold.gif" height="400"/> | <img src="examples/MgO/unfold_project_MgO_v_O_0_tall.png" height="400"/>

See the easyunfold YouTube tutorial for a quick overview of the theory of band structure unfolding, and a walkthrough of the calculation & analysis workflow with easyunfold.

Usage

To generate an unfolded band structure, one typically needs to perform the following steps:

1. Create a primitive unit cell, and generate a band structure k-point path corresponding to this primitive cell.
2. Create a supercell (e.g. disordered, defective, surface slab etc.), and obtain its optimised structure.
3. Generate a series of k-points for the supercell to be calculated.
4. Perform a band structure calculation with the supercell, and save its wavefunction output to file.
5. Post-process the supercell wavefunction to obtain the unfolded band structure in the k-point path of the primitive unit cell.

These generation and analysis steps are automated in easyunfold, with only the primitive unit cell and supercell structures required as inputs from the user.

Typically, the supercell comprises some form of symmetry-breaking relative to the primitive cell, such as defects, disorder (e.g. special quasi-random structures (SQS) for site disorder – other forms of disorder such as magnetic, dynamic/vibrational, polar, elastic etc. also possible), or a surface/interface slab. In all cases, the supercell symmetry is lowered compared to the pristine primitive cell. Hence, for a given k-point path in the primitive cell Brillouin Zone, additional k-points are required to be sampled for the supercell, and the extracted spectral weights need to be appropriately averaged to obtain the correct effective band structure (EBS). See the docs Theory page and/or JOSS paper for more details.

Please see the documentation for guides and examples.

Installation

Install from pip

easyunfold can be installed from pip:

pip install easyunfold

This will also install the package dependencies, if any are missing.

After installation, running easyunfold on the command-line should give the following output:

Usage: easyunfold [OPTIONS] COMMAND [ARGS]...

  Tool for performing band unfolding

Options:
  --help  Show this message and exit.

Commands:
  generate  Generate the kpoints for sampling the supercell
  unfold    Perform unfolding and plotting

Developer Installation (from source)

Assuming the package is in the easyunfold folder, use the following command to install:

pip install "./easyunfold[test,doc,pre-commit]"

which also installs additional dependencies for building documentation (doc), running tests (test) and dependencies for using pre-commit hooks (pre-commit).

Citation

If you use easyunfold in your work, please cite:

• B. Zhu, S. R. Kavanagh & D. O. Scanlon, (2024). easyunfold: A Python package for unfolding electronic band structures. Journal of Open Source Software, 9(93), 5974, https://doi.org/10.21105/joss.05974

Studies using easyunfold

We'll add papers that use easyunfold to this list as they come out!

• I. Caro-Campos et al. Phonon Scattering by Local Off‐Centering in Diamond‐Like Cu_2−XAg_xIn₂Se₄ Chalcopyrites: High Carrier Mobility and Ultralow Thermal Conductivity Small Structures 2026
• J. M. Domínguez-Vázquez et al. Enhanced thermoelectric performance in Fe₂V_0.8W_0.2Al thin films: synergistic effects of chemical ordering and tungsten substitution Journal of Materials Chemistry A 2026
• H. Li et al. CuI-enhanced thermoelectric performance in GeTe by synchronous modulation of hole concentration and thermal conductivity Matter 2026
• A. Pike et al. Alloying to tune the bandgap of the <i>AM</i>₂<i>Pn</i>₂ Zintl compounds Journal of Physics: Energy 2026
• M. Wróblewska et al. Continuous Alloying between Rocksalt and Half-Heusler Structures Drives Metal–Semiconductor Transition in ErNi_<i>x</i>Sb Chemistry of Materials 2026
• K. V. Sopiha et al. Functional off-stoichiometry in Cu(In,Ga)Se₂. Part II: electronic properties in a wide range of compositions Journal of Materials Chemistry A 2026
• Y.-S. Liao et al. Moiré-Induced Electronic Reconstruction in van der Waals Heterobilayer PtSe₂/PtTe₂ ACS Nano 2026
• J. J. Plata et al. High-Entropy Skutterudites as Thermoelectrics: Potential Synthesizability, Enhanced Stability, and Band Convergence via the Cocktail Effect PRX Energy 2026
• P. Russell et al. Computational prediction of Y-doped Cd₂Sb₂O₇ as a competitive Sb-based n-type Transparent Conducting Oxide ChemRxiv 2025
• P. Kumar et al. Theoretical insights into the h-NbN monolayer for selective and moisture-resistant gas sensing: an ab initio study Electronic Structure 2025
• M. Sigl et al. Solution-based synthesis of nanocrystalline KBiS₂ films at low temperatures and study of photoinduced charge generation Journal of Materials Chemistry C 2025
• Y. Yin et al. Halogen Chains with One-Dimensional Semi-Metallic Electronic Structure and Peierls Physics in Polymorphs of Na₄X₅ (X = I, Br, Cl) Compounds arXiv 2025
• V. Posligua et al. Deep Learning Framework for Accurate Prediction and High-Throughput Search of the Thermoelectric Figure of Merit in Skutterudites ChemRxiv 2025
• R. E. Philip et al. Disorder mediated fully compensated ferrimagnetic spin-gapless semiconducting behaviour in Cr₃Al Heusler alloy arXiv 2025
• S. Husremović et al. Local interface effects modulate global charge order and optical properties of 1T-TaS₂/1H-WSe₂ heterostructures ACS Nano 2025
• L. Richarz et al. Ferroelectric domain walls for environmental sensors ACS Applied Materials & Interfaces 2025
• J. M. Domínguez-Vázquez et al. Thermoelectric performance boost by chemical order in epitaxial L2₁ (100) and (110) oriented undoped Fe₂VAl thin films: an experimental and theoretical study Journal of Materials Chemistry A 2025
• J. Tu et al. Giant switchable ferroelectric photovoltage in double-perovskite epitaxial films through chemical negative strain Science Advances 2025
• L. F. Leon-Pinzon et al. Observation of Pseudogap in Cr_1−xY_xN magnetic alloy and its impact on the Seebeck coefficient by ab-initio calculations arXiv 2025
• C. Zhang & J. Recatala-Gomez & Z. Aabdin & Y. Jiang et al. Direct Joule-Heated Non-Equilibrium Synthesis Enables High Performing Thermoelectrics arXiv 2025
• W. Feng et al. Unraveling the role of oxygen vacancies in the electronic and optical properties of κ-Ga2O3 Communications Chemistry 2025
• Y. Gong Wang et al. **_Influence of Vanadium and Ch