{"id":9386,"library":"vasprun-xml","title":"vasprun-xml: VASP XML Analyzer","description":"vasprun-xml is a Python package designed for rapid analysis of VASP calculation results directly from the `vasprun.xml` file. It supports features like band gap calculation, plotting of Density of States (DOS) and band structures, generation of INCAR/POTCAR/POSCAR files, force analysis, and Kohn-Sham orbital eigenvalue analysis. The current PyPI version is 1.0.4, with active development and regular updates.","status":"active","version":"1.0.4","language":"en","source_language":"en","source_url":"https://github.com/qzhu2017/vasprun","tags":["VASP","materials science","DFT","computational chemistry","XML parsing"],"install":[{"cmd":"pip install vasprun-xml","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for efficient XML parsing.","package":"lxml","optional":false},{"reason":"Essential for generating DOS and band structure plots.","package":"matplotlib","optional":false},{"reason":"Core numerical computing library for data manipulation.","package":"numpy","optional":false},{"reason":"Used for scientific computing, potentially for data processing or smearing.","package":"scipy","optional":false},{"reason":"Data structures and analysis tools.","package":"pandas","optional":false}],"imports":[{"symbol":"vasprun","correct":"from vasprun import vasprun"}],"quickstart":{"code":"import os\nfrom vasprun import vasprun\n\n# Create a dummy vasprun.xml for demonstration or ensure one exists\n# In a real scenario, this file would be generated by a VASP calculation.\n# For quickstart, we'll assume 'vasprun.xml' exists in the current directory.\n# Example: Create a minimal mock file if not present (not a full VASP XML)\nif not os.path.exists('vasprun.xml'):\n    with open('vasprun.xml', 'w') as f:\n        f.write('<modeling><calculator><parameters></parameters></calculator></modeling>')\n\n# Load the vasprun.xml file\nvasp_data = vasprun('vasprun.xml')\n\n# Check if the calculation converged or for errors\nif vasp_data.error:\n    print(f\"VASP calculation reported an error: {vasp_data.errormsg}\")\nelse:\n    print(\"VASP calculation completed successfully.\")\n\n# Extract basic information\nprint(f\"Formula: {vasp_data.values.get('formula', 'N/A')}\")\nprint(f\"Band Gap (eV): {vasp_data.values.get('gap', 'N/A')}\")\n\n# Example: Plot DOS (requires a full vasprun.xml with DOS data)\n# vasp_data.plot_dos(filename='dos_plot.png', styles='t')\n# print(\"DOS plot generated as dos_plot.png\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your environment uses Python 3.6.1 or newer. Upgrade your Python installation if necessary.","message":"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.","severity":"breaking","affected_versions":"<3.6.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of vasprun-xml (dependent on VASP output)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (dependent on VASP version)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `vasprun.xml` file is incomplete or malformed, typically because the VASP job was terminated before the XML file could be fully written.","error":"lxml.etree.XMLSyntaxError: Premature end of data in tag ..."},{"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.","cause":"The Python package is named `vasprun-xml` on PyPI, but the import statement should use `vasprun` as the top-level module name.","error":"ModuleNotFoundError: No module named 'vasprun'"},{"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.","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.","error":"AttributeError: 'Vasprun' object has no attribute 'plot_dos'"}]}