Skip to main content

An effective mass package

Project description

effmass 2.2.0

PyPI version Documentation Status Build Status Test Coverage DOI License: MIT JOSS status

💃 Effmass now has a command line interface
💃 Effmass now supports FHI-Aims, Castep, ASE, and Octopus
⚠️ The Data class was renamed DataVasp in effmass versions 2.0.0+. You may need to update your scripts!

effmass is a peer-reviewed Python (3.6+) package for calculating various definitions of effective mass from the electronic bandstructure of a semiconducting material. It consists of a core Segment class that calculates the effective mass and other associated properties of selected bandstructure segments. The programme also contains functions for locating bandstructure extrema, constructing segments and plotting approximations to the dispersion. There is a command line interface for calculating parabolic effective mass values, and an API for the more complex, non-parabolic definitions of effective mass.

If you use effmass for your published research please cite accordingly.

What's new?

💃 effmass now interfaces with more codes:

  • it can read in Castep output data (in addition to Vasp and FHI-aims)
  • it can work with ASE bandstructure objects
  • it can work with Octopus output files

💃 effmass now includes a command line interface

As a result of these changes, and with view to supporting more DFT codes in the future, the Data class has been renamed to DataVasp ⚠️ On updating to the latest version of effmass you may need to update your scripts / Jupyter Notebook to reflect this change ⚠️


effmass can:

Read in a bandstructure: It is assumed you have used a DFT calculator to walk through a 1D slice of the Brillouin Zone, capturing the maxima and minima of interest. effmass uses the Python package vasppy for parsing VASP output.

Locate extrema: These correspond to the valence band maxima and conduction band minima. Maxima and minima within a certain energy range can also be located.

Calculate curvature, transport and optical effective masses: The curvature (aka inertial) and transport masses are calculated using the derivatives of a fitted polynomial function. The optical effective mass can also be calculated assuming a Kane dispersion.

Assess the extent of non-parabolicity: Parameters of the Kane quasi-linear dispersion are calculated to quantify the extent of non-parabolicity over a given energy range.

Calculate the quasi-fermi level for a given carrier concentration: Using density-of-states data and assuming no thermal smearing, effmass can calculate the energy to which states are occupied. This is a useful approximation to the quasi-Fermi level. Note: this is only supported for VASP and requires the output file DOSCAR.

Plot fits to the dispersion: Selected bandstructure segments and approximations to the dispersion (assuming a Kane, quadratic, or higher order fit) can be visualised.

Depending on the functionality and level of approximation you are looking for, it may be that one of the packages listed here will suit your needs better.

Supported Codes

effmass currently supports VASP, FHI-Aims, Castep, ASE, and Octopus. In the near future we hope to play nicely with other codes that interface with the ASE bandstructure class, and pymatgen. We especially welcome contributions that will help make effmass available to more researchers.


effmass can then be installed using the Python package manager pip:

pip install effmass

If you use conda/anaconda the safest thing to do is to create a new environment and then install effmass:

conda create --name effmass
conda activate effmass
conda install pip
pip install effmass

If you do not use pip you can download and install the latest release from GitHub and install:

cd effmass
python install

Command Line Interface

The command line interface provides basic functionality for calculating parabolic effective masses. For those who have a basic familiarity with Python there is an API which provides access to all features, including non-parabolic effective mass definitions.

To start the command line interface simply type


and follow the prompts. You are asked if you would like to print a plot of the segments found - we recommend that you do this, to check that the segments are "sensible". You are also asked if you would like to print a summary file - again, we recommend that you do this, so that you have a record of the CLI options chosen.


  • An overview of the features of effmass, along with example code for Vasp and FHI-aims output data, is contained in a Jupyter notebook here.
  • Additional Jupyter notebook examples for the Castep and ASE interfaces are here.
  • The API documentation is here.
  • Further details about the various effective mass definitions implemented in effmass can be found in Phys. Rev. B 99 (8), 085207, which is also available on arXiv.
  • The source code is available as a git repository at

Running notebook examples

If you want to run the jupyter notebook examples/tutorials you will also need to install notebook:

pip install notebook

To run the notebook, run the following command at the Terminal (Mac/Linux) or Command Prompt (Windows):

jupyter notebook

This will open a web browser tab, which you can use to navigate to the notebook examples.

Publications using effmass

A number of publications have used effmass.

effmass was initially developed for a project that has been published as Impact of nonparabolic electronic band structure on the optical and transport properties of photovoltaic materials Phys. Rev. B 99 (8), 085207. This paper is also avaiable on arXiv. The paper directory contains the Vasp input data (POSCAR), Vasp output data (OUTCAR/PROCAR) and band structures generated for this study.

Questions, bug reports, feature requests

Please use the Github issue tracker for any questions, feature requests or bug reports. Please do not contact the developers via email unless there is a specific reason you do not want the conversation to be public.


If you would like to contribute please do so via a pull request. All contributors must read and respect the code of conduct. In particular, we welcome contributions which would extend effmass so that it is able to parse output from other electronic structure codes.


Automated testing of the latest commit happens here.

You can also run tests locally:

pip install effmass[tests]
cd effmass
python -m pytest

Citing effmass

If you use this code in your research, please cite the following paper:

Whalley, Lucy D. (2018). effmass - an effective mass package. The Journal of Open Source Software, 3(28) 797. Link to paper here.


  author       = {Lucy D. Whalley},
  title        = {effmass: An effective mass package},
  volume       = {3},
  issue        = {28},
  pages        = {797},
  month        = {Aug},
  year         = {2018},
  doi          = {10.21105/joss.00797},
  url          = {}


Lead developer: Lucy Whalley, a.k.a lucydot

Austin Fatt (support for Ocotpus), a.k.a afatt //
Matthias Goloumb (Support for FHI-Aims), a.k.a MatthiasGolomb //
Sean Kavanagh (Documentation), a.k.a kavanase //
Benjamin Morgan (Vasppy compatability), a.k.a bjmorgan //

Project details

Download files

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

Files for effmass, version 2.2.0
Filename, size File type Python version Upload date Hashes
Filename, size effmass-2.2.0-py3-none-any.whl (31.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size effmass-2.2.0.tar.gz (32.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page