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. Note that the CUDA-enabled environments can also be
used to run on CPU only, and so only one version (either CPU only or
CUDA) should be installed.

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, UMA-S-1.2-OC20, UMA-S-1.2-OC22, UMA-S-1.2-OC25, UMA-S-1.2-ODAC, UMA-S-1.2-OMat, UMA-S-1.2-OMC, UMA-S-1.2-OMol
   Installed: not installed
   Environments: fairchem-cpu, fairchem-cu128

   M3GNet:
   Available Models: Custom, M3GNet-UP-2022
   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.
