vasprun-xml: VASP XML Analyzer

Common errors

• lxml.etree.XMLSyntaxError: Premature end of data in tag ...

  cause The `vasprun.xml` file is incomplete or malformed, typically because the VASP job was terminated before the XML file could be fully written.
  fix Verify that your VASP calculation completed successfully. If not, re-run the calculation ensuring a graceful termination. For partially written files, try opening the XML in a text editor to identify and potentially manually fix truncation points, though a re-run is generally more reliable.

• ModuleNotFoundError: No module named 'vasprun'

  cause The Python package is named `vasprun-xml` on PyPI, but the import statement should use `vasprun` as the top-level module name.
  fix Use `from vasprun import vasprun` or `import vasprun` in your Python code. The installation command `pip install vasprun-xml` installs the package under the `vasprun` module name.

• AttributeError: 'Vasprun' object has no attribute 'plot_dos'

  cause This error can occur if `matplotlib` (a required dependency for plotting) is not installed, or if the `vasprun.xml` file being parsed does not contain the necessary density of states (DOS) or band structure data for plotting.
  fix First, ensure `matplotlib` is installed (`pip install matplotlib`). Second, confirm that your `vasprun.xml` file contains the relevant sections (e.g., `EIGENVAL` for bands, `DOS` for density of states) as output by VASP.

Warnings

• breaking The `vasprun-xml` library explicitly requires Python 3. Support for Python 2.x is not provided, and attempts to use it with Python 2 will result in compatibility errors.
  Fix: Ensure your environment uses Python 3.6.1 or newer. Upgrade your Python installation if necessary.
• gotcha VASP's `vasprun.xml` can become corrupted or malformed if the VASP calculation terminates abruptly (e.g., due to system errors or manual termination), especially common with GPU VASP runs. This often leads to 'XML not well-formed' errors during parsing.
  Fix: Ensure VASP calculations terminate gracefully. If using a job scheduler or workflow manager, implement mechanisms for graceful termination (e.g., writing a `STOPCAR` file). For existing corrupted files, manual editing may be required, or the VASP calculation must be re-run.
• gotcha The internal structure of `vasprun.xml` can vary between major VASP versions (e.g., VASP 5 vs. VASP 6), which might affect how `vasprun-xml` parses certain data fields or lead to missing information for newer VASP features. While the library strives for robustness, significant schema changes may not be immediately supported.
  Fix: Consult the `vasprun-xml` documentation or GitHub issues for known compatibility notes with specific VASP versions. If encountering parsing issues, verify the XML structure against an expected format for your VASP version.

Install

• pip install vasprun-xml Install with pip

Imports

• vasprun

  from vasprun import vasprun

Quickstart

Initializes the `vasprun` parser with a `vasprun.xml` file, then demonstrates how to check for calculation errors and extract basic properties like chemical formula and band gap. Note that plotting functions require a complete `vasprun.xml` containing the relevant data sections.

import os
from vasprun import vasprun

# Create a dummy vasprun.xml for demonstration or ensure one exists
# In a real scenario, this file would be generated by a VASP calculation.
# For quickstart, we'll assume 'vasprun.xml' exists in the current directory.
# Example: Create a minimal mock file if not present (not a full VASP XML)
if not os.path.exists('vasprun.xml'):
    with open('vasprun.xml', 'w') as f:
        f.write('<modeling><calculator><parameters></parameters></calculator></modeling>')

# Load the vasprun.xml file
vasp_data = vasprun('vasprun.xml')

# Check if the calculation converged or for errors
if vasp_data.error:
    print(f"VASP calculation reported an error: {vasp_data.errormsg}")
else:
    print("VASP calculation completed successfully.")

# Extract basic information
print(f"Formula: {vasp_data.values.get('formula', 'N/A')}")
print(f"Band Gap (eV): {vasp_data.values.get('gap', 'N/A')}")

# Example: Plot DOS (requires a full vasprun.xml with DOS data)
# vasp_data.plot_dos(filename='dos_plot.png', styles='t')
# print("DOS plot generated as dos_plot.png")