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

Merge branch 'lammps:develop' into compute-snap

Browse Source
This commit is contained in:
Drew Rohskopf
2022-06-23 14:05:11 -04:00
committed by GitHub
parent 447c836629 ae18e1e01c
commit 19dcd9c623
568 changed files with 45452 additions and 18426 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
doc/src/Build_extras.rst
View File

@ -655,14 +655,13 @@ This list was last updated for version 3.5.0 of the Kokkos library.
platform-appropriate vendor library: rocFFT on AMD GPUs or cuFFT on
NVIDIA GPUs.
To simplify compilation, four preset files are included in the
To simplify compilation, five preset files are included in the
``cmake/presets`` folder, ``kokkos-serial.cmake``,
``kokkos-openmp.cmake``, ``kokkos-cuda.cmake``, and
``kokkos-sycl.cmake``. They will enable the KOKKOS package and
enable some hardware choice. So to compile with OpenMP host
parallelization, CUDA device parallelization (for GPUs with CC 5.0
and up) with some common packages enabled, you can do the
following:
``kokkos-openmp.cmake``, ``kokkos-cuda.cmake``,
``kokkos-hip.cmake``, and ``kokkos-sycl.cmake``. They will enable
the KOKKOS package and enable some hardware choice. So to compile
with CUDA device parallelization (for GPUs with CC 5.0 and up)
with some common packages enabled, you can do the following:
.. code-block:: bash

7
doc/src/Build_package.rst
View File

@ -150,7 +150,7 @@ other files dependent on that package are also excluded.
.. _cmake_presets:
CMake presets for installing many packages
""""""""""""""""""""""""""""""""""""""""""
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Instead of specifying all the CMake options via the command-line,
CMake allows initializing its settings cache using script files.
@ -178,6 +178,11 @@ one of them as a starting point and customize it to your needs.
cmake -C ../cmake/presets/all_off.cmake [OPTIONS] ../cmake # disable all packages
mingw64-cmake -C ../cmake/presets/mingw-cross.cmake [OPTIONS] ../cmake # compile with MinGW cross compilers
Presets that have names starting with "windows" are specifically for
compiling LAMMPS :doc:`natively on Windows <Build_windows>` and
presets that have names starting with "kokkos" are specifically for
selecting configurations for compiling LAMMPS with :ref:`KOKKOS <kokkos>`.
.. note::
Running cmake this way manipulates the CMake settings cache in your

15
doc/src/Build_settings.rst
View File

@ -287,8 +287,8 @@ Output of JPG, PNG, and movie files
The :doc:`dump image <dump_image>` command has options to output JPEG or
PNG image files. Likewise the :doc:`dump movie <dump_image>` command
outputs movie files in MPEG format. Using these options requires the
following settings:
outputs movie files in a variety of movie formats. Using these options
requires the following settings:
.. tabs::
@ -328,11 +328,12 @@ following settings:
JPG_LIB = -ljpeg -lpng -lz # library names
As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``,
if make can find the graphics header and library files. You must
specify ``JPG_LIB`` with a list of graphics libraries to include
in the link. You must insure ffmpeg is in a directory where
LAMMPS can find it at runtime, that is a directory in your PATH
environment variable.
if make can find the graphics header and library files in their
default system locations. You must specify ``JPG_LIB`` with a
list of graphics libraries to include in the link. You must make
certain that the ffmpeg executable (or ffmpeg.exe on Windows) is
in a directory where LAMMPS can find it at runtime; that is
usually a directory list in your ``PATH`` environment variable.
Using ``ffmpeg`` to output movie files requires that your machine
supports the "popen" function in the standard runtime library.

54
doc/src/Build_windows.rst
View File

