ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'github/amoeba' into amoeba-ak

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-07-02 21:58:15 -04:00
parent 5300a5aa58 d385a9be9d
commit 57a569eb3b
219 changed files with 25393 additions and 3009 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
doc/src/Build_settings.rst
View File

@ -297,15 +297,15 @@ requires the following settings:
.. code-block:: bash
-D WITH_JPEG=value # yes or no
# default = yes
# default = yes if CMake finds JPEG files, else no
-D WITH_PNG=value # yes or no
# default = yes
# default = yes if CMake finds PNG and ZLIB files, else no
-D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no
Usually these settings are all that is needed. If those libraries
or executables are installed but CMake cannot find the graphics header,
library, or executable files, you can set these variables accordingly:
Usually these settings are all that is needed. If CMake cannot
find the graphics header, library, executable files, you can set
these variables:
.. code-block:: bash
@ -317,9 +317,6 @@ requires the following settings:
-D ZLIB_LIBRARY=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
Otherwise, CMake will attempt to download, build, and link with
jpeg, png, and zlib libraries statically from source code.
.. tab:: Traditional make
.. code-block:: make

2
doc/src/Commands_pair.rst
View File

@ -271,6 +271,7 @@ OPT.
* :doc:`spin/neel <pair_spin_neel>`
* :doc:`srp <pair_srp>`
* :doc:`sw (giko) <pair_sw>`
* :doc:`sw/angle/table <pair_sw_angle_table>`
* :doc:`sw/mod (o) <pair_sw>`
* :doc:`table (gko) <pair_table>`
* :doc:`table/rx (k) <pair_table_rx>`
@ -281,6 +282,7 @@ OPT.
* :doc:`tersoff/table (o) <pair_tersoff>`
* :doc:`tersoff/zbl (gko) <pair_tersoff_zbl>`
* :doc:`thole <pair_thole>`
* :doc:`threebody/table <pair_threebody_table>`
* :doc:`tip4p/cut (o) <pair_coul>`
* :doc:`tip4p/long (o) <pair_coul>`
* :doc:`tip4p/long/soft (o) <pair_fep_soft>`

29
doc/src/Developer_plugins.rst
View File

@ -276,10 +276,27 @@ Compilation of the plugin can be managed via both, CMake or traditional
GNU makefiles. Some examples that can be used as a template are in the
``examples/plugins`` folder. The CMake script code has some small
adjustments to allow building the plugins for running unit tests with
them. Another example that converts the KIM package into a plugin can be
found in the ``examples/kim/plugin`` folder. No changes to the sources
of the KIM package themselves are needed; only the plugin interface and
loader code needs to be added. This example only supports building with
CMake, but is probably a more typical example. To compile you need to
run CMake with -DLAMMPS_SOURCE_DIR=<path/to/lammps/src/folder>. Other
them.
Another example that converts the KIM package into a plugin can be found
in the ``examples/kim/plugin`` folder. No changes to the sources of the
KIM package themselves are needed; only the plugin interface and loader
code needs to be added. This example only supports building with CMake,
but is probably a more typical example. To compile you need to run CMake
with -DLAMMPS_SOURCE_DIR=<path/to/lammps/src/folder>. Other
configuration setting are identical to those for compiling LAMMPS.
A second example for a plugin from a package is in the
``examples/PACKAGES/pace/plugin`` folder that will create a plugin from
the ML-PACE package. In this case the bulk of the code is in a static
external library that is being downloaded and compiled first and then
combined with the pair style wrapper and the plugin loader. This
example also contains a NSIS script that can be used to create an
Installer package for Windows (the mutual licensing terms of the
external library and LAMMPS conflict when distributing binaries, so the
ML-PACE package cannot be linked statically, but the LAMMPS headers
required to build the plugin are also available under a less restrictive
license). This will automatically set the required environment variable
and launching a (compatible) LAMMPS binary will load and register the
plugin and the ML-PACE package can then be used as it was linked into
LAMMPS.

4
doc/src/Howto_structured_data.rst
View File

@ -184,7 +184,7 @@ frame.
.. code-block:: python
import re, yaml
import yaml
import pandas as pd
try:
@ -193,7 +193,7 @@ frame.
from yaml import SafeLoader as Loader
with open("ave.yaml") as f:
ave = yaml.load(docs, Loader=Loader)
ave = yaml.load(f, Loader=Loader)
keys = ave['keywords']
df = {}

