autoplex is a software for generating and benchmarking machine learning (ML)-based interatomic potentials. The aim of autoplex is to provide a fully automated solution for creating high-quality ML potentials. The software is interfaced to multiple different ML potential fitting frameworks and to the atomate2 and ase environments for efficient high-throughput computations. The vision of this project is to allow a wide community of researchers to create accurate and reliable ML potentials for materials simulations.

autoplex is developed jointly by two research groups at BAM Berlin and the University of Oxford.

autoplex is an evolving project and contributions are very welcome! To ensure that the code remains of high quality, please raise a pull request for any contributions, which will be reviewed before integration into the main branch of the code. Initially, @JaGeo will handle the reviews.

Workflow overview

We currently have two different types of automation workflows available:

• Workflow to use random-structure searches for the systematic construction of interatomic potentials: arXiv: 10.48550/arXiv.2412.16736. The implementation automates ideas from the following articles: Phys. Rev. Lett. 120, 156001 (2018) and npj Comput. Mater. 5, 99 (2019).
• Workflow to train accurate interatomic potentials for harmonic phonon properties. The implementation automates the ideas from the following article: J. Chem. Phys. 153, 044104 (2020).

Documentation

You can find the autoplex documentation here! The documentation also contains tutorials that teach you how to use autoplex for different use cases for the RSS and phonon workflows and individual modules therein.

What to cite?

Please cite our publication introducing autoplex:

Y. Liu, J. D. Morrow, C. Ertural, N. L. Fragapane, J. L. A. Gardner, A. A. Naik, Y. Zhou, J. George, V. L. Deringer, Nat Commun 16, 7666 (2025). https://doi.org/10.1038/s41467-025-62510-6.

Please additionally cite all relevant software we rely on within autoplex and specific workflows. Please take a look below and check out the corresponding links.

Before you start using autoplex

We expect the general user of autoplex to be familiar with the Materials Project framework software tools and related packages for (high-throughput) workflow submission and management. This involves the following software packages:

• pymatgen for input and output handling of computational materials science software,
• atomate2 for providing a library of pre-defined computational materials science workflows,
• jobflow for processes, job and workflow handling,
• jobflow-remote or FireWorks for workflow and database (MongoDB) management,
• MongoDB as the database (we recommend installing the MongoDB community edition). More help regarding the MongoDB installation can be found here.

All of these software tools provide documentation and tutorials. Please take your time and check everything out! Please also cite the software packages if you are using them!

Setup

To set up the mandatory prerequisites for using autoplex, please follow the installation guide of atomate2.

After setting up atomate2, make sure to add VASP_INCAR_UPDATES: {"NPAR": number} in your ~/atomate2/config/atomate2.yaml file. Set a number that is a divisor of the number of tasks you use for the VASP calculations.

Installation

Python version

Before the installation, please make sure that you are using one of the supported Python versions (see pyproject.toml)

Standard installation

Only for Python 3.10

phonopy is normally installed automatically as a dependency through atomate2. However, build failures with newer scikit-build-core versions may prevent this. To avoid installation issues, install the phonopy build dependencies and phonopy separately before installing this package. Use the following commands:

pip install "scikit-build-core<0.10"
pip install setuptools-scm>=8.0 nanobind
pip install --no-build-isolation phonopy==2.30.1

Once this is done, you can install autoplex simply by:

For 3.10<=Python<=3.12

Basic installation

pip install autoplex[strict-base]

This will install all Python packages dependencies needed for GAP MLIP fits.

Other currently supported MLIPs fittings can be enabled as per needs with either of the following commands:

pip install autoplex[strict-matgl]
pip install autoplex[strict-nequip]
pip install autoplex[strict-nep]
pip install autoplex[pacemaker]
pip install autoplex[aims]

ℹ️ For fitting M3GNet models, additionally, dgl needs to be installed from source repository as necessary version for magl is not available directly available via PyPi. This can be done using following command:

pip install 'dgl==2.4.0' -f 'https://data.dgl.ai/wheels/torch-2.4/repo.html'

ℹ️ To fit and validate ACEpotentials, one also needs to install Julia, as autoplex relies on ACEpotentials, which supports fitting of linear ACE. Currently, no Python package exists for the same. Please run the following commands to enable the ACEpotentials fitting options and further functionality.

Install Julia v1.9.2

curl -fsSL https://install.julialang.org | sh -s -- default-channel 1.9.2

Once installed in the terminal, run the following commands to get Julia ACEpotentials dependencies.

