Machine Learned Interatomic Potentials - Training Suite (MLIPTS).

MLIPTS is a python package for training/fine-tuning machine learned interatomic potentials.

The key idea is to perform the following active learning workflow [1] with as little user input as possible:

<p align="center"> <img src="https://github.com/williamdavie/mlipts/blob/docs-edit/media/active_learning_flowchart.png" width="50%" height="auto"> </p>

[!NOTE] The scope of a fully-fledged python package to perform seemless MLIP training is significant, with many availible MD and DFT/Quantum Chemistry codes and ways to quantify data quality. Contributors are welcome to help make this goal a reality.

Version 0.1.0

Installation

MLIPTS can be installed via pip

pip install mlipts

Capability

0.1.0 is built to address the creation of an inital data set (Part 1 of the workflow above), however, note part of the current functionality is applicable across the main workflow, ultimately arriving at the following reduced workflow to address:

<p align="center"> <img src="https://github.com/williamdavie/mlipts/blob/docs-edit/media/workflow_%231.png" width="50%" height="auto"> </p>

The MD code supported is LAMMPS and DFT code supported is VASP, where the earth movers distance (EMD) has been implemented to filter configurations. The details of this method are found at [2] and average-minimum-distance (Copyright (C) 2025 Daniel Widdowson).

Usage

It is highly recommended to follow the availible example at PuO2_example.

The working directory is set up in the following way:

collect_data/
├─ MD_base/
├─ QM_base/
└─ workflow.ipynb

Where MD_base and QM_base include the input files for molecular dynamics and quantum mechanical simulations respectively. Since the current version only supports lammps and vasp, these directories will have the following format:

├─ lammps_base/
    ├─ in.test
    └─ test.dat
├─ vasp_base/
    ├─ INCAR
    ├─ KPOINTS
    └─ POTCAR

Noting POSCAR is intentially missing as this is to be generated.

[!TIP] The key to a successful data collection workflow is ensuring all files in the above are formatted correctly, so it is recommend to test each base directory. Collection of the full datase will be calling each calculation many times.

With a directory set up, mlipts allows simply following of the flow chart above:

1. Run many MD calculations:

workflow.build_MD_calculations('./lammps_base',variables,outdir='./MD_calculations')
workflow.write_MD_submission_scripts(MD_cmd_line,submit=True)

2. Filter new configurations from MD:

workflow.filter_active_MD(tol=0.1)

where tol defines a tolerence to keep or remove a configuration, i.e. if the earth movers distance (emd) between two configurations is less than tol one of the configurations is dropped.

[!NOTE] The emd is calculated between each pair of configurations and therefore can be costly.

3. Run DFT calculations on new configurations

workflow.write_QM_submission_scripts(QM_cmd_line,save_and_remove=True,submit=True)

where save_and_remove is an option to save the data from each QM calculation while running. Its default is True.

[!NOTE] save and remove uses a python enviroment with mlipts installed and utlizes py4vasp (requiring VASP version>6.2).

The final workflow will then appear as,

collect_data/
├─ MD_base/
├─ MD_calculations/
├─ MD_scripts/
├─ QM_base/
├─ QM_calculations/
├─ QM_scripts/
├─ workflow.ipynb
└─ training_data.xyz

and training_data_xyz can be passed into MACE [2] or reformatted for other MLIP architechtures.

References

[1] Jacobs, Ryan, et al. "A practical guide to machine learning interatomic potentials–Status and future." Current Opinion in Solid State and Materials Science 35 (2025): 101214.

[2] Widdowson, Daniel, and Vitaliy Kurlin. "Pointwise distance distributions for detecting near-duplicates in large materials databases." arXiv preprint arXiv:2108.04798 (2021).

[3] Batatia, Ilyes, et al. "MACE: Higher order equivariant message passing neural networks for fast and accurate force fields." Advances in neural information processing systems 35 (2022): 11423-11436.

Contact

William Davie, willdavie2002@gmail.com.

Department of Material Science and Metallurgy, University of Cambridge.