4
doc/src/Intro_citing.rst
View File

@ -30,8 +30,8 @@ initial versions of LAMMPS is:
`S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995). <http://www.sandia.gov/~sjplimp/papers/jcompphys95.pdf>`_
DOI for the LAMMPS code
^^^^^^^^^^^^^^^^^^^^^^^
DOI for the LAMMPS source code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LAMMPS developers use the `Zenodo service at CERN <https://zenodo.org/>`_
to create digital object identifies (DOI) for stable releases of the

BIN
doc/src/PDF/colvars-refman-lammps.pdf
View File

Binary file not shown.

2
doc/src/Packages_details.rst
View File

@ -676,7 +676,7 @@ advection-diffusion-reaction systems. The equations of motion of these
DPD extensions are integrated through a modified velocity-Verlet (MVV)
algorithm.
**Author:** Zhen Li (Division of Applied Mathematics, Brown University)
**Author:** Zhen Li (Department of Mechanical Engineering, Clemson University)
**Supporting info:**

3
doc/src/Speed_measure.rst
View File

@ -42,5 +42,4 @@ inaccurate relative timing data, because processors have to wait when
communication occurs for other processors to catch up. Thus the
reported times for "Communication" or "Other" may be higher than they
really are, due to load-imbalance. If this is an issue, you can
uncomment the MPI_Barrier() lines in src/timer.cpp, and re-compile
LAMMPS, to obtain synchronized timings.
use the :doc:`timer sync <timer>` command to obtain synchronized timings.

17
doc/src/Tools.rst
View File

@ -95,7 +95,7 @@ Miscellaneous tools
* :ref:`LAMMPS shell <lammps_shell>`
* :ref:`LAMMPS magic patterns for file(1) <magic>`
* :ref:`Offline build tool <offline>`
* :ref:`singularity <singularity_tool>`
* :ref:`singularity/apptainer <singularity_tool>`
* :ref:`SWIG interface <swig>`
* :ref:`vim <vim>`
@ -1007,14 +1007,15 @@ Ivanov, at University of Iceland (ali5 at hi.is).
.. _singularity_tool:
singularity tool
----------------------------------------
singularity/apptainer tool
--------------------------
The singularity sub-directory contains container definitions files
that can be used to build container images for building and testing
LAMMPS on specific OS variants using the `Singularity <https://sylabs.io>`_
container software. Contributions for additional variants are welcome.
For more details please see the README.md file in that folder.
The singularity sub-directory contains container definitions files that
can be used to build container images for building and testing LAMMPS on
specific OS variants using the `Apptainer <https://apptainer.org>`_ or
`Singularity <https://sylabs.io>`_ container software. Contributions for
additional variants are welcome. For more details please see the
README.md file in that folder.
----------

61
doc/src/compute_ave_sphere_atom.rst
View File

@ -35,16 +35,24 @@ Examples
Description
"""""""""""
Define a computation that calculates the local density and temperature
for each atom and neighbors inside a spherical cutoff.
Define a computation that calculates the local mass density and
temperature for each atom based on its neighbors inside a spherical
cutoff. If an atom has M neighbors, then its local mass density is
calculated as the sum of its mass and its M neighbor masses, divided
by the volume of the cutoff sphere (or circle in 2d). The local
temperature of the atom is calculated as the temperature of the
collection of M+1 atoms, after subtracting the center-of-mass velocity
of the M+1 atoms from each of the M+1 atom's velocities. This is
effectively the thermal velocity of the neighborhood of the central
atom, similar to :doc:`compute temp/com <compute_temp_com>`.
The optional keyword *cutoff* defines the distance cutoff
used when searching for neighbors. The default value is the cutoff
specified by the pair style. If no pair style is defined, then a cutoff
must be defined using this keyword. If the specified cutoff is larger than
that of the pair_style plus neighbor skin (or no pair style is defined),
the *comm_modify cutoff* option must also be set to match that of the
*cutoff* keyword.
The optional keyword *cutoff* defines the distance cutoff used when
searching for neighbors. The default value is the cutoff specified by
the pair style. If no pair style is defined, then a cutoff must be
defined using this keyword. If the specified cutoff is larger than
that of the pair_style plus neighbor skin (or no pair style is
defined), the *comm_modify cutoff* option must also be set to match
that of the *cutoff* keyword.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
@ -55,16 +63,16 @@ too frequently.
If you have a bonded system, 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 order parameter. This
difficulty can be circumvented by writing a dump file, and using the
:doc:`rerun <rerun>` command to compute the order parameter 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.
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 compute uses the
neighbor list, it also means those pairs will not be included in
the order parameter. This difficulty can be circumvented by
writing a dump file, and using the :doc:`rerun <rerun>` command to
compute the order parameter 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.
----------
@ -77,17 +85,20 @@ too frequently.
Output info
"""""""""""
This compute calculates a per-atom array with two columns: density and temperature.
This compute calculates a per-atom array with two columns: mass
density in density :doc:`units <units>` and temperature in temperature
:doc:`units <units>`.
These values can be accessed by any command that uses per-atom values
from a compute as input. See the :doc:`Howto output <Howto_output>` doc
page for an overview of LAMMPS output options.
from a compute as input. See the :doc:`Howto output <Howto_output>`
doc page for an overview of LAMMPS output options.
Restrictions
""""""""""""
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
@ -97,5 +108,5 @@ Related commands
Default
"""""""
The option defaults are *cutoff* = pair style cutoff
The option defaults are *cutoff* = pair style cutoff.

