Package: easyunfold
easyunfoldis intended for obtaining the effective band structure of a supercell for a certaink-point
path of the primitive cell. It was originally based onPyVaspwfcfor reading VASP wavefunction outputs,
with a notable improvement being that symmetry-breaking is properly accounted for by sampling necessary
additionalk-points and averaging accordingly. Documentation sitehere!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 anddocs examples.For the methodology of supercell band unfolding, seehere.Example OutputsCs₂(Sn/Ti)Br₆ Vacancy-Ordered Perovskite AlloysOxygen Vacancy (Vₒ⁰) in MgOUsageTo generate an unfolded band structure, one typically needs to perform the following steps:Create a primitive unit cell, and generate a band structurek-point path corresponding to this
primitive cell.Create a supercell (e.g. disordered, defective, surface slab etc.), and obtain its optimised structure.Generate a series ofk-points for the supercell to be calculated.Perform a band structure calculation with the supercell, and save its wavefunction output to file.Post-process the supercell wavefunction to obtain the unfolded band structure in thek-point path
of the primitive unit cell.These generation and analysis steps are automated ineasyunfold, 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 givenk-point path in the primitive cell Brillouin Zone, additionalk-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 docsTheorypage for more details.Please see thedocumentationfor guides and examples.InstallationInstall frompipeasyunfoldcan be installed frompip:pip install easyunfoldThis will also install the package dependencies, if any are missing.After installation, runningeasyunfoldon 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 plottingDeveloper Installation (from source)A recent version ofpipis needed to do this, due to the new style of thepyproject.tomlconfiguration
file.
To upgrade yourpip, do:pip install -U pipAssuming the package is in theeasyunfoldfolder, 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).Studies usingeasyunfoldWe'll add papers that useeasyunfoldto this list as they come out!S. M. Liga & S. R. Kavanagh, A. Walsh, D. O. Scanlon and G. KonstantatosJournal of Physical Chemistry C2023Y. T. Huang & S. R. Kavanagh et al.Nature Communications2022A. T. J. Nicolson et al.Journal of the Americal Chemical Society2023Y. Wang & S. R. Kavanagh et al.Nature Photonics2022 (early version)DFT code supportAt the moment, easyunfold supportsVASPandCASTEP, but most of the routines are abstracted from the code specific details.
In principle, support for other plane wave DFT code can be added by:Implementing a subclass ofWaveFunctionthat handles reading the wave function output.Implementing functions for reading/writingk-points.Adding branches for dispatching based on thedft_codeattribute of theUnfoldKSetobject in
various places within the code.The Atomic Simulation Environment (ASE) is used byeasyunfoldfor
reading in structures, so structure file IO is natively supported for essentially all public DFT codes.Code Compatibility NotesAtom-projected band structures are currently only supported forVASPcalculation outputs.Gamma-only and non-collinear spin calculations are not supported forCASTEP.ContributorsBonan ZhuSeán KavanaghAdair NicolsonAnd those who helped in the development:Joe WillisDavid O. Scanlon