diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 07a1794bd1..e7dc905e22 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -100,6 +100,7 @@ page gives those details. * :ref:`USER-QMMM ` * :ref:`USER-QTB ` * :ref:`USER-QUIP ` + * :ref:`USER-RANN ` * :ref:`USER-REACTION ` * :ref:`USER-REAXC ` * :ref:`USER-SCAFACOS ` @@ -2277,6 +2278,31 @@ This package has :ref:`specific installation instructions ` 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 ` +* examples/USER/rann + +---------- + .. _PKG-USER-REACTION: USER-REACTION package diff --git a/doc/src/Packages_user.rst b/doc/src/Packages_user.rst index 33226d1b1d..3bf1323d16 100644 --- a/doc/src/Packages_user.rst +++ b/doc/src/Packages_user.rst @@ -101,6 +101,8 @@ package: +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+ | :ref:`USER-QUIP ` | QUIP/libatoms interface | :doc:`pair_style quip ` | USER/quip | ext | +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+ +| :ref:`USER-RANN ` | rapid atomistic neural network (RANN) potentials | :doc:`pair rann ` | USER/rann | no | ++------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+ | :ref:`USER-REACTION ` | chemical reactions in classical MD | :doc:`fix bond/react ` | USER/reaction | no | +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+ | :ref:`USER-REAXC ` | ReaxFF potential (C/C++) | :doc:`pair_style reaxc ` | reax | no | diff --git a/doc/src/pair_rann.rst b/doc/src/pair_rann.rst index 197bdfdd07..4177bae0c7 100644 --- a/doc/src/pair_rann.rst +++ b/doc/src/pair_rann.rst @@ -23,49 +23,43 @@ Examples Description """"""""""" -Style *rann* computes pairwise interactions for a variety of materials -using rapid atomistic neural network (RANN) potentials (:ref:`Dickel ` , :ref:`Nitol `). -Neural network potentials work by first generating a series of symmetry functions -i.e. structural fingerprints from the neighbor list and then using these values -as the input layer of a neural network. There is a single output neuron in the -final layer which is the energy. Atomic forces are found by analytical -derivatives computed via backpropagation. For alloy systems, each element has a unique -network. +Pair style *rann* computes pairwise interactions for a variety of +materials using rapid atomistic neural network (RANN) potentials +(:ref:`Dickel ` , :ref:`Nitol `). Neural network +potentials work by first generating a series of symmetry functions +i.e. structural fingerprints from the neighbor list and then using these +values as the input layer of a neural network. There is a single output +neuron in the final layer which is the energy. Atomic forces are found +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 potential file also 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: +The RANN potential is defined by a single text file which contains all +the fitting parameters for the alloy system. The potential file also +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 -ordering, 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 '#' character is treated as a comment marker, similar to LAMMPS +input scripts. Sections are not required to follow a rigid ordering, +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. -This number must be specified for each element keyword. Active elements for each fingerprint depend upon the -type of the central atom and the neighboring atoms. Pairwise fingerprints may be defined for a Mg atom based -exclusively on its Al neighbors, for example. Bond fingerprints may use two neighborlists of different -element types. In computing fingerprintsperelement from all defined fingerprints, only the fingerprints -defined for atoms of a 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: +*fingerprintsperelement* specifies how many fingerprints are active for +computing the energy of a given atom. This number must be specified for +each element keyword. Active elements for each fingerprint depend upon +the type of the central atom and the neighboring atoms. Pairwise +fingerprints may be defined for a Mg atom based exclusively on its Al +neighbors, for example. Bond fingerprints may use two neighbor lists of +different element types. In computing fingerprintsperelement from all +defined fingerprints, only the fingerprints defined for atoms of a +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 -specified for two elements, while bond fingerprints are specified for three elements. Only one fingerprints -header should be used for an individual combination of elements. The ordering of the fingerprints in the -network input layer is determined by the order of element combinations specified by subsequent *fingerprints* -lines, and the order of the fingerprints defined for each element combination. Multiple fingerprints of the same 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: +*fingerprints* specifies the active fingerprints for a certain element +combination. Pair fingerprints are specified for two elements, while +bond fingerprints are specified for three elements. Only one +fingerprints header should be used for an individual combination of +elements. The ordering of the fingerprints in the network input layer +is determined by the order of element combinations specified by +subsequent *fingerprints* lines, and the order of the fingerprints +defined for each element combination. Multiple fingerprints of the same +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,32 +129,26 @@ 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 ` below for their definitions: +The following fingerprint styles are currently defined. See the +:ref:`formulation section ` 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, -alpha, dr, o, and n must be specified. re should usually be the stable interatomic distance, rc is the cutoff +*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 -used for exponential decay of radial contributions. It may be set proportionally to the bulk modulus similarly -to MEAM potentials, but other values may provided better fitting in special cases. Bond style fingerprints require -specification of re, rc, alphak, dr, k, and m. Here m is the power of the bond cosines and k is the number of -decay parameters. Cosine powers go from 0 to m-1 and are each computed for all values of alphak. Thus the total +is the highest power term. The total length of the fingerprint vector is (n-o+1). alpha is a list of decay parameters +used for exponential decay of radial contributions. It may be set proportionally to the bulk modulus similarly +to MEAM potentials, but other values may provided better fitting in special cases. Bond style fingerprints require +specification of re, rc, alphak, dr, k, and m. Here m is the power of the bond cosines and k is the number of +decay parameters. Cosine powers go from 0 to m-1 and are each computed for all values of alphak. Thus the total length of the fingerprint vector is m*k. .. code-block:: @@ -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 -fingerprint are omitted if they are blocked by a closer neighbor, and reduced if they are partially blocked. -Larger values of Cmin correspond to neighbors being blocked more easily. Cmax cannot be greater than 3, and -Cmin 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. +*screening* specifies the Cmax and Cmin values used in the screening +fingerprints. Contributions form neighbors to the fingerprint are +omitted if they are blocked by a closer neighbor, and reduced if they +are partially blocked. Larger values of Cmin correspond to neighbors +being blocked more easily. Cmax cannot be greater than 3, and Cmin +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 -and so is 2+hiddenlayers. +*networklayers* species the size of the neural network for each atom. +It counts both the input and output layer and so is 2 + \. .. code-block:: networklayers:Mg: 3 -*layersize* specifies the length of each layer, including the input layer and output layer. The input layer is -layer 0. The size of the input layer size must match the summed length of all the fingerprints for that element, -and the output layer size must be 1: +*layersize* specifies the length of each layer, including the input +layer and output layer. The input layer is layer 0. The size of the +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. -The bias of layer i is a nx1 vector where n is the layer size of i+1: +*bias* specifies the bias for a given element and layer. Bias cannot be +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 -cannot be specified for the output layer: +*activationfunctions* specifies the activation function for a given +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 ` below for their definitions. +The following activation styles are currently specified. See the +:ref:`formulation section ` 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 -the activation function, weight matrix and bias vector of the n-th layer 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 +Here :math:`E^\alpha` is the energy of atom :math:`\alpha`, +:math:`{}^n\!F()`, :math:`{}^n\!W_{ij}` and :math:`{}^n\!B_i` are the +activation function, weight matrix and bias vector of the n-th layer +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 -full neighborlist of atom :math:`\alpha`. :math:`\delta_i` are decay metaparameters, and :math:`r_e` is a metaparameter -roughly proportional to the first neighbor distance. :math:`r_c` and :math:`dr` are the neighbor cutoff distance and -cutoff smoothing distance respectively. :math:`S^{\alpha\beta}` is the MEAM screening function -:ref:`(Baskes) `, :math:`s_i^\alpha` and :math:`s_i^\beta` are the atom spin vectors :ref:`(Tranchida) `. -: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: +Eight types of structural fingerprints are currently defined. In the +following, :math:`\beta` and :math:`\gamma` span the full neighbor list +of atom :math:`\alpha`. :math:`\delta_i` are decay meta-parameters, and +:math:`r_e` is a meta-parameter roughly proportional to the first +neighbor distance. :math:`r_c` and :math:`dr` are the neighbor cutoff +distance and cutoff smoothing distance respectively. +:math:`S^{\alpha\beta}` is the MEAM screening function :ref:`(Baskes) +`, :math:`s_i^\alpha` and :math:`s_i^\beta` are the atom spin +vectors :ref:`(Tranchida) `. :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,8 +378,8 @@ 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 -package. Additionally, if any spin fingerprint styles are used LAMMPS must be built with the SPIN +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. Defaults @@ -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). + diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index d92cf4694e..0367808002 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/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