pyVASPlot

📡 Python toolkit for VASP electronic-structure analysis and visualization.

---

---

⚠️ Work in progress

pyVASPlot is currently under active development and the API is not yet stable. Interfaces and functionality may change between releases.

Description

pyVASPlot is a Python package for loading, manipulating, and visualizing electronic-structure data from VASP calculations.

The package provides a convenient data container, PyVASP, built around loaders from pymatgen. It is designed primarily for use in Jupyter notebooks, where VASP results can be loaded and further analyzed interactively.

A particular focus of the package is the visualization of orbital- and ion-projected electronic structure, with the aim of facilitating comparison between DFT calculations and ARPES (angle-resolved photoemission spectroscopy) measurements.

In addition to the core data structures and VASP loaders, pyVASPlot provides plotting and selection utilities for electronic-structure data, including band structures, k-space paths, PROCAR projections, and projected k-space maps.

The package can also handle calculations performed along custom k-space planes, such as a kx–ky plane, and can generate projected constant-energy maps suitable for comparison with experimental ARPES maps.

Features

• Load VASP calculations from directories or ZIP archives.

• Parse data from common VASP output files, including:

  • PROCAR
  • CONTCAR
  • OUTCAR
  • KPOINTS

• Load different types of electronic-structure calculations, including:

  • band structures along k-paths
  • spin-orbit coupling calculations
  • HSE calculations
  • custom k-space scans and kx–ky data

• Use pymatgen-based loaders for parsing VASP output.

• Store calculation data in a convenient PyVASP container.

• Plot band structures and reciprocal-space k-paths.

• Visualize orbital- and ion-projected data from PROCAR.

• Generate projected k-space maps.

• Select ions and orbitals for projection plots.

• Cache parsed data locally to speed up subsequent loads.

• Designed for interactive use in Jupyter notebooks.

Installation

pyVASPlot currently requires Python 3.12 or newer.

The package is currently under development and is not yet available as a stable PyPI release.

For development, clone the repository and install it in editable mode:

git clone <repository-url>
cd pyvasplot
pip install -e ".[dev]"

Example

A typical workflow starts by loading a VASP calculation into a PyVASP object.

from pyvasplot import PyVASP
from pyvasplot.plotting import plot_bands, plot_kpath

dft = PyVASP(
    "path/to/Sb_111_GGA_0014",
    calculation_type="BS_KPATH",
    sub_path="BS_MGKM",
)

dft.load()

# Plot the reciprocal-space calculation path
plot_kpath(dft)

# Plot the band structure
plot_bands(dft)

Projection maps can be generated by selecting specific ions and orbitals from the PROCAR data:

from pyvasplot.select.ions import by_name
from pyvasplot.plotting import plot_procar_map

orbitals = ("s", "py", "pz", "px")
ions = by_name(dft, "Sb")

# Parameters defining the k-space section
sec_MGM = {
    "k_section": 0,
    "k_mirror": True,
    "k_flip": True,
}

# Plot the projection onto the selected ions and orbitals
plot_procar_map(
    dft,
    ions=ions,
    orbitals=orbitals,
    **sec_MGM,
)

More examples and detailed documentation will be added as the package develops.

Documentation

The documentation is available on Read the Docs:

https://pyvasplot.readthedocs.io/

Citing

If you use pyVASPlot in your work, please cite it using the metadata in CITATION.cff.

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for the development workflow, test commands, and pull request guidelines.

Development status

pyVASPlot is currently under heavy development.

The API should be considered unstable, and breaking changes may occur without following a strict backwards-compatibility policy.

Contributions, bug reports, and suggestions are welcome.

Dependencies and acknowledgements

pyVASPlot builds heavily on several excellent open-source scientific Python packages:

• pymatgen — VASP file parsing and electronic-structure data handling
• ASE — atomic structures and structure visualization
• NumPy — numerical data processing and array operations
• Matplotlib — plotting and visualization

We are grateful to the developers and contributors of these projects for making their software available to the scientific community. Please see the respective projects for their licensing information and citation guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for details.