Key Features & Optimizations

Optimized for High-Throughput (Caching)

Unlike standard pymatgen tools, this library is specifically designed to handle huge numbers of VASP outputs efficiently.

  • Persistent Caching: The core IMDGVaspDir class implements a persistent disk cache (stored in ~/.cache/imdgVASPDIRcache or XDG_CACHE_HOME).

  • Lazy Loading: Parsed VASP data is cached automatically. Subsequent analysis of the same directories is orders of magnitude faster, making it feasible to analyze thousands of calculations repeatedly without re-parsing XML or OUTCAR files.

Automated Health Checks & Warnings

The library proactively monitors VASP calculations for common pitfalls, essential for reliable high-throughput workflows:

  • VASP Warnings: Automatically parses logs (e.g., vasp.out, slurm*.out) to surface execution warnings like convergence failures or grid errors.

  • Structural Integrity: Checks for physical anomalies during relaxation to catch problems early:

    • Large Displacements: Warns if atoms move significantly more than expected (e.g., indicating bond breaking or phase instability).

    • Symmetry Changes: Detects if the framework symmetry breaks during relaxation, which often indicates a failed calculation or unwanted phase transition.

    • Stress & Forces: Monitors for unexpected hydrostatic stress or excessive residual forces.

Example output:

img

Extensions to pymatgen

While heavily based on pymatgen, this library introduces several key differences:

  • imdg analyze vs pmg analyze

    • The imdg analyze command is built on the caching IMDGVaspDir class.

    • It focuses on relative changes: instead of just reporting absolute values, it calculates changes between the initial and final structures (e.g., volume change %vol, lattice parameter changes %a, %b, %c, and total atomic displacement displ).

    • It supports grouping runs by identical INCAR parameters to easily compare different calculation settings.

  • Enhanced Input Sets: New input sets like IMDDerivedInputSet allow deriving new calculations (relaxations, strains, NEB) directly from existing output directories, preserving context/history.

Getting Help

Command Line

You can get help for any command directly in the terminal:

# General help and list of subcommands
imdg --help

# Help for a specific subcommand (e.g., arguments for analyze)
imdg analyze --help
imdg derive . ins --help

Python Code

All classes and functions are documented with docstrings. You can access them using Python’s built-in help() function:

from IMDgroup.pymatgen.io.vasp.vaspdir import IMDGVaspDir
help(IMDGVaspDir)

Installation

git clone https://git.sr.ht/~yantar92/IMDgroup-pymatgen
cd IMDgroup-pymatgen
pip install .