Skip to content


Repository files navigation

Welcome to MacroDensity

MacroDensity is a Python package to post-process electrostatic potential and electron density files from electronic structure calculations and plot in a number of ways, including:

  1. Planar average
  2. Spherical average
  3. Atom centred average

Statement of Need

To assess the potential utility of novel semiconducting devices (like p-n junctions, heterostructures, surface terminations), it is key to understand how the electrostatic potential and electron density change across the system. However, extraction and useful presentation of this data from the raw output of the simulation can prove cumbersome and often requires the use of visualisation software followed by manual data extraction. This can result in bottlenecks in high throughput screening projects, where the same data extraction procedure is repeatedly applied to large databases of candidate structures.

To address this, the Macrodensity package has been developed to post-process the output of ab-initio codes like VASP, FHI-AIMS and GULP. The package contains functions that enable the user to format the data from the VASP LOCPOT and CHGCAR files, the FHI-AIMS *.cube file, and GULP *.out file into physically meaningful quantities, which can then be plotted for user interpretation.


User installation

Macrodensity can be installed using pip:

pip install macrodensity

Developer installation

For development of MacroDensity, you can install a copy of the package from the source directory:

git clone
cd MacroDensity
pip install -e .


For more information on the theory behind the package, please see the following references:


Bugs reports, feature requests and questions

Please use the Issue Tracker to report bugs or request new features.

Contributions to extend this package are very welcome! Please use the Fork and Pull workflow to do so and follow the PEP8 style guidelines.


Unit tests are in the tests directory and can be run from the top directory using unittest. Automatic testing is run on the master and develop branches using Github Actions. Please run tests and add new tests for any new features whenever submitting pull requests.

License and citation

MacroDensity is made available under the MIT License.

If you use it in your research, please cite: