Pymatgen I/O Validation

0.1.2 · active · verified Thu Apr 16

Pymatgen-io-validation is a Python library, currently at version 0.1.2, that extends the pymatgen framework to provide comprehensive I/O validation for electronic structure calculations. It primarily focuses on ensuring VASP calculations are compliant with the stringent standards required for integration with the Materials Project database. The library helps identify discrepancies between a calculation and a provided input set, flags known bugs related to parameter combinations, and performs other critical checks. Its release cadence typically involves minor updates to address dependencies and improve validation logic.

Common errors

```
Calculation invalid: ADDGRID must be set to False.
```
cause The VASP INCAR file contains `ADDGRID = True` or `ADDGRID` is not explicitly set (which might default to True in some VASP versions or setups), violating Materials Project standards.

fix Modify your INCAR file to include `ADDGRID = False`. This parameter can affect forces, and MP calculations require it to be false for compatibility.
```
Calculation invalid: ISIF values must be one of: -1, 1, 2.
```
cause The VASP INCAR file specifies `ISIF` as a value other than -1, 1, or 2, which are the only values compatible with Materials Project standards for structural relaxations.

fix Adjust the `ISIF` parameter in your INCAR file to `-1` (no relaxation), `1` (cell shape and volume fixed), or `2` (cell shape fixed, volume allowed to change).
```
ModuleNotFoundError: No module named 'pymatgen.io.validation'
```
cause The `pymatgen-io-validation` package has not been installed, or the Python environment is not correctly configured.

fix Install the package using pip: `pip install pymatgen-io-validation`. Ensure your Python environment is active if using a virtual environment.

Warnings

gotcha The validator enforces strict adherence to Materials Project (MP) standards for VASP input parameters (e.g., INCAR tags like ADDGRID, ISIF, ISYM, IVDW, PREC, NBANDS, ALGO, LORBIT, LREAL, ICHARG, IBRION). Calculations not meeting these specific requirements will be flagged as invalid or generate warnings, even if VASP itself runs successfully.
Fix: Consult the Materials Project documentation or the pymatgen-io-validation source code (especially the Rationale section in the GitHub README) for detailed parameter requirements. Ensure your VASP input files align with these standards to pass validation.
gotcha The validator explicitly checks for allowed VASP versions. For instance, VASP versions <= 5.4.3 are not allowed, while 5.4.4 or >6.0.0 are accepted. Using an unsupported VASP version will lead to validation failure.
Fix: Ensure your VASP executable version is compatible with the Materials Project standards. Update VASP to a supported version if necessary (e.g., 5.4.4 or above 6.0.0).
gotcha Calculations might generate a warning related to 'Electronic entropy too large (SIGMA too high)'. This indicates that the SIGMA parameter in the INCAR file is set too high, potentially leading to inaccurate results or numerical issues.
Fix: Review and reduce the SIGMA parameter in your VASP INCAR file to a more appropriate value. Version 0.0.3 improved the detection logic for this specific issue.
breaking Pymatgen itself underwent a significant architectural change (v2022.0.3 onwards) by adopting namespace packages, which affects how some modules are imported. While `pymatgen-io-validation` is designed as a namespace package, older client code that directly imported from `pymatgen` for functionalities now residing in separate add-ons (including `pymatgen.io` components) might break if not updated to use explicit subpackage imports.
Fix: If encountering import errors with related `pymatgen` components, ensure your `pymatgen` installation is recent (>=2022.0.3) and update import statements to explicitly reference subpackages (e.g., `from pymatgen.io.vasp import Poscar` instead of `from pymatgen import Poscar` if such a pattern was ever used).

Install

pip install pymatgen-io-validation PyPI

Imports

VaspValidator

from pymatgen.io.validation import VaspValidator

Quickstart

This quickstart demonstrates how to instantiate `VaspValidator` from a VASP calculation directory and check its validity, reasons for invalidation, and any warnings. The `from_directory` class method automatically parses the necessary VASP input and output files to perform the checks. The `valid`, `reasons`, and `warnings` attributes of the returned `validation_doc` object provide a comprehensive report.

import os
from pymatgen.io.validation import VaspValidator

# Assuming 'path_to_vasp_calculation_directory' contains VASP input/output files (e.g., INCAR, KPOINTS, POSCAR, OUTCAR)
# For a runnable example, we'll create a dummy directory and files.
# In a real scenario, this path would point to your actual VASP calculation directory.

dummy_vasp_dir = "./dummy_vasp_calc"
os.makedirs(dummy_vasp_dir, exist_ok=True)

with open(os.path.join(dummy_vasp_dir, "INCAR"), "w") as f:
    f.write("ENCUT = 520\nISIF = 2\nISYM = 2\nPREC = Accurate\nALGO = Fast\n")
with open(os.path.join(dummy_vasp_dir, "POSCAR"), "w") as f:
    f.write("Dummy structure\n1.0\n1.0 0.0 0.0\n0.0 1.0 0.0\n0.0 0.0 1.0\nFe\n1\nDirect\n0.0 0.0 0.0\n")
# Add other necessary dummy files (KPOINTS, POTCAR) for a full run if needed, 
# but the example focuses on VaspValidator usage structure.

# Validate a VASP calculation from its directory
validation_doc = VaspValidator.from_directory(dummy_vasp_dir)

print(f"Calculation is valid: {validation_doc.valid}")
if not validation_doc.valid:
    print("Reasons for invalidation:")
    for reason in validation_doc.reasons:
        print(f"- {reason}")
if validation_doc.warnings:
    print("Warnings:")
    for warning in validation_doc.warnings:
        print(f"- {warning}")

# Clean up dummy files
os.remove(os.path.join(dummy_vasp_dir, "INCAR"))
os.remove(os.path.join(dummy_vasp_dir, "POSCAR"))
os.rmdir(dummy_vasp_dir)

view raw JSON →