IonDiff

Despite playing a central role in the design of high performance solid-state electrolytes, little is known about the processes governing ionic diffusion in these materials and the spatio-temporal correlations acting on migrating particles. Computer simulations can reproduce the trajectories of individual diffusing ions in real time with extraordinary accuracy, thus providing incredibly valuable atomistic data that in practice cannot be resolved by experiments.

However, the identification of hopping events in computer simulations typically relies on active supervision and definition of arbitrary material-dependent geometrical parameters, thus frustrating high throughput screenings of diffusing paths and mechanisms across simulation databases and the assessment of many-diffusing-ion correlations.

Here, we introduce a novel approach for analyzing ion hopping events in molecular dynamics (MD) simulations in a facile and totally unsupervised manner, what would allow the extraction of completely new descriptors related to these diffusions. Our approach relies on the k-means clustering algorithm and allows to identify with precision which and when particles diffuse in a simulation and the exact migrating paths that they follow as well.

Documentation showing functionality and usage of the code are provided one the docs site. Please be aware that the code is under active development, bug reports are welcomed in the GitHub issues!

Installation

IonDiff can be installed from PyPI:

pip3 install IonDiff

or installed from source:

git clone https://github.com/IonRepo/IonDiff.git
cd IonDiff
pip3 install .

or used directly from source without explicit installation:

git clone https://github.com/IonRepo/IonDiff.git
cd IonDiff
pip3 install -r docs/requirements.txt

Execution

To extract the diffusion paths from a XDATCAR simulation file (with its corresponding INCAR file) located at examples folder, from the IonDiff folder run:

python3 cli.py identify_diffusion --MD_path examples/LLZO/400K

To analyze temporal correlations among the diffusions of different simulations, from the IonDiff folder run:

python3 cli.py analyze_correlations --MD_path examples

and to extract atomistic descriptors from the simulations and diffusion events run:

python3 cli.py analyze_descriptors --MD_path examples/LLZO/400K

where it has to be provided a file named DIFFUSION_paths, as in examples folder, for which each line represents the relative path to a simulation folder which is to be considered, name of the compound, its stoichiometricity/polymorf and the temperature of simulation. Each folder must contain a XDATCAR simulation file (with its corresponding INCAR file).

An ab initio MD simulation based on density functional theory of non-stoichiometric Li₇La₃Zr₂O₁₂ (LLZO) fast-ion conductor at temperatures of 400K and 800K are provided to run as examples:

• INCAR: Basic parameters of the simulation (only POTIM and NBLOCK flags are considered).
• XDATCAR: Concatenation of all simulated configurations (recorded each NBLOCK simulation steps).
• README.md: More specific information regarding these files.

Input trajectories

The IonDiff code can be perfectly used by any scientist performing either classical molecular dynamics simulations (classical MD) or ab initio molecular dynamics simulations (AIMD). In both types of simulations, atomic trajectories are generated and this is the main input information that the IonDiff code necessitates to perform its correlation and ionic hopping analysis. In other words, the IonDiff analysis does not depend on how the atomic forces are calculated in the undertaken molecular dynamics simulations, whether these are obtained through classical force fields or quantum mechanical methods (e.g., density functional theory). As far as the output trajectory files generated by any classical MD code can be converted to the output trajectory file format of VASP, the IonDiff code can be purposely employed.

There is already a myriad of open-source codes and scripts that can be used for this end, namely, to convert a trajectory file generated by a classical MD code to the VASP format, like, for instance, LAVA or xfroggie (to convert from LAMMPS or GROMACS format to VASP format, respectively).

References and citing

If you use this repository in your work, please consider citing:

López et al., (2024). IonDiff: command-line tool to identify ionic diffusion events and hopping correlations in molecular dynamics simulations. JOSS, 9(99), 6616

Authors

IonDiff is being developed by:

• Cibrán López
• Riccardo Rurali
• Claudio Cazorla

Contact, questions and contributing

If you have questions, please don't hesitate to reach out at: cibran.lopez@upc.edu