From 65a7a05ca699a5701c4625cbe03a4ad1cec8cf8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ole=20Sch=C3=BCtt?= Date: Sun, 19 Nov 2023 12:05:13 +0100 Subject: [PATCH] Manual: Migrate howto:allegro from wiki (Orig. Author: Gabriele Tocci) --- docs/methods/allegro.md | 76 ++++++++++++++++++++++++++++++++ docs/methods/machine_learning.md | 2 +- 2 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 docs/methods/allegro.md diff --git a/docs/methods/allegro.md b/docs/methods/allegro.md new file mode 100644 index 0000000000..b9f30f6302 --- /dev/null +++ b/docs/methods/allegro.md @@ -0,0 +1,76 @@ +# Nequip and Allegro + +This +[Colab tutorial](https://colab.research.google.com/github/gabriele16/cp2k/blob/nequip-cp2k-colab/colab/allegro-cp2k-tutorial.ipynb) +illustrates how to train an equivariant neural network interatomic potential for bulk water using +the Allegro framework. You will learn how to train a model, deploy it in production, and run +molecular dynamics simulations in CP2K. The training and inference will be carried out on the GPU +provided by the Colab environment. + +Allegro is designed for constructing highly accurate and scalable interatomic potentials for +molecular dynamics simulations. The methodology is described in detail in this paper +([](#Musaelian2023)). An open-source package that implements +[Allegro](https://github.com/mir-group/allegro), built on the +[Nequip framework](https://github.com/mir-group/nequip) was developed by the Allegro and NequIP +authors, A. Musaelian, S. Batzner, A. Johansson, L. Sun, C. J. Owen, M. Kornbluth, B. Kozinsky. + +## Input Section + +Inference in CP2K is performed through the +[NEQUIP](#CP2K_INPUT.FORCE_EVAL.MM.FORCEFIELD.NONBONDED.NEQUIP) and +[ALLEGRO](#CP2K_INPUT.FORCE_EVAL.MM.FORCEFIELD.NONBONDED.ALLEGRO) sections. As an example, the +relevant section for Allegro (or similarly for NequIP) is: + +```none +&ALLEGRO + ATOMS Si + PARM_FILE_NAME Allegro/si-deployed.pth + UNIT_COORDS angstrom + UNIT_ENERGY eV + UNIT_FORCES eV*angstrom^-1 +&END ALLEGRO +``` + +where the `si-deployed.pth` refers to the PyTorch model that was deployed using the Allegro +framework, and the `UNIT` tags refer to the units of the coordinates, energy and forces of the model +itself. An example for the full input file can be found in the +[Colab tutorial](https://colab.research.google.com/github/gabriele16/cp2k/blob/nequip-cp2k-colab/colab/allegro-cp2k-tutorial.ipynb) +and on the regtests, see +[Allegro_si_MD.inp](https://github.com/cp2k/cp2k/blob/master/tests/Fist/regtest-allegro/Allegro_si_MD.inp) + +### Input details + +The tag [ATOMS](#CP2K_INPUT.FORCE_EVAL.MM.FORCEFIELD.NONBONDED.ALLEGRO.ATOMS) expects a list of +elements/kinds in a way and order that is consistent with the YAML file of NequIP and Allegro. If +this is not done unphysical results will be obtained. Additionally, the atomic coordinates in the +[COORD](#CP2K_INPUT.FORCE_EVAL.SUBSYS.COORD) or [TOPOLOGY](#CP2K_INPUT.FORCE_EVAL.SUBSYS.TOPOLOGY) +section have to be provided in a way that is consistent with the YAML file. If this is not done +unphysical results will be obtained. Spotting such issues is quite straightforward as the energy is +significantly wrong. For example, by inverting the order of one of the elements in the test +`regtest-nequip/NequIP_water.inp`, the error with respect to the reference value is of the order of +1 eV. Additionally, running MD leads rapidly to highly unstable simulations. + +## Compiling CP2K with LibTorch + +Running with NequIP or Allegro requires compiling CP2K with the libtorch library. For the CP2K +binaries running on CPUs installing the toolchain using the flag `--with-libtorch` is enough. To +benefit from (often significant) GPU acceleration, the precompiled Libtorch library for CUDA can be +obtained at [https://pytorch.org](https://pytorch.org), for example for CUDA 11.8: + +```shell +wget https://download.pytorch.org/libtorch/cu118/libtorch-cxx11-abi-shared-with-deps-2.0.0%2Bcu118.zip +``` + +After extracting the libtorch CUDA binaries, the toolchain script `./install_cp2k_toolchain.sh` can +be run providing the appropriate path with the flag `--with-libtorch=`. + +## Further Resources + +For additional references on NequIP, Allegro and equivariant neural networks (e3nn) see: + +- Allegro paper [](#Musaelian2023) and code +- NequIP paper [](#Batzner2022) and code +- A Tutorial on LAMMPS by the NequIP/Allegro authors is found at the Colab notebook + [here](https://colab.research.google.com/drive/1yq2UwnET4loJYg_Fptt9kpklVaZvoHnq) +- For an introduction to e3nn see [e3nn.org](https://e3nn.org) and + [doi:10.5281/zenodo.7430260](https://dx.doi.org/10.5281/zenodo.7430260) diff --git a/docs/methods/machine_learning.md b/docs/methods/machine_learning.md index e68dde6f82..d7541f9158 100644 --- a/docs/methods/machine_learning.md +++ b/docs/methods/machine_learning.md @@ -5,7 +5,7 @@ titlesonly: maxdepth: 1 --- -Nequip / Allegro +allegro Neural Network Potentials pao-ml ```