@ -5,6 +5,7 @@ Notes for building LAMMPS on Windows
* :ref:`Running Linux on Windows <linux>`
* :ref:`Using GNU GCC ported to Windows <gnu>`
* :ref:`Using Visual Studio <msvc>`
* :ref:`Using Intel oneAPI compilers and libraries <oneapi>`
* :ref:`Using a cross-compiler <cross>`
----------
@ -25,8 +26,10 @@ assistance in resolving portability issues. This is particularly true
for compiling LAMMPS on Windows, since this platform has significant
differences in some low-level functionality. As of LAMMPS version 14
December 2021, large parts of LAMMPS can be compiled natively with the
Microsoft Visual C++ Compilers. This is largely facilitated by using
the :doc:`Developer_platform` in the ``platform`` namespace.
Microsoft Visual C++ Compilers. As of LAMMPS version 31 May 2022, also
the Intel oneAPI compilers can compile large parts of LAMMPS natively on
Windows. This is mostly facilitated by using the
:doc:`Developer_platform` in the ``platform`` namespace and CMake.
Before trying to build LAMMPS on Windows yourself, please consider the
`pre-compiled Windows installer packages <https://packages.lammps.org/windows.html>`_
@ -129,6 +132,53 @@ LAMMPS with MPI enabled.
via GitHub or the `LAMMPS forum at MatSci <https://matsci.org/c/lammps/lammps-development/>`_,
if you have questions or LAMMPS specific problems.
.. _oneapi:
Using Intel oneAPI Compilers and Libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 31May2022
After installing the `Intel oneAPI
<https://www.intel.com/content/www/us/en/developer/tools/oneapi/toolkits.html>`_
base toolkit and the HPC toolkit, it is also possible to compile large
parts of LAMMPS natively on Windows using Intel compilers. The HPC
toolkit provides two sets of C/C++ and Fortran compilers: the so-called
"classic" compilers (``icl.exe`` and ``ifort.exe``) and newer, LLVM
based compilers (``icx.exe`` and ``ifx.exe``). In addition to the
compilers and their dependent modules, also the thread building blocks
(TBB) and the math kernel library (MKL) need to be installed. Two
presets (``cmake/presets/windows-intel-llvm.cmake`` and
``cmake/presets/windows-intel-classic.cmake``) are provided for
selecting the LLVM based or classic compilers, respectively. The preset
``cmake/presets/windows.cmake`` enables compatible packages that are not
dependent on additional features or libraries. You **must** use the
CMake based build procedure and use Ninja as build tool. For compiling
from the command prompt, thus both `CMake <https://cmake.org>`_ and
`Ninja-build <https://ninja-build.org>`_ binaries must be installed. It
is also possible to use Visual Studio, if it is started (``devenv.exe``)
from a command prompt that has the Intel oneAPI compilers enabled. The
Visual Studio settings file in the ``cmake`` folder contains
configurations for both compiler variants in debug and release settings.
Those will use the CMake and Ninja binaries bundled with Visual Studio,
thus a separate installation is not required.
.. admonition:: Known Limitations
:class: note
In addition to portability issues with several packages and external
libraries, the classic Intel compilers are currently not able to
compile the googletest libraries and thus enabling the ``-DENABLE_TESTING``
option will result in compilation failure. The LLVM based compilers
are compatible.
.. note::
This is work in progress and you should contact the LAMMPS developers
via GitHub or the `LAMMPS forum at MatSci <https://matsci.org/c/lammps/lammps-development/>`_,
if you have questions or LAMMPS specific problems.
.. _cross:
Using a cross-compiler

43
doc/src/Commands_all.rst
View File

@ -14,7 +14,7 @@
General commands
================
An alphabetic list of all general LAMMPS commands.
An alphabetic list of general LAMMPS commands.
.. table_from_list::
:columns: 5
@ -47,35 +47,26 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`displace_atoms <displace_atoms>`
* :doc:`dump <dump>`
* :doc:`dump_modify <dump_modify>`
* :doc:`dynamical_matrix (k) <dynamical_matrix>`
* :doc:`echo <echo>`
* :doc:`fix <fix>`
* :doc:`fix_modify <fix_modify>`
* :doc:`group <group>`
* :doc:`group2ndx <group2ndx>`
* :doc:`hyper <hyper>`
* :doc:`if <if>`
* :doc:`improper_coeff <improper_coeff>`
* :doc:`improper_style <improper_style>`
* :doc:`include <include>`
* :doc:`info <info>`
* :doc:`jump <jump>`
* :doc:`kim <kim_commands>`
* :doc:`kspace_modify <kspace_modify>`
* :doc:`kspace_style <kspace_style>`
* :doc:`label <label>`
* :doc:`lattice <lattice>`
* :doc:`log <log>`
* :doc:`mass <mass>`
* :doc:`mdi <mdi>`
* :doc:`minimize <minimize>`
* :doc:`min_modify <min_modify>`
* :doc:`min_style <min_style>`
* :doc:`min_style spin <min_spin>`
* :doc:`molecule <molecule>`
* :doc:`ndx2group <group2ndx>`
* :doc:`neb <neb>`
* :doc:`neb/spin <neb_spin>`
* :doc:`neigh_modify <neigh_modify>`
* :doc:`neighbor <neighbor>`
* :doc:`newton <newton>`
@ -86,11 +77,8 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`pair_style <pair_style>`
* :doc:`pair_write <pair_write>`
* :doc:`partition <partition>`
* :doc:`plugin <plugin>`
* :doc:`prd <prd>`
* :doc:`print <print>`
* :doc:`processors <processors>`
* :doc:`python <python>`
* :doc:`quit <quit>`
* :doc:`read_data <read_data>`
* :doc:`read_dump <read_dump>`
@ -108,14 +96,9 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`shell <shell>`
* :doc:`special_bonds <special_bonds>`
* :doc:`suffix <suffix>`
* :doc:`tad <tad>`
* :doc:`temper <temper>`
* :doc:`temper/grem <temper_grem>`
* :doc:`temper/npt <temper_npt>`
* :doc:`thermo <thermo>`
* :doc:`thermo_modify <thermo_modify>`
* :doc:`thermo_style <thermo_style>`
* :doc:`third_order (k) <third_order>`
* :doc:`timer <timer>`
* :doc:`timestep <timestep>`
* :doc:`uncompute <uncompute>`
@ -128,3 +111,27 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`write_data <write_data>`
* :doc:`write_dump <write_dump>`
* :doc:`write_restart <write_restart>`
Additional general LAMMPS commands provided by packages. A few
commands have accelerated versions. This is indicated by an
additional letter in parenthesis: k = KOKKOS.
.. table_from_list::
:columns: 5
* :doc:`dynamical_matrix (k) <dynamical_matrix>`
* :doc:`group2ndx <group2ndx>`
* :doc:`hyper <hyper>`
* :doc:`kim <kim_commands>`
* :doc:`mdi <mdi>`
* :doc:`ndx2group <group2ndx>`
* :doc:`neb <neb>`
* :doc:`neb/spin <neb_spin>`
* :doc:`plugin <plugin>`
* :doc:`prd <prd>`
* :doc:`python <python>`
* :doc:`tad <tad>`
* :doc:`temper <temper>`
* :doc:`temper/grem <temper_grem>`
* :doc:`temper/npt <temper_npt>`
* :doc:`third_order (k) <third_order>`

