Skip to content

Commit

Permalink
Merge branch 'autoatml:main' into fix_custom_yaml_loading
Browse files Browse the repository at this point in the history
  • Loading branch information
naik-aakash authored Jan 4, 2025
2 parents acb670d + 8d7f995 commit 3b9dbde
Show file tree
Hide file tree
Showing 20 changed files with 152 additions and 116 deletions.
2 changes: 2 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ jobs:
micromamba activate autoplex_docs
uv pip install --upgrade pip
uv pip install --prerelease=allow .[docs,strict]
uv pip install --upgrade monty
uv pip install numpy==1.26.4
- name: Build
run: micromamba run -n autoplex_docs sphinx-build -W docs _build
- name: Deploy to GitHub Pages
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/python-package.yml
Original file line number Diff line number Diff line change
Expand Up @@ -156,5 +156,7 @@ jobs:
micromamba activate autoplex_docs
uv pip install --upgrade pip
uv pip install --prerelease=allow .[docs,strict]
uv pip install --upgrade monty
uv pip install numpy==1.26.4
- name: Build
run: micromamba run -n autoplex_docs sphinx-build -W docs _build
47 changes: 31 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,29 @@

`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
# 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](https://arxiv.org/abs/2412.16736).
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).


## 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.

## 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](https://arxiv.org/abs/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](https://github.com/materialsproject) framework software tools and related
Expand All @@ -35,9 +53,9 @@ This involves the following software packages:
- [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!
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
## 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).

Expand All @@ -46,11 +64,11 @@ Set a number that is a divisor of the number of tasks you use for the VASP calcu

# Installation

### Python version
## 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
## Standard installation

Please install `autoplex` using
```
Expand All @@ -73,15 +91,17 @@ Once installed in the terminal, run the following commands to get Julia ACEpoten
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
## 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
Please find out about licenses and citation requirements here: [https://airss-docs.github.io/](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:
Expand All @@ -108,7 +128,7 @@ 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.
After the installation, enter the following commands in the Python environment.
If you get the same output, it means the installation was successful.

```python
Expand All @@ -123,13 +143,8 @@ OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:98
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
Please find out about licenses and citation requirements here: [https://www.lammps.org/](https://www.lammps.org/)

We currently have two different types of automation workflows available:
# Contributing guidelines / Developer's installation

* 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).
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).
4 changes: 4 additions & 0 deletions docs/about/contributing.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,6 @@
---
orphan: true
---

```{include} ../../CONTRIBUTING.md
```
4 changes: 2 additions & 2 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
import os
import sys

from atomate2 import __version__
from autoplex import __version__

sys.path.insert(0, os.path.abspath("../../"))

Expand Down Expand Up @@ -103,7 +103,7 @@
language = "en"
html_static_path = ["_static"]
html_css_files = ["custom.css"]
suppress_warnings = "etoc.toctree"
suppress_warnings = ['toc.excluded', 'toc.not_readable']

# autodoc options
autosummary_imported_members = False
Expand Down
2 changes: 2 additions & 0 deletions docs/glossary.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
:orphan:

.. _glossary:

Glossary
Expand Down
4 changes: 4 additions & 0 deletions docs/user/jobflowremote.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
orphan: true
---

# Jobflow-remote setup

This will result in a setup for automation where
Expand Down
4 changes: 4 additions & 0 deletions docs/user/mongodb.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
orphan: true
---

# MongoDB setup tutorial

`autoplex` and `atomate2` use the MongoDB database framework to store the data output from the calculations.
Expand Down
3 changes: 3 additions & 0 deletions docs/user/rss.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
---
orphan: true
---
2 changes: 1 addition & 1 deletion docs/user/rss/flow/example/example.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(rss)=
(example)=

# Examples

Expand Down
2 changes: 1 addition & 1 deletion docs/user/rss/flow/input/input.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(rss)=
(input)=

# Input YAML configuration file

Expand Down
2 changes: 1 addition & 1 deletion docs/user/rss/flow/introduction/intro.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(rss)=
(introduction)=

# Brief overview

Expand Down
10 changes: 5 additions & 5 deletions docs/user/rss/flow/quick_start/start.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
(rss)=
(rss-quickstart)=

# Quick start

Expand All @@ -24,7 +24,7 @@ The `RssMaker` class in `autoplex` is the core interface for creating ML-RSS pot

Parameters can be specified either through a YAML configuration file or as direct arguments in the `make` method.

### Running the workflow with a YAML configuration file
## Running the workflow with a YAML configuration file

> **Recommendation**: This is currently our recommended approach for setting up and managing RSS workflows.
Expand Down Expand Up @@ -56,7 +56,7 @@ print(submit_flow(rss_job, worker="your worker", resources=resources, project="y

For details on setting up `FireWorks`, see [FireWorks setup](../../../mongodb.md#fireworks-configuration) and for `jobflow-remote`, see [jobflow-remote setup](../../../jobflowremote.md).

### Running the workflow with direct parameter specification
## Running the workflow with direct parameter specification

As an alternative to using a YAML configuration file, the RSS workflow can be initiated by directly specifying parameters in the `make` method. This approach is ideal for cases where only a few parameters need to be customized. You can override the default settings by passing them as keyword arguments, offering a more flexible and lightweight way to set up the workflow.

Expand All @@ -79,7 +79,7 @@ If you choose to use the direct parameter specification method, at a minimum, yo
> **Note**: If both a YAML file and direct parameter specifications are provided, any overlapping parameters will be overridden by the directly specified values.
### Building RSS models with various ML potentials
## Building RSS models with various ML potentials

Currently, `RssMaker` supports GAP (Gaussian Approximation Potential), ACE (Atomic Cluster Expansion), and three graph-based network models including NequIP, M3GNet, and MACE. You can specify the desired model using the `mlip_type` argument and adjust relevant hyperparameters within the `make` method. Default and adjustable hyperparameters are available in `autoplex/fitting/common/mlip-rss-defaults.json`.

Expand All @@ -93,7 +93,7 @@ rss_job = RssMaker(name="your workflow name").make(tag='SiO2',

> **Note**: We primarily recommend the GAP-RSS model for now, as GAP has demonstrated great stability with small datasets. Other models have not been thoroughly explored yet. However, we encourage users to experiment with and test other individual models or combinations for potentially interesting results.
### Resuming workflow from point of interruption
## Resuming workflow from point of interruption

To resume an interrupted RSS workflow, use the `resume_from_previous_state` argument, which accepts a dictionary containing the necessary state information. Additionally, ensure that `train_from_scratch` is set to `False` to enable resuming from the previous state. This way, you are allowed to continue the workflow from any previously saved state.

Expand Down
4 changes: 2 additions & 2 deletions docs/user/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,15 +26,15 @@ Once installed in the terminal, run the following commands to get Julia ACEpoten
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
## 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
## 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:
Expand Down
6 changes: 3 additions & 3 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,11 @@ docs = [
"autodoc_pydantic==2.2.0",
"ipython",
"jsonschema[format]",
"myst_parser==2.0.0",
"myst_parser==4.0.0",
"numpydoc==1.8.0",
"sphinx-copybutton==0.5.2",
"sphinx==7.2.6",
"sphinx_design==0.5.0",
"sphinx==8.1.3",
"sphinx_design==0.6.1",
"myst-nb==1.0.0",
"sphinx-book-theme==1.1.0",
"sphinxcontrib-mermaid",
Expand Down
2 changes: 2 additions & 0 deletions src/autoplex/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,5 @@
DFT-labelled data.
"""

from autoplex._version import __version__
3 changes: 3 additions & 0 deletions src/autoplex/_version.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
from importlib.metadata import version

__version__ = version("autoplex")
Loading

0 comments on commit 3b9dbde

Please sign in to comment.