julia -e 'using Pkg; Pkg.Registry.add("General"); Pkg.Registry.add(Pkg.Registry.RegistrySpec(url="https://github.com/ACEsuit/ACEregistry")); Pkg.add(Pkg.PackageSpec(;name="ACEpotentials", version="0.6.7")); Pkg.add("DataFrames"); Pkg.add("CSV")'

ℹ️ To fit and validate Pacemaker ACE potentials, one also needs to install tensorflow, tensorpotential, and python-ace. Please note that Pacemaker ACE fitting can be run on both CPU and GPU. ⚠️ Please also note on versioning: to prevent dependency conflicts (e.g., with pandas versions) and ensure stability, please install the exact commit hashes listed below using the --no-deps flag. These specific versions have been fully tested and validated for use with Autoplex.

pip install autoplex[pacemaker]
pip install setuptools==81.0.0
pip install tensorflow==2.8.0
pip install --no-deps git+https://github.com/ICAMS/TensorPotential.git@1e44b2558356800ae070658c0bb856ff9bf74538
# Ensure CMake is available before running this:
pip install --no-deps git+https://github.com/ICAMS/python-ace.git@d1c213a7d9c5b809a3ae83b2e5a916be26d921f0

ℹ️ To fit and validate NEP potentials, one requires an Nvidia GPU card with compute capability no less than 3.5 and CUDA toolkit 9.0 or newer. This potential can only be trained on GPU only and currently interface to NEP potential training is provided via calorine package that uses nep executable from the GPUMD package. To get this executable please follow the compilation instructions here and add this executable to the system path.

Enabling RSS workflows

Additionally, buildcell as a part of AIRSS needs to be installed if one wants to use the RSS functionality:

ℹ️ To be able to build the AIRSS utilities one needs gcc and gfortran version 5 and above. Other compiler families (such as ifort) are not supported. These compilers are usually available on HPCs and one can simply load them if needed. On Ubuntu/Debian systems, one can install the necessary compilers with the following command:

apt install -y build-essential gfortran

curl -O https://www.mtg.msm.cam.ac.uk/files/airss-0.9.3.tgz; tar -xf airss-0.9.3.tgz; rm airss-0.9.3.tgz; cd airss; make spglib; make internal; make install_internal; make neat; cd ..

Please find out about licenses and citation requirements here: https://airss-docs.github.io/

LAMMPS installation

You only need to install LAMMPS, if you want to use J-ACE as your MLIP. Recipe for compiling lammps-ace including the download of the libpace.tar.gz file:

git clone -b stable_29Aug2024_update1 https://github.com/lammps/lammps.git
cd lammps
mkdir build
cd build
wget -O libpace.tar.gz https://github.com/wcwitt/lammps-user-pace/archive/main.tar.gz

cmake  -C ../cmake/presets/clang.cmake -D BUILD_SHARED_LIBS=on -D BUILD_MPI=yes \
-DMLIAP_ENABLE_PYTHON=yes -D PKG_PYTHON=on -D PKG_KOKKOS=yes -D Kokkos_ARCH_ZEN3=yes \
-D PKG_PHONON=yes -D PKG_MOLECULE=yes -D PKG_MANYBODY=yes \
-D Kokkos_ENABLE_OPENMP=yes -D BUILD_OMP=yes -D LAMMPS_EXCEPTIONS=yes \
-D PKG_ML-PACE=yes -D PACELIB_MD5=$(md5sum libpace.tar.gz | awk '{print $1}') \
-D CMAKE_INSTALL_PREFIX=$LAMMPS_INSTALL -D CMAKE_EXE_LINKER_FLAGS:STRING="-lgfortran" \
../cmake

make -j 16
make install-python

$LAMMPS_INSTALL is the conda environment for installing the lammps-python interface. Use BUILD_MPI=yes to enable MPI for parallelization.

After the installation, enter the following commands in the Python environment. If you get the same output, it means the installation was successful.

from lammps import lammps; lmp = lammps()

LAMMPS (29 Aug 2024 - Update 1)
OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:98)
  using 1 OpenMP thread(s) per MPI task
>>>

It is very important to have it compiled with Python (-D PKG_PYTHON=on) and LIB PACE flags (-D PACELIB_MD5=$(md5sum libpace.tar.gz | awk '{print $1}')).

Please find out about licenses and citation requirements here: https://www.lammps.org/

Contributing guidelines / Developer's installation

A short guide to contributing to autoplex can be found here. Additional information for developers can be found here.