2
doc/src/Commands_bond.rst
View File

@ -88,7 +88,7 @@ OPT.
* :doc:`dipole (o) <angle_dipole>`
* :doc:`fourier (o) <angle_fourier>`
* :doc:`fourier/simple (o) <angle_fourier_simple>`
* :doc:`gaussian <angle_gaussian>` - multicentered Gaussian-based angle potential
* :doc:`gaussian <angle_gaussian>`
* :doc:`harmonic (iko) <angle_harmonic>`
* :doc:`mm3 <angle_mm3>`
* :doc:`quartic (o) <angle_quartic>`

2
doc/src/Commands_pair.rst
View File

@ -269,6 +269,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>`
@ -279,6 +280,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.

2
doc/src/Howto_body.rst
View File

@ -239,7 +239,7 @@ is consistent with the 6 moments of inertia: ixx iyy izz ixy ixz iyz =
.. parsed-literal::
3 1 27
3 1 19
4
1 1 4 0 0 0
-0.7071 -0.7071 0

2
doc/src/Howto_spc.rst
View File

@ -19,7 +19,7 @@ atoms and the water molecule to run a rigid SPC model.
| LJ :math:`\sigma` of OO = 3.166
| LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
| :math:`r_0` of OH bond = 1.0
| :math:`\theta` of HOH angle = 109.47\ :math:`^{\circ}`
| :math:`\theta_0` of HOH angle = 109.47\ :math:`^{\circ}`
|
Note that as originally proposed, the SPC model was run with a 9

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

@ -657,7 +657,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.

40
doc/src/Tools.rst
View File

@ -56,6 +56,7 @@ Pre-processing tools
* :ref:`moltemplate <moltemplate>`
* :ref:`msi2lmp <msi>`
* :ref:`polybond <polybond>`
* :ref:`stl_bin2txt <stlconvert>`
Post-processing tools
@ -94,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>`
@ -1006,14 +1007,37 @@ 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.
----------
.. _stlconvert:
stl_bin2txt tool
----------------
The file stl_bin2txt.cpp converts binary STL files - like they are
frequently offered for download on the web - into ASCII format STL files
that LAMMPS can read with the :doc:`create_atoms mesh <create_atoms>` or
the :doc:`fix smd/wall_surface <fix_smd_wall_surface>` commands. The syntax
for running the tool is
.. code-block:: bash
stl_bin2txt infile.stl outfile.stl
which creates outfile.stl from infile.stl. This tool must be compiled
on a platform compatible with the byte-ordering that was used to create
the binary file. This usually is a so-called little endian hardware
(like x86).
----------

2
doc/src/angle_style.rst
View File

@ -87,7 +87,7 @@ of (g,i,k,o,t) to indicate which accelerated styles exist.
* :doc:`dipole <angle_dipole>` - angle that controls orientation of a point dipole
* :doc:`fourier <angle_fourier>` - angle with multiple cosine terms
* :doc:`fourier/simple <angle_fourier_simple>` - angle with a single cosine term
* :doc:`gaussian <angle_gaussian>` - multicentered Gaussian-based angle potential
* :doc:`gaussian <angle_gaussian>` - multi-centered Gaussian-based angle potential
* :doc:`harmonic <angle_harmonic>` - harmonic angle
* :doc:`mm3 <angle_mm3>` - anharmonic angle
* :doc:`quartic <angle_quartic>` - angle with cubic and quartic terms

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.

117
doc/src/create_atoms.rst
View File

