Machine Learning forcefields / interatomic potentials

atomate2 includes an interface to a few common machine learning interatomic potentials (MLIPs), also known variously as machine learning forcefields (MLFFs), or foundation potentials (FPs) for universal variants. These can be installed using pip install 'atomate2[ase]'.

As of atomate2==0.1.2, all forcefield packages are opt-in only. You must install those forcefields which you plan to use.

Running pip install 'atomate2[forcefields-demo]' will install the chgnet package to permit you to try the forcefield jobs/workflows. You can then install additional forcefield libraries.

If you need a sense of which forcefields are compatible, you can use the pyproject.toml to see which versions are grouped together for testing.

Most of Maker classes using the forcefields inherit from atomate2.forcefields.utils.ForceFieldMixin to specify which forcefield to use. The ForceFieldMixin mixin provides the following configurable parameters:

• force_field_name: Name of the forcefield to use.

• calculator_kwargs: Keyword arguments to pass to the corresponding ASE calculator.

These parameters are passed to atomate2.forcefields.utils.ase_calculator() to instantiate the appropriate ASE calculator.

The force_field_name should be either one of predefined atomate2.forcefields.utils.MLFF (or its string equivalent) or a dictionary decodable as a class or function for ASE calculator as follows.

Using predefined forcefields supported via atomate2.forcefields.utils.MLFF

Support is provided for the following models, which can be selected using atomate2.forcefields.utils.MLFF, as shown in the table below (in alphabetical order): You need only install packages for the forcefields you wish to use.

Forcefield Name	MLFF	Reference	Description
Allegro	Allegro	10.1038/s41467-023-36329-y	Requires the nequip-allegro package
CHGNet	CHGNet	10.1038/s42256-023-00716-3	Available via the chgnet and matgl packages
DeepMD	DeepMD	10.1103/PhysRevB.108.L180104	The Deep Potential model used for this test is UniPero, a universal interatomic potential for perovskite oxides. It can be downloaded here
FAIRChem	FAIRChem	Meta’s FAIRChem Github	Proprietary, requires extra authentication. See notes below.
Gaussian Approximation Potential (GAP)	GAP	10.1103/PhysRevLett.104.136403	Relies on quippy-ase package
M3GNet	M3GNet	10.1038/s43588-022-00349-3	Relies on matgl package
MACE-Field	MACE_FIELD	10.1103/b116-xy8k	Born effective charges and dielectric tensor only, via ForceFieldDielectricMaker. Relies on the MACE-Field fork of mace_torch and a model file. See notes below.
MACE-MP-0	MACE or MACE_MP_0 (recommended)	10.1063/5.0297006	Relies on mace_torch and optionally torch_dftd packages
MACE-MP-0b3	MACE_MP_0B3	10.1063/5.0297006	Relies on mace_torch and optionally torch_dftd packages
MACE-MPA-0	MACE_MPA_0	10.1063/5.0297006	Relies on mace_torch and optionally torch_dftd packages
MatPES-PBE	MATPES_PBE	10.48550/arXiv.2503.04070	Relies on matgl. Defaults to TensorNet architecture, but can also use M3GNet or CHGNet architectures via kwargs. See atomate2.forcefields.utils._DEFAULT_CALCULATOR_KWARGS for more options.
MatPES-r2SCAN	MATPES_R2SCAN	10.48550/arXiv.2503.04070	Relies on matgl. Defaults to TensorNet architecture, but can also use M3GNet or CHGNet architectures via kwargs. See atomate2.forcefields.utils._DEFAULT_CALCULATOR_KWARGS for more options.
MatterSim	MatterSim	arXiv:2405.04967	Requires the mattersim package
Neuroevolution Potential (NEP)	NEP	10.1103/PhysRevB.104.104309	Relies on calorine package
Neural Equivariant Interatomic Potentials (Nequip)	Nequip	10.1038/s41467-022-29939-5	Relies on the nequip package
SevenNet	SevenNet	10.1021/acs.jctc.4c00190	Relies on the sevenn package
Universal Point Edge Transformer (UPET)	UPET	10.1038/s41467-025-65662-7	Relies on the upet package. Defaults to the “pet-mad-s” model.

Using custom forcefields by dictionary

force_field_name also accepts an import-like string, or MSONable dictionary to specify a custom ASE calculator class or function [1]. For example, a Job created with the either of the following two code snippets instantiates a chgnet.model.dynamics.CHGNetCalculator as the ASE calculator.

