Source-linked AI summary
PyProcar: A Python library for electronic structure pre/post-processing
Uthpala Herath, Pedram Tavadze, Xu He, Eric Bousquet, Sobhit Singh, Francisco Muñoz, Aldo H. Romero
TL;DR
DFT electronic-structure outputs can be difficult to interpret and require flexible post-processing. PyProcar addresses this with a Python library that projects and visualizes bands, surfaces, spins, and external properties, while supporting band unfolding. Its examples demonstrate orbital and spin-resolved analysis across several materials, with numerical Fermi-velocity visualization and a phase-factor requirement for unfolding.
Problem
Increasingly large and complex DFT calculations require efficient tools that extract and visualize essential electronic-structure information with less coding.
Method
PyProcar parses PROCAR-based DFT outputs and projects bands, Fermi surfaces, spin textures, and external momentum-space properties using command-line-configurable visualizations.
Results
PyProcar demonstrates orbital projections, Rashba spin textures, Weyl-point analysis, Fermi-velocity coloring, and band unfolding across representative materials.
Takeaways & Limitations
The library provides accessible analysis of spin-, orbital-, atom-, and property-resolved electronic structures across band and surface representations.
Takeaways & Limitations
Band unfolding requires a primitive-cell Brillouin-zone calculation with phase factors included in the PROCAR file by setting LORBIT=12 in VASP.
Abstract
from arXiv · showhide
The PyProcar Python package plots the band structure and the Fermi surface as a function of site and/or s,p,d,f - projected wavefunctions obtained for each $k$-point in the Brillouin zone and band in an electronic structure calculation. This can be performed on top of any electronic structure code, as long as the band and projection information is written in the PROCAR format, as done by the VASP and ABINIT codes. PyProcar can be easily modified to read other formats as well. This package is particularly suitable for understanding atomic effects into the band structure, Fermi surface, spin texture, etc. PyProcar can be conveniently used in a command line mode, where each one of the parameters define a plot property. In the case of Fermi-surfaces, the package is able to plot the surface with colors depending on other properties such as the electron velocity or spin projection. The mesh used to calculate the property does not need to be the same as the one used to obtain the Fermi surface. A file with a specific property evaluated for each $k$-point in a $k-$mesh and for each band can be used to project other properties such as electron-phonon mean path, Fermi velocity, electron effective mass, etc. Another existing feature refers to the band unfolding of supercell calculations into predefined unit cells.
PROGRAM SUMMARY
PyProcar automates electronic-structure analysis by parsing, combining, extracting, plotting, and repairing density-functional calculation data.
- PyProcar handles density-functional data through parsing, extraction, plotting, combination, and repair operations.Color maps represent relevant electronic-structure characteristics on band structures and Fermi surfaces.
1. Introduction
Increasing computational capability has made electronic-structure datasets larger and harder to analyze, motivating efficient, reliable, and user-friendly DFT post-processing tools. PyProcar addresses this need with an open-source Python library supporting scripted analysis and multiple electronic-structure workflows.
- Motivation: Larger and more complex calculated systems hinder analysis and abstraction of key electronic-structure features.The authors identify a need for tools that extract essential information from large data files.
- PyProcar: PyProcar provides open-source DFT pre- and post-processing for projected bands, Fermi surfaces, Fermi velocities, band unfolding, comparisons, and k-path generation.The library supports plain and spin-, atom-, or orbital-projected band structures and two- and three-dimensional surfaces.
- Scope: PyProcar can be adapted to output from other DFT codes, while the paper presents examples illustrating its electronic-structure analysis capabilities.The stated examples follow a brief explanation of the library’s basic aspects.
2. Library Overview
PyProcar organizes PROCAR and OUTCAR electronic-structure information for analysis, including orbital, spin, and phase-sensitive projections. Its modular Python design supports parsing, selection, coordinate handling, visualization, and band unfolding.
- Electronic structure projection: PROCAR stores orbital and spin projections of Kohn-Sham states for each k-point, band, and atom, with phase information available for band unfolding.Noncollinear calculations add Sx, Sy, and Sz blocks, while phase-sensitive files include complex projections.
- Electronic structure projection: The projection data provide material details but can be too large for analysis without computational post-processing.PyProcar stores projections across every k-point, energy band, and crystal atom.
- Workflow and availability: PyProcar can generate KPOINTS files, process VASP PROCAR and OUTCAR outputs, and extend to other DFT codes through its flexible architecture.The library also provides installation and documentation through pip, GitHub, and an online user manual.
- PyProcar design: PyProcar separates parsing, utility, and selection tasks into loosely connected classes that organize data for later calculations and analysis.Core classes include ProcarParser, Utilsprocar, and ProcarSelect.
- PyProcar design: Utilsprocar reads Fermi energy and reciprocal lattice vectors, enabling Fermi-level shifts and conversion between direct and Cartesian k-mesh coordinates.These quantities may also be supplied manually through command-line inputs.
- PyProcar design: ProcarParser reads bands, k-points, and orbitals into memory and is resilient to fixed-format irregularities, while ProcarSelect isolates requested orbitals, atoms, or spin data.The parser handles issues such as missing blank spaces and *** index characters.
3. Examples: MgB2, BiSb, TaSb, and SrVO3
Examples using MgB2, BiSb, TaSb, and SrVO3 demonstrate PyProcar’s workflows for k-path generation, projected electronic structures, Fermi surfaces, spin textures, and topological-point analysis.
- Examples: The paper uses MgB2, BiSb, TaSb, and SrVO3 to illustrate PyProcar capabilities with DFT calculations performed primarily using VASP.The examples cover distinct materials and electronic-structure properties.
- Fermi surfaces and topology: MgB2 is used to demonstrate Fermi-surface plotting and band unfolding, while BiSb and TaSb demonstrate spin-texture and Weyl-point analysis.The examples use dedicated DFT settings for each material and capability.
- Generating a k-path: PyProcar automatically generates a suitable k-path from a crystal structure, typically read from POSCAR, using the seekpath library.Users can configure grid size, time reversal, recipe, and tolerance-related parameters.
3.3. Repair
PyProcar repairs malformed PROCAR files before analysis and supports multiple band-structure projection modes. These modes expose spin, atomic, and orbital contributions through color-coded plots that reveal material-specific electronic features.
- Repair: pyprocar.repair() fixes PROCAR formatting errors such as missing whitespace between numbers and negative signs.It is typically recommended before using other utilities.
- Band-structure modes: Plain band structures contain no projection information, while scatter, parametric, and atomic modes provide different visualization options.Parametric mode interpolates points into projectable bands, whereas atomic mode plots atomic energy levels.
- Spin projection: Spin projections separate collinear spin channels or noncollinear Sx, Sy, and Sz directions, with parametric mode required for these plots.For collinear calculations, spin=0 plots total density and spin=1 plots channels separately.
- Atom and orbital projections: Atomic and orbital projections identify which atoms and orbitals contribute to electronic bands, including states near the Fermi level.Multiple atom or orbital types can be projected simultaneously.
- Physical interpretation: Projected SrVO3 bands capture V-3d and O-2p contributions from -6 eV to -1 eV and show t2g states below eg states.The latter pattern reflects the expected octahedral crystal-field splitting.
3.6. 3D Fermi surface
PyProcar generates 3D Fermi surfaces colored by spin, atomic, orbital, or external properties, while interpolating eigenvalues and handling Brillouin-zone sampling for visualization.
- Surface generation and projections: PyProcar generates Fermi surfaces projected over spin, atoms, orbitals, or combinations of these properties.It can also project scalar or vector fields supplied through external momentum-space files.
- Mesh and Brillouin-zone handling: PyProcar uses Fourier interpolation for periodic eigenvalues and identifies first-Brillouin-zone points with reciprocal-lattice geometry and parallel processing.The procedure adds missing first-zone points rather than simply transforming outside points, avoiding iso-surface distortion.
- Surface generation and projections: The utility supports plain Fermi-surface plots and user-specified face colors, including the MgB2 example.Face colors are supplied as normalized (r,g,b) tuples.
- Surface generation and projections: PROCAR data can be combined across atom, orbital, and spin contributions, such as projecting selected Boron px, py, and pz orbitals onto MgB2 surfaces.The resulting contribution is summed and projected onto each surface face.
- External-property projection: External properties need not use the PROCAR mesh because PyProcar interpolates them and evaluates the field at each Fermi-surface face center.This supports properties such as Fermi velocity, electron-phonon coupling, and effective mass.
- External-property projection: External-file band data are matched positionally: the first supplied band maps to the first requested band, the second to the second, and so on.A MgB2 Fermi-velocity plot demonstrates the functionality, though Wannier interpolation can provide greater accuracy.
3.7. Handling big files: filtering the selected data and reducing the memory requirement for post-processing
PyProcar reduces post-processing costs for large PROCAR files by extracting only selected bands, especially those near the Fermi level, into a smaller file.
- Band filtering: PyProcar can generate a simpler PROCAR file containing only a selected subset of bands from a larger dataset.This is useful for heterostructures or supercell calculations with many bands.
- Band filtering: Filtering bands near the Fermi level considerably reduces file size and speeds post-processing.The example retains bands 50 through 70 while excluding bands farther from the Fermi level.
- Band filtering: The resulting PROCAR-repaired-band50-70 file supports further analysis with relatively low memory requirements.The filtered output is written as a new file for subsequent post-processing.
3.8. 2D spin-texture
PyProcar visualizes constant-energy 2D spin textures on centered k-space grids, supporting component maps or arrows to examine spin-splitting and related effects.
- Spin-texture visualization: The 2D spin-texture module visualizes constant-energy surfaces near a selected special k-point in the Brillouin zone.It requires a 2D k-grid centered on the k-point of interest.
- BiSb demonstration: BiSb spin projections Sx, Sy, and Sz are plotted on a kx-ky mesh centered at Γ, above and below the Fermi energy.The examples use E = EF + 0.60 eV for conduction bands and E = EF −0.90 eV for valence bands.
- BiSb demonstration: The BiSb plots reveal linear-in-k Rashba spin splitting above the Fermi level and additional k^3 warping effects in lower-energy valence bands.These effects are demonstrated at the two constant-energy surfaces shown in Figure 10.
- Spin-texture visualization: Spin texture can be rendered with arrows instead of a heat map by setting noarrow=False.Arrow plots can show spin direction or directional spin projections.
3.9. Identification of Weyl points
PyProcar identifies Weyl points by examining spin degeneracy and band dispersion near crossings. TaSb illustrates spin-projected bands containing both type-I and type-II Weyl points.
- Weyl points are topologically non-trivial gapless points formed when spin non-degenerate valence and conduction bands linearly cross near the Fermi level.
- Type-I Weyl points have untilted cones and crossing bands with opposite Fermi velocities, whereas type-II points have a different dispersion classification.The supplied passage introduces the type-II category but its description is truncated.
- PyProcar checks spin degeneracy and analyzes nearby band dispersion to determine the type of gapless point.
- TaSb hosts both type-I and type-II Weyl points, shown through spin-projected band structures near the crossing points.Figure 12 displays Sx projection, with colors indicating spin projection on the electronic bands.
3.10. Compare Bands
PyProcar provides tools for comparing band structures from different materials and combining separate PROCAR calculations. Comparisons use a common k-path, while concatenation assembles segments from distinct high-symmetry directions.
- Compare Bands: The bandscompare() module overlays bands from different materials on one plot using the same k-path for meaningful comparison.The compared structures may contain different numbers of k-points in each interval.
- Compare Bands: Legends and distinct marker styles help differentiate the two band structures in the comparison plot.
- Compare Bands: Multiple PROCAR files from separate DFT calculations can be combined with PyProcar utilities.This supports workflows where large-system calculations are split across separate runs.
- Compare Bands: Bandstructure segments calculated along Γ-K, K-M, and M-Γ can be concatenated into one full bandstructure plot.
- Compare Bands: The workflow also provides commands for concatenating PROCAR files generated by Abinit.
3.12. Band Unfolding
Band unfolding represents supercell bands within the primitive-cell Brillouin zone, addressing the difficulty caused by Brillouin-zone folding. PyProcar uses unfolding weights to highlight the resulting bands.
- Band Unfolding: Supercell Brillouin-zone folding makes comparison with primitive-cell band structures difficult.
- Band Unfolding: Band unfolding represents supercell bands within the primitive-cell Brillouin zone.
- Band Unfolding: Unfolding weights are plotted as fat-band line widths, making bands with larger weights more prominent.Figure 14 uses blue-line width to denote unfolding weight, while gray lines show the original bands.
- Band Unfolding: The demonstrated example unfolds a 2×2×2 MgB2 supercell, including a case where one B atom is replaced by Al.
- Band Unfolding: The PROCAR must include phase factors, obtained in VASP by setting LORBIT=12, before using the unfold module.
4. Conclusion
PyProcar is presented as an open-source Python library for DFT electronic-structure pre- and post-processing. The authors conclude that its accessible format support and user-oriented capabilities can aid computational materials research.
- PyProcar is a user-friendly, open-source Python library for DFT pre- and post-processing calculations.
- The library projects spin, orbital, and atomic contributions in band structures and two- and three-dimensional Fermi or constant-energy surfaces.
- PyProcar is freely available through GitHub and pip, with an accompanying user manual.
- Because PROCAR is easy to implement in DFT codes, PyProcar is accessible across a wide range of DFT codes.