@ -11,7 +11,7 @@ Syntax
create_atoms type style args keyword values ...
* type = atom type (1-Ntypes) of atoms to create (offset for molecule creation)
* style = *box* or *region* or *single* or *random*
* style = *box* or *region* or *single* or *mesh* or *random*
.. parsed-literal::
@ -20,6 +20,8 @@ Syntax
region-ID = particles will only be created if contained in the region
*single* args = x y z
x,y,z = coordinates of a single particle (distance units)
*mesh* args = STL-file
STL-file = file with triangle mesh in STL format
*random* args = N seed region-ID
N = number of particles to create
seed = random # seed (positive integer)
@ -47,6 +49,14 @@ Syntax
*set* values = dim name
dim = *x* or *y* or *z*
name = name of variable to set with x, y, or z atom position
*radscale* value = factor
factor = scale factor for setting atom radius
*meshmode* values = mode arg
mode = *bisect* or *qrand*
*bisect* arg = radthresh
radthresh = threshold value for *mesh* to determine when to split triangles (distance units)
*qrand* arg = density
density = minimum number density for atoms place on *mesh* triangles (inverse distance squared units)
*rotate* values = theta Rx Ry Rz
theta = rotation angle for single molecule (degrees)
Rx,Ry,Rz = rotation vector for single molecule
@ -69,21 +79,23 @@ Examples
create_atoms 3 single 0 0 5
create_atoms 1 box var v set x xpos set y ypos
create_atoms 2 random 50 12345 NULL overlap 2.0 maxtry 50
create_atoms 1 mesh open_box.stl meshmode qrand 0.1 units box
create_atoms 1 mesh funnel.stl meshmode bisect 4.0 units box radscale 0.9
Description
"""""""""""
This command creates atoms (or molecules) within the simulation box,
either on a lattice, or a single atom (or molecule), or a random
collection of atoms (or molecules). It is an alternative to reading
in atom coordinates explicitly via a :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` command. A simulation box must
already exist, which is typically created via the :doc:`create_box
<create_box>` command. Before using this command, a lattice must also
be defined using the :doc:`lattice <lattice>` command, unless you
specify the *single* style with units = box or the *random* style.
For the remainder of this doc page, a created atom or molecule is
referred to as a "particle".
either on a lattice, or a single atom (or molecule), or on a surface
defined by a triangulated mesh, or a random collection of atoms (or
molecules). It is an alternative to reading in atom coordinates
explicitly via a :doc:`read_data <read_data>` or :doc:`read_restart
<read_restart>` command. A simulation box must already exist, which is
typically created via the :doc:`create_box <create_box>` command.
Before using this command, a lattice must also be defined using the
:doc:`lattice <lattice>` command, unless you specify the *single* style
with units = box or the *random* style. For the remainder of this doc
page, a created atom or molecule is referred to as a "particle".
If created particles are individual atoms, they are assigned the
specified atom *type*, though this can be altered via the *basis*
@ -119,6 +131,62 @@ the specified coordinates. This can be useful for debugging purposes
or to create a tiny system with a handful of particles at specified
positions.
.. figure:: img/marble_race.jpg
:figwidth: 33%
:align: right
:target: _images/marble_race.jpg
For the *mesh* style, a file with a triangle mesh in `STL format
<https://en.wikipedia.org/wiki/STL_(file_format)>`_ is read and one or
more particles are placed into the area of each triangle. The reader
supports both ASCII and binary files conforming to the format on the
Wikipedia page. Binary STL files (e.g. as frequently offered for
3d-printing) can also be first converted to ASCII for editing with the
:ref:`stl_bin2txt tool <stlconvert>`. The use of the *units box* option
is required. There are two algorithms available for placing atoms:
*bisect* and *qrand*. They can be selected via the *meshmode* option;
*bisect* is the default. If the atom style allows it, the radius will
be set to a value depending on the algorithm and the value of the
*radscale* parameter (see below), and the atoms created from the mesh
are assigned a new molecule ID.
In *bisect* mode a particle is created at the center of each triangle
unless the average distance of the triangle vertices from its center is
larger than the *radthresh* value (default is lattice spacing in
x-direction). In case the average distance is over the threshold, the
triangle is recursively split into two halves along the the longest side
until the threshold is reached. There will be at least one sphere per
triangle. The value of *radthresh* is set as an argument to *meshmode
bisect*. The average distance of the vertices from the center is also
used to set the radius.
In *qrand* mode a quasi-random sequence is used to distribute particles
on mesh triangles using an approach by :ref:`(Roberts) <Roberts2019>`.
Particles are added to the triangle until the minimum number density is
met or exceeded such that every triangle will have at least one
particle. The minimum number density is set as an argument to the
*qrand* option. The radius will be set so that the sum of the area of
the radius of the particles created in place of a triangle will be equal
to the area of that triangle.
.. note::
The atom placement algorithms in the *mesh* style benefit from meshes
where triangles are close to equilateral. It is therefore
recommended to pre-process STL files to optimize the mesh
accordingly. There are multiple open source and commercial software
tools available with the capability to generate optimized meshes.
.. note::
In most cases the atoms created in *mesh* style will become an
immobile or rigid object that would not be time integrated or moved
by :doc:`fix move <fix_move>` or :doc:`fix rigid <fix_rigid>`. For
computational efficiency *and* to avoid undesired contributions to
pressure and potential energy due to close contacts, it is usually
beneficial to exclude computing interactions between the created
particles using :doc:`neigh_modify exclude <neigh_modify>`.
For the *random* style, *N* particles are added to the system at
randomly generated coordinates, which can be useful for generating an
amorphous system. The particles are created one by one using the
@ -316,6 +384,13 @@ the atoms around the rotation axis is consistent with the right-hand
rule: if your right-hand's thumb points along *R*, then your fingers
wrap around the axis in the direction of rotation.
The *radscale* keyword only applies to the *mesh* style and adjusts the
radius of created particles (see above), provided this is supported by
the atom style. Its value is a prefactor (must be > 0.0, default is
1.0) that is applied to the atom radius inferred from the size of the
individual triangles in the triangle mesh that the particle corresponds
to.
The *overlap* keyword only applies to the *random* style. It prevents
newly created particles from being created closer than the specified
*Doverlap* distance from any other particle. When the particles being
@ -424,9 +499,11 @@ values specified in the file read by the :doc:`molecule <molecule>`
command. E.g. the file typically defines bonds (angles,etc) between
atoms in the molecule, and can optionally define charges on each atom.
Note that the *sphere* atom style sets the default particle diameter
to 1.0 as well as the density. This means the mass for the particle
is not 1.0, but is PI/6 \* diameter\^3 = 0.5236.
Note that the *sphere* atom style sets the default particle diameter to
1.0 as well as the density. This means the mass for the particle is not
1.0, but is PI/6 \* diameter\^3 = 0.5236. When using the *mesh* style,
the particle diameter is adjusted from the size of the individual
triangles in the triangle mesh.
Note that the *ellipsoid* atom style sets the default particle shape
to (0.0 0.0 0.0) and the density to 1.0 which means it is a point
@ -460,5 +537,13 @@ Default
The default for the *basis* keyword is that all created atoms are
assigned the argument *type* as their atom type (when single atoms are
being created). The other defaults are *remap* = no, *rotate* =
random, *overlap* not checked, *maxtry* = 10, and *units* = lattice.
being created). The other defaults are *remap* = no, *rotate* = random,
*radscale* = 1.0, *radthresh* = x-lattice spacing, *overlap* not
checked, *maxtry* = 10, and *units* = lattice.
----------
.. _Roberts2019:
**(Roberts)** R. Roberts (2019) "Evenly Distributing Points in a Triangle." Extreme Learning.
`<http://extremelearning.com.au/evenly-distributing-points-in-a-triangle/>`_

63
doc/src/delete_atoms.rst
View File

@ -10,7 +10,7 @@ Syntax
delete_atoms style args keyword value ...
* style = *group* or *region* or *overlap* or *porosity* or *variable*
* style = *group* or *region* or *overlap* or *random* or *variable*
.. parsed-literal::
@ -20,11 +20,17 @@ Syntax
cutoff = delete one atom from pairs of atoms within the cutoff (distance units)
group1-ID = one atom in pair must be in this group
group2-ID = other atom in pair must be in this group
*porosity* args = group-ID region-ID fraction seed
*random* args = ranstyle value eflag group-ID region-ID seed
ranstyle = *fraction* or *count*
for *fraction*:
value = fraction (0.0 to 1.0) of eligible atoms to delete
eflag = *no* for fast approximate deletion, *yes* for exact deletion
for *count*:
value = number of atoms to delete
eflag = *no* for warning if count > eligible atoms, *yes* for error
group-ID = group within which to perform deletions
region-ID = region within which to perform deletions
or NULL to only impose the group criterion
fraction = delete this fraction of atoms
seed = random number seed (positive integer)
*variable* args = variable-name
@ -46,16 +52,17 @@ Examples
delete_atoms region sphere compress no
delete_atoms overlap 0.3 all all
delete_atoms overlap 0.5 solvent colloid
delete_atoms porosity all cube 0.1 482793 bond yes
delete_atoms porosity polymer cube 0.1 482793 bond yes
delete_atoms random fraction 0.1 yes all cube 482793 bond yes
delete_atoms random fraction 0.3 no polymer NULL 482793 bond yes
delete_atoms random count 500 no ions NULL 482793
detele_atoms variable checkers
Description
"""""""""""
Delete the specified atoms. This command can be used to carve out
voids from a block of material or to delete created atoms that are too
close to each other (e.g. at a grain boundary).
Delete the specified atoms. This command can be used, for example, to
carve out voids from a block of material or to delete created atoms
that are too close to each other (e.g. at a grain boundary).
For style *group*, all atoms belonging to the group are deleted.
@ -81,17 +88,33 @@ have occurred that no atom pairs within the cutoff will remain
minimum number of atoms will be deleted, or that the same atoms will
be deleted when running on different numbers of processors.
For style *porosity* a specified *fraction* of atoms are deleted which
are both in the specified group and within the specified region. The
region-ID can be specified as NULL to only impose the group criterion.
Likewise, specifying the group-ID as *all* will only impose the region
criterion.
For style *random* a subset of eligible atoms are deleted. Which
atoms to delete are chosen randomly using the specified random number
*seed*. Which atoms are deleted may vary when running on different
numbers of processors.
For example, if fraction is 0.1, then 10% of the eligible atoms will
be deleted. The atoms to delete are chosen randomly. There is no
guarantee that the exact fraction of atoms will be deleted, or that
the same atoms will be deleted when running on different numbers of
processors.
For *ranstyle* = *fraction*, the specified fractional *value* (0.0 to
1.0) of eligible atoms are deleted. If *eflag* is set to *no*, then
the number of deleted atoms will be approximate, but the operation
will be fast. If *eflag* is set to *yes*, then the number deleted
will match the requested fraction, but for large systems the selection
of deleted atoms may take additional time to determine.
For *ranstyle* = *count*, the specified integer *value* is the number
of eligible atoms are deleted. If *eflag* is set to *no*, then if the
requested number is larger then the number of eligible atoms, a
warning is issued and only the eligible atoms are deleted instead of
the requested *value*. If *eflag* is set to *yes*, an error is
triggered instead and LAMMPS will exit. For large systems the
selection of atoms to delete may take additional time to determine,
the same as for requesting an exact fraction with *pstyle* =
*fraction*.
Which atoms are eligible for deletion for style *random* is determined
by the specified *group-ID* and *region-ID*. To be eligible, an atom
must be in both the specified group and region. If *group-ID* = all,
there is effectively no group criterion. If *region-ID* is specified
as NULL, no region criterion is imposed.
For style *variable*, all atoms for which the atom-style variable with
the given name evaluates to non-zero will be deleted. Additional atoms
@ -100,6 +123,10 @@ were deleted within the region; see the *mol* keyword discussion below.
This option allows complex selections of atoms not covered by the
other options listed above.
----------
Here is the meaning of the optional keywords.
If the *compress* keyword is set to *yes*, then after atoms are
deleted, then atom IDs are re-assigned so that they run from 1 to the
number of atoms in the system. Note that this is not done for

