integrate documentation

doc/src/Packages_details.rst

@@ -100,6 +100,7 @@ page gives those details.
    * :ref:`USER-QMMM <PKG-USER-QMMM>`
    * :ref:`USER-QTB <PKG-USER-QTB>`
    * :ref:`USER-QUIP <PKG-USER-QUIP>`
+   * :ref:`USER-RANN <PKG-USER-RANN>`
    * :ref:`USER-REACTION <PKG-USER-REACTION>`
    * :ref:`USER-REAXC <PKG-USER-REAXC>`
    * :ref:`USER-SCAFACOS <PKG-USER-SCAFACOS>`
@@ -2277,6 +2278,31 @@ This package has :ref:`specific installation instructions <user-quip>` on the :d
 
 ----------
 
+.. _PKG-USER-RANN:
+
+USER-RANN package
+-----------------
+
+**Contents:**
+
+A pair style for using rapid atomistic neural network (RANN) potentials.
+These neural network potentials work by first generating a series of symmetry
+functions from the neighbor list and then using these values as the input layer
+of a neural network.
+
+**Authors:**
+
+This package was written by Christopher Barrett
+with contributions by Doyl Dickel, Mississippi State University.
+
+**Supporting info:**
+
+* src/USER-RANN: filenames -> commands
+* :doc:`pair_style rann <pair_rann>`
+* examples/USER/rann
+
+----------
+
 .. _PKG-USER-REACTION:
 
 USER-REACTION package

doc/src/Packages_user.rst

