From 9122b18c6f16a1298b8ccb00976a070ed1799e4a Mon Sep 17 00:00:00 2001 From: Aidan Thompson Date: Wed, 23 Dec 2020 10:17:55 -0700 Subject: [PATCH] Updated README files --- examples/mliap/README | 54 +++++++++++++++++++++++-------------------- src/MLIAP/README | 22 ++++++++++-------- 2 files changed, 41 insertions(+), 35 deletions(-) diff --git a/examples/mliap/README b/examples/mliap/README index 2641bdc975..9d7d22b0c5 100644 --- a/examples/mliap/README +++ b/examples/mliap/README @@ -1,7 +1,7 @@ -This directory contains multipler examples of +This directory contains multiple examples of machine-learning potentials defined using the MLIAP package in LAMMPS. The input files -are descirbed below. +are described below. in.mliap.snap.Ta06A ------------------- @@ -21,58 +21,62 @@ Run EME-SNAP, equivalent to examples/snap/in.snap.InP.JCPA2020 in.mliap.snap.compute --------------------- -Generate gradients w.r.t. coefficients for linear SNAP, -equivalent to in.snap.compute +Generate the A matrix, the gradients (w.r.t. coefficients) +of total potential energy, forces, and stress tensor for +linear SNAP, equivalent to in.snap.compute in.mliap.quadratic.compute -------------------------- -Generate gradients w.r.t. coefficients for quadratic SNAP, -equivalent to in.snap.compute.quadratic +Generate the A matrix, the gradients (w.r.t. coefficients) +of total potential energy, forces, and stress tensor for +for quadratic SNAP, equivalent to in.snap.compute.quadratic in.mliap.pytorch.Ta06A ----------------------- This reproduces the output of in.mliap.snap.Ta06A above, but using the Python coupling to PyTorch. -It can be run in two different ways: + +This example can be run in two different ways: 1: Running a LAMMPS executable: in.mliap.pytorch.Ta06A -First run convert_mliap_Ta06A.py, which will convert the Ta06A potential -into a pytorch model. It will be saved as "Ta06A.mliap.pytorch.model.pkl". +First run ``python convert_mliap_Ta06A.py``. It creates +a PyTorch energy model that replicates the +SNAP Ta06A potential and saves it in the file +"Ta06A.mliap.pytorch.model.pt". -It will also copy "../../src/MLIAP/mliappy_pytorch.py" -file into the current working directory. mliappy_pytorch.py contains -class definitions suitable for wrapping an arbitrary PyTorch -energy model. It must be available to python when -creating or unpickling a PyTorch energy model. - -From that point you can run the example as follows +You can then run the example as follows `lmp -in in.mliap.pytorch.Ta06A -echo both` The resultant log.lammps output should be identical to that generated by in.mliap.snap.Ta06A. +If this fails, see the instructions for building the MLIAP package +with Python support enabled. Also, confirm that the +LAMMPS Python embedded Python interpreter is +working by running ../examples/in.python. + 2: Running a Python script: mliap_pytorch_Ta06A.py -Before testing this, ensure that the first example -(using LAMMPS executable) works. -Also, not all python installations support this mode of operation. -It requires that the Python interpreter be initialized. -To check this for your Python library, -try running the Py_IsInitialized() method. -If the return value is True, you should be able to run the example, -as follows: +Before testing this, ensure that the previous method +(running a LAMMPS executable) works. + +You can run the example in serial: `python mliap_pytorch_Ta06A.py` -or +or in parallel: `mpirun -np 4 python mliap_pytorch_Ta06A.py` The resultant log.lammps output should be identical to that generated by in.mliap.snap.Ta06A and in.mliap.pytorch.Ta06A. +Not all Python installations support this mode of operation. +It requires that the Python interpreter be initialized. If not, +the script will exit with an error message. + in.mliap.pytorch.relu1hidden ---------------------------- This example demonstrates a simple neural network potential diff --git a/src/MLIAP/README b/src/MLIAP/README index 9179d9d02f..59eb5e34b3 100644 --- a/src/MLIAP/README +++ b/src/MLIAP/README @@ -8,12 +8,15 @@ definitions of the interatomic potential functional form (*model*) and the geometric quantities that characterize the atomic positions (*descriptor*). By defining *model* and *descriptor* separately, it is possible to use many different models with a given descriptor, -or many different descriptors with a given model. Currently, the pair_style -supports just two models, *linear* and *quadratic*, -and one descriptor, *sna*, the SNAP descriptor, including the -linear, quadratic, and chem variants. Work is currently underway to extend -the interface to handle neural network energy models, -and it is also straightforward to add new descriptor styles. +or many different descriptors with a given model. The pair_style +supports the following models: *linear*, *quadratic*, and +*mliappy* (general Python interface to things like PyTorch, see below +for build instructions). +It currently supports only one class of descriptors, +*sna*, the SNAP descriptors, including the +linear, quadratic, and chem variants. +It is straightforward to add new descriptor and model +styles. The mliap compute style provides gradients of the energy, force, and stress tensor w.r.t. model parameters. @@ -27,13 +30,13 @@ reference potential. To see how this command can be used within a Python workflow to train machine-learning interatomic -potentials, see the examples in FitSNAP https://github.com/FitSNAP/FitSNAP>. +potentials, see the examples in FitSNAP https://github.com/FitSNAP/FitSNAP. *Additional instructions for building MLIAP with Python support enabled* The *mliappy* energy model requires that the MLIAP package be compiled with Python support enabled. -This extension written by Nick Lubbers (LANL) +This extension, written by Nick Lubbers (LANL), provides a coupling to PyTorch and other Python modules. This should be automatically enabled by default if the prerequisite software is installed. It can be @@ -51,5 +54,4 @@ file(s) in the src/MLIAP folder or there may be problems during compilation. More information on building LAMMPS with this package is here: -https://lammps.sandia.gov/doc/html/Build_extras.html#mliap - +https://lammps.sandia.gov/doc/Build_extras.html#mliap