Installation & Uninstallation

Tip

If AMS does not support your preferred ML potential, you may be able to create a Python environment yourself and use it through engine ASE.

The Amsterdam Modeling Suite requires the installation of additional Python environments to run the machine learning potential backends.

If you set up an MLPotential job via the graphical user interface, you will be asked to install the environments if they have not been installed already when you save your input. You can also use the package manager. A command-line installation tool can also be used, for instance to install the torchani backend:

"$AMSBIN"/amspackages install torchani-cpu

You can use the command line installer to install these environments on a remote system, so that you can seamlessly run MLPotential jobs also on remote machines.

The packages are installed into an isolated Python environment and do not affect any other Python installation on the system. For the installation, an Internet connection is required, unless you have configured the AMS package manager for offline use.

To uninstall a package, e.g. torchani, run:

"$AMSBIN"/amspackages remove torchani-cpu

Installing GPU-enabled backends using AMSpackages

Note

These instructions are suitable for AMS2026.101 and later. See here for older versions of AMS.

Various versions of the ML potential environments may be available through the AMSpackages, with different system dependencies such as GPU drivers. The type of the package is indicated by the name and package-id postfix.

For example, for MACE you will see the following entries:

$ "$AMSBIN"/amspackages list --format long | grep -A 3 "MACE Environment"
Package : MACE Environment (v1, CPU Only)
[id]: mace-cpu
Description: This is the environment for the MACE machine learning potential
(https://github.com/ACEsuit/mace), for CPU only on all platforms.
--
Package : MACE Environment (v1, CUDA 12.8)
[id]: mace-cu128
Description: This is the environment for the MACE machine learning potential
(https://github.com/ACEsuit/mace), for CUDA 12.8.

Note that CUDA-enabled versions are currently only available for the Linux platform.

Then select the version to install. Selecting -cpu variants will use CPU-only versions of PyTorch and TensorFlow, while -cu128 will use the CUDA-enabled 12.8 versions. CUDA-enabled environments are typically much larger in size as the required drivers are included, but allow usage of the GPU which can lead to significant speedups when using ML models.

If a suitable version of the environment is not available for your needs, you may be able to create a Python environment yourself and use it through engine ASE.

Debugging installation and available resources

A tool is provided to investigate the current installation of ML backends and frameworks. This tool will also report the resources that would be found by AMS if a calculation was performed with default settings.

The tool is used as follows:

$AMSBIN/amspython $AMSHOME/Utils/check_ml_backends.py

Example output:

ML Environment Summary:

AIMNet2:
Available Models: AIMNet2-B973c, AIMNet2-wB97MD3
Installed: not installed
Environments: aimnet2-cpu, aimnet2-cu128

FAIRChem:
Available Models: Custom, eSEN-S-Con-OMol, eSEN-Sm-Conserving, UMA-S-1.1-OC20, UMA-S-1.1-ODAC, UMA-S-1.1-OMat, UMA-S-1.1-OMC, UMA-S-1.1-OMol, UMA-S-1P1
Installed: not installed
Environments: fairchem-cpu, fairchem-cu128

M3GNet:
Available Models: Custom, M3GNet-UP-2022, MP-2021.2.8-EFS
Installed: installed (m3gnet)
Environments: m3gnet

MACE:
Available Models: Custom, MACE-MP-0-Large, MACE-MP-0-Medium, MACE-MP-0-Small, MACE-MPA-0
Installed: installed (mace-cpu)
Environments: mace-cpu, mace-cu128

NequIP:
Available Models: Custom
Installed: not installed
Environments: nequip-cpu, nequip-cu128

TorchANI:
Available Models: ANI-1ccx, ANI-1x, ANI-2x, Custom
Installed: not installed
Environments: torchani-cpu, torchani-cu128

Testing Installed Backends:
M3GNet:
Dependencies installed: True

###################TensorFlow setup##################
TensorFlow 2.9.1-cpu found the following devices:
PhysicalDevice(name='/physical_device:CPU:0', device_type='CPU')
NumThreads was not specified in the MLPotential engine block, so TensorFlow will use all available cores.
#####################################################

MACE:
Dependencies installed: True

#####################PyTorch setup###################
PyTorch 2.8.0 found the following devices:
Number of threads were not limited, using all available CPU cores.
Using CPU only.
#####################################################

If there are any issues, before contacting support, please run the following command:

$AMSBIN/amspython $AMSHOME/Utils/check_ml_backends.py --debug

and then report the output with your question.

This will give us additional details on why a framework or backend was not considered installed and report potential issues in the environment.