py4vasp

Common errors

• FileNotFoundError: VASP_H5_data.h5

  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.
  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.

• AttributeError: 'SomeDataObject' object has no attribute 'plot_bands'

  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.
  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()`.

• OSError: Unable to open file (file is not an HDF5 file) or OSError: Unable to open file (file is truncated)

  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.
  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.

• KeyError: 'Some_Expected_Data_Key' or AttributeError: 'Calculation' object has no attribute 'some_data_type'

  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.
  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.

Warnings

• breaking 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.
  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()`.
• breaking 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.
  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()`.
• gotcha 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.
  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.

Install

• pip install py4vasp Install stable version

Imports

• py4vasp

  import py4vasp as pv

• Calculation
  wrong:

  from py4vasp.raw import Calculation

  correct:

  from py4vasp import Calculation

  The Calculation class is exposed directly under the top-level package since v0.10.0. Older versions might have used different paths or initialization.

Quickstart

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.

import py4vasp as pv
import matplotlib.pyplot as plt
import os

# This example assumes a VASP calculation's output files
# (especially VASP_H5_data.h5) are present in the 'example_calc_path' directory.
# Replace 'example_calc_path' with the actual directory containing your VASP output.
# For demonstration, we use a placeholder and handle potential errors.

# If you have VASP output in a specific directory, set it here:
example_calc_path = os.environ.get("VASP_CALC_PATH", ".") # Defaults to current directory

try:
    # Initialize a Calculation object from the path
    calc = pv.Calculation(example_calc_path)

    # Access and plot the Density of States (DOS)
    if hasattr(calc, 'dos') and calc.dos.is_readable():
        print(f"Loading DOS from: {example_calc_path}")
        dos_plot = calc.dos.plot()
        # dos_plot.show() # Uncomment to display the plot (requires matplotlib backend)

        # Export DOS data to a dictionary
        dos_data = calc.dos.to_dict()
        print("DOS data keys:", dos_data.keys())
    else:
        print(f"DOS data not found or not readable in '{example_calc_path}'.")
        print("Ensure VASP_H5_data.h5 exists and contains DOS information.")

except Exception as e:
    print(f"Error accessing VASP calculation at '{example_calc_path}': {e}")
    print("Please ensure the path is correct and contains valid VASP HDF5 output files.")

# Example of accessing the band structure data object directly
bands_object = pv.data.band()
print(f"\nExample of accessing band structure data object: {bands_object}")
# bands_object.plot().show() # Would require a VASP_H5_data.h5 with band data