tx258/lammps-gran-kokkos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs to list examples and include links to the tutorials

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-06-02 12:11:10 -04:00
parent 217b070204
commit 7a02043f18
2 changed files with 238 additions and 223 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
doc/src/pair_sw_angle_table.rst
View File

@ -20,7 +20,12 @@ Examples
pair_style sw/angle/table
pair_coeff * * spce.sw type
pair_coeff * * GaN.sw Ga N Ga
Used in example input script:
.. parsed-literal::
examples/PACKAGES/manybody_table/in.spce_sw
Description
@ -47,27 +52,29 @@ system of atoms as
where :math:`\phi_2` is a two-body term and :math:`\phi_3` is a
three-body term. The summations in the formula are over all neighbors J
and K of atom I within a cutoff distance :math:`a \sigma`.
In contrast to the original *sw* style, *sw/angle/table* allows for a flexible
three-body term :math:`f^{\textrm{3b}}\left(\theta_{ijk}\right)` which is read in
as a tabulated interaction. It can be parameterized with the csg_fmatch app of VOTCA
as available at: https://gitlab.mpcdf.mpg.de/votca/votca.
and K of atom I within a cutoff distance :math:`a \sigma`. In contrast
to the original *sw* style, *sw/angle/table* allows for a flexible
three-body term :math:`f^{\textrm{3b}}\left(\theta_{ijk}\right)` which
is read in as a tabulated interaction. It can be parameterized with the
csg_fmatch app of VOTCA as available at:
https://gitlab.mpcdf.mpg.de/votca/votca.
Only a single pair_coeff command is used with the *sw/angle/table* style
which specifies a modified Stillinger-Weber potential file with parameters for all
needed elements. These are mapped to LAMMPS atom types by specifying
N_el additional arguments after the ".sw" filename in the pair_coeff command,
where N_el is the number of LAMMPS atom types:
which specifies a modified Stillinger-Weber potential file with
parameters for all needed elements. These are mapped to LAMMPS atom
types by specifying N_el additional arguments after the ".sw" filename
in the pair_coeff command, where N_el is the number of LAMMPS atom
types:
* ".sw" filename
* N_el element names = mapping of SW elements to atom types
See the :doc:`pair_coeff <pair_coeff>` page for alternate ways
to specify the path for the potential file.
See the :doc:`pair_coeff <pair_coeff>` page for alternate ways to
specify the path for the potential file.
As an example, imagine a file SiC.sw has Stillinger-Weber values for
Si and C. If your LAMMPS simulation has 4 atoms types and you want
the first 3 to be Si, and the fourth to be C, you would use the following
As an example, imagine a file SiC.sw has Stillinger-Weber values for Si
and C. If your LAMMPS simulation has 4 atoms types and you want the
first 3 to be Si, and the fourth to be C, you would use the following
pair_coeff command:
.. code-block:: LAMMPS
@ -76,20 +83,20 @@ pair_coeff command:
The first 2 arguments must be \* \* so as to span all LAMMPS atom types.
The first three Si arguments map LAMMPS atom types 1,2,3 to the Si
element in the SW file. The final C argument maps LAMMPS atom type 4
to the C element in the SW file. If a mapping value is specified as
NULL, the mapping is not performed. This can be used when a *sw/angle/table*
element in the SW file. The final C argument maps LAMMPS atom type 4 to
the C element in the SW file. If a mapping value is specified as NULL,
the mapping is not performed. This can be used when a *sw/angle/table*
potential is used as part of the *hybrid* pair style. The NULL values
are placeholders for atom types that will be used with other
potentials.
are placeholders for atom types that will be used with other potentials.
The (modified) Stillinger-Weber files have a ".sw" suffix. Lines that are not blank or
comments (starting with #) define parameters for a triplet of
elements. The parameters in a single entry correspond to the two-body
and three-body coefficients in the formula above. Here, also the suffix
".sw" is used though the original Stillinger-Weber file format is supplemented
with four additional lines per parameter block to specify the tabulated
three-body interaction. A single entry then contains:
The (modified) Stillinger-Weber files have a ".sw" suffix. Lines that
are not blank or comments (starting with #) define parameters for a
triplet of elements. The parameters in a single entry correspond to the
two-body and three-body coefficients in the formula above. Here, also
the suffix ".sw" is used though the original Stillinger-Weber file
format is supplemented with four additional lines per parameter block to
specify the tabulated three-body interaction. A single entry then
contains:
* element 1 (the center atom in a 3-body interaction)
* element 2
@ -111,11 +118,12 @@ three-body interaction. A single entry then contains:
* N
The A, B, p, and q parameters are used only for two-body interactions.
The :math:`\lambda` and :math:`\cos\theta_0` parameters, only used
for three-body interactions in the original Stillinger-Weber style, are read
in but ignored in this modified pair style. The :math:`\epsilon` parameter is only used
for two-body interactions in this modified pair style and not for the three-body
terms. The :math:`\sigma` and *a* parameters are used for both two-body and three-body
The :math:`\lambda` and :math:`\cos\theta_0` parameters, only used for
three-body interactions in the original Stillinger-Weber style, are read
in but ignored in this modified pair style. The :math:`\epsilon`
parameter is only used for two-body interactions in this modified pair
style and not for the three-body terms. The :math:`\sigma` and *a*
parameters are used for both two-body and three-body
interactions. :math:`\gamma` is used only in the three-body
interactions, but is defined for pairs of atoms. The non-annotated
parameters are unitless.
@ -132,25 +140,25 @@ provides a *tol* value for each of the three-body entries so that they
can be separately controlled. If tol = 0.0, then the standard
Stillinger-Weber cutoff is used.
The additional parameters *filename*, *keyword*, *style*, and *N* refer to
the tabulated angular potential :math:`f^{\textrm{3b}}\left(\theta_{ijk}\right)`.
The tabulated angular potential has to be of the format as used in the
:doc:`angle_style table <angle_table>` command:
The additional parameters *filename*, *keyword*, *style*, and *N* refer
to the tabulated angular potential
:math:`f^{\textrm{3b}}\left(\theta_{ijk}\right)`. The tabulated angular
potential has to be of the format as used in the :doc:`angle_style table
<angle_table>` command:
An interpolation tables of length *N* is created. The
interpolation is done in one of 2 *styles*: *linear* or *spline*.
For the *linear* style, the angle is used to find 2 surrounding table
values from which an energy or its derivative is computed by linear
interpolation. For the *spline* style, a cubic spline coefficients are computed and
stored at each of the *N* values in the table. The angle is used to
find the appropriate set of coefficients which are used to evaluate a
cubic polynomial which computes the energy or derivative.
An interpolation tables of length *N* is created. The interpolation is
done in one of 2 *styles*: *linear* or *spline*. For the *linear*
style, the angle is used to find 2 surrounding table values from which
an energy or its derivative is computed by linear interpolation. For the
*spline* style, a cubic spline coefficients are computed and stored at
each of the *N* values in the table. The angle is used to find the
appropriate set of coefficients which are used to evaluate a cubic
polynomial which computes the energy or derivative.
The *filename* specifies the file containing the tabulated energy and
derivative values of :math:`f^{\textrm{3b}}\left(\theta_{ijk}\right)`.
The *keyword* then specifies a section of the file. The
format of this file is as follows (without the
parenthesized comments):
The *keyword* then specifies a section of the file. The format of this
file is as follows (without the parenthesized comments):
.. parsed-literal::
@ -166,31 +174,30 @@ parenthesized comments):
A section begins with a non-blank line whose first character is not a
"#"; blank lines or lines starting with "#" can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The next line lists (in any
order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.
between sections. The first line begins with a keyword which identifies
the section. The next line lists (in any order) one or more parameters
for the table. Each parameter is a keyword followed by one or more
numeric values.
The parameter "N" is required and its value is the number of table
entries that follow. Note that this may be different than the *N*
specified in the Stillinger-Weber potential file. Let
Nsw = *N* in the ".sw" file, and Nfile = "N" in the
tabulated angular file. What LAMMPS does is a preliminary interpolation by
creating splines using the Nfile tabulated values as nodal points. It
uses these to interpolate as needed to generate energy and derivative
values at Ntable different points. The resulting tables of length
Nsw are then used as described above, when computing energy and
force for individual angles and their atoms. This means that if you
want the interpolation tables of length Nsw to match exactly what
is in the tabulated file (with effectively no preliminary
interpolation), you should set Nsw = Nfile.
specified in the Stillinger-Weber potential file. Let Nsw = *N* in the
".sw" file, and Nfile = "N" in the tabulated angular file. What LAMMPS
does is a preliminary interpolation by creating splines using the Nfile
tabulated values as nodal points. It uses these to interpolate as
needed to generate energy and derivative values at Ntable different
points. The resulting tables of length Nsw are then used as described
above, when computing energy and force for individual angles and their
atoms. This means that if you want the interpolation tables of length
Nsw to match exactly what is in the tabulated file (with effectively no
preliminary interpolation), you should set Nsw = Nfile.
The "FP" parameter is optional. If used, it is followed by two values
fplo and fphi, which are the second derivatives at the innermost and
outermost angle settings. These values are needed by the spline
construction routines. If not specified by the "FP" parameter, they
are estimated (less accurately) by the first two and last two
derivative values in the table.
construction routines. If not specified by the "FP" parameter, they are
estimated (less accurately) by the first two and last two derivative
values in the table.
The "EQ" parameter is also optional. If used, it is followed by a the
equilibrium angle value, which is used, for example, by the :doc:`fix
@ -209,14 +216,15 @@ increase from one line to the next. The angle values must also begin
with 0.0 and end with 180.0, i.e. span the full range of possible
angles.
Note that one angular potential file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified *keyword* of appropriate section of the ".sw" file.
Note that one angular potential file can contain many sections, each
with a tabulated potential. LAMMPS reads the file section by section
until it finds one that matches the specified *keyword* of appropriate
section of the ".sw" file.
The Stillinger-Weber potential file must contain entries for all the
elements listed in the pair_coeff command. It can also contain
entries for additional elements not being used in a particular
simulation; LAMMPS ignores those entries.
elements listed in the pair_coeff command. It can also contain entries
for additional elements not being used in a particular simulation;
LAMMPS ignores those entries.
For a single-element simulation, only a single entry is required
(e.g. SiSiSi). For a two-element simulation, the file must contain 8
@ -225,40 +233,31 @@ specify SW parameters for all permutations of the two elements
interacting in three-body configurations. Thus for 3 elements, 27
entries would be required, etc.
As annotated above, the first element in the entry is the center atom
in a three-body interaction. Thus an entry for SiCC means a Si atom
with 2 C atoms as neighbors. The parameter values used for the
two-body interaction come from the entry where the second and third
elements are the same. Thus the two-body parameters for Si
interacting with C, comes from the SiCC entry. The three-body
angular potential :math:`f^{\textrm{3b}}\left(\theta_{ijk}\right)`
can in principle be specific to the three elements of the
configuration. However, the user must ensure that it makes physically sense.
Note also that the function :math:`\phi_3` contains two exponential
screening factors with parameter values from the ij pair and ik
pairs. So :math:`\phi_3` for a C atom bonded to a Si atom and a second C atom
will depend on the three-body parameters for the CSiC entry, and also
on the two-body parameters for the CCC and CSiSi entries. Since the
order of the two neighbors is arbitrary, the three-body parameters
and the tabulated angular potential for
entries CSiC and CCSi should be the same. Similarly, the two-body
As annotated above, the first element in the entry is the center atom in
a three-body interaction. Thus an entry for SiCC means a Si atom with 2
C atoms as neighbors. The parameter values used for the two-body
interaction come from the entry where the second and third elements are
the same. Thus the two-body parameters for Si interacting with C, comes
from the SiCC entry. The three-body angular potential
:math:`f^{\textrm{3b}}\left(\theta_{ijk}\right)` can in principle be
specific to the three elements of the configuration. However, the user
must ensure that it makes physically sense. Note also that the function
:math:`\phi_3` contains two exponential screening factors with parameter
values from the ij pair and ik pairs. So :math:`\phi_3` for a C atom
bonded to a Si atom and a second C atom will depend on the three-body
parameters for the CSiC entry, and also on the two-body parameters for
the CCC and CSiSi entries. Since the order of the two neighbors is
arbitrary, the three-body parameters and the tabulated angular potential
for entries CSiC and CCSi should be the same. Similarly, the two-body
parameters for entries SiCC and CSiSi should also be the same. The
parameters used only for two-body interactions (A, B, p, and q) in
entries whose second and third element are different (e.g. SiCSi) are not
used for anything and can be set to 0.0 if desired.
This is also true for the parameters in :math:`\phi_3` that are
taken from the ij and ik pairs (:math:`\sigma`, *a*, :math:`\gamma`)
entries whose second and third element are different (e.g. SiCSi) are
not used for anything and can be set to 0.0 if desired. This is also
true for the parameters in :math:`\phi_3` that are taken from the ij and
ik pairs (:math:`\sigma`, *a*, :math:`\gamma`)
----------
.. include:: accel_styles.rst
.. note::
When using the INTEL package with this style, there is an additional
5 to 10 percent performance improvement when the Stillinger-Weber
parameters p and q are set to 4 and 0 respectively. These
parameters are common for modeling silicon and water.
Additional input files and reference data can be found at:
https://gitlab.mpcdf.mpg.de/votca/votca/-/tree/master/csg-tutorials/spce/3body_sw
----------
@ -266,16 +265,17 @@ Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
For atom type pairs I,J and I != J, where types I and J correspond to
two different element types, mixing is performed by LAMMPS as
described above from values in the potential file, but not for the
tabulated angular potential file.
two different element types, mixing is performed by LAMMPS as described
above from values in the potential file, but not for the tabulated
angular potential file.
This pair style does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
This pair style does not write its information to :doc:`binary restart files <restart>`, since it is stored in potential files.
Thus, you need to re-specify the pair_style and pair_coeff commands in an input
script that reads a restart file.
This pair style does not write its information to :doc:`binary restart
files <restart>`, since it is stored in potential files. Thus, you need
to re-specify the pair_style and pair_coeff commands in an input script
that reads a restart file.
This pair style can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does not support the
@ -286,15 +286,13 @@ This pair style can only be used via the *pair* keyword of the
Restrictions
""""""""""""
This is a user pair style. For more information, see :ref:`Scherer1
<Scherer1>`. It is only enabled if LAMMPS was explicitly built with it.
This pair style is part of the MANYBODY package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
This pair style requires the :doc:`newton <newton>` setting to be "on"
for pair interactions.
For an example of an extended Stillinger-Weber potential file, have a look at the tutorial
in the tutorial folder.
Related commands
""""""""""""""""

237
doc/src/pair_threebody_table.rst
View File

@ -19,18 +19,28 @@ Examples
.. code-block:: LAMMPS
pair_style threebody/table
pair_coeff * * spce.3b type
pair_coeff * * GaN.3b Ga N Ga
pair_coeff * * spce2.3b type1 type2
pair_style hybrid/overlay table linear 1200 threebody/table
pair_coeff 1 1 table table_CG_CG.txt VOTCA
pair_coeff * * threebody/table spce.3b type
Used in example input scripts:
.. parsed-literal::
examples/PACKAGES/manybody_table/in.spce
examples/PACKAGES/manybody_table/in.spce2
Description
"""""""""""
The *threebody/table* style is a pair style for generic tabulated three-body
interactions. It has been developed for (coarse-grained) simulations
(of water) with Kernel-based machine learning (ML) potentials
(:ref:`Scherer2 <Scherer2>`). As for many other MANYBODY package pair styles
the energy of a system is computed as a sum over three-body terms:
The *threebody/table* style is a pair style for generic tabulated
three-body interactions. It has been developed for (coarse-grained)
simulations (of water) with Kernel-based machine learning (ML)
potentials (:ref:`Scherer2 <Scherer2>`). As for many other MANYBODY
package pair styles the energy of a system is computed as a sum over
three-body terms:
.. math::
@ -40,24 +50,25 @@ The summations in the formula are over all neighbors J and K of atom I
within a cutoff distance :math:`cut`. In contrast to the
Stillinger-Weber potential, all forces are not calculated analytically,
but read in from a three-body force/energy table which can be generated
with the csg_ml app of VOTCA as available at: https://gitlab.mpcdf.mpg.de/votca/votca.
with the csg_ml app of VOTCA as available at:
https://gitlab.mpcdf.mpg.de/votca/votca.
Only a single pair_coeff command is used with the *threebody/table* style
which specifies a threebody potential (".3b") file with parameters for all
needed elements. These are then mapped to LAMMPS atom types by specifying
N_el additional arguments after the ".3b" filename in the pair_coeff command,
where N_el is the number of LAMMPS atom types:
Only a single pair_coeff command is used with the *threebody/table*
style which specifies a threebody potential (".3b") file with parameters
for all needed elements. These are then mapped to LAMMPS atom types by
specifying N_el additional arguments after the ".3b" filename in the
pair_coeff command, where N_el is the number of LAMMPS atom types:
* ".3b" filename
* N_el element names = mapping of threebody elements to atom types
See the :doc:`pair_coeff <pair_coeff>` page for alternate ways
to specify the path for the potential file.
See the :doc:`pair_coeff <pair_coeff>` page for alternate ways to
specify the path for the potential file.
As an example, imagine a file SiC.3b has three-body values for
Si and C. If your LAMMPS simulation has 4 atoms types and you want
the first 3 to be Si, and the fourth to be C, you would use the following
pair_coeff command:
As an example, imagine a file SiC.3b has three-body values for Si and C.
If your LAMMPS simulation has 4 atoms types and you want the first 3 to
be Si, and the fourth to be C, you would use the following pair_coeff
command:
.. code-block:: LAMMPS
@ -66,17 +77,17 @@ pair_coeff command:
The first 2 arguments must be \* \* so as to span all LAMMPS atom types.
The first three Si arguments map LAMMPS atom types 1,2,3 to the Si
element in the ".3b" file. The final C argument maps LAMMPS atom type 4
to the C element in the threebody file. If a mapping value is specified as
NULL, the mapping is not performed. This can be used when a *threebody/table*
potential is used as part of the *hybrid* pair style. The NULL values
are placeholders for atom types that will be used with other
potentials.
to the C element in the threebody file. If a mapping value is specified
as NULL, the mapping is not performed. This can be used when a
*threebody/table* potential is used as part of the *hybrid* pair style.
The NULL values are placeholders for atom types that will be used with
other potentials.
The three-body files have a ".3b" suffix. Lines that are not blank or
comments (starting with #) define parameters for a triplet of
elements. The parameters in a single entry specify to the
(three-body) cutoff distance and the tabulated
three-body interaction. A single entry then contains:
elements. The parameters in a single entry specify to the (three-body)
cutoff distance and the tabulated three-body interaction. A single entry
then contains:
* element 1 (the center atom in a 3-body interaction)
* element 2
@ -87,33 +98,33 @@ three-body interaction. A single entry then contains:
* style
* N
The parameter :math:`cut` is the (three-body) cutoff distance.
When set to 0, no interaction is calculated for this element triplet.
The parameters *filename*, *keyword*, *style*, and *N* refer to
the tabulated three-body potential.
The parameter :math:`cut` is the (three-body) cutoff distance. When set
to 0, no interaction is calculated for this element triplet. The
parameters *filename*, *keyword*, *style*, and *N* refer to the
tabulated three-body potential.
The tabulation is done on a three-dimensional grid of the two distances
:math:`r_{ij}` and :math:`r_{ik}` as well as the angle :math:`\theta_{ijk}`
which is constructed in the following way. There are two different cases.
If element 2 and element 3 are of the same type (e.g. SiCC), the distance
:math:`r_{ij}` is varied in "N" steps from rmin to rmax and the distance
:math:`r_{ik}` is varied from :math:`r_{ij}` to rmax. This can be done,
due to the symmetry of the triplet. If element 2 and element 3 are not
of the same type (e.g. SiCSi), there is no additional symmetry and the
distance :math:`r_{ik}` is also varied from rmin to rmax in "N" steps.
The angle :math:`\theta_{ijk}` is always varied in "2N" steps from
(0.0 + 180.0/(4N)) to (180.0 - 180.0/(4N)). Therefore, the total number
of table entries is "M = N * N * (N+1)" for the symmetric (element 2 and element 3
are of the same type) and "M = 2 * N * N * N" for the general case
(element 2 and element 3 are not of the same type).
:math:`r_{ij}` and :math:`r_{ik}` as well as the angle
:math:`\theta_{ijk}` which is constructed in the following way. There
are two different cases. If element 2 and element 3 are of the same
type (e.g. SiCC), the distance :math:`r_{ij}` is varied in "N" steps
from rmin to rmax and the distance :math:`r_{ik}` is varied from
:math:`r_{ij}` to rmax. This can be done, due to the symmetry of the
triplet. If element 2 and element 3 are not of the same type
(e.g. SiCSi), there is no additional symmetry and the distance
:math:`r_{ik}` is also varied from rmin to rmax in "N" steps. The angle
:math:`\theta_{ijk}` is always varied in "2N" steps from (0.0 +
180.0/(4N)) to (180.0 - 180.0/(4N)). Therefore, the total number of
table entries is "M = N * N * (N+1)" for the symmetric (element 2 and
element 3 are of the same type) and "M = 2 * N * N * N" for the general
case (element 2 and element 3 are not of the same type).
The forces on all three particles I, J, and K of a triplet
of this type of three-body interaction potential
(:math:`\phi_3 (r_{ij}, r_{ik}, \theta_{ijk})`) lie within
the plane defined by the three inter-particle distance vectors
:math:`{\mathbf r}_{ij}`, :math:`{\mathbf r}_{ik}`, and :math:`{\mathbf r}_{jk}`.
This property is used to project the forces onto the inter-particle
distance vectors as follows
The forces on all three particles I, J, and K of a triplet of this type
of three-body interaction potential (:math:`\phi_3 (r_{ij}, r_{ik},
\theta_{ijk})`) lie within the plane defined by the three inter-particle
distance vectors :math:`{\mathbf r}_{ij}`, :math:`{\mathbf r}_{ik}`, and
:math:`{\mathbf r}_{jk}`. This property is used to project the forces
onto the inter-particle distance vectors as follows
.. math::
@ -133,18 +144,18 @@ distance vectors as follows
{\mathbf r}_{jk} \\
\end{pmatrix}
and then tabulate the 6 force constants :math:`f_{i1}`, :math:`f_{i2}`, :math:`f_{j1}`,
:math:`f_{j2}`, :math:`f_{k1}`, and :math:`f_{k2}`, as well as the energy of a triplet e.
Due to symmetry reasons, the following relations hold: :math:`f_{i1}=-f_{j1}`,
:math:`f_{i2}=-f_{k1}`, and :math:`f_{j2}=-f_{k2}`. As in this pair style the
forces are read in directly, a correct MD simulation is also performed in the case that
the triplet energies are set to e=0.
and then tabulate the 6 force constants :math:`f_{i1}`, :math:`f_{i2}`,
:math:`f_{j1}`, :math:`f_{j2}`, :math:`f_{k1}`, and :math:`f_{k2}`, as
well as the energy of a triplet e. Due to symmetry reasons, the
following relations hold: :math:`f_{i1}=-f_{j1}`,
:math:`f_{i2}=-f_{k1}`, and :math:`f_{j2}=-f_{k2}`. As in this pair
style the forces are read in directly, a correct MD simulation is also
performed in the case that the triplet energies are set to e=0.
The *filename* specifies the file containing the tabulated energy and
derivative values of :math:`\phi_3 (r_{ij}, r_{ik}, \theta_{ijk})`.
The *keyword* then specifies a section of the file. The
format of this file is as follows (without the
parenthesized comments):
derivative values of :math:`\phi_3 (r_{ij}, r_{ik}, \theta_{ijk})`. The
*keyword* then specifies a section of the file. The format of this file
is as follows (without the parenthesized comments):
.. parsed-literal::
@ -160,45 +171,51 @@ parenthesized comments):
A section begins with a non-blank line whose first character is not a
"#"; blank lines or lines starting with "#" can be used as comments
between sections. The first line begins with a keyword which
identifies the section. The next line lists (in any
order) one or more parameters for the table. Each parameter is a
keyword followed by one or more numeric values.
between sections. The first line begins with a keyword which identifies
the section. The next line lists (in any order) one or more parameters
for the table. Each parameter is a keyword followed by one or more
numeric values.
The parameter "N" is required. It should be the same than the parameter "N" of the ".3b" file,
otherwise its value is overwritten. "N" determines the number of table
entries "M" that follow: "M = N * N * (N+1)" (symmetric triplet, e.g. SiCC) or
"M = 2 * N * N * N" (asymmetric triplet, e.g. SiCSi). Therefore "M = 12 * 12 * 13 = 1872"
in the above symmetric example. The parameters "rmin" and "rmax" are also required
The parameter "N" is required. It should be the same than the parameter
"N" of the ".3b" file, otherwise its value is overwritten. "N"
determines the number of table entries "M" that follow: "M = N * N *
(N+1)" (symmetric triplet, e.g. SiCC) or "M = 2 * N * N * N" (asymmetric
triplet, e.g. SiCSi). Therefore "M = 12 * 12 * 13 = 1872" in the above
symmetric example. The parameters "rmin" and "rmax" are also required
and determine the minimum and maximum of the inter-particle distances
:math:`r_{ij}` and :math:`r_{ik}`.
Following a blank line, the next M lines of the angular table file list the tabulated values.
On each line, the first value is the index from 1 to M, the second value is the distance
:math:`r_{ij}`, the third value is the distance :math:`r_{ik}`, the fourth value
is the angle :math:`\theta_{ijk})`, the next six values are the force constants :math:`f_{i1}`,
:math:`f_{i2}`, :math:`f_{j1}`, :math:`f_{j2}`, :math:`f_{k1}`, and :math:`f_{k2}`, and the
last value is the energy e.
Following a blank line, the next M lines of the angular table file list
the tabulated values. On each line, the first value is the index from 1
to M, the second value is the distance :math:`r_{ij}`, the third value
is the distance :math:`r_{ik}`, the fourth value is the angle
:math:`\theta_{ijk})`, the next six values are the force constants
:math:`f_{i1}`, :math:`f_{i2}`, :math:`f_{j1}`, :math:`f_{j2}`,
:math:`f_{k1}`, and :math:`f_{k2}`, and the last value is the energy e.
Note that one three-body potential file can contain many sections, each with a tabulated
potential. LAMMPS reads the file section by section until it finds
one that matches the specified *keyword* of appropriate section of the ".3b" file.
Note that one three-body potential file can contain many sections, each
with a tabulated potential. LAMMPS reads the file section by section
until it finds one that matches the specified *keyword* of appropriate
section of the ".3b" file.
At the moment, only the *style* *linear* is allowed and implemented. After reading in the
force table, it is internally stored in LAMMPS as a lookup table. For each triplet
configuration occurring in the simulation within the cutoff distance,
the next nearest tabulated triplet configuration is looked up. No interpolation is done.
This allows for a very efficient force calculation
with the stored force constants and energies. Due to the know table structure, the lookup
can be done efficiently. It has been tested (:ref:`Scherer2 <Scherer2>`) that with a reasonably
small bin size, the accuracy and speed is comparable to that of a Stillinger-Weber potential
with tabulated three-body interactions (:doc:`pair_style sw/angle/table <pair_sw_angle_table>`) while
the table format of this pair style allows for more flexible three-body interactions.
At the moment, only the *style* *linear* is allowed and
implemented. After reading in the force table, it is internally stored
in LAMMPS as a lookup table. For each triplet configuration occurring in
the simulation within the cutoff distance, the next nearest tabulated
triplet configuration is looked up. No interpolation is done. This
allows for a very efficient force calculation with the stored force
constants and energies. Due to the know table structure, the lookup can
be done efficiently. It has been tested (:ref:`Scherer2 <Scherer2>`)
that with a reasonably small bin size, the accuracy and speed is
comparable to that of a Stillinger-Weber potential with tabulated
three-body interactions (:doc:`pair_style sw/angle/table
<pair_sw_angle_table>`) while the table format of this pair style allows
for more flexible three-body interactions.
As for the Stillinger-Weber potential, the three-body potential file must contain entries for all the
elements listed in the pair_coeff command. It can also contain
entries for additional elements not being used in a particular
simulation; LAMMPS ignores those entries.
As for the Stillinger-Weber potential, the three-body potential file
must contain entries for all the elements listed in the pair_coeff
command. It can also contain entries for additional elements not being
used in a particular simulation; LAMMPS ignores those entries.
For a single-element simulation, only a single entry is required
(e.g. SiSiSi). For a two-element simulation, the file must contain 8
@ -207,16 +224,17 @@ specify threebody parameters for all permutations of the two elements
interacting in three-body configurations. Thus for 3 elements, 27
entries would be required, etc.
As annotated above, the first element in the entry is the center atom
in a three-body interaction. Thus an entry for SiCC means a Si atom
with 2 C atoms as neighbors. The tabulated three-body forces can in
principle be specific to the three elements of the configuration.
However, the user must ensure that it makes physically sense.
E.g., the tabulated three-body forces for the
entries CSiC and CCSi should be the same exchanging :math:`r_{ij}` with
r_{ik}, :math:`f_{j1}` with :math:`f_{k1}`,
and :math:`f_{j2}` with :math:`f_{k2}`.
As annotated above, the first element in the entry is the center atom in
a three-body interaction. Thus an entry for SiCC means a Si atom with 2
C atoms as neighbors. The tabulated three-body forces can in principle
be specific to the three elements of the configuration. However, the
user must ensure that it makes physically sense. E.g., the tabulated
three-body forces for the entries CSiC and CCSi should be the same
exchanging :math:`r_{ij}` with r_{ik}, :math:`f_{j1}` with
:math:`f_{k1}`, and :math:`f_{j2}` with :math:`f_{k2}`.
Additional input files and reference data can be found at:
https://gitlab.mpcdf.mpg.de/votca/votca/-/tree/master/csg-tutorials/ml
----------
@ -228,9 +246,10 @@ As all interactions are tabulated, no mixing is performed.
This pair style does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
This pair style does not write its information to :doc:`binary restart files <restart>`, since it is stored in potential files.
Thus, you need to re-specify the pair_style and pair_coeff commands in an input
script that reads a restart file.
This pair style does not write its information to :doc:`binary restart
files <restart>`, since it is stored in potential files. Thus, you need
to re-specify the pair_style and pair_coeff commands in an input script
that reads a restart file.
This pair style can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does not support the
@ -241,15 +260,13 @@ This pair style can only be used via the *pair* keyword of the
Restrictions
""""""""""""
This is a user pair style. For more information, see :ref:`Scherer2 <Scherer2>`. It is only enabled
if LAMMPS was explicitly built with it.
This pair style is part of the MANYBODY package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
This pair style requires the :doc:`newton <newton>` setting to be "on"
for pair interactions.
For an example of a three-body potential file, have a look at the tutorial
in the tutorial folder.
Related commands
""""""""""""""""