{"id":10076,"library":"py4vasp","title":"py4vasp","description":"py4vasp is a Python interface for analyzing and setting up VASP calculations, primarily by extracting data from the new HDF5 file format (`VASP_H5_data.h5`). It's designed for quick data inspection, plotting, and export to other tools, serving as a powerful assistant for materials science researchers working with VASP output. The library is actively developed, with regular releases providing new features and improvements.","status":"active","version":"0.11.2","language":"en","source_language":"en","source_url":"https://github.com/vasp-dev/py4vasp","tags":["vasp","materials-science","physics","data-analysis","hdf5","quantum-mechanics"],"install":[{"cmd":"pip install py4vasp","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core for reading VASP HDF5 data","package":"h5py","optional":false},{"reason":"Numerical operations and array handling","package":"numpy","optional":false},{"reason":"Scientific computing routines, often used for data processing","package":"scipy","optional":false},{"reason":"Plotting and visualization of VASP data","package":"matplotlib","optional":false},{"reason":"Configuration and serialization","package":"pyyaml","optional":false}],"imports":[{"symbol":"py4vasp","correct":"import py4vasp as pv"},{"note":"The Calculation class is exposed directly under the top-level package since v0.10.0. Older versions might have used different paths or initialization.","wrong":"from py4vasp.raw import Calculation","symbol":"Calculation","correct":"from py4vasp import Calculation"}],"quickstart":{"code":"import py4vasp as pv\nimport matplotlib.pyplot as plt\nimport os\n\n# This example assumes a VASP calculation's output files\n# (especially VASP_H5_data.h5) are present in the 'example_calc_path' directory.\n# Replace 'example_calc_path' with the actual directory containing your VASP output.\n# For demonstration, we use a placeholder and handle potential errors.\n\n# If you have VASP output in a specific directory, set it here:\nexample_calc_path = os.environ.get(\"VASP_CALC_PATH\", \".\") # Defaults to current directory\n\ntry:\n    # Initialize a Calculation object from the path\n    calc = pv.Calculation(example_calc_path)\n\n    # Access and plot the Density of States (DOS)\n    if hasattr(calc, 'dos') and calc.dos.is_readable():\n        print(f\"Loading DOS from: {example_calc_path}\")\n        dos_plot = calc.dos.plot()\n        # dos_plot.show() # Uncomment to display the plot (requires matplotlib backend)\n\n        # Export DOS data to a dictionary\n        dos_data = calc.dos.to_dict()\n        print(\"DOS data keys:\", dos_data.keys())\n    else:\n        print(f\"DOS data not found or not readable in '{example_calc_path}'.\")\n        print(\"Ensure VASP_H5_data.h5 exists and contains DOS information.\")\n\nexcept Exception as e:\n    print(f\"Error accessing VASP calculation at '{example_calc_path}': {e}\")\n    print(\"Please ensure the path is correct and contains valid VASP HDF5 output files.\")\n\n# Example of accessing the band structure data object directly\nbands_object = pv.data.band()\nprint(f\"\\nExample of accessing band structure data object: {bands_object}\")\n# bands_object.plot().show() # Would require a VASP_H5_data.h5 with band data","lang":"python","description":"This quickstart demonstrates how to initialize a `Calculation` object from a VASP output directory, access common data types like the Density of States (DOS), plot them, and export them to a Python dictionary. It includes error handling for cases where VASP output files are missing or incomplete."},"warnings":[{"fix":"Update your code to use `py4vasp.data.Kpoints` and call the `.plot()` method directly on data objects, e.g., `calc.bands.plot()` instead of `calc.bands.plot_bands()`.","message":"Significant API changes occurred in v0.11.0. The `Kpoint` class was renamed to `Kpoints`, and specific plotting methods (e.g., `plot_bands()`, `plot_dos()`) were consolidated into a generic `.plot()` method available on data objects.","severity":"breaking","affected_versions":">=0.11.0"},{"fix":"Consult the `py4vasp` documentation for the specific data type you are working with. Data is now typically accessed directly as attributes (e.g., `calc.dos.energies`) or by passing arguments to methods like `.to_dict()` or `.plot()`.","message":"In v0.10.0, the explicit `Selection` class for filtering data was removed and replaced by direct attribute access or arguments passed to data access and plotting methods. The `.read()` method on data objects was also deprecated.","severity":"breaking","affected_versions":">=0.10.0"},{"fix":"Always provide the correct absolute or relative path to your VASP calculation directory: `calc = pv.Calculation('/absolute/path/to/my_vasp_output')` or ensure your script's working directory is the calculation directory.","message":"When initializing `pv.Calculation(path)`, py4vasp expects the VASP output files (especially `VASP_H5_data.h5`) to be located at the specified `path` or in the current working directory. If your script is run from a different location, it will fail to find the files.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure your VASP version (VASP 6+) is configured to produce `VASP_H5_data.h5`. Check that the file exists in the directory passed to `pv.Calculation()` or the current working directory. If you are using an older VASP version, py4vasp will not work without manual data conversion.","cause":"The VASP HDF5 output file is missing or located in a different directory than specified. This often happens with older VASP versions (pre-VASP 6), calculations that failed before HDF5 output, or incorrect paths.","error":"FileNotFoundError: VASP_H5_data.h5"},{"fix":"Update your code to use the generic `.plot()` method. For example, change `calc.bands.plot_bands()` to `calc.bands.plot()` and `calc.dos.plot_dos()` to `calc.dos.plot()`.","cause":"In py4vasp v0.11.0 and later, specific plotting methods like `plot_bands()` or `plot_dos()` were consolidated into a single, generic `.plot()` method available on data objects.","error":"AttributeError: 'SomeDataObject' object has no attribute 'plot_bands'"},{"fix":"Re-run the VASP calculation to ensure it completes successfully and generates a valid HDF5 file. Check the file size; a very small `VASP_H5_data.h5` often indicates a truncated or empty file. You can also use `h5dump` or `h5ls` command-line tools to inspect the file integrity.","cause":"The `VASP_H5_data.h5` file is corrupted, incomplete, or not a valid HDF5 file. This can occur if a VASP calculation was interrupted prematurely or if the file was transferred incorrectly.","error":"OSError: Unable to open file (file is not an HDF5 file) or OSError: Unable to open file (file is truncated)"},{"fix":"Verify that your VASP input files (e.g., INCAR, KPOINTS) were correctly configured to perform the calculation that generates the desired data. Refer to the VASP manual for required tags. You can inspect the contents of `VASP_H5_data.h5` using `h5ls VASP_H5_data.h5` to see what data is actually available.","cause":"The specific data requested (e.g., Density of States, Band Structure, specific magnetic moments) was not calculated in the VASP run, or it is not present in the `VASP_H5_data.h5` output file.","error":"KeyError: 'Some_Expected_Data_Key' or AttributeError: 'Calculation' object has no attribute 'some_data_type'"}]}