@@ -101,6 +101,8 @@ package:
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-QUIP <PKG-USER-QUIP>`               | QUIP/libatoms interface                                         | :doc:`pair_style quip <pair_quip>`                                            | USER/quip                                            | ext     |
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
+| :ref:`USER-RANN <PKG-USER-RANN>`               | rapid atomistic neural network (RANN) potentials                | :doc:`pair rann <pair_rann>`                                                  | USER/rann                                            | no      |
++------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-REACTION <PKG-USER-REACTION>`       | chemical reactions in classical MD                              | :doc:`fix bond/react <fix_bond_react>`                                        | USER/reaction                                        | no      |
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-REAXC <PKG-USER-REAXC>`             | ReaxFF potential (C/C++)                                        | :doc:`pair_style reaxc <pair_reaxc>`                                          | reax                                                 | no      |

doc/src/pair_rann.rst

@@ -23,49 +23,43 @@ Examples
 Description
 """""""""""
 
-Style *rann* computes pairwise interactions for a variety of materials
+Pair style *rann* computes pairwise interactions for a variety of
-using rapid atomistic neural network (RANN) potentials (:ref:`Dickel <Dickel>` , :ref:`Nitol <Nitol>`).
+materials using rapid atomistic neural network (RANN) potentials
-Neural network potentials work by first generating a series of symmetry functions
+(:ref:`Dickel <Dickel>` , :ref:`Nitol <Nitol>`).  Neural network
-i.e. structural fingerprints from the neighbor list and then using these values
+potentials work by first generating a series of symmetry functions
-as the input layer of a neural network. There is a single output neuron in the
+i.e. structural fingerprints from the neighbor list and then using these
-final layer which is the energy. Atomic forces are found by analytical
+values as the input layer of a neural network.  There is a single output
-derivatives computed via backpropagation. For alloy systems, each element has a unique
+neuron in the final layer which is the energy.  Atomic forces are found
-network.
+by analytical derivatives computed via back-propagation.  For alloy
+systems, each element has a unique network.
 
 Potential file syntax
 """""""""""""""""""""
 
-The RANN potential is defined by a single text file which contains all the fitting parameters for the alloy system.
+The RANN potential is defined by a single text file which contains all
-The potential file also defines the active fingerprints, network architecture, activation functions, etc.
+the fitting parameters for the alloy system.  The potential file also
-The potential file is divided into several sections which are identified by one of the following keywords:
+defines the active fingerprints, network architecture, activation
+functions, etc.  The potential file is divided into several sections
+which are identified by one of the following keywords:
 
 * atomtypes
-
 * mass
-
 * fingerprintsperelement
-
 * fingerprints
-
 * fingerprintconstants
-
 * screening (optional)
-
 * networklayers
-
 * layersize
-
 * weight
-
 * bias
-
 * activationfunctions
-
 * calibrationparameters (ignored)
 
-# is treated as a comment marker, similar to LAMMPS input scripts. Sections are not required to follow a rigid
+The '#' character is treated as a comment marker, similar to LAMMPS
-ordering, but do require previous definition of prerequisite information. E.g., fingerprintconstants for a
+input scripts.  Sections are not required to follow a rigid ordering,
-particular fingerprint must follow the fingerprints definition; layersize for a particular layer must follow
+but do require previous definition of prerequisite information.  E.g.,
+fingerprintconstants for a particular fingerprint must follow the
+fingerprints definition; layersize for a particular layer must follow
 the declaration of network layers.
 
 *atomtypes* are defined as follows using element keywords separated by spaces.
@@ -86,15 +80,20 @@ the declaration of network layers.
     mass:Al:
     26.982
 
-*fingerprintsperelement* specifies how many fingerprints are active for computing the energy of a given atom.
+*fingerprintsperelement* specifies how many fingerprints are active for
-This number must be specified for each element keyword. Active elements for each fingerprint depend upon the
+computing the energy of a given atom.  This number must be specified for
-type of the central atom and the neighboring atoms. Pairwise fingerprints may be defined for a Mg atom based
+each element keyword.  Active elements for each fingerprint depend upon
-exclusively on its Al neighbors, for example. Bond fingerprints may use two neighborlists of different
+the type of the central atom and the neighboring atoms.  Pairwise
-element types. In computing fingerprintsperelement from all defined fingerprints, only the fingerprints
+fingerprints may be defined for a Mg atom based exclusively on its Al
-defined for atoms of a particular element should be considered, regardless of the elements used in its
+neighbors, for example.  Bond fingerprints may use two neighbor lists of
-neighbor list. In the following code, for example, some fingerprints may compute pairwise fingerprints summing
+different element types.  In computing fingerprintsperelement from all
-contributions about Fe atoms based on a neighbor list of exclusively Al atoms, but if there are no fingerprints
+defined fingerprints, only the fingerprints defined for atoms of a
-summing contributions of all neighbors about a central Al atom, then fingerprintsperelement of Al is zero:
+particular element should be considered, regardless of the elements used
+in its neighbor list.  In the following code, for example, some
+fingerprints may compute pairwise fingerprints summing contributions
+about Fe atoms based on a neighbor list of exclusively Al atoms, but if
+there are no fingerprints summing contributions of all neighbors about a
+central Al atom, then fingerprintsperelement of Al is zero:
 
 .. code-block::
 
@@ -105,15 +104,21 @@ summing contributions of all neighbors about a central Al atom, then fingerprint
     fingerprintsperelement:Al:
     0
 
-*fingerprints* specifies the active fingerprints for a certain element combination. Pair fingerprints are
+*fingerprints* specifies the active fingerprints for a certain element
-specified for two elements, while bond fingerprints are specified for three elements. Only one fingerprints
+combination.  Pair fingerprints are specified for two elements, while
-header should be used for an individual combination of elements. The ordering of the fingerprints in the
+bond fingerprints are specified for three elements.  Only one
-network input layer is determined by the order of element combinations specified by subsequent *fingerprints*
+fingerprints header should be used for an individual combination of
-lines, and the order of the fingerprints defined for each element combination. Multiple fingerprints of the same style or
+elements.  The ordering of the fingerprints in the network input layer
-different ones may be specified. If the same style and element combination is used for multiple fingerprints,
+is determined by the order of element combinations specified by
-they should have different id numbers. The first element specifies the atoms for which this fingerprint is
+subsequent *fingerprints* lines, and the order of the fingerprints
-computed while the other(s) specify which atoms to use in the neighbor lists for the computation. Switching
+defined for each element combination.  Multiple fingerprints of the same
-the second and third element type in bond fingerprints has no effect on the computation:
+style or different ones may be specified.  If the same style and element
+combination is used for multiple fingerprints, they should have
+different id numbers.  The first element specifies the atoms for which
+this fingerprint is computed while the other(s) specify which atoms to
+use in the neighbor lists for the computation.  Switching the second and
+third element type in bond fingerprints has no effect on the
+computation:
 
 .. code-block::
 
@@ -124,25 +129,19 @@ the second and third element type in bond fingerprints has no effect on the comp
     fingerprints:Mg_Al:
     radial_0 radialscreened_0
 
-The following fingerprint styles are currently defined. See the :ref:`formulation section <fingerprints>` below for their definitions:
+The following fingerprint styles are currently defined.  See the
+:ref:`formulation section <fingerprints>` below for their definitions:
 
 * radial
-
 * radialscreened
-
 * radialspin
-
 * radialscreenedspin
-
 * bond
-
 * bondscreened
-
 * bondspin
-
 * bondscreenedspin
 
-*fingerprintconstants*  specifies the metaparameters for a defined fingerprint. For all radial styles, re, rc,
+*fingerprintconstants*  specifies the meta-parameters for a defined fingerprint.  For all radial styles, re, rc,
 alpha, dr, o, and n must be specified.  re should usually be the stable interatomic distance, rc is the cutoff
 radius, dr is the cutoff smoothing distance, o is the lowest radial power term (which may be negative), and n
 is the highest power term.  The total length of the fingerprint vector is (n-o+1).  alpha is a list of decay parameters
@@ -167,12 +166,16 @@ length of the fingerprint vector is m*k.
    fingerprintconstants:Mg_Mg:radialscreened_0:n:
    3
 
-*screening* specifies the Cmax and Cmin values used in the screening fingerprints. Neighbors' contribution to the
+*screening* specifies the Cmax and Cmin values used in the screening
-fingerprint are omitted if they are blocked by a closer neighbor, and reduced if they are partially blocked.
+fingerprints. Contributions form neighbors to the fingerprint are
-Larger values of Cmin correspond to neighbors being blocked more easily. Cmax cannot be greater than 3, and
+omitted if they are blocked by a closer neighbor, and reduced if they
-Cmin cannot be greater than Cmax or less than zero. Screening may be omitted in which case the default values
+are partially blocked.  Larger values of Cmin correspond to neighbors
-Cmax = 2.8, Cmin = 0.8 are used. Since screening is a bond computation, it is specified separately for each
+being blocked more easily.  Cmax cannot be greater than 3, and Cmin
-combination of three elements in which the latter two may be interchanged with no effect.
+cannot be greater than Cmax or less than zero.  Screening may be omitted
+in which case the default values Cmax = 2.8, Cmin = 0.8 are used.  Since
+screening is a bond computation, it is specified separately for each
+combination of three elements in which the latter two may be
+interchanged with no effect.
 
 .. code-block::
 
@@ -181,17 +184,18 @@ combination of three elements in which the latter two may be interchanged with n
     screening:Mg_Mg_Mg:Cmin:
     0.400000
 
-*networklayers* species the size of the neural network for each atom. It counts both the input and output layer
+*networklayers* species the size of the neural network for each atom.
-and so is 2+hiddenlayers.
+It counts both the input and output layer and so is 2 + \<hidden layers\>.
 
 .. code-block::
 
    networklayers:Mg:
    3
 
-*layersize* specifies the length of each layer, including the input layer and output layer. The input layer is
+*layersize* specifies the length of each layer, including the input
-layer 0. The size of the input layer size must match the summed length of all the fingerprints for that element,
+layer and output layer.  The input layer is layer 0.  The size of the
-and the output layer size must be 1:
+input layer size must match the summed length of all the fingerprints
+for that element, and the output layer size must be 1:
 
 .. code-block::
 
@@ -202,8 +206,11 @@ and the output layer size must be 1:
     layersize:Mg:2:
     1
 
-*weight* specifies the weight for a given element and layer. Weight cannot be specified for the output layer.
+
-The weight of layer i is a mxn matrix where m is the layer size of i and n is the layer size of i+1:
+*weight* specifies the weight for a given element and layer.  Weight
+cannot be specified for the output layer.  The weight of layer i is a
+*m* x *n* matrix where *m* is the layer size of *i* and *n* is the layer size of
+*i*\ +1:
 
 .. code-block::
 
@@ -212,8 +219,9 @@ The weight of layer i is a mxn matrix where m is the layer size of i and n is th
    w21 w22 w23 ...
    ...
 
-*bias* specifies the bias for a given element and layer. Bias cannot be specified for the output layer.
+*bias* specifies the bias for a given element and layer.  Bias cannot be
-The bias of layer i is a nx1 vector where n is the layer size of i+1:
+specified for the output layer.  The bias of layer i is a nx1 vector
+where n is the layer size of i+1:
 
 .. code-block::
 
@@ -223,8 +231,9 @@ The bias of layer i is a nx1 vector where n is the layer size of i+1:
    b3
    ...
 
-*activationfunctions* specifies the activation function for a given element and layer. Activation functions
+*activationfunctions* specifies the activation function for a given
-cannot be specified for the output layer:
+element and layer.  Activation functions cannot be specified for the
+output layer:
 
 .. code-block::
 
@@ -233,7 +242,8 @@ cannot be specified for the output layer:
     activationfunctions:Mg:1:
     linear
 
-The following activation styles are currently specified. See the :ref:`formulation section <activations>` below for their definitions.
+The following activation styles are currently specified.  See the
+:ref:`formulation section <activations>` below for their definitions.
 
 * sigI
 
@@ -255,19 +265,26 @@ is given by:
     {}^{n+1}\!A_i^{\alpha} = {}^{n}\!F\left({}^{n}\!W_{ij}{\;}^{n}\!A_j^{\alpha}+{}^{n}\!B_i\right)\\\\
     {}^{0}\!A_i^{\alpha} = \left[\begin{array}{c} {}^1\!S\!f^\alpha\\ {}^2\!S\!f^\alpha \\...\\\end{array}\right]
 
-Here :math:`E^\alpha` is the energy of atom :math:`\alpha`, :math:`{}^n\!F()`, :math:`{}^n\!W_{ij}` and :math:`{}^n\!B_i` are
+Here :math:`E^\alpha` is the energy of atom :math:`\alpha`,
-the activation function, weight matrix and bias vector of the n-th layer respectively. The
+:math:`{}^n\!F()`, :math:`{}^n\!W_{ij}` and :math:`{}^n\!B_i` are the
-inputs to the first layer are a collection of structural fingerprints which are collected and reshaped into a single long vector.
+activation function, weight matrix and bias vector of the n-th layer
-The individual fingerprints may be defined in any order and have various shapes and sizes. Multiple fingerprints of the same
+respectively.  The inputs to the first layer are a collection of
+structural fingerprints which are collected and reshaped into a single
+long vector.  The individual fingerprints may be defined in any order
+and have various shapes and sizes.  Multiple fingerprints of the same
 type and varying parameters may also be defined in the input layer.
 
-Eight types of structural fingerprints are currently defined. In the following, :math:`\beta` and :math:`\gamma` span the
+Eight types of structural fingerprints are currently defined.  In the
-full neighborlist of atom :math:`\alpha`. :math:`\delta_i` are decay metaparameters, and :math:`r_e` is a metaparameter
+following, :math:`\beta` and :math:`\gamma` span the full neighbor list
-roughly proportional to the first neighbor distance. :math:`r_c` and :math:`dr` are the neighbor cutoff distance and
+of atom :math:`\alpha`.  :math:`\delta_i` are decay meta-parameters, and
-cutoff smoothing distance respectively. :math:`S^{\alpha\beta}` is the MEAM screening function
+:math:`r_e` is a meta-parameter roughly proportional to the first
-:ref:`(Baskes) <Baskes97>`, :math:`s_i^\alpha` and :math:`s_i^\beta` are the atom spin vectors :ref:`(Tranchida) <Tranchida>`.
+neighbor distance.  :math:`r_c` and :math:`dr` are the neighbor cutoff
-:math:`r^{\alpha\beta}` is the distance from atom :math:`\alpha` to atom :math:`\beta`, and :math:`\theta^{\alpha\beta\gamma}`
+distance and cutoff smoothing distance respectively.
-is the bond angle:
+:math:`S^{\alpha\beta}` is the MEAM screening function :ref:`(Baskes)
+<Baskes97>`, :math:`s_i^\alpha` and :math:`s_i^\beta` are the atom spin
+vectors :ref:`(Tranchida) <Tranchida7>`.  :math:`r^{\alpha\beta}` is the
+distance from atom :math:`\alpha` to atom :math:`\beta`, and
+:math:`\theta^{\alpha\beta\gamma}` is the bond angle:
 
 .. math ::
 
@@ -361,7 +378,7 @@ The activation functions are computed as follows:
 Restrictions
 """"""""""""
 
-pair_style rann requires the USER-RANN package. It is only enabled if LAMMPS was built with that
+Pair style *rann* is part of the USER-RANN package.  It is only enabled if LAMMPS was built with that
 package.  Additionally, if any spin fingerprint styles are used LAMMPS must be built with the SPIN
 package as well.
 
@@ -372,22 +389,24 @@ Cmin = 0.8, Cmax = 2.8.
 
 ----------
 
+
 .. _Baskes97:
 
-.. _Nitol:
-
-.. _Dickel:
-
-.. _Dickel1:
-
 **(Baskes)** Baskes,
 Materials Chemistry and Physics, 50(2), 152-158, (1997).
 
+.. _Dickel:
+
 **(Dickel)** Dickel, Francis, and Barrett,
 Computational Materials Science 171 (2020): 109157.
 
+.. _Nitol:
+
 **(Nitol)** Nitol, Dickel, and Barrett,
 Computational Materials Science 188 (2021): 110207.
 
+.. _Tranchida7:
+
 **(Tranchida)** Tranchida, Plimpton, Thibaudeau and Thompson,
 Journal of Computational Physics, 372, 406-425, (2018).
+

doc/utils/sphinx-config/false_positives.txt

@@ -23,6 +23,7 @@ acolor
 acos
 Acta
 actinide
+activationfunctions
 acylindricity
 addforce
 Addington
@@ -75,6 +76,7 @@ allocaters
 allosws
 AlO
 Alonso
+alphak
 alphashrink
 amap
 Amatrix
@@ -153,6 +155,7 @@ atomfile
 AtomicPairStyle
 atomID
 atomistic
+atomtypes
 attogram
 attograms
 attrac
@@ -288,6 +291,9 @@ BondAngle
 BondBond
 bondchk
 bondmax
+bondscreened
+bondscreenedspin
+bondspin
 bondtype
 Bonet
 Bonomi
@@ -340,6 +346,8 @@ bz
 cadetblue
 Cagin
 calc
+calibrationfunctions
+calibrationparameters
 calibre
 caltech
 Caltech
@@ -670,6 +678,7 @@ diagonalized
 diagonalizers
 diagonalizing
 Diallo
+Dickel
 diel
 differentiable
 diffusively
@@ -722,6 +731,7 @@ doxygenclass
 doxygenfunction
 downarrow
 Doye
+Doyl
 dpd
 DPD
 dpdTheta
@@ -1638,6 +1648,7 @@ Laupretre
 Lauriat
 lavenderblush
 lawngreen
+layersize
 lB
 lbfgs
 lbl
@@ -2164,6 +2175,7 @@ nemd
 netcdf
 netstat
 Nettleton
+networklayers
 Neumann
 Nevent
 nevery
@@ -2198,6 +2210,7 @@ Ninteger
 NiO
 Nissila
 nist
+Nitol
 nitride
 nitrides
 niu
@@ -2672,6 +2685,9 @@ qw
 qx
 qy
 qz
+radialscreened
+radialscreenedspin
+radialspin
 radian
 radians
 Rafferty
@@ -2684,6 +2700,8 @@ ramping
 Ramprasad
 Randisi
 randomizations
+rann
+RANN
 Raphson
 Rappe
 Ravelo
@@ -2960,6 +2978,7 @@ SiC
 Siegmund
 Siepmann
 Sievers
+sigI
 sigmoid
 Sij
 Sikandar
@@ -3661,6 +3680,8 @@ zz
 Zm
 PowerShell
 filesystems
+fingerprintconstants
+fingerprintsperelement
 zincblende
 Zstandard
 Zstd