Merge pull request #2508 from athomps/mliappy3
Add support for Python based models to the MLIAP package
This commit is contained in:
Axel Kohlmeyer
@ -37,6 +37,7 @@ This is the list of packages that may require additional steps.
|
||||
* :ref:`KOKKOS <kokkos>`
|
||||
* :ref:`LATTE <latte>`
|
||||
* :ref:`MESSAGE <message>`
|
||||
* :ref:`MLIAP <mliap>`
|
||||
* :ref:`MSCG <mscg>`
|
||||
* :ref:`OPT <opt>`
|
||||
* :ref:`POEMS <poems>`
|
||||
@ -770,6 +771,54 @@ be installed on your system.
|
||||
|
||||
----------
|
||||
|
||||
.. _mliap:
|
||||
|
||||
MLIAP package
|
||||
---------------------------
|
||||
|
||||
Building the MLIAP package requires including the :ref:`SNAP <PKG-SNAP>`
|
||||
package. There will be an error message if this requirement is not satisfied.
|
||||
Using the *mliappy* model also requires enabling Python support, which
|
||||
in turn requires the :ref:`PYTHON <PKG-PYTHON>`
|
||||
package **and** requires you have the `cython <https://cython.org>`_ software
|
||||
installed and with it a working ``cythonize`` command. This feature requires
|
||||
compiling LAMMPS with Python version 3.6 or later.
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. tab:: CMake build
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
-D MLIAP_ENABLE_PYTHON=value # enable mliappy model (default is autodetect)
|
||||
|
||||
Without this setting, CMake will check whether it can find a
|
||||
suitable Python version and the ``cythonize`` command and choose
|
||||
the default accordingly. During the build procedure the provided
|
||||
.pyx file(s) will be automatically translated to C++ code and compiled.
|
||||
Please do **not** run ``cythonize`` manually in the ``src/MLIAP`` folder,
|
||||
as that can lead to compilation errors if Python support is not enabled.
|
||||
If you did by accident, please remove the generated .cpp and .h files.
|
||||
|
||||
.. tab:: Traditional make
|
||||
|
||||
The build uses the ``lib/python/Makefile.mliap_python`` file in the
|
||||
compile/link process to add a rule to update the files generated by
|
||||
the ``cythonize`` command in case the corresponding .pyx file(s) were
|
||||
modified. You may need to modify ``lib/python/Makefile.lammps``
|
||||
if the LAMMPS build fails.
|
||||
To manually enforce building MLIAP with Python support enabled,
|
||||
you can add
|
||||
``-DMLIAP_PYTHON`` to the ``LMP_INC`` variable in your machine makefile.
|
||||
You may have to manually run the ``cythonize`` command on .pyx file(s)
|
||||
in the ``src`` folder, if this is not automatically done during
|
||||
installing the MLIAP package. Please do **not** run ``cythonize``
|
||||
in the ``src/MLIAP`` folder, as that can lead to compilation errors
|
||||
if Python support is not enabled.
|
||||
If you did by accident, please remove the generated .cpp and .h files.
|
||||
|
||||
----------
|
||||
|
||||
.. _mscg:
|
||||
|
||||
MSCG package
|
||||
|
||||
@ -662,19 +662,31 @@ MLIAP package
|
||||
|
||||
**Contents:**
|
||||
|
||||
A general interface for machine-learning interatomic potentials.
|
||||
A general interface for machine-learning interatomic potentials, including PyTorch.
|
||||
|
||||
**Install:**
|
||||
|
||||
To use this package, also the :ref:`SNAP package <PKG-SNAP>` needs to be installed.
|
||||
To use this package, also the :ref:`SNAP package <PKG-SNAP>` package needs
|
||||
to be installed. To make the *mliappy* model available, also the
|
||||
:ref:`PYTHON package <PKG-PYTHON>` package needs to be installed, the version of
|
||||
Python must be 3.6 or later, and the `cython <https://cython.org/>`_ software
|
||||
must be installed.
|
||||
|
||||
**Author:** Aidan Thompson (Sandia).
|
||||
**Author:** Aidan Thompson (Sandia), Nicholas Lubbers (LANL).
|
||||
|
||||
**Supporting info:**
|
||||
|
||||
* src/MLIAP: filenames -> commands
|
||||
* src/MLIAP/README
|
||||
* :doc:`pair_style mliap <pair_mliap>`
|
||||
* examples/mliap
|
||||
* :doc:`compute_style mliap <compute_mliap>`
|
||||
* examples/mliap (see README)
|
||||
|
||||
When built with the *mliappy* model this package includes an extension for
|
||||
coupling with Python models, including PyTorch. In this case, the Python
|
||||
interpreter linked to LAMMPS will need the ``cython`` and ``numpy`` modules
|
||||
installed. The provided examples build models with PyTorch, which would
|
||||
therefore also needs to be installed to run those examples.
|
||||
|
||||
----------
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ Syntax
|
||||
.. parsed-literal::
|
||||
|
||||
*model* values = style
|
||||
style = *linear* or *quadratic*
|
||||
style = *linear* or *quadratic* or *mliappy*
|
||||
*descriptor* values = style filename
|
||||
style = *sna*
|
||||
filename = name of file containing descriptor definitions
|
||||
@ -56,13 +56,15 @@ and it is also straightforward to add new descriptor styles.
|
||||
The compute *mliap* command must be followed by two keywords
|
||||
*model* and *descriptor* in either order.
|
||||
|
||||
The *model* keyword is followed by a model style, currently limited to
|
||||
either *linear* or *quadratic*.
|
||||
The *model* keyword is followed by the model style (*linear*, *quadratic* or *mliappy*).
|
||||
The *mliappy* model is only available
|
||||
if lammps is built with MLIAPPY package.
|
||||
|
||||
The *descriptor* keyword is followed by a descriptor style, and additional arguments.
|
||||
Currently the only descriptor style is *sna*, indicating the bispectrum component
|
||||
descriptors used by the Spectral Neighbor Analysis Potential (SNAP) potentials of
|
||||
:doc:`pair_style snap <pair_snap>`.
|
||||
The compute currently supports just one descriptor style, but it is
|
||||
is straightforward to add new descriptor styles.
|
||||
The SNAP descriptor style *sna* is the same as that used by :doc:`pair_style snap <pair_snap>`,
|
||||
including the linear, quadratic, and chem variants.
|
||||
A single additional argument specifies the descriptor filename
|
||||
containing the parameters and setting used by the SNAP descriptor.
|
||||
The descriptor filename usually ends in the *.mliap.descriptor* extension.
|
||||
@ -162,9 +164,10 @@ potentials, see the examples in `FitSNAP <https://github.com/FitSNAP/FitSNAP>`_.
|
||||
Restrictions
|
||||
""""""""""""
|
||||
|
||||
This compute is part of the MLIAP package. It is only enabled if
|
||||
LAMMPS was built with that package. In addition, building LAMMPS with the MLIAP package
|
||||
This compute is part of the MLIAP package. It is only enabled if LAMMPS
|
||||
was built with that package. In addition, building LAMMPS with the MLIAP package
|
||||
requires building LAMMPS with the SNAP package.
|
||||
The *mliappy* model requires building LAMMPS with the PYTHON package.
|
||||
See the :doc:`Build package <Build_package>` doc page for more info.
|
||||
|
||||
Related commands
|
||||
|
||||
@ -16,7 +16,7 @@ Syntax
|
||||
.. parsed-literal::
|
||||
|
||||
*model* values = style filename
|
||||
style = *linear* or *quadratic*
|
||||
style = *linear* or *quadratic* or *mliappy*
|
||||
filename = name of file containing model definitions
|
||||
*descriptor* values = style filename
|
||||
style = *sna*
|
||||
@ -40,12 +40,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 used by :doc:`pair_style snap <pair_snap>`, 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 currently supports just one descriptor style, but it is
|
||||
is straightforward to add new descriptor styles.
|
||||
The SNAP descriptor style *sna* is the same as that used by :doc:`pair_style snap <pair_snap>`,
|
||||
including the linear, quadratic, and chem variants.
|
||||
The available models are *linear*, *quadratic*, and *mliappy*.
|
||||
The *mliappy* style can be used to couple python models,
|
||||
e.g. PyTorch neural network energy models, and requires building
|
||||
LAMMPS with the PYTHON package (see below).
|
||||
In order to train a model, it is useful to know the gradient or derivative
|
||||
of energy, force, and stress w.r.t. model parameters. This information
|
||||
can be accessed using the related :doc:`compute mliap <compute_mliap>` command.
|
||||
@ -59,9 +62,8 @@ that specify the mapping of MLIAP
|
||||
element names to LAMMPS atom types,
|
||||
where N is the number of LAMMPS atom types.
|
||||
|
||||
The *model* keyword is followed by a model style, currently limited to
|
||||
either *linear* or *quadratic*. In both cases,
|
||||
this is followed by a single argument specifying the model filename containing the
|
||||
The *model* keyword is followed by the model style. This is followed
|
||||
by a single argument specifying the model filename containing the
|
||||
parameters for a set of elements.
|
||||
The model filename usually ends in the *.mliap.model* extension.
|
||||
It may contain parameters for many elements. The only requirement is that it
|
||||
@ -82,6 +84,16 @@ for the :doc:`pair_style snap <pair_snap>` coefficient file.
|
||||
Specifically, the line containing the element weight and radius is omitted,
|
||||
since these are handled by the *descriptor*.
|
||||
|
||||
Notes on mliappy models:
|
||||
When the *model* keyword is *mliappy*, the filename should end in '.pt',
|
||||
'.pth' for pytorch models, or be a pickle file. To load a model from
|
||||
memory (i.e. an existing python object), specify the filename as
|
||||
"LATER", and then call `lammps.mliap.load_model(model)` from python
|
||||
before using the pair style. When using lammps via the library mode, you will need to call
|
||||
`lammps.mliappy.activate_mliappy(lmp)` on the active lammps object
|
||||
before the pair style is defined. This call locates and loads the mliap-specific
|
||||
python module that is built into lammps.
|
||||
|
||||
The *descriptor* keyword is followed by a descriptor style, and additional arguments.
|
||||
Currently the only descriptor style is *sna*, indicating the bispectrum component
|
||||
descriptors used by the Spectral Neighbor Analysis Potential (SNAP) potentials of
|
||||
@ -138,11 +150,13 @@ This pair style can only be used via the *pair* keyword of the
|
||||
Restrictions
|
||||
""""""""""""
|
||||
|
||||
This style is part of the MLIAP package. It is only enabled if LAMMPS
|
||||
This pair style is part of the MLIAP package. It is only enabled if LAMMPS
|
||||
was built with that package. In addition, building LAMMPS with the MLIAP package
|
||||
requires building LAMMPS with the SNAP package.
|
||||
The *mliappy* model requires building LAMMPS with the PYTHON package.
|
||||
See the :doc:`Build package <Build_package>` doc page for more info.
|
||||
|
||||
|
||||
Related commands
|
||||
""""""""""""""""
|
||||
|
||||
|
||||
Reference in New Issue
Block a user