10
doc/src/fix_mdi_aimd.rst
View File

@ -12,7 +12,6 @@ Syntax
* ID, group-ID are documented in :doc:`fix <fix>` command
* mdi/aimd = style name of this fix command
* optional keyword = *plugin*
Examples
""""""""
@ -20,7 +19,6 @@ Examples
.. code-block:: LAMMPS
fix 1 all mdi/aimd
fix 1 all mdi/aimd plugin
Description
"""""""""""
@ -53,14 +51,6 @@ same time as LAMMPS, or as a plugin library. See the :doc:`mdi plugin
Again, the examples/mdi/README file explains how to launch both driver
and engine codes so that engine is used in plugin mode.
To use this fix with a plugin engine, you must specify the
*plugin* keyword as the last argument, as illustrated above.
.. note::
As of April 2022, the *plugin* keyword is needed. In a future
version of the MDI library it will no longer be necessary.
----------
This fix performs the timestepping portion of an AIMD simulation.

4
doc/src/kspace_style.rst
View File

@ -129,8 +129,8 @@ Examples
kspace_style pppm 1.0e-4
kspace_style pppm/cg 1.0e-5 1.0e-6
kspace style msm 1.0e-4
kspace style scafacos fmm 1.0e-4
kspace_style msm 1.0e-4
kspace_style scafacos fmm 1.0e-4
kspace_style none
Used in input scripts:

91
doc/src/pair_e3b.rst
View File

@ -50,6 +50,12 @@ Examples
pair_style hybrid/overlay e3b 1 lj/cut/tip4p/long 1 2 1 1 0.15 8.5
pair_coeff * * e3b preset 2011
Used in example input script:
.. parsed-literal::
examples/PACKAGES/e3b/in.e3b-tip4p2005
Description
"""""""""""
@ -68,21 +74,27 @@ The *e3b* style computes an \"explicit three-body\" (E3B) potential for water :r
0 & r>R_f\\
\end{cases}
This potential was developed as a water model that includes the three-body cooperativity of hydrogen bonding explicitly.
To use it in this way, it must be applied in conjunction with a conventional two-body water model, through *pair_style hybrid/overlay*.
The three body interactions are split into three types: A, B, and C.
Type A corresponds to anti-cooperative double hydrogen bond donor interactions.
Type B corresponds to the cooperative interaction of molecules that both donate and accept a hydrogen bond.
Type C corresponds to anti-cooperative double hydrogen bond acceptor interactions.
The three-body interactions are smoothly cutoff by the switching function s(r) between Rs and Rc3.
The two-body interactions are designed to correct for the effective many-body interactions implicitly included in the conventional two-body potential.
The two-body interactions are cut off sharply at Rc2, because K3 is typically significantly smaller than K2.
See :ref:`(Kumar 2008) <Kumar>` for more details.
This potential was developed as a water model that includes the
three-body cooperativity of hydrogen bonding explicitly. To use it in
this way, it must be applied in conjunction with a conventional two-body
water model, through pair style :doc:`hybrid/overlay <pair_hybrid>`. The
three body interactions are split into three types: A, B, and C. Type A
corresponds to anti-cooperative double hydrogen bond donor interactions.
Type B corresponds to the cooperative interaction of molecules that both
donate and accept a hydrogen bond. Type C corresponds to
anti-cooperative double hydrogen bond acceptor interactions. The
three-body interactions are smoothly cutoff by the switching function
s(r) between Rs and Rc3. The two-body interactions are designed to
correct for the effective many-body interactions implicitly included in
the conventional two-body potential. The two-body interactions are cut
off sharply at Rc2, because K3 is typically significantly smaller than
K2. See :ref:`(Kumar 2008) <Kumar>` for more details.
Only a single *pair_coeff* command is used with the *e3b* style.
The first two arguments must be \* \*.
The oxygen atom type for the pair style is passed as the only argument to the *pair_style* command, not in the *pair_coeff* command.
The hydrogen atom type is inferred by the ordering of the atoms.
Only a single :doc:`pair_coeff <pair_coeff>` command is used with the
*e3b* style and the first two arguments must be \* \*. The oxygen atom
type for the pair style is passed as the only argument to the
*pair_style* command, not in the *pair_coeff* command. The hydrogen
atom type is inferred from the ordering of the atoms.
.. note::
@ -90,26 +102,41 @@ The hydrogen atom type is inferred by the ordering of the atoms.
Each water molecule must have consecutive IDs with the oxygen first.
This pair style does not test that this criteria is met.
The *pair_coeff* command must have at least one keyword/value pair, as described above.
The *preset* keyword sets the potential parameters to the values used in :ref:`(Tainter 2011) <Tainter2011>` or :ref:`(Tainter 2015) <Tainter2015>`.
To use the water models defined in those references, the *e3b* style should always be used in conjunction with an *lj/cut/tip4p/long* style through *pair_style hybrid/overlay*, as demonstrated in the second example above.
The *preset 2011* option should be used with the :doc:`TIP4P water model <Howto_tip4p>`.
The *preset 2015* option should be used with the :doc:`TIP4P/2005 water model <Howto_tip4p>`.
If the *preset* keyword is used, no other keyword is needed.
Changes to the preset parameters can be made by specifying the *preset* keyword followed by the specific parameter to change, like *Ea*\ .
Note that the other keywords must come after *preset* in the pair_style command.
The *e3b* style can also be used to implement any three-body potential of the same form by specifying all the keywords except *neigh*\ : *Ea*, *Eb*, *Ec*, *E2*, *K3*, *K2*, *Rc3*, *Rc2*, *Rs*, and *bondL*\ .
The keyword *bondL* specifies the intramolecular OH bond length of the water model being used.
This is needed to include H atoms that are within the cutoff even when the attached oxygen atom is not.
The *pair_coeff* command must have at least one keyword/value pair, as
described above. The *preset* keyword sets the potential parameters to
the values used in :ref:`(Tainter 2011) <Tainter2011>` or
:ref:`(Tainter 2015) <Tainter2015>`. To use the water models defined in
those references, the *e3b* style should always be used in conjunction
with an *lj/cut/tip4p/long* style through *pair_style hybrid/overlay*,
as demonstrated in the second example above. The *preset 2011* option
should be used with the :doc:`TIP4P water model <Howto_tip4p>`. The
*preset 2015* option should be used with the :doc:`TIP4P/2005 water
model <Howto_tip4p>`. If the *preset* keyword is used, no other keyword
is needed. Changes to the preset parameters can be made by specifying
the *preset* keyword followed by the specific parameter to change, like
*Ea*\ . Note that the other keywords must come after *preset* in the
pair_style command. The *e3b* style can also be used to implement any
three-body potential of the same form by specifying all the keywords
except *neigh*\ : *Ea*, *Eb*, *Ec*, *E2*, *K3*, *K2*, *Rc3*, *Rc2*,
*Rs*, and *bondL*\ . The keyword *bondL* specifies the intramolecular
OH bond length of the water model being used. This is needed to include
H atoms that are within the cutoff even when the attached oxygen atom is
not.
This pair style allocates arrays sized according to the number of pairwise interactions within Rc3.
To do this it needs an estimate for the number of water molecules within Rc3 of an oxygen atom.
This estimate defaults to 10 and can be changed using the *neigh* keyword, which takes an integer as an argument.
If the neigh setting is too small, the simulation will fail with the error "neigh is too small".
If the neigh setting is too large, the pair style will use more memory than necessary.
This pair style allocates arrays sized according to the number of
pairwise interactions within Rc3. To do this it needs an estimate for
the number of water molecules within Rc3 of an oxygen atom. This
estimate defaults to 10 and can be changed using the *neigh* keyword,
which takes an integer as an argument. If the neigh setting is too
small, the simulation will fail with the error "neigh is too small". If
the neigh setting is too large, the pair style will use more memory than
necessary.
This pair style tallies a breakdown of the total E3B potential energy into sub-categories, which can be accessed via the :doc:`compute pair <compute_pair>` command as a vector of values of length 4.
The 4 values correspond to the terms in the first equation above: the E2 term, the Ea term, the Eb term, and the Ec term.
This pair style tallies a breakdown of the total E3B potential energy
into sub-categories, which can be accessed via the :doc:`compute pair
<compute_pair>` command as a vector of values of length 4. The 4 values
correspond to the terms in the first equation above: the E2 term, the Ea
term, the Eb term, and the Ec term.
See the examples/PACKAGES/e3b directory for a complete example script.

