[](https://github.com/JaGeo/autoplex/actions/workflows/python-package.yml) [](https://results.pre-commit.ci/latest/github/autoatml/autoplex/main) [](https://doi.org/10.5281/zenodo.14105049)  [](https://badge.fury.io/py/autoplex)
<img src="docs/_static/autoplex_logo.png" width="66%">
<div style="border: 1px solid #2e3191; padding: 5px; position: relative;">
<div style="background-color: #2e3191; color: #ffffff; padding: 0px; position: absolute; top: 0; left: 0; right: 0; text-align: center;">
<strong>Disclaimer</strong>
</div>
<br>
`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.
</div>
<br>
`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](https://github.com/JaGeo) will handle the reviews.
# Documentation
You can find the `autoplex` documentation [here](https://autoatml.github.io/autoplex/index.html)!
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.
# Before you start using `autoplex`
We expect the general user of `autoplex` to be familiar with the [Materials Project](https://github.com/materialsproject) framework software tools and related
packages for (high-throughput) workflow submission and management.
This involves the following software packages:
- [pymatgen](https://github.com/materialsproject/pymatgen) for input and output handling of computational materials science software,
- [atomate2](https://github.com/materialsproject/atomate2) for providing a library of pre-defined computational materials science workflows,
- [jobflow](https://github.com/materialsproject/jobflow) for processes, job and workflow handling,
- [jobflow-remote](https://github.com/Matgenix/jobflow-remote) or [FireWorks](https://github.com/materialsproject/fireworks) for workflow and database (MongoDB) management,
- [MongoDB](https://www.mongodb.com/) as the database (we recommend installing the MongoDB community edition). More help regarding the MongoDB installation can be found [here](https://materialsproject.github.io/fireworks/installation.html#install-mongodb).
All of these software tools provide documentation and tutorials. Please take your time and check everything out!
# Setup
To set up the mandatory prerequisites for using `autoplex,` please follow the [installation guide of atomate2](https://materialsproject.github.io/atomate2/user/install.html).
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](https://github.com/autoatml/autoplex/blob/main/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](https://acesuit.github.io/ACEpotentials.jl/dev/gettingstarted/installation/), 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
```bash
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.
```bash
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:
```bash
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 ..
```
### 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 is completed, enter the following commands in the Python environment.
If you get the same output, it means the installation was successful.
```python
from lammps import lammps; lmp = lammps()
```
```bash
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}')`).
### Contributing guidelines / Developer's installation
A short guide to contributing to autoplex can be found [here](https://autoatml.github.io/autoplex/dev/contributing.html). Additional information for developers can be found [here](https://autoatml.github.io/autoplex/dev/dev_install.html).
# 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. The implementation automates ideas from the following articles: [*Phys. Rev. Lett.* **120**, 156001 (2018)](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.156001) and [*npj Comput. Mater.* **5**, 99 (2019)](https://www.nature.com/articles/s41524-019-0236-6).
* 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)](https://pubs.aip.org/aip/jcp/article/153/4/044104/1056348/Combining-phonon-accuracy-with-high).
Raw data
{
"_id": null,
"home_page": null,
"name": "autoplex",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.10",
"maintainer_email": null,
"keywords": "high-throughput, automated, mlpotential",
"author": null,
"author_email": "Janine George <janine.george@bam.de>",
"download_url": "https://files.pythonhosted.org/packages/70/34/0ba1ce5f21a30e3932597d729f9efcc20d740b085881aa20c4d33feb7fe8/autoplex-0.1.0.tar.gz",
"platform": null,
"description": "[](https://github.com/JaGeo/autoplex/actions/workflows/python-package.yml) [](https://results.pre-commit.ci/latest/github/autoatml/autoplex/main) [](https://doi.org/10.5281/zenodo.14105049)  [](https://badge.fury.io/py/autoplex)\n\n<img src=\"docs/_static/autoplex_logo.png\" width=\"66%\">\n\n<div style=\"border: 1px solid #2e3191; padding: 5px; position: relative;\">\n <div style=\"background-color: #2e3191; color: #ffffff; padding: 0px; position: absolute; top: 0; left: 0; right: 0; text-align: center;\">\n <strong>Disclaimer</strong>\n </div>\n<br>\n\n`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.\n</div>\n\n<br>\n\n`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.\n\n`autoplex` is developed jointly by two research groups at BAM Berlin and the University of Oxford.\n\n`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](https://github.com/JaGeo) will handle the reviews.\n\n# Documentation\n\nYou can find the `autoplex` documentation [here](https://autoatml.github.io/autoplex/index.html)!\nThe 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.\n\n# Before you start using `autoplex`\n\nWe expect the general user of `autoplex` to be familiar with the [Materials Project](https://github.com/materialsproject) framework software tools and related\npackages for (high-throughput) workflow submission and management.\nThis involves the following software packages:\n- [pymatgen](https://github.com/materialsproject/pymatgen) for input and output handling of computational materials science software,\n- [atomate2](https://github.com/materialsproject/atomate2) for providing a library of pre-defined computational materials science workflows,\n- [jobflow](https://github.com/materialsproject/jobflow) for processes, job and workflow handling,\n- [jobflow-remote](https://github.com/Matgenix/jobflow-remote) or [FireWorks](https://github.com/materialsproject/fireworks) for workflow and database (MongoDB) management,\n- [MongoDB](https://www.mongodb.com/) as the database (we recommend installing the MongoDB community edition). More help regarding the MongoDB installation can be found [here](https://materialsproject.github.io/fireworks/installation.html#install-mongodb).\n\nAll of these software tools provide documentation and tutorials. Please take your time and check everything out!\n\n# Setup\n\nTo set up the mandatory prerequisites for using `autoplex,` please follow the [installation guide of atomate2](https://materialsproject.github.io/atomate2/user/install.html).\n\nAfter setting up `atomate2`, make sure to add `VASP_INCAR_UPDATES: {\"NPAR\": number}` in your `~/atomate2/config/atomate2.yaml` file.\nSet a number that is a divisor of the number of tasks you use for the VASP calculations.\n\n# Installation\n\n### Python version\n\nBefore the installation, please make sure that you are using one of the supported Python versions (see [pyproject.toml](https://github.com/autoatml/autoplex/blob/main/pyproject.toml))\n\n### Standard installation\n\nPlease install `autoplex` using\n```\npip install autoplex[strict]\n```\nThis will install all the Python packages and dependencies needed for MLIP fits.\n\nAdditionally, to fit and validate `ACEpotentials`, one also needs to install Julia, as `autoplex` relies on [ACEpotentials](https://acesuit.github.io/ACEpotentials.jl/dev/gettingstarted/installation/), which supports fitting of linear ACE. Currently, no Python package exists for the same.\nPlease run the following commands to enable the `ACEpotentials` fitting options and further functionality.\n\nInstall Julia v1.9.2\n\n```bash\ncurl -fsSL https://install.julialang.org | sh -s -- default-channel 1.9.2\n```\n\nOnce installed in the terminal, run the following commands to get Julia ACEpotentials dependencies.\n\n```bash\njulia -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\")'\n```\n\n### Enabling RSS workflows\n\nAdditionally, `buildcell` as a part of `AIRSS` needs to be installed if one wants to use the RSS functionality:\n\n```bash\ncurl -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 ..\n```\n\n### LAMMPS installation\n\nYou only need to install LAMMPS, if you want to use J-ACE as your MLIP.\nRecipe for compiling lammps-ace including the download of the `libpace.tar.gz` file:\n\n```\ngit clone -b stable_29Aug2024_update1 https://github.com/lammps/lammps.git\ncd lammps\nmkdir build\ncd build\nwget -O libpace.tar.gz https://github.com/wcwitt/lammps-user-pace/archive/main.tar.gz\n\ncmake -C ../cmake/presets/clang.cmake -D BUILD_SHARED_LIBS=on -D BUILD_MPI=yes \\\n-DMLIAP_ENABLE_PYTHON=yes -D PKG_PYTHON=on -D PKG_KOKKOS=yes -D Kokkos_ARCH_ZEN3=yes \\\n-D PKG_PHONON=yes -D PKG_MOLECULE=yes -D PKG_MANYBODY=yes \\\n-D Kokkos_ENABLE_OPENMP=yes -D BUILD_OMP=yes -D LAMMPS_EXCEPTIONS=yes \\\n-D PKG_ML-PACE=yes -D PACELIB_MD5=$(md5sum libpace.tar.gz | awk '{print $1}') \\\n-D CMAKE_INSTALL_PREFIX=$LAMMPS_INSTALL -D CMAKE_EXE_LINKER_FLAGS:STRING=\"-lgfortran\" \\\n../cmake\n\nmake -j 16\nmake install-python\n```\n\n$LAMMPS_INSTALL is the conda environment for installing the lammps-python interface.\nUse `BUILD_MPI=yes` to enable MPI for parallelization.\n\nAfter the installation is completed, enter the following commands in the Python environment.\nIf you get the same output, it means the installation was successful.\n\n```python\nfrom lammps import lammps; lmp = lammps()\n```\n```bash\nLAMMPS (29 Aug 2024 - Update 1)\nOMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:98)\n using 1 OpenMP thread(s) per MPI task\n>>>\n```\nIt is very important to have it compiled with Python (`-D PKG_PYTHON=on`) and\nLIB PACE flags (`-D PACELIB_MD5=$(md5sum libpace.tar.gz | awk '{print $1}')`).\n\n### Contributing guidelines / Developer's installation\n\nA short guide to contributing to autoplex can be found [here](https://autoatml.github.io/autoplex/dev/contributing.html). Additional information for developers can be found [here](https://autoatml.github.io/autoplex/dev/dev_install.html).\n\n# Workflow overview\n\nWe currently have two different types of automation workflows available:\n\n* Workflow to use random-structure searches for the systematic construction of interatomic potentials. The implementation automates ideas from the following articles: [*Phys. Rev. Lett.* **120**, 156001 (2018)](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.156001) and [*npj Comput. Mater.* **5**, 99 (2019)](https://www.nature.com/articles/s41524-019-0236-6).\n* 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)](https://pubs.aip.org/aip/jcp/article/153/4/044104/1056348/Combining-phonon-accuracy-with-high).\n",
"bugtrack_url": null,
"license": "GPL-3.0 license",
"summary": "Automated machine-learned Potential Landscape explorer",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"high-throughput",
" automated",
" mlpotential"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "efb2d12ac4e67c31ba95218205847fe999a56997e508aed4196cecfb9716c824",
"md5": "b0184c5ce1a540fae9c59bd3d9563087",
"sha256": "6a51d261fb7e6b20361cbabb0a9dfc9e1c27a1cc99207cf3d8aa940c55149ca1"
},
"downloads": -1,
"filename": "autoplex-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0184c5ce1a540fae9c59bd3d9563087",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.10",
"size": 126522,
"upload_time": "2024-12-18T19:36:44",
"upload_time_iso_8601": "2024-12-18T19:36:44.614995Z",
"url": "https://files.pythonhosted.org/packages/ef/b2/d12ac4e67c31ba95218205847fe999a56997e508aed4196cecfb9716c824/autoplex-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "70340ba1ce5f21a30e3932597d729f9efcc20d740b085881aa20c4d33feb7fe8",
"md5": "67d30078fb4d3be929a2cdba9f3eb3ff",
"sha256": "9718832b114a29c4ce94ffdf6ad0523892f56c32f09cb5324ea8d64799b123e2"
},
"downloads": -1,
"filename": "autoplex-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "67d30078fb4d3be929a2cdba9f3eb3ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.10",
"size": 115906,
"upload_time": "2024-12-18T19:36:46",
"upload_time_iso_8601": "2024-12-18T19:36:46.786823Z",
"url": "https://files.pythonhosted.org/packages/70/34/0ba1ce5f21a30e3932597d729f9efcc20d740b085881aa20c4d33feb7fe8/autoplex-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 19:36:46",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "autoplex"
}
JSON