Metadata-Version: 2.4
Name: pyvasplot
Version: 0.4.0
Summary: Python toolkit for VASP electronic-structure analysis and visualization.
Author-email: Marek Kopciuszynski <Marek.Kopciuszynski@umcs.pl>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: pymatgen>=2026.5.4
Requires-Dist: matplotlib>=3.4
Requires-Dist: dill>=0.3.4
Requires-Dist: tqdm>=4.60
Requires-Dist: ase>=3.26
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Dynamic: license-file

# pyVASPlot

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

---
[![CI](https://github.com/mkopciuszynski/pyvasplot/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mkopciuszynski/pyvasplot/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Linter: ruff](https://img.shields.io/badge/linter-ruff-46a2f1.svg?logo=ruff)](https://github.com/astral-sh/ruff)
[![Package manager: uv](https://img.shields.io/badge/packaging-uv-blue)](https://github.com/astral-sh/uv)
---

> **⚠️ 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](https://www.vasp.at/) calculations.

The package provides a convenient data container, `PyVASP`, built around loaders from [`pymatgen`](https://pymatgen.org/). 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:

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

## Example

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

```python
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:

```python
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

Documentation is currently under development.

The full documentation will be hosted on **Read the Docs** once the package reaches a more stable stage.

## 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](https://pymatgen.org/)** — VASP file parsing and electronic-structure data handling
* **[ASE](https://wiki.fysik.dtu.dk/ase/)** — atomic structures and structure visualization
* **[NumPy](https://numpy.org/)** — numerical data processing and array operations
* **[Matplotlib](https://matplotlib.org/)** — 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`](LICENSE) file for details.