2
doc/src/pair_style.rst
View File

@ -350,6 +350,7 @@ accelerated styles exist.
* :doc:`spin/neel <pair_spin_neel>` -
* :doc:`srp <pair_srp>` -
* :doc:`sw <pair_sw>` - Stillinger-Weber 3-body potential
* :doc:`sw/angle/table <pair_sw_angle_table>` - Stillinger-Weber potential with tabulated angular term
* :doc:`sw/mod <pair_sw>` - modified Stillinger-Weber 3-body potential
* :doc:`table <pair_table>` - tabulated pair potential
* :doc:`table/rx <pair_table_rx>` -
@ -360,6 +361,7 @@ accelerated styles exist.
* :doc:`tersoff/table <pair_tersoff>` -
* :doc:`tersoff/zbl <pair_tersoff_zbl>` - Tersoff/ZBL 3-body potential
* :doc:`thole <pair_thole>` - Coulomb interactions with thole damping
* :doc:`threebody/table <pair_threebody_table>` - generic tabulated three-body potential
* :doc:`tip4p/cut <pair_coul>` - Coulomb for TIP4P water w/out LJ
* :doc:`tip4p/long <pair_coul>` - long-range Coulomb for TIP4P water w/out LJ
* :doc:`tip4p/long/soft <pair_fep_soft>` -