8
doc/src/dump.rst
View File

@ -133,13 +133,14 @@ Examples
.. code-block:: LAMMPS
dump myDump all atom 100 dump.atom
dump myDump all atom 100 dump.lammpstrj
dump myDump all atom/mpiio 100 dump.atom.mpiio
dump myDump all atom/gz 100 dump.atom.gz
dump myDump all atom/zstd 100 dump.atom.zst
dump 2 subgroup atom 50 dump.run.bin
dump 2 subgroup atom/mpiio 50 dump.run.mpiio.bin
dump 4a all custom 100 dump.myforce.* id type x y vx fx
dump 4a all custom 100 dump.myvel.lammpsbin id type x y z vx vy vz
dump 4b flow custom 100 dump.%.myforce id type c_myF[3] v_ke
dump 4b flow custom 100 dump.%.myforce id type c_myF[*] v_ke
dump 2 inner cfg 10 dump.snap.*.cfg mass type xs ys zs vx vy vz
@ -419,6 +420,7 @@ style.
.. code-block:: yaml
---
creator: LAMMPS
timestep: 0
units: lj
time: 0
@ -534,11 +536,11 @@ MPI-IO.
Note that MPI-IO dump files are one large file which all processors
write to. You thus cannot use the "%" wildcard character described
above in the filename since that specifies generation of multiple
files. You can use the ".bin" suffix described below in an MPI-IO
files. You can use the ".bin" or ".lammpsbin" suffix described below in an MPI-IO
dump file; again this file will be written in parallel and have the
same binary format as if it were written without MPI-IO.
If the filename ends with ".bin", the dump file (or files, if "\*" or
If the filename ends with ".bin" or ".lammpsbin", the dump file (or files, if "\*" or
"%" is also used) is written in binary format. A binary dump file
will be about the same size as a text version, but will typically
write out much faster. Of course, when post-processing, you will need

2
doc/src/dump_image.rst
View File

@ -44,7 +44,7 @@ Syntax
color = *type*
bflag1,bflag2 = 2 numeric flags to affect how bodies are drawn
*fix* = fixID color fflag1 fflag2
fixID = ID of fix that generates objects to dray
fixID = ID of fix that generates objects to draw
color = *type*
fflag1,fflag2 = 2 numeric flags to affect how fix objects are drawn
*size* values = width height = size of images

5
doc/src/dump_modify.rst
View File

@ -392,9 +392,8 @@ keyword. For *atom* dump styles only the keywords "id", "type", "x",
"y", "z", "ix", "iy", "iz" can be accessed via string regardless of
whether scaled or unwrapped coordinates were enabled or disabled, and
it always assumes 8 columns for indexing regardless of whether image
flags are enabled or not. For dump style *cfg* only the "auxiliary"
keywords (6th or later keyword) may be changed and the column indexing
considers only them (i.e. the 6th keyword is the the 1st column).
flags are enabled or not. For dump style *cfg* only changes to the
"auxiliary" keywords (6th or later keyword) will become visible.
The *colname* keyword can be used multiple times. If multiple *colname*
settings refer to the same keyword, the last setting has precedence. A

4
doc/src/fix_hyper_local.rst
View File

@ -75,7 +75,7 @@ doc page. This description of LHD builds on the GHD description.
The definition of bonds and :math:`E_{ij}` are the same for GHD and LHD.
The formulas for :math:`V^{max}_{ij}` and :math:`F^{max}_{ij}` are also
the same except for a pre-factor :math:`C_{ij}`, explained below.
the same except for a prefactor :math:`C_{ij}`, explained below.
The bias energy :math:`V_{ij}` applied to a bond *ij* with maximum strain is
@ -256,7 +256,7 @@ Note that this fix does not know the *cutevent* parameter, but uses
half the *cutbond* parameter as an estimate to warn if the ghost
cutoff is not long enough.
As described above the *alpha* argument is a pre-factor in the
As described above the *alpha* argument is a prefactor in the
boostostat update equation for each bond's :math:`C_{ij}` prefactor.
*Alpha* is specified in time units, similar to other thermostat or barostat
damping parameters. It is roughly the physical time it will take the

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.

5
doc/src/fix_momentum.rst
View File

@ -21,7 +21,8 @@ Syntax
* momentum = style name of this fix command
* N = adjust the momentum every this many timesteps
one or more keyword/value pairs may be appended
* keyword = *linear* or *angular* or *rescale*
.. parsed-literal::
fix ID group-ID momentum/chunk N chunkID keyword values ...
@ -30,7 +31,7 @@ Syntax
* N = adjust the momentum per chunk every this many timesteps
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
one or more keyword/value pairs may be appended
one or more keyword/value settings may be appended to each of the fix commands:
* keyword = *linear* or *angular* or *rescale*
.. parsed-literal::

2
doc/src/fix_restrain.rst
View File

@ -59,7 +59,7 @@ of a bond or angle or dihedral interaction whose strength can vary
over time during a simulation. This is functionally similar to
creating a bond or angle or dihedral for the same atoms in a data
file, as specified by the :doc:`read_data <read_data>` command, albeit
with a time-varying pre-factor coefficient, and except for exclusion
with a time-varying prefactor coefficient, and except for exclusion
rules, as explained below.
For the purpose of force field parameter-fitting or mapping a molecular

4
doc/src/fix_wall.rst
View File

@ -199,7 +199,7 @@ inside the colloid particle and wall. Note that the cutoff distance Rc
in this case is the distance from the colloid particle center to the
wall. The prefactor :math:`\epsilon` can be thought of as an effective
Hamaker constant with energy units for the strength of the colloid-wall
interaction. More specifically, the :math:`\epsilon` pre-factor is
interaction. More specifically, the :math:`\epsilon` prefactor is
:math:`4\pi^2 \rho_{wall} \rho_{colloid} \epsilon \sigma^6`, where
:math:`\epsilon` and :math:`\sigma` are the LJ parameters for the
constituent LJ particles. :math:`\rho_{wall}` and :math:`\rho_{colloid}`
@ -211,7 +211,7 @@ constituent LJ particles of size :math:`\sigma` within the colloid particle
and a 3d half-lattice of Lennard-Jones 12/6 particles of size :math:`\sigma`
in the wall. As mentioned in the preceding paragraph, the density of
particles in the wall and colloid can be different, as specified by
the :math:`\epsilon` pre-factor.
the :math:`\epsilon` prefactor.
For the *wall/harmonic* style, :math:`\epsilon` is effectively the spring
constant K, and has units (energy/distance\^2). The input parameter

2
doc/src/fix_wall_ees.rst
View File

@ -88,7 +88,7 @@ examples/ directory.
The prefactor :math:`\epsilon` can be thought of as an
effective Hamaker constant with energy units for the strength of the
ellipsoid-wall interaction. More specifically, the :math:`\epsilon`
pre-factor is
prefactor is
.. math::

BIN
doc/src/img/marble_race.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB

8
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:
@ -475,8 +475,8 @@ that package **and** the KSPACE package. See the :doc:`Build package
<Build_package>` page for more info.
For MSM, a simulation must be 3d and one can use any combination of
periodic, non-periodic, or shrink-wrapped boundaries (specified using
the :doc:`boundary <boundary>` command).
periodic, non-periodic, but not shrink-wrapped boundaries (specified
using the :doc:`boundary <boundary>` command).
For Ewald and PPPM, a simulation must be 3d and periodic in all
dimensions. The only exception is if the slab option is set with

4
doc/src/min_spin.rst
View File

@ -98,6 +98,10 @@ see their implementation reported in :ref:`(Ivanov) <Ivanov1>`.
Restrictions
""""""""""""
The *spin*, *spin/cg*, and *spin/lbfgps* styles are part of the SPIN
package. They are only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` page for more info.
This minimization procedure is only applied to spin degrees of
freedom for a frozen lattice configuration.

42
doc/src/min_style.rst
View File

@ -1,25 +1,55 @@
.. index:: min_style
min_style command
=================
min_style cg command
====================
min_style hftn command
======================
min_style sd command
====================
min_style quickmin command
==========================
min_style fire command
======================
min_style fire/old command
==========================
:doc:`min_style spin <min_spin>` command
========================================
:doc:`min_style spin/cg <min_spin>` command
===========================================
:doc:`min_style spin/lbfgs <min_spin>` command
==============================================
Syntax
""""""
.. code-block:: LAMMPS
.. parsed-literal::
min_style style
* style = *cg* or *hftn* or *sd* or *quickmin* or *fire* or *fire/old* or *spin* or *spin/cg* or *spin/lbfgs*
.. parsed-literal::
*spin* is discussed briefly here and fully on :doc:`min_style spin <min_spin>` doc page
*spin/cg* is discussed briefly here and fully on :doc:`min_style spin <min_spin>` doc page
*spin/lbfgs* is discussed briefly here and fully on :doc:`min_style spin <min_spin>` doc page
Examples
""""""""
.. code-block:: LAMMPS
min_style cg
min_style spin
min_style fire
min_style spin
Description
"""""""""""
@ -124,7 +154,9 @@ calculations via the :doc:`neb/spin <neb_spin>` command.
Restrictions
""""""""""""
none
The *spin*, *spin/cg*, and *spin/lbfgps* styles are part of the SPIN
package. They are only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` page for more info.
Related commands
""""""""""""""""

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_gran.rst
View File

@ -144,7 +144,7 @@ two particles, and is thus a non-linear function of overlap distance.
Thus Kn has units of force per area and is thus specified in units of
(pressure). The effects of absolute particle size (monodispersity)
and relative size (polydispersity) are captured in the radii-dependent
pre-factors. When these pre-factors are carried through to the other
prefactors. When these prefactors are carried through to the other
terms in the force equation it means that the specified :math:`\gamma_n` is in
units of (1/(time\*distance)), :math:`K_t` is in units of (pressure), and
:math:`\gamma_t` is in units of (1/(time\*distance)).

2
doc/src/pair_multi_lucy.rst
View File

@ -54,7 +54,7 @@ form.
An interpolation table is used to evaluate the density-dependent energy
(:math:`\int A(\rho') d\rho'`) and force (:math:`A(\rho')`). Note that
the pre-factor to the energy is computed after the interpolation, thus
the prefactor to the energy is computed after the interpolation, thus
the :math:`\int A(\rho') d \rho'` will have units of energy / length\^4.
The interpolation table is created as a pre-computation by fitting

2
doc/src/pair_multi_lucy_rx.rst
View File

@ -67,7 +67,7 @@ form.
An interpolation table is used to evaluate the density-dependent energy
(:math:`\int A(\rho') d \rho'`) and force (:math:`A(\rho')`). Note that
the pre-factor to the energy is computed after the interpolation, thus
the prefactor to the energy is computed after the interpolation, thus
the :math:`\int A(\rho') d\rho'` will have units of energy / length\^4.
The interpolation table is created as a pre-computation by fitting

41
doc/src/pair_none.rst
View File

@ -20,28 +20,37 @@ Examples
Description
"""""""""""
Using a pair style of none means pair forces and energies are not
computed.
Using a pair style of *none* means that any previous pair style setting
will be deleted and pairwise forces and energies are not computed.
With this choice, the force cutoff is 0.0, which means that only atoms
within the neighbor skin distance (see the :doc:`neighbor <neighbor>`
command) are communicated between processors. You must insure the
skin distance is large enough to acquire atoms needed for computing
bonds, angles, etc.
As a consequence there will be a pairwise force cutoff of 0.0, which has
implications for the default setting of the neighbor list and the
communication cutoff. Those are the sum of the largest pairwise cutoff
and the neighbor skin distance (see the documentation of the
:doc:`neighbor <neighbor>` command and the :doc:`comm_modify
<comm_modify>` command). When you have bonds, angles, dihedrals, or
impropers defined at the same time, you must set the communication
cutoff so that communication cutoff distance is large enough to acquire
and communicate sufficient ghost atoms from neighboring sub-domains as
needed for computing bonds, angles, etc.
A pair style of *none* will also prevent pairwise neighbor lists from
being built. However if the :doc:`neighbor <neighbor>` style is *bin*,
data structures for binning are still allocated. If the neighbor skin
distance is small, then these data structures can consume a large
amount of memory. So you should either set the neighbor style to
*nsq* or set the skin distance to a larger value.
A pair style of *none* will also not request a pairwise neighbor list.
However if the :doc:`neighbor <neighbor>` style is *bin*, data
structures for binning are still allocated. If the neighbor list cutoff
is small, then these data structures can consume a large amount of
memory. So you should either set the neighbor style to *nsq* or set the
skin distance to a larger value.
See the :doc:`pair_style zero <pair_zero>` for a way to trigger the
building of a neighbor lists, but compute no pairwise interactions.
See the :doc:`pair_style zero <pair_zero>` for a way to set a pairwise
cutoff and thus trigger the building of a neighbor lists and setting
a corresponding communication cutoff, but compute no pairwise interactions.
Restrictions
""""""""""""
none
You must not use a :doc:`pair_coeff <pair_coeff>` command with this pair
style. Since there is no interaction computed, you cannot set any
coefficients for it.
Related commands
""""""""""""""""

2
doc/src/pair_soft.rst
View File

@ -41,7 +41,7 @@ Style *soft* computes pairwise interactions with the formula
\qquad r < r_c
It is useful for pushing apart overlapping atoms, since it does not
blow up as r goes to 0. A is a pre-factor that can be made to vary in
blow up as r goes to 0. A is a prefactor that can be made to vary in
time from the start to the end of the run (see discussion below),
e.g. to start with a very soft potential and slowly harden the
interactions over time. Rc is the cutoff. See the :doc:`fix nve/limit <fix_nve_limit>` command for another way to push apart

2
doc/src/pair_style.rst
View File

@ -348,6 +348,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>` -
@ -358,6 +359,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.
----------

2
doc/src/special_bonds.rst
View File

@ -88,7 +88,7 @@ The Coulomb factors are applied to any Coulomb (charge interaction)
term that the potential calculates. The LJ factors are applied to the
remaining terms that the potential calculates, whether they represent
LJ interactions or not. The weighting factors are a scaling
pre-factor on the energy and force between the pair of atoms. A value
prefactor on the energy and force between the pair of atoms. A value
of 1.0 means include the full interaction; a value of 0.0 means
exclude it completely.

22
doc/src/variable.rst
View File

@ -847,15 +847,6 @@ Special Functions
Special functions take specific kinds of arguments, meaning their
arguments cannot be formulas themselves.
The is_file(name) function is a test whether *name* is a (readable) file
and returns 1 in this case, otherwise it returns 0. For that *name*
is taken as a literal string and must not have any blanks in it.
The extract_setting(name) function allows to access some basic settings
through calling the :cpp:func:`lammps_extract_setting` library function.
For available keywords *name* and their meaning, please see the
documentation of that function.
The sum(x), min(x), max(x), ave(x), trap(x), and slope(x) functions
each take 1 argument which is of the form "c_ID" or "c_ID[N]" or
"f_ID" or "f_ID[N]" or "v_name". The first two are computes and the
@ -934,6 +925,19 @@ invoked more times than there are lines or sets of lines in the file,
the variable is deleted, similar to how the :doc:`next <next>` command
operates.
The is_file(name) function is a test whether *name* is a (readable) file
and returns 1 in this case, otherwise it returns 0. For that *name*
is taken as a literal string and must not have any blanks in it.
The extract_setting(name) function enables access to basic settings for
the LAMMPS executable and the running simulation via calling the
:cpp:func:`lammps_extract_setting` library function. For example, the
number of processors (MPI ranks) being used by the simulation or the MPI
process ID (for this processor) can be queried, or the number of atom
types, bond types and so on. For the full list of available keywords
*name* and their meaning, see the documentation for extract_setting()
via the link in this paragraph.
----------
Feature Functions