diff --git a/doc/src/compute_mliap.rst b/doc/src/compute_mliap.rst new file mode 100644 index 0000000000..c04a647993 --- /dev/null +++ b/doc/src/compute_mliap.rst @@ -0,0 +1,154 @@ +.. index:: compute mliap + +compute mliap command +==================== + +Syntax +"""""" + +.. code-block:: LAMMPS + + compute mliap + +Examples +"""""""" + +.. code-block:: LAMMPS + + compute mliap model linear nelems nparams descriptor sna InP.mliap.descriptor + +Description +""""""""""" + +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 ` to match target data. +It provides separate +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 +compute supports just two models, *linear* and *quadratic*, +and one descriptor, *sna*, the SNAP descriptor used by +:doc:`pair_style 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. + +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*. 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 +are identical to those of *nelems* and *nparams* in the +:doc:`pair_style mliap ` model file. + +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 `. +The \'p\' in SNAP is dropped, because keywords that match pair_styles are silently stripped +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 +:doc:`pair_style mliap `, and is described in detail +there. + +.. note:: + +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 +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. + +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. +The potential energy calculation uses the built in compute *thermo_pe*. +The stress calculation uses a compute called *snap_press* that is +automatically created behind the scenes, according to the following +command: + +.. code-block:: LAMMPS + + compute snap_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 +too frequently. + +.. note:: + + If you have a bonded system, then the settings of + :doc:`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 ` + 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 ` + command to compute the bispectrum components for snapshots in the dump + file. The rerun script can use a :doc:`special_bonds ` + command that includes all pairs in the neighbor list. + +---------- + +**Output info:** + +Compute *mliap* evaluates a global array. +The columns are arranged into +*nelems* blocks, listed in order of element *I*\ . Each block +contains one column for each of the *nparams* model parameters. +A final column contains the corresponding energy, force component +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*. + +These values can be accessed by any command that uses per-atom values +from a compute as input. See the :doc:`Howto output ` doc +page for an overview of LAMMPS output options. + +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 +requires building LAMMPS with the SNAP package. +See the :doc:`Build package ` doc page for more info. +doc page for more info. + +Related commands +"""""""""""""""" + +:doc:`pair_style snap ` + +**Default:** none diff --git a/doc/src/pair_mliap.rst b/doc/src/pair_mliap.rst index b569a26910..c65c4c66d5 100644 --- a/doc/src/pair_mliap.rst +++ b/doc/src/pair_mliap.rst @@ -47,9 +47,9 @@ 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 -linear or quadratic coefficients for a set of elements. +parameters for a set of elements. The model filename usually ends in the *.mliap.model* extension. -It may contain coefficients for many elements. The only requirement is that it +It may contain parameters for many elements. The only requirement is that it contain at least those element names appearing in the *pair_coeff* command. @@ -58,10 +58,10 @@ but follows a strict format after that. The first non-blank non-comment line must contain two integers: * nelems = Number of elements -* ncoeff = Number of coefficients +* nparams = Number of parameters This is followed by one block for each of the *nelem* elements. -Each block consists of *ncoeff* coefficients, one per line. +Each block consists of *nparams* parameters, one per line. Note that this format is similar, but not identical to that used for the :doc:`pair_style snap ` coefficient file. Specifically, the line containing the element weight and radius is omitted,