311
doc/src/pair_sw_angle_table.rst Normal file
View File

@ -0,0 +1,311 @@
.. index:: pair_style sw/angle/table
pair_style sw/angle/table command
=================================
Syntax
""""""
.. code-block:: LAMMPS
pair_style style
* style = *sw/angle/table*
Examples
""""""""
.. code-block:: LAMMPS
pair_style sw/angle/table
pair_coeff * * spce.sw type
Used in example input script:
.. parsed-literal::
examples/PACKAGES/manybody_table/in.spce_sw
Description
"""""""""""
The *sw/angle/table* style is a modification of the original
:doc:`pair_style sw <pair_sw>`. It has been developed for coarse-grained
simulations (of water) (:ref:`Scherer1 <Scherer1>`), but can be employed
for all kinds of systems. It computes a modified 3-body
:ref:`Stillinger-Weber <Stillinger3>` potential for the energy E of a
system of atoms as
.. math::
E & = \sum_i \sum_{j > i} \phi_2 (r_{ij}) +
\sum_i \sum_{j \neq i} \sum_{k > j}
\phi_3 (r_{ij}, r_{ik}, \theta_{ijk}) \\
\phi_2(r_{ij}) & = A_{ij} \epsilon_{ij} \left[ B_{ij} (\frac{\sigma_{ij}}{r_{ij}})^{p_{ij}} -
(\frac{\sigma_{ij}}{r_{ij}})^{q_{ij}} \right]
\exp \left( \frac{\sigma_{ij}}{r_{ij} - a_{ij} \sigma_{ij}} \right) \\
\phi_3(r_{ij},r_{ik},\theta_{ijk}) & = f^{\textrm{3b}}\left(\theta_{ijk}\right)
\exp \left( \frac{\gamma_{ij} \sigma_{ij}}{r_{ij} - a_{ij} \sigma_{ij}} \right)
\exp \left( \frac{\gamma_{ik} \sigma_{ik}}{r_{ik} - a_{ik} \sigma_{ik}} \right)
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.
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:
* ".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.
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
pair_coeff * * SiC.sw Si Si Si C
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*
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 (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
* element 3
* :math:`\epsilon` (energy units)
* :math:`\sigma` (distance units)
* a
* :math:`\lambda`
* :math:`\gamma`
* :math:`\cos\theta_0`
* A
* B
* p
* q
* tol
* filename
* keyword
* style
* 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
interactions. :math:`\gamma` is used only in the three-body
interactions, but is defined for pairs of atoms. The non-annotated
parameters are unitless.
LAMMPS introduces an additional performance-optimization parameter tol
that is used for both two-body and three-body interactions. In the
Stillinger-Weber potential, the interaction energies become negligibly
small at atomic separations substantially less than the theoretical
cutoff distances. LAMMPS therefore defines a virtual cutoff distance
based on a user defined tolerance tol. The use of the virtual cutoff
distance in constructing atom neighbor lists can significantly reduce
the neighbor list sizes and therefore the computational cost. LAMMPS
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:
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):
.. parsed-literal::
# Angle potential for harmonic (one or more comment or blank lines)
HAM (keyword is the first text on line)
N 181 FP 0 0 EQ 90.0 (N, FP, EQ parameters)
(blank line)
1 0.0 200.5 2.5 (index, angle, energy, derivative)
2 1.0 198.0 2.5
...
181 180.0 0.0 0.0
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.
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.
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.
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
shake <fix_shake>` command. If not used, the equilibrium angle is set to
180.0.
Following a blank line, the next N lines of the angular table file list
the tabulated values. On each line, the first value is the index from 1
to N, the second value is the angle value (in degrees), the third value
is the energy (in energy units), and the fourth is -dE/d(theta) (also in
energy units). The third term is the energy of the 3-atom configuration
for the specified angle. The last term is the derivative of the energy
with respect to the angle (in degrees, not radians). Thus the units of
the last term are still energy, not force. The angle values must
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.
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.
For a single-element simulation, only a single entry is required
(e.g. SiSiSi). For a two-element simulation, the file must contain 8
entries (for SiSiSi, SiSiC, SiCSi, SiCC, CSiSi, CSiC, CCSi, CCC), that
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
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`)
Additional input files and reference data can be found at:
https://gitlab.mpcdf.mpg.de/votca/votca/-/tree/master/csg-tutorials/spce/3body_sw
----------
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.
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 can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does not support the
*inner*, *middle*, *outer* keywords.
----------
Restrictions
""""""""""""
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.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`pair_style sw <pair_sw>`, :doc:`pair_style threebody/table <pair_threebody_table>`
----------
.. _Stillinger3:
**(Stillinger)** Stillinger and Weber, Phys Rev B, 31, 5262 (1985).
.. _Scherer1:
**(Scherer1)** C. Scherer and D. Andrienko, Phys. Chem. Chem. Phys. 20, 22387-22394 (2018).

281
doc/src/pair_threebody_table.rst Normal file
View File

@ -0,0 +1,281 @@
.. index:: pair_style threebody/table
pair_style threebody/table command
==================================
Syntax
""""""
.. code-block:: LAMMPS
pair_style style
* style = *threebody/table*
Examples
""""""""
.. code-block:: LAMMPS
pair_style threebody/table
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:
.. math::
E = \sum_i \sum_{j \neq i} \sum_{k > j} \phi_3 (r_{ij}, r_{ik}, \theta_{ijk})
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.
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.
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
pair_coeff * * SiC.3b Si Si Si C
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.
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:
* element 1 (the center atom in a 3-body interaction)
* element 2
* element 3
* cut (distance units)
* filename
* keyword
* 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 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).
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::
\begin{pmatrix}
{\mathbf f}_{i} \\
{\mathbf f}_{j} \\
{\mathbf f}_{k} \\
\end{pmatrix} =
\begin{pmatrix}
f_{i1} & f_{i2} & 0 \\
f_{j1} & 0 & f_{j2} \\
0 & f_{k1} & f_{k2} \\
\end{pmatrix}
\begin{pmatrix}
{\mathbf r}_{ij} \\
{\mathbf r}_{ik} \\
{\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.
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):
.. parsed-literal::
# Tabulated three-body potential for spce water (one or more comment or blank lines)
ENTRY1 (keyword is the first text on line)
N 12 rmin 2.55 rmax 3.65 (N, rmin, rmax parameters)
(blank line)
1 2.55 2.55 3.75 -867.212 -611.273 867.212 21386.8 611.273 -21386.8 0.0 (index, r_ij, r_ik, theta, f_i1, f_i2, f_j1, f_j2, f_k1, f_k2, e)
2 2.55 2.55 11.25 -621.539 -411.189 621.539 5035.95 411.189 -5035.95 0.0
...
1872 3.65 3.65 176.25 -0.00215132 -0.00412886 0.00215137 0.00111754 0.00412895 -0.00111757 0.0
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.
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.
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.
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
entries (for SiSiSi, SiSiC, SiCSi, SiCC, CSiSi, CSiC, CCSi, CCC), that
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}`.
Additional input files and reference data can be found at:
https://gitlab.mpcdf.mpg.de/votca/votca/-/tree/master/csg-tutorials/ml
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
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 can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does not support the
*inner*, *middle*, *outer* keywords.
----------
Restrictions
""""""""""""
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.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`pair sw/angle/table <pair_sw_angle_table>`
----------
.. _Scherer2:
**(Scherer2)** C. Scherer, R. Scheid, D. Andrienko, and T. Bereau, J. Chem. Theor. Comp. 16, 3194-3204 (2020).

4
doc/src/read_data.rst
View File

@ -56,7 +56,7 @@ Examples
read_data ../run7/data.polymer.gz
read_data data.protein fix mycmap crossterm CMAP
read_data data.water add append offset 3 1 1 1 1 shift 0.0 0.0 50.0
read_data data.water add merge 1 group solvent
read_data data.water add merge group solvent
Description
"""""""""""
@ -622,6 +622,8 @@ of analysis.
- atom-ID molecule-ID atom-type x y z
* - charge
- atom-ID atom-type q x y z
* - dielectric
- atom-ID atom-type q x y z normx normy normz area ed em epsilon curvature
* - dipole
- atom-ID atom-type q x y z mux muy muz
* - dpd

