autoplex 0.1.2

Automated machine-learned Potential Landscape explorer

Disclaimer

autoplex is still under very active development and is only suitable for expert users as not all of the documentation is in place. This will change until end of November 2024.

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 preprint on the random-structure searches (RSS) performed with 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, 2024, DOI 10.48550/arXiv.2412.16736.

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

Please install autoplex using

pip install autoplex[strict]

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

Additionally, 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")'

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 ; make install ; 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.