Skip to main content

Collection of code for band unfolding

Project description

build docs codecov PyPI Downloads JOSS

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

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 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)

A recent version of pip is needed to do this, due to the new style of the pyproject.toml configuration file. To upgrade your pip, do:

pip install -U pip

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!

  • K. Eggestad, B. A. D. Williamson, D. Meier and S. M. Selbach Mobile Intrinsic Point Defects for Conductive Neutral Domain Walls in LiNbO3 ChemRxiv 2024
  • L. Zhang et al. Study of native point defects in Al0.5Ga0.5N by first principles calculations Computational Materials Science 2024
  • S. M. Liga & S. R. Kavanagh, A. Walsh, D. O. Scanlon and G. Konstantatos Mixed-Cation Vacancy-Ordered Perovskites (Cs2Ti1–xSnxX6; X = I or Br): Low-Temperature Miscibility, Additivity, and Tunable Stability Journal of Physical Chemistry C 2023
  • Y. T. Huang & S. R. Kavanagh et al. Strong absorption and ultrafast localisation in NaBiS2 nanocrystals with slow charge-carrier recombination Nature Communications 2022
  • A. T. J. Nicolson et al. Interplay of Static and Dynamic Disorder in the Mixed-Metal Chalcohalide Sn2SbS2I3 Journal of the Americal Chemical Society 2023
  • Y. Wang & S. R. Kavanagh et al. Cation disorder engineering yields AgBiS2 nanocrystals with enhanced optical absorption for efficient ultrathin solar cells Nature Photonics 2022 (early version)

DFT code support

At the moment, easyunfold supports VASP and CASTEP, 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 of WaveFunction that handles reading the wave function output.
  • Implementing functions for reading/writing k-points.
  • Adding branches for dispatching based on the dft_code attribute of the UnfoldKSet object in various places within the code.

The Atomic Simulation Environment (ASE) is used by easyunfold for reading in structures, so structure file IO is natively supported for essentially all public DFT codes.

Code Compatibility Notes

  • Atom-projected band structures are currently only supported for VASP calculation outputs.
  • Gamma-only and non-collinear spin calculations are not supported for CASTEP.

Contributors

And those who helped in the development:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

easyunfold-0.3.7.tar.gz (54.5 kB view hashes)

Uploaded Source

Built Distribution

easyunfold-0.3.7-py3-none-any.whl (55.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page