102
doc/src/read_restart.rst
View File

@ -11,7 +11,6 @@ Syntax
read_restart file flag
* file = name of binary restart file to read in
* flag = remap (optional)
Examples
""""""""
@ -19,44 +18,40 @@ Examples
.. code-block:: LAMMPS
read_restart save.10000
read_restart save.10000 remap
read_restart restart.*
read_restart restart.*.mpiio
read_restart poly.*.% remap
Description
"""""""""""
Read in a previously saved system configuration from a restart file.
This allows continuation of a previous run. Details about what
information is stored (and not stored) in a restart file is given
below. Basically this operation will re-create the simulation box
with all its atoms and their attributes as well as some related global
settings, at the point in time it was written to the restart file by a
previous simulation. The simulation box will be partitioned into a
regular 3d grid of rectangular bricks, one per processor, based on the
number of processors in the current simulation and the settings of the
information is stored (and not stored) in a restart file is given below.
Basically this operation will re-create the simulation box with all its
atoms and their attributes as well as some related global settings, at
the point in time it was written to the restart file by a previous
simulation. The simulation box will be partitioned into a regular 3d
grid of rectangular bricks, one per processor, based on the number of
processors in the current simulation and the settings of the
:doc:`processors <processors>` command. The partitioning can later be
changed by the :doc:`balance <balance>` or :doc:`fix balance <fix_balance>` commands.
.. note::
Normally, restart files are written by the
:doc:`restart <restart>` or :doc:`write_restart <write_restart>` commands
so that all atoms in the restart file are inside the simulation box.
If this is not the case, the read_restart command will print an error
that atoms were "lost" when the file is read. This error should be
reported to the LAMMPS developers so the invalid writing of the
restart file can be fixed. If you still wish to use the restart file,
the optional *remap* flag can be appended to the read_restart command.
This should avoid the error, by explicitly remapping each atom back
into the simulation box, updating image flags for the atom
appropriately.
changed by the :doc:`balance <balance>` or :doc:`fix balance
<fix_balance>` commands.
Restart files are saved in binary format to enable exact restarts,
meaning that the trajectories of a restarted run will precisely match
those produced by the original run had it continued on.
The binary restart file format was not designed with backward, forward,
or cross-platform compatibility in mind, so the files are only expected
to be read correctly by the same LAMMPS executable on the same platform.
Changes to the architecture, compilation settings, or LAMMPS version can
render a restart file unreadable or it may read the data incorrectly.
If you want a more portable format, you can use the data file format as
created by the :doc:`write_data <write_data>` command. Binary restart
files can also be converted into a data file from the command line by
the LAMMPS executable that wrote them using the :ref:`-restart2data
<restart2data>` command line flag.
Several things can prevent exact restarts due to round-off effects, in
which case the trajectories in the 2 runs will slowly diverge. These
include running on a different number of processors or changing
@ -65,7 +60,8 @@ certain settings such as those set by the :doc:`newton <newton>` or
these cases.
Certain fixes will not restart exactly, though they should provide
statistically similar results. These include :doc:`fix shake <fix_shake>` and :doc:`fix langevin <fix_langevin>`.
statistically similar results. These include :doc:`fix shake
<fix_shake>` and :doc:`fix langevin <fix_langevin>`.
Certain pair styles will not restart exactly, though they should
provide statistically similar results. This is because the forces
@ -81,18 +77,19 @@ produced the restart file, it could be a LAMMPS bug, so consider
:doc:`reporting it <Errors_bugs>` if you think the behavior is a bug.
Because restart files are binary, they may not be portable to other
machines. In this case, you can use the :doc:`-restart command-line switch <Run_options>` to convert a restart file to a data file.
machines. In this case, you can use the :doc:`-restart command-line
switch <Run_options>` to convert a restart file to a data file.
Similar to how restart files are written (see the
:doc:`write_restart <write_restart>` and :doc:`restart <restart>`
commands), the restart filename can contain two wild-card characters.
If a "\*" appears in the filename, the directory is searched for all
filenames that match the pattern where "\*" is replaced with a timestep
value. The file with the largest timestep value is read in. Thus,
this effectively means, read the latest restart file. It's useful if
you want your script to continue a run from where it left off. See
the :doc:`run <run>` command and its "upto" option for how to specify
the run command so it does not need to be changed either.
Similar to how restart files are written (see the :doc:`write_restart
<write_restart>` and :doc:`restart <restart>` commands), the restart
filename can contain two wild-card characters. If a "\*" appears in the
filename, the directory is searched for all filenames that match the
pattern where "\*" is replaced with a timestep value. The file with the
largest timestep value is read in. Thus, this effectively means, read
the latest restart file. It's useful if you want your script to
continue a run from where it left off. See the :doc:`run <run>` command
and its "upto" option for how to specify the run command so it does not
need to be changed either.
If a "%" character appears in the restart filename, LAMMPS expects a
set of multiple files to exist. The :doc:`restart <restart>` and
@ -222,17 +219,17 @@ its calculations in a consistent manner.
.. note::
There are a handful of commands which can be used before or
between runs which may require a system initialization. Examples
include the "balance", "displace_atoms", "delete_atoms", "set" (some
options), and "velocity" (some options) commands. This is because
they can migrate atoms to new processors. Thus they will also discard
unused "state" information from fixes. You will know the discard has
There are a handful of commands which can be used before or between
runs which may require a system initialization. Examples include the
"balance", "displace_atoms", "delete_atoms", "set" (some options),
and "velocity" (some options) commands. This is because they can
migrate atoms to new processors. Thus they will also discard unused
"state" information from fixes. You will know the discard has
occurred because a list of discarded fixes will be printed to the
screen and log file, as explained above. This means that if you wish
to retain that info in a restarted run, you must re-specify the
relevant fixes and computes (which create fixes) before those commands
are used.
relevant fixes and computes (which create fixes) before those
commands are used.
Some pair styles, like the :doc:`granular pair styles <pair_gran>`, also
use a fix to store "state" information that persists from timestep to
@ -245,18 +242,19 @@ LAMMPS allows bond interactions (angle, etc) to be turned off or
deleted in various ways, which can affect how their info is stored in
a restart file.
If bonds (angles, etc) have been turned off by the :doc:`fix shake <fix_shake>` or :doc:`delete_bonds <delete_bonds>` command,
their info will be written to a restart file as if they are turned on.
This means they will need to be turned off again in a new run after
the restart file is read.
If bonds (angles, etc) have been turned off by the :doc:`fix shake
<fix_shake>` or :doc:`delete_bonds <delete_bonds>` command, their info
will be written to a restart file as if they are turned on. This means
they will need to be turned off again in a new run after the restart
file is read.
Bonds that are broken (e.g. by a bond-breaking potential) are written
to the restart file as broken bonds with a type of 0. Thus these
bonds will still be broken when the restart file is read.
Bonds that have been broken by the :doc:`fix bond/break <fix_bond_break>` command have disappeared from the
system. No information about these bonds is written to the restart
file.
Bonds that have been broken by the :doc:`fix bond/break
<fix_bond_break>` command have disappeared from the system. No
information about these bonds is written to the restart file.
----------