* ID, group-ID are documented in :doc:`compute <compute>` command
* mliap = style name of this compute command
* two keyword/value pairs must be appended
* keyword = *model* or *descriptor*
.. parsed-literal::
*model* values = style Nelems Nparams
style = *linear* or *quadratic*
Nelems = number of elements
Nparams = number of parameters per element
*descriptor* values = style filename
style = *sna*
filename = name of file containing descriptor definitions
Examples
""""""""
.. code-block:: LAMMPS
compute mliap model linear nelems nparams descriptor sna InP.mliap.descriptor
compute mliap model linear 2 31 descriptor sna Ta06A.mliap.descriptor
Description
"""""""""""
@@ -24,7 +39,7 @@ Compute style *mliap* provides a general interface to the gradient
of machine-learning interatomic potentials w.r.t. model parameters.
It is used primarily for calculating the gradient of energy, force, and
stress components w.r.t. model parameters, which is useful when training
:doc:`MLIAP pair_style <pair_mliap>` to match target data.
:doc:`mliap pair_style <pair_mliap>` models to match target data.
It provides separate
definitions of the interatomic potential functional form (*model*)
and the geometric quantities that characterize the atomic positions
@@ -46,7 +61,7 @@ either *linear* or *quadratic*. In both cases,
this is followed by two arguments. *nelems* is the number of elements.
It must be equal to the number of LAMMPS atom types. *nparams*
is the number of parameters per element for this model i.e.
the number of paramter gradients for each element. Note these definitions
the number of parameter gradients for each element. Note these definitions
are identical to those of *nelems* and *nparams* in the
:doc:`pair_style mliap <pair_mliap>` model file.
@@ -58,7 +73,7 @@ The \'p\' in SNAP is dropped, because keywords that match pair_styles are silent
out by the LAMMPS command parser. 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.
The format of this file is identical to descriptor file in the
The format of this file is identical to the descriptor file in the
:doc:`pair_style mliap <pair_mliap>`, and is described in detail
there.
@@ -68,33 +83,34 @@ The number of LAMMPS atom types (and the value of *nelems* in the model)
must match the value of *nelems* in the descriptor file.
Compute *mliap* calculates a global array containing gradient information.
The number of columns in the array is the :math:`nelems \times nparams + 1`.
The first row of the array contain the derivative of potential energy w.r.t to
The number of columns in the array is :math:`nelems \times nparams + 1`.
The first row of the array contain the derivative of potential energy w.r.t. to
each parameter and each element. The last six rows
of the array contain the corresponding derivatives of the
virial stress tensor, listed in Voigt notation: *pxx*, *pyy*, *pzz*,
*pyz*, *pxz*, *pxy*. In between 3\*\ *N* rows containing the derivatives
of the force components.
*pyz*, *pxz*, *pxy*. In between the energy and stress rows are
the 3\*\ *N* rows containing the derivatives of the force components.
See section below on output for a detailed description of how
rows and columns are ordered.
The element in the last column of each row contains
the potential energy, force, or stress, according to the row.
These quantities correspond to the user-specified reference potential
that must be subtracted from the target data when fitting SNAP.
that must be subtracted from the target data when training a model.
The potential energy calculation uses the built in compute *thermo_pe*.
The stress calculation uses a compute called *snap_press* that is
The stress calculation uses a compute called *mliap_press* that is
automatically created behind the scenes, according to the following
command:
.. code-block:: LAMMPS
compute snap_press all pressure NULL virial
compute mliap_press all pressure NULL virial
See section below on output for a detailed explanation of the data
layout in the global array.
Atoms not in the group do not contribute to this compute.
Neighbor atoms not in the group do not contribute to this compute.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
@@ -102,17 +118,19 @@ too frequently.
.. note::
If you have a bonded system, then the settings of
If the user-specified reference potentials includes bonded and
non-bonded pairwise interactions, then the settings of
:doc:`special_bonds <special_bonds>` command can remove pairwise
interactions between atoms in the same bond, angle, or dihedral. This
is the default setting for the :doc:`special_bonds <special_bonds>`
command, and means those pairwise interactions do not appear in the
neighbor list. Because this fix uses the neighbor list, it also means
those pairs will not be included in the calculation. One way to get
around this, is to write a dump file, and use the :doc:`rerun <rerun>`
command to compute the bispectrum components for snapshots in the dump
file. The rerun script can use a :doc:`special_bonds <special_bonds>`
command that includes all pairs in the neighbor list.
those pairs will not be included in the calculation. The :doc:`rerun <rerun>`
command is not an option here, since the reference potential is required
for the last column of the global array. A work-around is to prevent
pairwise interactions from being removed by explicitly adding a
*tiny* positive value for every pairwise interaction that would otherwise be
set to zero in the :doc:`special_bonds <special_bonds>` command.
----------
@@ -127,15 +145,14 @@ on an atom, or virial stress component. The rows of the array appear
in the following order:
* 1 row: Derivatives of potential energy w.r.t. each parameter of each element.
* 3\*\ *N* rows: Derivatives of force components. x, y, and z components of
force on atom *i* appearing in consecutive rows. The atoms are sorted based on atom ID.
* 6 rows: Derivatives of virial stress tensor w.r.t. each parameter of each element.
The ordering of the rows follows Voigt notation: *pxx*, *pyy*, *pzz*,
*pyz*, *pxz*, *pxy*.
* 3\*\ *N* rows: Derivatives of force components. x, y, and z components of force on atom *i* appearing in consecutive rows. The atoms are sorted based on atom ID.
* 6 rows: Derivatives of virial stress tensor w.r.t. each parameter of each element. The ordering of the rows follows Voigt notation: *pxx*, *pyy*, *pzz*, *pyz*, *pxz*, *pxy*.
These values can be accessed by any command that uses per-atom values
These values can be accessed by any command that uses a global array
from a compute as input. See the :doc:`Howto output <Howto_output>` doc
page for an overview of LAMMPS output options.
page for an overview of LAMMPS output options. 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>`_.
Restrictions
""""""""""""
@@ -144,11 +161,10 @@ 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.
See the :doc:`Build package <Build_package>` doc page for more info.
