lammps/examples/mliap

This directory contains multiple examples of
machine-learning potentials defined using the
ML-IAP package in LAMMPS. The input files
are described below.

in.mliap.snap.Ta06A
-------------------
Run linear SNAP, equivalent to examples/snap/in.snap.Ta06A

in.mliap.snap.WBe.PRB2019
-------------------------
Run linear SNAP, equivalent to examples/snap/in.snap.WBe.PRB2019

in.mliap.snap.quadratic
-----------------------
Run quadratic SNAP

in.mliap.snap.chem
------------------
Run EME-SNAP, equivalent to examples/snap/in.snap.InP.JCPA2020

in.mliap.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 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.

This example can be run in two different ways:

1: Running a LAMMPS executable: in.mliap.pytorch.Ta06A

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".

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 ML-IAP 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 previous method
(running a LAMMPS executable) works.

You can run the example in serial:

`python mliap_pytorch_Ta06A.py`

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
using PyTorch and SNAP descriptors.

`lmp -in in.mliap.pytorch.relu1hidden -echo both`

It was trained on just the energy component (no forces) of
the data used in the original SNAP Ta06A potential for
tantalum (Thompson, Swiler, Trott, Foiles, Tucker,
J Comp Phys, 285, 316 (2015).). Because of the very small amount
of energy training data, it uses just 1 hidden layer with
a ReLU activation function. It is not expected to be
very accurate for forces.

NOTE: Unlike the previous example, this example uses
a pre-built PyTorch file `Ta06A.mliap.pytorch.model.pt`.
It is read using `torch.load`,
which implicitly uses the Python `pickle` module.
This is known to be insecure. It is possible to construct malicious
pickle data that will execute arbitrary code during unpickling. Never
load data that could have come from an untrusted source, or that
could have been tampered with. Only load data you trust.

in.mliap.nn.Ta06A
-------------------
Run linear SNAP using the "nn" model style, equivalent to examples/snap/in.snap.Ta06A

in.mliap.nn.cu
-------------------------
Run a neural network potential for Cu, a combination of SNAP descriptors and the "nn" model style

in.mliap.unified.lj.Ar
-----------------------
This reproduces the output of examples/melt/in.melt,
but using the ``unified`` keyword and
the Python coupling to PyTorch.

This example can be run in two different ways:

1: Running a LAMMPS executable: in.mliap.unified.lj.Ar

You can run the example as follows

`lmp -in in.mliap.unified.lj.Ar -echo both`

The resultant thermo output should be identical to that generated
by in.melt.

The input first runs some python code that creates an ML-IAP unified model
that replicates the ``lj/cut`` pair style with parameters as defined in
examples/melt/in/melt and saves it in the file "mliap_unified_lj_Ar.pkl".

If this fails, see the instructions for building the ML-IAP package
with Python support enabled. Also, confirm that the LAMMPS Python
embedded Python interpreter is working by running ../examples/in.python
and that the LAMMPS python module is installed and working.

2: Running a Python script: mliap_unified_lj_Ar.py

Before testing this, ensure that the previous method
(running a LAMMPS executable) works.

You can run the example in serial:

`python mliap_unified_lj_Ar.py`

or in parallel:

`mpirun -np 4 python mliap_unified_lj_Ar.py`

The resultant log.lammps output should be identical to that generated
by in.melt and in.mliap.unified.lj.Ar.

in.mliap.so3.Ni_Mo
------------------

Example of linear model with SO3 descriptors for Ni/Mo

in.mliap.so3.nn.Si
------------------

Example of NN model with SO3 descriptors for Si