Theory and usage¶
The MLPotential engine in the Amsterdam Modeling Suite can calculate the potential energy surface using several different types of machine learning (ML) potentials.
To set up a simple MLPotential job using the graphical user interface, see the ANI-1ccx Thermochemistry tutorial.
Theory of ML potentials¶
With machine learning potentials, it is possible to quickly evaluate the energies and forces in a system with close to first-principles accuracy. Machine learning potentials are fitted (trained, parameterized) to reproduce reference data, typically calculated using an ab initio or DFT method. Machine learning potentials are sometimes referred to as machine learning force fields, or as interatomic potentials based on machine learning.
Several types of machine learning potentials exist, for example neural-network-based methods and kernel-based methods.
Several types of neural network potentials exist. It is common for such potentials to calculate the total energy as a sum of atomic contributions. In a high-dimensional neural network potential (HDNNP), as proposed by Behler and Parrinello , each atomic contribution is calculated by means of a feed-forward neural network, that takes in a representation of the chemical environment around the atom as input. This representation, or atomic environment descriptor or fingerprint, consists of a vector of rotationally, translationally, and permutationally invariant functions known as atom-centered symmetry functions (ACSF).
Graph convolutional neural network potentials (GCNNPs), or message-passing network neural potentials, similarly construct the total energy by summing up atomic contribution, but the appropriate representations of local atomic chemical environments are learned from the reference data.
Kernel-based methods make predictions based on how similar a system is to the systems in the training set.
Installation and uninstallation¶
The Amsterdam Modeling Suite by default does not include the Python packages necessary 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 Python packages if they have not been installed already when you save your input. Moreover, the run script will also contain instructions to install the necessary packages if needed, so that you can seamlessly run MLPotential jobs also on remote machines.
The graphical user interface will install a CPU-only version of PyTorch. To install a CUDA-enabled version (GPU-accelerated), use the installation wizard.
A command-line installation wizard can also be used:
The packages are installed into the AMS Python environment, and do not affect any other Python installation on the system. For the installation, an internet connection is required.
The packages are installed into a subdirectory of the
SCM_PYTHONDIR environment variable. This variable should be set in the
ams_command_line.bat files. If
SCM_PYTHONDIR is unset or empty, the installation will be done into a subdirectory of
To uninstall a package, e.g.
"$AMSBIN"/amspython -m pip uninstall torch
If this fails, you can simply delete the directories containing the packages.
Included (pre-parameterized) models¶
A model is the combination of a functional form with a set of parameters. Three pre-parameterized models can be selected, ANI-2x, ANI-1ccx, and ANI-1x. The predictions from these models are calculated from ensembles, meaning that the final prediction is an average over several independently trained neural networks.
|Atomic environment descriptor||ACSF||ACSF||ACSF|
|Supported elements||H, C, N, O, F, S, Cl||H, C, N, O||H, C, N, O|
|Training set structures||organic molecules||organic molecules||organic molecules|
For the ANI-*x models, the standard deviation for the energy predictions are
calculated for the “main” output molecule (e.g., the final point of a geometry
optimization). The summary statistics can be found in the
file in the
worker.0 subdirectory of the results directory.
Type: Multiple Choice Default value: ANI-2x Options: [Custom, ANI-1ccx, ANI-1x, ANI-2x] Description: Select a particular parameterization. ANI-1x and ANI-2x: based on DFT (wB97X) ANI-1cxx: based on DLPNO-CCSD(T)/CBS ANI-1x and ANI-1ccx have been parameterized to give good geometries, vibrational frequencies, and reaction energies for gasphase organic molecules containing H, C, O, and N. ANI-2x can also handle the atoms F, S, and Cl. Set to Custom to specify the backend and parameter files yourself.
Custom models (custom parameters)¶
Model to Custom and specify which backend to use with the
In a typical case, you would have used that backend to train your own machine
The backend reads the parameters, and any other necessary information (for
example neural network architecture), from either a file or a directory.
ParameterDir option accordingly, with a
path to the file or directory. Read the backend’s documentation to find out
which option is appropriate.
Some backends may require that an energy unit (
MLEnergyUnit) and/or distance
MLDistanceUnit) be specified. These units correspond to the units
used during the training of the machine learning potential.
Engine MLPotential Backend SchNetPack Model Custom ParameterFile ethanol.schnet-model MLEnergyUnit kcal/mol MLDistanceUnit angstrom EndEngine
Type: Multiple Choice Options: [PiNN, SchNetPack, sGDML, TorchANI] Description: The machine learning potential backend.
Type: Multiple Choice Default value: Auto Options: [Auto, angstrom, bohr] GUI name: Internal distance unit Description: Unit of distances expected by the ML backend (not the ASE calculator). The ASE calculator may require this information.
Type: Multiple Choice Default value: Auto Options: [Auto, Hartree, eV, kcal/mol, kJ/mol] GUI name: Internal energy unit Description: Unit of energy output by the ML backend (not the unit output by the ASE calculator). The ASE calculator may require this information.
Type: String Default value: GUI name: Parameter directory Description: Path to a set of parameters for the backend, if it expects to read from a directory.
Type: String Default value: Description: Path to a set of parameters for the backend, if it expects to read from a file.
|Methods||HDNNPs, GCNNPs, …||HDNNPs, GCNNPs, …||GDML, sGDML||[ensembles of] HDNNPs|
|Pre-built models||none||none||none||ANI-1x, ANI-2x, ANI-1ccx|
|ML framework||TensorFlow 1.15||PyTorch||none, PyTorch||PyTorch|
For sGDML, the order of the atoms in the input file must match the order of atoms which was used during the fitting of the model.
If you use a custom parameter file with TorchANI, the model specified
ParameterFile filename.pt is loaded with
torch.load('filename.pt')['model'], such that a forward call should be
coordinates)). The energy shifter is not read from custom parameter files,
so the absolute predicted energies will be shifted with respect to the
reference data, but this does not affect relative energies (e.g., reaction energies).
CPU and GPU (CUDA), parallelization¶
By default a calculation will run on the CPU, and use all available CPU power.
To limit the number of threads, the
NumThreads keyword can be used if the
backend uses PyTorch as its machine learning framework. Alternatively, you can
set the environment variable OMP_NUM_THREADS.
To use a CUDA-enabled GPU, ensure that a CUDA-enabled version of TensorFlow or
PyTorch has been installed (see Installation and uninstallation). Then set
the device on which you would like to run, for example, cuda:0.
Calculations are typically much faster on the GPU than on the CPU.
Type: Multiple Choice Default value: Options: [, cpu, cuda:0, cuda:1] Description: Device on which to run the calculation (e.g. cpu, cuda:0). If empty, the device can be controlled using environment variables for TensorFlow or PyTorch.
Type: String Default value: GUI name: Number of threads Description: Number of threads. If not empty, OMP_NUM_THREADS will be set to this number; for PyTorch-engines, torch.set_num_threads() will be called.
Because the calculation runs in a separate process, the number of threads is controlled by the input keyword NumThreads and not by the environment variable NSCM. We recommend setting NSCM=1 when using the MLPotential engine.
Only single-node calculations are currently supported.
If you run a PyTorch-based backend and receive an error message starting with:
sh: line 1: 1351 Illegal instruction: 4 sh
you may be attempting to run PyTorch on a rather old cpu. You could try to upgrade PyTorch to a newer version:
"$AMSBIN"/amspython -m pip install torch -U -f https://download.pytorch.org/whl/torch_stable.html
If this does not help, please contact SCM support.
SCM does not provide support for parameterization using the MLPotential backends. SCM only provides technical (non-scientific) support for running simulations via the AMS driver.
Each of the supported backends can be used as ASE (Atomic Simulation
Environment) calculators. The MLPotential engine
is an interface to those ASE calculators. The communication between the AMS
driver and the backends is implemented with a named pipe interface. The MLPotential engine launches a
ase_calculators.py, which initializes the ASE calculator.
The exact command that is executed is written as
WorkerCommand in the
|||J. Behler, M. Parrinello. Phys. Rev. Lett. 98 (2007) 146401 https://doi.org/10.1103/PhysRevLett.98.146401|
|||J. Behler. J. Chem. Phys. 145 (2016) 170901. https://doi.org/10.1063/1.4966192|
|||T. Mueller, A. Hernandez, C. Wang. J. Chem. Phys. 152 (2020) 050902. https://doi.org/10.1063/1.4966192|
|||C. Devereux et al., J. Chem. Theory Comput. 16 (2020) 4192-4202. https://doi.org/10.1021/acs.jctc.0c00121|
|||J. S. Smith et al., Nat. Commun. 10 (2019) 2903. https://doi.org/10.1038/s41467-019-10827-4|
|||J. S. Smith et al., J. Chem. Phys. 148 (2018) 241733. https://doi.org/10.1063/1.5023802|
|||Y. Shao et al., J. Chem. Inf. Model. 60 (2020) 1184-1193. https://doi.org/10.1021/acs.jcim.9b00994|
|||K. T. Schütt et al., J. Chem. Theory Comput. 15 (2019) 448-455. https://doi.org/10.1021/acs.jctc.8b00908|
|||S. Chmiela et al. Comp. Phys. Commun. 240 (2019) 38-45. https://doi.org/10.1016/j.cpc.2019.02.007|
|||X. Gao et al. J. Chem. Inf. Model (2020). https://doi.org/10.1021/acs.jcim.0c00451|