# simple import string
job = ForceFieldStaticMaker(
    calculator_meta="chgnet.model.dynamics.CHGNetCalculator",
).make(structure)

or using force_field_name when

# monty MSONable style
job = ForceFieldStaticMaker(
    calculator_meta={
        "@module": "chgnet.model.dynamics",
        "@callable": "CHGNetCalculator",
    }
).make(structure)

Note that one can also specify force_field_name = {"@module": ...,"@callable": ...} in the second example for backwards compatibility. However, this may not be preserved in future versions, and calculator_meta is preferred.

Notes on FairChem (Meta) models {#fairchem-notes}

The FAIRChem models provided by Meta require extra authentication via HuggingFace:

1. Request access to the UMA models via HuggingFace. You will need to set up a HuggingFace account. You will need to receive approval for the UMA models to proceed.

2. Install the HuggingFace CLI with pip install 'huggingface_hub'.

3. Run huggingface-cli login from a shell to authenticate your session. You will need to set up an access token.

4. You can now use the FAIRChem calculators. The general syntax for setting up a FAIRChem calculator in atomate2 is:

calculator_kwargs = {
    "predict_unit": {"model_name": "uma-s-1p1"},
    "task_name": "omat",
}

atomate2 will then set up a FAIRChemCalculator:

from atomate2.forcefields.utils import MLFF, _DEFAULT_CALCULATOR_KWARGS
from fairchem.core import FAIRChemCalculator, pretrained_mlip

predict_unit_kwargs = calculator_kwargs.pop(
    "predict_unit", _DEFAULT_CALCULATOR_KWARGS[MLFF.FAIRChem]["predict_unit"]
)
calculator = FAIRChemCalculator(
    pretrained_mlip.get_predict_unit(predict_unit_kwargs),
    **{k: v for k, v in calculator_kwargs.items() if k != "predict_unit"},
)

The default in atomate2 is the OMat24 model with uma-s-1p1.

Notes on MACE-Field {#mace-field-notes}

MACE-Field gives the Born effective charges and the high-frequency dielectric tensor of inorganic crystals. ForceFieldDielectricMaker computes them. The phonon workflows use them for the non-analytical correction when ForceFieldDielectricMaker is set as born_maker.

MACE-Field is a fork of MACE that installs as mace_torch, so it replaces MACE. Install it with pip install git+https://github.com/mdi-group/mace-field.git@45d5c5fa7b40a155855b3d155df1760e36849e64, the commit atomate2 is tested with. The fork also runs the MACE foundation models, so the forces can come from MACE-OMAT in the same environment. The model file has to be downloaded from the MACE-Field releases. There is no default model, so model must be set. Give its absolute path, since each job runs in its own folder:

from pymatgen.core import Lattice, Structure

from atomate2.forcefields.flows.phonons import PhononMaker
from atomate2.forcefields.jobs import ForceFieldDielectricMaker

structure = Structure.from_spacegroup(
    "Fm-3m", Lattice.cubic(5.64), ["Na", "Cl"], [[0, 0, 0], [0.5, 0.5, 0.5]]
).get_primitive_structure()

flow = PhononMaker.from_force_field_name(
    "MACE_MP_0",
    calculator_kwargs={"model": "medium-omat-0"},
    born_maker=ForceFieldDielectricMaker(
        calculator_kwargs={"model": "/path/to/MACEField-MH-0-omat-dielectric.model"}
    ),
).make(structure)

Born charges from VASP can be passed to make as born and epsilon_static. They must be in the same order as the sites of the structure.

Limitations:

• Both tensors are computed at zero electric field by default. The dielectric tensor is the clamped-ion one, 1 + chi, with chi the electronic susceptibility of the model.

• The model has the heads “mp-dielectric”, “mp-ferroelectric” and “pt_head”. “mp-dielectric” is used by default.

• The model runs on the CPU unless device is set in calculator_kwargs.

• The fork reports itself as mace-torch 0.3.15, so this is the forcefield_version in the output.

Warning

This feature is new and has not been tested widely. It might still change in future versions.

We compared the “mp-dielectric” head with the DFPT results in the Materials Project’s Harmonic Phonon Database. The 50 materials have no Materials Project dielectric data, so they are likely not in the training data of MACE-Field. The Born charges are off by 0.26 e on average, about 11%. The high-frequency dielectric constants are off by 8% on average, and by more than 20% for 2 of the 50 materials.

---

[1]

In this context, the type annotation of the decoded dict should be either Type[Calculator] or Callable[..., Calculator], where Calculator is from ase.calculators.calculator.