You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* first attempt reorganizing mlff ci
* fix wf file
* tweak ff workflow file
* typos
* ensure torch dftd is installed with mace
* separate mlff neb tests
* annotations in pyproject for future dev work; make phonon tutorial only use matgl since these dep groups are split
* reorg phonon tests
* revert to numpy<2
* try numpy>2 with numba pin
* documentation on fairchem + test data should a user install it, correct APIs to some MLIPs, try to test nequip in CI
* nequip broken api syntax yet again?
* mattersim tests
* bump deps
* other mattersim tests
* organize + expand ff docs + fix mattersim test tol
* forcefield dev notes + add on notes
* precommit
# Maintaining the machine learning forcefields module
2
+
3
+
Some of these points are already noted in the `pyproject.toml`. This goes into a bit more depth.
4
+
5
+
## Overview
6
+
7
+
`atomate2` contains a convenience interface to many common machine learning interatomic forcefields (MLFFs) via the atomic simulation environment (ASE). In the literature, these may also be known as machine learning interatomic potentials (MLIPs), or, when specifically referring to MLIPs with coverage of most of the periodic table, foundation potentials (FPs).
8
+
9
+
There is both an `ase` module in `atomate2`, based around general `ase``Calculator`s, and a `forcefields`-specific module which has a higher number of workflows.
10
+
11
+
The `ase` module should be used to manage high-level tasks, such as geometry optimization, molecular dynamics, and nudged elastic band. Any further developments to these tools in `ase` should also warrant updates in this module in `atomate2`. For example, when `ase` rolled out the `MTKNPT` NPT MD barostat as a replacement for the default barostat, this was also made the default in `atomate2`.
12
+
13
+
The `forcefields` library should be used to develop concrete implementations of workflows, e.g., harmonic phonon, Grüneisen parameter, ApproxNEB.
14
+
15
+
## Dependency Chaos
16
+
17
+
The individual MLFFs in `atomate2` often have conflicting dependencies. This makes testing and managing a consistent, relatively up-to-date testing environment challenging.
18
+
We want to avoid pinning MLFF libraries at older versions, because this may break their API within `atomate2`, or lead to drift in test data as models evolve.
19
+
20
+
Thus, it is likely that the `pyproject.toml` contains multiple optional dependencies under the header `strict-forcefields-*`. These groupings are used to ensure the most recent version of a MLFF library is installed in CI testing, with acceptable dependencies. The names of these groups can change over time, but the names should be chosen to be informative as to why they exist: ex., `strict-forcefields-e3nn-limited` to indicate that these MLFFs need an older version of `e3nn`, or `strict-forcefields-generic` to indicate that no strong dependency limitation is observed.
21
+
22
+
When updating these groupings, it is critical to ensure that you also update the `.github/workflows/testing.yml` testing workflow. You will see that the different forcefield dependency groups are tested separately.
23
+
24
+
When adding a new MLFF and tests for it (if possible), you must ensure that appropriate `pytest.mark.skipif` decorators are applied if that MLFF package is not installed. A `mlff_is_installed` boolean check is included in `tests/forcefields/conftest.py` for convenience in writing these skip test markers. See `tests/forcefields/test_jobs.py` for examples.
25
+
26
+
## Testing limitations
27
+
28
+
Some MLFFs, like FAIRChem, have access restrictions on them which prohibit running tests in CI. For these, we should also likely create tests for continuing development even if they are not run in CI.
29
+
30
+
Other MLFFs, like GAP or Nequip, are more generic architectures and require specific potential files to describe certain chemical spaces. Contributors adding new architectures which require these potential fields should submit minimal potential files (as small as possible to test, accuracy is not important here) to run tests for these.
Copy file name to clipboardExpand all lines: docs/dev/input_sets.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ Most ab-initio codes rely on input files read from disk. The `InputSet` class au
11
11
- As a dictionary-like collection, the `InputSet` associates file names (the keys) with their content (which can be either simple strings or `InputFile` instances). The main methods of this class are `write_input()` for standardized file writing and `from_directory()` to read in pre-existing `InputSets`. The `validate()` method confirms the validity of the `InputSet`.
12
12
-`InputGenerators` implement the `get_input_set()` method, which provides the recipe, i.e., logic to return a suitable `InputSet` for a `Molecule`, `Structure`, or another set of atomic coordinates. During the initialization of an `InputGenerator` additional inputs can be provided that adjust the recipe.
13
13
14
-
While generally the input classes are supposed to be part of `pymatgen` during development it is recommended to include them in `atomate2` at first to facilitate rapid iteration. Once mature, they can be moved to `pymatgen` or to a `pymatgen`[addon package](https://.org/addons). When implementing your own input classes take note of the recommendations and rules in the pymatgen documentation [[1](https://pymatgen.org/pymatgen.io.html#module-pymatgen.io.core), [2](https://pymatgen.org/pymatgen.io.vasp.html#module-pymatgen.io.vasp.sets)].
14
+
While generally the input classes are supposed to be part of `pymatgen` during development it is recommended to include them in `atomate2` at first to facilitate rapid iteration. Once mature, they can be moved to `pymatgen` or to a `pymatgen`[addon package](https://github.com/materialsproject/pymatgen-addon-template). When implementing your own input classes take note of the recommendations and rules in the pymatgen documentation [[1](https://pymatgen.org/pymatgen.io.html#module-pymatgen.io.core), [2](https://pymatgen.org/pymatgen.io.vasp.html#module-pymatgen.io.vasp.sets)].
15
15
16
16
The `InputGenerators` interact with the atomate2 workflows through `Makers`. Each `Maker` for a code that requires input files, sets its `input_set_generator` parameter during initialization. For example, for the `RelaxMaker`, the default `input_set_generator` is the `RelaxSetGenerator`, but of course, users can provide or modify any `VaspInputGenerator` and provide it as input to a Maker.
0 commit comments