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

Merge https://github.com/lammps/lammps into pair_rann

Browse Source
This commit is contained in:
kipbarrett
2021-04-23 10:35:35 -05:00
parent 92abca3910 c8d16353e8
commit b2bfb26161
2710 changed files with 42514 additions and 16730 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/Build_basics.rst
View File

@ -1,7 +1,7 @@
Basic build options
===================
The following topics are covered on this page, for building both with
The following topics are covered on this page, for building with both
CMake and make:
* :ref:`Serial vs parallel build <serial>`

54
doc/src/Build_extras.rst
View File

@ -52,6 +52,7 @@ This is the list of packages that may require additional steps.
* :ref:`USER-MESONT <user-mesont>`
* :ref:`USER-MOLFILE <user-molfile>`
* :ref:`USER-NETCDF <user-netcdf>`
* :ref:`USER-PACE <user-pace>`
* :ref:`USER-PLUMED <user-plumed>`
* :ref:`USER-OMP <user-omp>`
* :ref:`USER-QMMM <user-qmmm>`
@ -125,7 +126,7 @@ CMake build
# default is sm_50
-D HIP_ARCH=value # primary GPU hardware choice for GPU_API=hip
# value depends on selected HIP_PLATFORM
# default is 'gfx906' for HIP_PLATFORM=hcc and 'sm_50' for HIP_PLATFORM=nvcc
# default is 'gfx906' for HIP_PLATFORM=amd and 'sm_50' for HIP_PLATFORM=nvcc
-D HIP_USE_DEVICE_SORT=value # enables GPU sorting
# value = yes (default) or no
-D CUDPP_OPT=value # use GPU binning on with CUDA (should be off for modern GPUs)
@ -169,17 +170,24 @@ desired, you can set :code:`USE_STATIC_OPENCL_LOADER` to :code:`no`.
If you are compiling with HIP, note that before running CMake you will have to
set appropriate environment variables. Some variables such as
:code:`HCC_AMDGPU_TARGET` or :code:`CUDA_PATH` are necessary for :code:`hipcc`
:code:`HCC_AMDGPU_TARGET` (for ROCm <= 4.0) or :code:`CUDA_PATH` are necessary for :code:`hipcc`
and the linker to work correctly.
.. code:: bash
# AMDGPU target
# AMDGPU target (ROCm <= 4.0)
export HIP_PLATFORM=hcc
export HCC_AMDGPU_TARGET=gfx906
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4
.. code:: bash
# AMDGPU target (ROCm >= 4.1)
export HIP_PLATFORM=amd
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
make -j 4
.. code:: bash
# CUDA target (not recommended, use GPU_ARCH=cuda)
@ -1240,6 +1248,46 @@ be built for the most part with all major versions of the C++ language.
----------
.. _user-pace:
USER-PACE package
-----------------------------
This package requires a library that can be downloaded and built
in lib/pace or somewhere else, which must be done before building
LAMMPS with this package. The code for the library can be found
at: `https://github.com/ICAMS/lammps-user-pace/ <https://github.com/ICAMS/lammps-user-pace/>`_
.. tabs::
.. tab:: CMake build
By default the library will be downloaded from the git repository
and built automatically when the USER-PACE package is enabled with
``-D PKG_USER-PACE=yes``. The location for the sources may be
customized by setting the variable ``PACELIB_URL`` when
configuring with CMake (e.g. to use a local archive on machines
without internet access). Since CMake checks the validity of the
archive with ``md5sum`` you may also need to set ``PACELIB_MD5``
if you provide a different library version than what is downloaded
automatically.
.. tab:: Traditional make
You can download and build the USER-PACE library
in one step from the ``lammps/src`` dir, using these commands,
which invoke the ``lib/pace/Install.py`` script.
.. code-block:: bash
$ make lib-pace # print help message
$ make lib-pace args="-b" # download and build the default version in lib/pace
You should not need to edit the ``lib/pace/Makefile.lammps`` file.
----------
.. _user-plumed:
USER-PLUMED package

22
doc/src/Build_package.rst
View File

@ -30,17 +30,17 @@ steps, as explained on the :doc:`Build extras <Build_extras>` page.
These links take you to the extra instructions for those select
packages:
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`COMPRESS <compress>` | :ref:`GPU <gpu>` | :ref:`KIM <kim>` | :ref:`KOKKOS <kokkos>` | :ref:`LATTE <latte>` | :ref:`MESSAGE <message>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`MSCG <mscg>` | :ref:`OPT <opt>` | :ref:`POEMS <poems>` | :ref:`PYTHON <python>` | :ref:`VORONOI <voronoi>` | :ref:`USER-ADIOS <user-adios>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-ATC <user-atc>` | :ref:`USER-AWPMD <user-awpmd>` | :ref:`USER-COLVARS <user-colvars>` | :ref:`USER-H5MD <user-h5md>` | :ref:`USER-INTEL <user-intel>` | :ref:`USER-MOLFILE <user-molfile>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-NETCDF <user-netcdf>` | :ref:`USER-PLUMED <user-plumed>` | :ref:`USER-OMP <user-omp>` | :ref:`USER-QMMM <user-qmmm>` | :ref:`USER-QUIP <user-quip>` | :ref:`USER-SCAFACOS <user-scafacos>` |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-SMD <user-smd>` | :ref:`USER-VTK <user-vtk>` | | | | |
+----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`COMPRESS <compress>` | :ref:`GPU <gpu>` | :ref:`KIM <kim>` | :ref:`KOKKOS <kokkos>` | :ref:`LATTE <latte>` | :ref:`MESSAGE <message>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`MSCG <mscg>` | :ref:`OPT <opt>` | :ref:`POEMS <poems>` | :ref:`PYTHON <python>` | :ref:`VORONOI <voronoi>` | :ref:`USER-ADIOS <user-adios>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-ATC <user-atc>` | :ref:`USER-AWPMD <user-awpmd>` | :ref:`USER-COLVARS <user-colvars>` | :ref:`USER-H5MD <user-h5md>` | :ref:`USER-INTEL <user-intel>` | :ref:`USER-MOLFILE <user-molfile>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-NETCDF <user-netcdf>` | :ref:`USER-PACE <user-pace>` | :ref:`USER-PLUMED <user-plumed>` | :ref:`USER-OMP <user-omp>` | :ref:`USER-QMMM <user-qmmm>` | :ref:`USER-QUIP <user-quip>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-SCAFACOS <user-scafacos>` | :ref:`USER-SMD <user-smd>` | :ref:`USER-VTK <user-vtk>` | | | |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
The mechanism for including packages is simple but different for CMake
versus make.

1
doc/src/Commands_all.rst
View File

@ -86,6 +86,7 @@ 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>`

2
doc/src/Commands_bond.rst
View File

@ -126,7 +126,7 @@ OPT.
* :doc:`quadratic (o) <dihedral_quadratic>`
* :doc:`spherical <dihedral_spherical>`
* :doc:`table (o) <dihedral_table>`
* :doc:`table/cut <dihedral_table_cut>`
* :doc:`table/cut <dihedral_table>`
.. _improper:

1
doc/src/Commands_fix.rst
View File

@ -46,6 +46,7 @@ OPT.
* :doc:`bond/react <fix_bond_react>`
* :doc:`bond/swap <fix_bond_swap>`
* :doc:`box/relax <fix_box_relax>`
* :doc:`charge/regulation <fix_charge_regulation>`
* :doc:`client/md <fix_client_md>`
* :doc:`cmap <fix_cmap>`
* :doc:`colvars <fix_colvars>`

6
doc/src/Commands_pair.rst
View File

@ -26,6 +26,7 @@ OPT.
* :doc:`zero <pair_zero>`
* :doc:`hybrid (k) <pair_hybrid>`
* :doc:`hybrid/overlay (k) <pair_hybrid>`
* :doc:`hybrid/scaled <pair_hybrid>`
* :doc:`kim <pair_kim>`
* :doc:`list <pair_list>`
*
@ -33,7 +34,6 @@ OPT.
*
*
*
*
* :doc:`adp (o) <pair_adp>`
* :doc:`agni (o) <pair_agni>`
* :doc:`airebo (io) <pair_airebo>`
@ -69,6 +69,7 @@ OPT.
* :doc:`comb3 <pair_comb>`
* :doc:`cosine/squared <pair_cosine_squared>`
* :doc:`coul/cut (gko) <pair_coul>`
* :doc:`coul/cut/global (o) <pair_coul>`
* :doc:`coul/cut/soft (o) <pair_fep_soft>`
* :doc:`coul/debye (gko) <pair_coul>`
* :doc:`coul/diel (o) <pair_coul_diel>`
@ -187,7 +188,7 @@ OPT.
* :doc:`mgpt <pair_mgpt>`
* :doc:`mie/cut (g) <pair_mie>`
* :doc:`mliap <pair_mliap>`
* :doc:`mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>`
* :doc:`mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
* :doc:`momb <pair_momb>`
* :doc:`morse (gkot) <pair_morse>`
* :doc:`morse/smooth/linear (o) <pair_morse>`
@ -215,6 +216,7 @@ OPT.
* :doc:`oxrna2/stk <pair_oxrna2>`
* :doc:`oxrna2/xstk <pair_oxrna2>`
* :doc:`oxrna2/coaxstk <pair_oxrna2>`
* :doc:`pace <pair_pace>`
* :doc:`peri/eps <pair_peri>`
* :doc:`peri/lps (o) <pair_peri>`
* :doc:`peri/pmb (o) <pair_peri>`

1
doc/src/Developer.rst
View File

@ -14,6 +14,7 @@ of time and requests from the LAMMPS user community.
Developer_flow
Developer_write
Developer_notes
Developer_plugins
Developer_unittest
Classes
Developer_utils

16
doc/src/Developer_org.rst
View File

@ -49,8 +49,8 @@ underscore character '_' to separate words. Outside of bundled libraries
which may have different conventions, all C and C++ header files have a
``.h`` extension, all C++ files have a ``.cpp`` extension, and C files a
``.c`` extension. A small number of C++ classes and utility functions
are implemented with only a ``.h`` file. Examples are the Pointer class
or the MathVec functions.
are implemented with only a ``.h`` file. Examples are the Pointers and
Commands classes or the MathVec functions.
Class topology
--------------
@ -144,7 +144,7 @@ implement specific commands that can be invoked before, after, or in
between runs. For these an instance of the class is created, its
command() method called and then, after completion, the class instance
deleted. Examples for this are the create_box, create_atoms, minimize,
run, or velocity command styles.
run, set, or velocity command styles.
For all those ``styles`` certain naming conventions are employed: for
the fix nve command the class is called FixNVE and the source files are
@ -175,11 +175,11 @@ follows:
- The Input class reads and processes input input strings and files,
stores variables, and invokes :doc:`commands <Commands_all>`.
- As discussed above, command style classes are directly derived from
the Pointers class. They provide input script commands that perform
one-time operations before/after/between simulations or which invoke a
simulation. They are instantiated from within the Input class,
invoked, then immediately destructed.
- Command style classes are derived from the Command class. They provide
input script commands that perform one-time operations
before/after/between simulations or which invoke a simulation. They
are usually instantiated from within the Input class, its ``command``
method invoked, and then immediately destructed.
- The Finish class is instantiated to print statistics to the screen
after a simulation is performed, by commands like run and minimize.

251
doc/src/Developer_plugins.rst Normal file
View File

@ -0,0 +1,251 @@
Writing plugins
---------------
Plugins provide a mechanism to add functionality to a LAMMPS executable
without recompiling LAMMPS. The functionality for this and the
:doc:`plugin command <plugin>` are implemented in the
:ref:`PLUGIN package <PKG-PLUGIN>` which must be installed to use plugins.
Plugins use the operating system's capability to load dynamic shared
object (DSO) files in a way similar shared libraries and then reference
specific functions in those DSOs. Any DSO file with plugins has to include
an initialization function with a specific name, "lammpsplugin_init", that
has to follow specific rules described below. When loading the DSO with
the "plugin" command, this function is looked up and called and will then
register the contained plugin(s) with LAMMPS.
From the programmer perspective this can work because of the object
oriented design of LAMMPS where all pair style commands are derived from
the class Pair, all fix style commands from the class Fix and so on and
usually only functions present in those base classes are called
directly. When a :doc:`pair_style` command or :doc:`fix` command is
issued a new instance of such a derived class is created. This is done
by a so-called factory function which is mapped to the style name. Thus
when, for example, the LAMMPS processes the command ``pair_style lj/cut
2.5``, LAMMPS will look up the factory function for creating the
``PairLJCut`` class and then execute it. The return value of that
function is a ``Pair *`` pointer and the pointer will be assigned to the
location for the currently active pair style.
A DSO file with a plugin thus has to implement such a factory function
and register it with LAMMPS so that it gets added to the map of available
styles of the given category. To register a plugin with LAMMPS an
initialization function has to be present in the DSO file called
``lammpsplugin_init`` which is called with three ``void *`` arguments:
a pointer to the current LAMMPS instance, a pointer to the opened DSO
handle, and a pointer to the registration function. The registration
function takes two arguments: a pointer to a ``lammpsplugin_t`` struct
with information about the plugin and a pointer to the current LAMMPS
instance. Please see below for an example of how the registration is
done.
Members of ``lammpsplugin_t``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table::
:header-rows: 1
:widths: auto
* - Member
- Description
* - version
- LAMMPS Version string the plugin was compiled for
* - style
- Style of the plugin (pair, bond, fix, command, etc.)
* - name
- Name of the plugin style
* - info
- String with information about the plugin
* - author
- String with the name and email of the author
* - creator.v1
- Pointer to factory function for pair, bond, angle, dihedral, improper or command styles
* - creator.v2
- Pointer to factory function for compute, fix, or region styles
* - handle
- Pointer to the open DSO file handle
Only one of the three alternate creator entries can be used at a time
and which of those is determined by the style of plugin. The
"creator.v1" element is for factory functions of supported styles
computing forces (i.e. command, pair, bond, angle, dihedral, or
improper styles) and the function takes as single argument the pointer
to the LAMMPS instance. The factory function is cast to the
``lammpsplugin_factory1`` type before assignment. The "creator.v2"
element is for factory functions creating an instance of a fix, compute,
or region style and takes three arguments: a pointer to the LAMMPS
instance, an integer with the length of the argument list and a ``char
**`` pointer to the list of arguments. The factory function pointer
needs to be cast to the ``lammpsplugin_factory2`` type before
assignment.
Pair style example
^^^^^^^^^^^^^^^^^^
As an example, a hypothetical pair style plugin "morse2" implemented in
a class ``PairMorse2`` in the files ``pair_morse2.h`` and
``pair_morse2.cpp`` with the factory function and initialization
function would look like this:
.. code-block:: C++
#include "lammpsplugin.h"
#include "version.h"
#include "pair_morse2.h"
using namespace LAMMPS_NS;
static Pair *morse2creator(LAMMPS *lmp)
{
return new PairMorse2(lmp);
}
extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)
{
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;
lammpsplugin_t plugin;
plugin.version = LAMMPS_VERSION;
plugin.style = "pair";
plugin.name = "morse2";
plugin.info = "Morse2 variant pair style v1.0";
plugin.author = "Axel Kohlmeyer (akohlmey@gmail.com)";
plugin.creator.v1 = (lammpsplugin_factory1 *) &morse2creator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}
The factory function in this example is called ``morse2creator()``. It
receives a pointer to the LAMMPS class as only argument and thus has to
be assigned to the *creator.v1* member of the plugin struct and cast to
the ``lammpsplugin_factory1`` function pointer type. It returns a
pointer to the allocated class instance derived from the ``Pair`` class.
This function may be declared static to avoid clashes with other
plugins. The name of the derived class, ``PairMorse2``, however must be
unique inside the entire LAMMPS executable.
Fix style example
^^^^^^^^^^^^^^^^^
If the factory function would be for a fix or compute, which take three
arguments (a pointer to the LAMMPS class, the number of arguments and the
list of argument strings), then the pointer type is ``lammpsplugin_factory2``
and it must be assigned to the *creator.v2* member of the plugin struct.
Below is an example for that:
.. code-block:: C++
#include "lammpsplugin.h"
#include "version.h"
#include "fix_nve2.h"
using namespace LAMMPS_NS;
static Fix *nve2creator(LAMMPS *lmp, int argc, char **argv)
{
return new FixNVE2(lmp,argc,argv);
}
extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)
{
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;
lammpsplugin_t plugin;
plugin.version = LAMMPS_VERSION;
plugin.style = "fix";
plugin.name = "nve2";
plugin.info = "NVE2 variant fix style v1.0";
plugin.author = "Axel Kohlmeyer (akohlmey@gmail.com)";
plugin.creator.v2 = (lammpsplugin_factory2 *) &nve2creator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}
Command style example
^^^^^^^^^^^^^^^^^^^^^
Command styles also use the first variant of factory function as
demonstrated in the following example, which also shows that the
implementation of the plugin class may be within the same source
file as the plugin interface code:
.. code-block:: C++
#include "lammpsplugin.h"
#include "comm.h"
#include "error.h"
#include "command.h"
#include "version.h"
#include <cstring>
namespace LAMMPS_NS {
class Hello : public Command {
public:
Hello(class LAMMPS *lmp) : Command(lmp) {};
void command(int, char **);
};
}
using namespace LAMMPS_NS;
void Hello::command(int argc, char **argv)
{
if (argc != 1) error->all(FLERR,"Illegal hello command");
if (comm->me == 0)
utils::logmesg(lmp,fmt::format("Hello, {}!\n",argv[0]));
}
static void hellocreator(LAMMPS *lmp)
{
return new Hello(lmp);
}
extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)
{
lammpsplugin_t plugin;
lammpsplugin_regfunc register_plugin = (lammpsplugin_regfunc) regfunc;
plugin.version = LAMMPS_VERSION;
plugin.style = "command";
plugin.name = "hello";
plugin.info = "Hello world command v1.1";
plugin.author = "Axel Kohlmeyer (akohlmey@gmail.com)";
plugin.creator.v1 = (lammpsplugin_factory1 *) &hellocreator;
plugin.handle = handle;
(*register_plugin)(&plugin,lmp);
}
Additional Details
^^^^^^^^^^^^^^^^^^
The initialization function **must** be called ``lammpsplugin_init``, it
**must** have C bindings and it takes three void pointers as arguments.
The first is a pointer to the LAMMPS class that calls it and it needs to
be passed to the registration function. The second argument is a
pointer to the internal handle of the DSO file, this needs to be added
to the plugin info struct, so that the DSO can be closed and unloaded
when all its contained plugins are unloaded. The third argument is a
function pointer to the registration function and needs to be stored
in a variable of ``lammpsplugin_regfunc`` type and then called with a
pointer to the ``lammpsplugin_t`` struct and the pointer to the LAMMPS
instance as arguments to register a single plugin. There may be multiple
calls to multiple plugins in the same initialization function.
To register a plugin a struct of the ``lammpsplugin_t`` needs to be filled
with relevant info: current LAMMPS version string, kind of style, name of
style, info string, author string, pointer to factory function, and the
DSO handle. The registration function is called with a pointer to the address
of this struct and the pointer of the LAMMPS class. The registration function
will then add the factory function of the plugin style to the respective
style map under the provided name. It will also make a copy of the struct
in a list of all loaded plugins and update the reference counter for loaded
plugins from this specific DSO file.
The pair style itself (i.e. the PairMorse2 class in this example) can be
written just like any other pair style that is included in LAMMPS. For
a plugin, the use of the ``PairStyle`` macro in the section encapsulated
by ``#ifdef PAIR_CLASS`` is not needed, since the mapping of the class
name to the style name is done by the plugin registration function with
the information from the ``lammpsplugin_t`` struct. It may be included
in case the new code is intended to be later included in LAMMPS directly.

45
doc/src/Developer_unittest.rst
View File

@ -4,10 +4,10 @@ Adding tests for unit testing
This section discusses adding or expanding tests for the unit test
infrastructure included into the LAMMPS source code distribution.
Unlike example inputs, unit tests focus on testing the "local" behavior
of individual features, tend to run very fast, and should be set up to
cover as much of the added code as possible. When contributing code to
the distribution, the LAMMPS developers will appreciate if additions
to the integrated unit test facility are included.
of individual features, tend to run fast, and should be set up to cover
as much of the added code as possible. When contributing code to the
distribution, the LAMMPS developers will appreciate if additions to the
integrated unit test facility are included.
Given the complex nature of MD simulations where many operations can
only be performed when suitable "real" simulation environment has been
@ -50,6 +50,9 @@ available:
* - File name:
- Test name:
- Description:
* - ``test_argutils.cpp``
- ArgInfo
- Tests for ``ArgInfo`` class used by LAMMPS
* - ``test_fmtlib.cpp``
- FmtLib
- Tests for ``fmtlib::`` functions used by LAMMPS
@ -155,23 +158,27 @@ have the desired effect:
{
ASSERT_EQ(lmp->update->ntimestep, 0);
if (!verbose) ::testing::internal::CaptureStdout();
lmp->input->one("reset_timestep 10");
if (!verbose) ::testing::internal::GetCapturedStdout();
BEGIN_HIDE_OUTPUT();
command("reset_timestep 10");
END_HIDE_OUTPUT();
ASSERT_EQ(lmp->update->ntimestep, 10);
if (!verbose) ::testing::internal::CaptureStdout();
lmp->input->one("reset_timestep 0");
if (!verbose) ::testing::internal::GetCapturedStdout();
BEGIN_HIDE_OUTPUT();
command("reset_timestep 0");
END_HIDE_OUTPUT();
ASSERT_EQ(lmp->update->ntimestep, 0);
TEST_FAILURE(".*ERROR: Timestep must be >= 0.*", command("reset_timestep -10"););
TEST_FAILURE(".*ERROR: Illegal reset_timestep .*", command("reset_timestep"););
TEST_FAILURE(".*ERROR: Illegal reset_timestep .*", command("reset_timestep 10 10"););
TEST_FAILURE(".*ERROR: Expected integer .*", command("reset_timestep xxx"););
}
Please note the use of the (global) verbose variable to control whether
the LAMMPS command will be silent by capturing the output or not. In
the default case, verbose == false, the test output will be compact and
not mixed with LAMMPS output. However setting the verbose flag (via
setting the ``TEST_ARGS`` environment variable, ``TEST_ARGS=-v``) can be
helpful to understand why tests fail unexpectedly.
Please note the use of the ``BEGIN_HIDE_OUTPUT`` and ``END_HIDE_OUTPUT``
functions that will capture output from running LAMMPS. This is normally
discarded but by setting the verbose flag (via setting the ``TEST_ARGS``
environment variable, ``TEST_ARGS=-v``) it can be printed and used to
understand why tests fail unexpectedly.
Another complexity of these tests stems from the need to capture
situations where LAMMPS will stop with an error, i.e. handle so-called
@ -210,6 +217,12 @@ The following test programs are currently available:
* - ``test_lattice_region.cpp``
- LatticeRegion
- Tests to validate the :doc:`lattice <lattice>` and :doc:`region <region>` commands
* - ``test_groups.cpp``
- GroupTest
- Tests to validate the :doc:`group <group>` command
* - ``test_variables.cpp``
- VariableTest
- Tests to validate the :doc:`variable <variable>` command
* - ``test_kim_commands.cpp``
- KimCommands
- Tests for several commands from the :ref:`KIM package <PKG-KIM>`

3
doc/src/Developer_utils.rst
View File

@ -101,6 +101,9 @@ and parsing files or arguments.
.. doxygenfunction:: split_words
:project: progguide
.. doxygenfunction:: split_lines
:project: progguide
.. doxygenfunction:: strmatch
:project: progguide

1
doc/src/Howto_bioFF.rst
View File

@ -91,6 +91,7 @@ documentation for the formula it computes.
* :doc:`bond_style <bond_harmonic>` harmonic
* :doc:`bond_style <bond_morse>` morse
* :doc:`angle_style <angle_cosine_squared>` cosine/squared
* :doc:`angle_style <angle_harmonic>` harmonic
* :doc:`angle_style <angle_cosine>` cosine
* :doc:`angle_style <angle_cosine_periodic>` cosine/periodic

10
doc/src/Howto_granular.rst
View File

@ -18,12 +18,13 @@ This compute
calculates rotational kinetic energy which can be :doc:`output with thermodynamic info <Howto_output>`.
Use one of these 3 pair potentials, which compute forces and torques
Use one of these 4 pair potentials, which compute forces and torques
between interacting pairs of particles:
* :doc:`pair_style <pair_style>` gran/history
* :doc:`pair_style <pair_style>` gran/no_history
* :doc:`pair_style <pair_style>` gran/hertzian
* :doc:`pair_style gran/history <pair_gran>`
* :doc:`pair_style gran/no_history <pair_gran>`
* :doc:`pair_style gran/hertzian <pair_gran>`
* :doc:`pair_style granular <pair_granular>`
These commands implement fix options specific to granular systems:
@ -31,6 +32,7 @@ These commands implement fix options specific to granular systems:
* :doc:`fix pour <fix_pour>`
* :doc:`fix viscous <fix_viscous>`
* :doc:`fix wall/gran <fix_wall_gran>`
* :doc:`fix wall/gran/region <fix_wall_gran_region>`
The fix style *freeze* zeroes both the force and torque of frozen
atoms, and should be used for granular system instead of the fix style

4
doc/src/Howto_spins.rst
View File

@ -21,8 +21,8 @@ orientations and their associated inter-atomic distances.
The command :doc:`fix precession/spin <fix_precession_spin>` allows to
apply a constant magnetic torque on all the spins in the system. This
torque can be an external magnetic field (Zeeman interaction), or an
uniaxial magnetic anisotropy.
torque can be an external magnetic field (Zeeman interaction), and an
uniaxial or cubic magnetic anisotropy.
A Langevin thermostat can be applied to those magnetic spins using
:doc:`fix langevin/spin <fix_langevin_spin>`. Typically, this thermostat

70
doc/src/Install_git.rst
View File

@ -86,33 +86,59 @@ check out any other desired branch) first.
Once you have updated your local files with a ``git pull`` (or ``git
checkout``), you still need to re-build LAMMPS if any source files have
changed. To do this, you should cd to the src directory and type:
changed. How to do this depends on the build system you are using.
.. code-block:: bash
.. tabs::
$ make purge # remove any deprecated src files
$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)
.. tab:: CMake build
just as described on the :doc:`Apply patch <Install_patch>` page,
after a patch has been installed.
Change to your build folder and type:
.. warning::
.. code-block:: bash
If you wish to edit/change a src file that is from a
package, you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The version in
the source directory is merely a copy and will be wiped out if you type "make
package-update".
cmake . --build
.. warning::
CMake should auto-detect whether it needs to re-run the CMake
configuration step and otherwise redo the build for all files
that have been changed or files that depend on changed files.
In case some build options have been changed or renamed, you
may have to update those by running:
The GitHub servers support both the "git://" and
"https://" access protocols for anonymous read-only access. If you
have a correspondingly configured GitHub account, you may also use
SSH access with the URL "git@github.com:lammps/lammps.git".
.. code-block:: bash
The LAMMPS GitHub project is managed by Christoph Junghans (LANL,
junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at
gmail.com) and Richard Berger (Temple U, richard.berger at
temple.edu).
cmake .
and then rebuild.
.. tab:: Traditional make
Switch to the src directory and type:
.. code-block:: bash
$ make purge # remove any deprecated src files
$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)
Just as described on the :doc:`Apply patch <Install_patch>` page,
after a patch has been installed.
.. warning::
If you wish to edit/change a src file that is from a package,
you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The
version in the source directory is merely a copy and will be
wiped out if you type "make package-update".
.. admonition:: Git protocols
:class: note
The servers at github.com support the "git://" and "https://" access
protocols for anonymous, read-only access. If you have a suitably
configured GitHub account, you may also use SSH protocol with the
URL "git@github.com:lammps/lammps.git".
The LAMMPS GitHub project is currently managed by Axel Kohlmeyer
(Temple U, akohlmey at gmail.com) and Richard Berger (Temple U,
richard.berger at temple.edu).

62
doc/src/Install_patch.rst
View File

@ -43,24 +43,54 @@ up to date.
* A list of updated files print out to the screen. The -b switch
creates backup files of your originals (e.g. src/force.cpp.orig), so
you can manually undo the patch if something goes wrong.
* Type the following from the src directory, to enforce consistency
between the src and package directories. This is OK to do even if you
don't use one or more packages. If you are applying several patches
successively, you only need to type this once at the end. The purge
command removes deprecated src files if any were removed by the patch
from package sub-directories.
.. code-block:: bash
* Once you have updated your local files you need to re-build LAMMPS.
If you are applying several patches successively, you only need to
do the rebuild once at the end. How to do it depends on the build
system you are using.
$ make purge
$ make package-update
.. tabs::
* Re-build LAMMPS via the "make" command.
.. tab:: CMake build
.. warning::
Change to your build folder and type:
If you wish to edit/change a source file that is part of a package,
you should edit the version of the file inside the package folder in
src, and then re-install or update the package. The version in the
src directory is merely a copy and will be wiped out when you type
"make package-update".
.. code-block:: bash
cmake . --build
CMake should auto-detect whether it needs to re-run the CMake
configuration step and otherwise redo the build for all files
that have been changed or files that depend on changed files.
In case some build options have been changed or renamed, you
may have to update those by running:
.. code-block:: bash
cmake .
and then rebuild.
.. tab:: Traditional make
Switch to the src directory and type:
.. code-block:: bash
$ make purge # remove any deprecated src files
$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)
to enforce consistency of the source between the src folder
and package directories. This is OK to do even if you don't
use any packages. The "make purge" command removes any deprecated
src files if they were removed by the patch from a package
sub-directory.
.. warning::
If you wish to edit/change a src file that is from a package,
you should edit the version of the file inside the package
sub-directory with src, then re-install the package. The
version in the source directory is merely a copy and will be
wiped out if you type "make package-update".

BIN
doc/src/JPG/lammps-classes.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 254 KiB

After

Width:  |  Height:  |  Size: 286 KiB

2
doc/src/Library_scatter.rst
View File

@ -76,7 +76,7 @@ It documents the following functions:
-----------------------
.. doxygenfunction:: lammps_create_atoms(void *handle, int n, int *id, int *type, double *x, double *v, int *image, int bexpand)
.. doxygenfunction:: lammps_create_atoms(void *handle, int n, const int *id, const int *type, const double *x, const double *v, const int *image, int bexpand)
:project: progguide

17
doc/src/Modify_command.rst
View File

@ -1,14 +1,15 @@
Input script command style
==========================
New commands can be added to LAMMPS input scripts by adding new
classes that have a "command" method. For example, the create_atoms,
read_data, velocity, and run commands are all implemented in this
fashion. When such a command is encountered in the LAMMPS input
script, LAMMPS simply creates a class with the corresponding name,
invokes the "command" method of the class, and passes it the arguments
from the input script. The command method can perform whatever
operations it wishes on LAMMPS data structures.
New commands can be added to LAMMPS input scripts by adding new classes
that are derived from the Command class and thus must have a "command"
method. For example, the create_atoms, read_data, velocity, and run
commands are all implemented in this fashion. When such a command is
encountered in the LAMMPS input script, LAMMPS simply creates a class
instance with the corresponding name, invokes the "command" method of
the class, and passes it the arguments from the input script. The
command method can perform whatever operations it wishes on LAMMPS data
structures.
The single method your new class must define is as follows:

72
doc/src/Packages_details.rst
View File

@ -50,6 +50,7 @@ page gives those details.
* :ref:`MSCG <PKG-MSCG>`
* :ref:`OPT <PKG-OPT>`
* :ref:`PERI <PKG-PERI>`
* :ref:`PLUGIN <PKG-PLUGIN>`
* :ref:`POEMS <PKG-POEMS>`
* :ref:`PYTHON <PKG-PYTHON>`
* :ref:`QEQ <PKG-QEQ>`
@ -89,6 +90,7 @@ page gives those details.
* :ref:`USER-MOLFILE <PKG-USER-MOLFILE>`
* :ref:`USER-NETCDF <PKG-USER-NETCDF>`
* :ref:`USER-OMP <PKG-USER-OMP>`
* :ref:`USER-PACE <PKG-USER-PACE>`
* :ref:`USER-PHONON <PKG-USER-PHONON>`
* :ref:`USER-PLUMED <PKG-USER-PLUMED>`
* :ref:`USER-PTM <PKG-USER-PTM>`
@ -584,7 +586,7 @@ MC package
Several fixes and a pair style that have Monte Carlo (MC) or MC-like
attributes. These include fixes for creating, breaking, and swapping
bonds, for performing atomic swaps, and performing grand-canonical MC
(GCMC) in conjunction with dynamics.
(GCMC) or similar processes in conjunction with dynamics.
**Supporting info:**
@ -592,8 +594,12 @@ bonds, for performing atomic swaps, and performing grand-canonical MC
* :doc:`fix atom/swap <fix_atom_swap>`
* :doc:`fix bond/break <fix_bond_break>`
* :doc:`fix bond/create <fix_bond_create>`
* :doc:`fix bond/create/angle <fix_bond_create>`
* :doc:`fix bond/swap <fix_bond_swap>`
* :doc:`fix charge/regulation <fix_charge_regulation>`
* :doc:`fix gcmc <fix_gcmc>`
* :doc:`fix tfmc <fix_tfmc>`
* :doc:`fix widom <fix_widom>`
* :doc:`pair_style dsmc <pair_dsmc>`
* https://lammps.sandia.gov/movies.html#gcmc
@ -843,6 +849,28 @@ Foster (UTSA).
----------
.. _PKG-PLUGIN:
PLUGIN package
--------------
**Contents:**
A :doc:`plugin <plugin>` command that can load and unload several
kind of styles in LAMMPS from shared object files at runtime without
having to recompile and relink LAMMPS.
**Authors:** Axel Kohlmeyer (Temple U)
**Supporting info:**
* src/PLUGIN: filenames -> commands
* :doc:`plugin command <plugin>`
* :doc:`Information on writing plugins <Developer_plugins>`
* examples/plugin
----------
.. _PKG-POEMS:
POEMS package
@ -1326,6 +1354,46 @@ This package has :ref:`specific installation instructions <user-colvars>` on the
----------
.. _PKG-USER-PACE:
USER-PACE package
-------------------
**Contents:**
A pair style for the Atomic Cluster Expansion potential (ACE).
ACE is a methodology for deriving a highly accurate classical potential
fit to a large archive of quantum mechanical (DFT) data. The USER-PACE
package provides an efficient implementation for running simulations
with ACE potentials.
**Authors:**
This package was written by Yury Lysogorskiy^1,
Cas van der Oord^2, Anton Bochkarev^1,
Sarath Menon^1, Matteo Rinaldi^1, Thomas Hammerschmidt^1, Matous Mrovec^1,
Aidan Thompson^3, Gabor Csanyi^2, Christoph Ortner^4, Ralf Drautz^1.
^1: Ruhr-University Bochum, Bochum, Germany
^2: University of Cambridge, Cambridge, United Kingdom
^3: Sandia National Laboratories, Albuquerque, New Mexico, USA
^4: University of British Columbia, Vancouver, BC, Canada
**Install:**
This package has :ref:`specific installation instructions <user-pace>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/USER-PACE: filenames -> commands
* :doc:`pair_style pace <pair_pace>`
* examples/USER/pace
----------
.. _PKG-USER-PLUMED:
USER-PLUMED package
@ -2456,6 +2524,6 @@ which discuss the `QuickFF <quickff_>`_ methodology.
* :doc:`bond_style mm3 <bond_mm3>`
* :doc:`improper_style distharm <improper_distharm>`
* :doc:`improper_style sqdistharm <improper_sqdistharm>`
* :doc:`pair_style mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>`
* :doc:`pair_style mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
* :doc:`pair_style lj/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
* examples/USER/yaff

2
doc/src/Packages_standard.rst
View File

@ -71,6 +71,8 @@ package:
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`PERI <PKG-PERI>` | Peridynamics models | :doc:`pair_style peri <pair_peri>` | peri | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`PLUGIN <PKG-PLUGIN>` | Plugin loader command | :doc:`plugin <plugin>` | plugins | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`POEMS <PKG-POEMS>` | coupled rigid body motion | :doc:`fix poems <fix_poems>` | rigid | int |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`PYTHON <PKG-PYTHON>` | embed Python code in an input script | :doc:`python <python>` | python | sys |

2
doc/src/Packages_user.rst
View File

@ -81,6 +81,8 @@ package:
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-OMP <PKG-USER-OMP>` | OpenMP-enabled styles | :doc:`Speed omp <Speed_omp>` | `Benchmarks <https://lammps.sandia.gov/bench.html>`_ | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-PACE <PKG-USER-PACE>` | Fast implementation of Atomic Cluster Expansion (ACE) potential | :doc:`pair pace <pair_pace>` | USER/pace | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-PHONON <PKG-USER-PHONON>` | phonon dynamical matrix | :doc:`fix phonon <fix_phonon>` | USER/phonon | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-PLUMED <PKG-USER-PLUMED>` | :ref:`PLUMED <PLUMED>` free energy library | :doc:`fix plumed <fix_plumed>` | USER/plumed | ext |

2
doc/src/Python_module.rst
View File

@ -142,7 +142,7 @@ Style Constants
Type Constants
--------------
.. py:data:: LMP_TYPE_SCALAR, LMP_TYLE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
.. py:data:: LMP_TYPE_SCALAR, LMP_TYPE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
:type: int
Constants in the :py:mod:`lammps` module to select what type of data

37
doc/src/Python_neighbor.rst
View File

@ -1,6 +1,43 @@
Neighbor list access
====================
Access to neighbor lists is handled through a couple of wrapper classes
that allows to treat it like either a python list or a NumPy array. The
access procedure is similar to that of the C-library interface: use one
of the "find" functions to look up the index of the neighbor list in the
global table of neighbor lists and then get access to the neighbor list
data. The code sample below demonstrates reading the neighbor list data
using the NumPy access method.
.. code-block:: python
from lammps import lammps
import numpy as np
lmp = lammps()
lmp.commands_string("""
region box block -2 2 -2 2 -2 2
lattice fcc 1.0
create_box 1 box
create_atoms 1 box
mass 1 1.0
pair_style lj/cut 2.5
pair_coeff 1 1 1.0 1.0
run 0 post no""")
# look up the neighbor list
nlidx = lmp.find_pair_neighlist('lj/cut')
nl = lmp.numpy.get_neighlist(nlidx)
tags = lmp.extract_atom('id')
print("half neighbor list with {} entries".format(nl.size))
# print neighbor list contents
for i in range(0,nl.size):
idx, nlist = nl.get(i)
print("\natom {} with ID {} has {} neighbors:".format(idx,tags[idx],nlist.size))
if nlist.size > 0:
for n in np.nditer(nlist):
print(" atom {} with ID {}".format(n,tags[n]))
**Methods:**
* :py:meth:`lammps.get_neighlist() <lammps.lammps.get_neighlist()>`: Get neighbor list for given index

22
doc/src/angle_cosine_periodic.rst
View File

@ -24,20 +24,17 @@ Examples
Description
"""""""""""
The *cosine/periodic* angle style uses the following potential, which
is commonly used in the :doc:`DREIDING <Howto_bioFF>` force field,
particularly for organometallic systems where :math:`n` = 4 might be used
The *cosine/periodic* angle style uses the following potential, which may be
particularly used for organometallic systems where :math:`n` = 4 might be used
for an octahedral complex and :math:`n` = 3 might be used for a trigonal
center:
.. math::
E = C \left[ 1 - B(-1)^n\cos\left( n\theta\right) \right]
E = \frac{2.0}{n^2} * C \left[ 1 - B(-1)^n\cos\left( n\theta\right) \right]
where :math:`C`, :math:`B` and :math:`n` are coefficients defined for each angle type.
See :ref:`(Mayo) <cosine-Mayo>` for a description of the DREIDING force field
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
@ -47,10 +44,9 @@ or :doc:`read_restart <read_restart>` commands:
* :math:`B` = 1 or -1
* :math:`n` = 1, 2, 3, 4, 5 or 6 for periodicity
Note that the prefactor :math:`C` is specified and not the overall force
constant :math:`K = \frac{C}{n^2}`. When :math:`B = 1`, it leads to a minimum for the
linear geometry. When :math:`B = -1`, it leads to a maximum for the linear
geometry.
Note that the prefactor :math:`C` is specified as coefficient and not the overall force
constant :math:`K = \frac{2 C}{n^2}`. When :math:`B = 1`, it leads to a minimum for the
linear geometry. When :math:`B = -1`, it leads to a maximum for the linear geometry.
----------
@ -75,9 +71,3 @@ Default
none
----------
.. _cosine-Mayo:
**(Mayo)** Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909
(1990).

14
doc/src/angle_cosine_squared.rst
View File

@ -30,8 +30,11 @@ The *cosine/squared* angle style uses the potential
E = K [\cos(\theta) - \cos(\theta_0)]^2
where :math:`\theta_0` is the equilibrium value of the angle, and :math:`K` is a
prefactor. Note that the usual 1/2 factor is included in :math:`K`.
, which is commonly used in the :doc:`DREIDING <Howto_bioFF>` force field,
where :math:`\theta_0` is the equilibrium value of the angle, and :math:`K`
is a prefactor. Note that the usual 1/2 factor is included in :math:`K`.
See :ref:`(Mayo) <cosine-Mayo>` for a description of the DREIDING force field.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
@ -66,3 +69,10 @@ Default
"""""""
none
----------
.. _cosine-Mayo:
**(Mayo)** Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909
(1990).

2
doc/src/atom_style.rst
View File

@ -27,7 +27,7 @@ Syntax
template-ID = ID of molecule template specified in a separate :doc:`molecule <molecule>` command
*hybrid* args = list of one or more sub-styles, each with their args
* accelerated styles (with same args) = *angle/kk* or *atomic/kk* or *bond/kk* or *charge/kk* or *full/kk* or *molecular/kk*
* accelerated styles (with same args) = *angle/kk* or *atomic/kk* or *bond/kk* or *charge/kk* or *full/kk* or *molecular/kk* or *spin/kk*
Examples
""""""""

4
doc/src/balance.rst
View File

@ -257,7 +257,7 @@ factor, similar to how the :doc:`fix balance shift <fix_balance>`
command operates.
The *dimstr* argument is a string of characters, each of which must be
an "x" or "y" or "z". Eacn character can appear zero or one time,
an "x" or "y" or "z". Each character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.
@ -285,7 +285,7 @@ plane gets closer to the target value.
After the balanced plane positions are determined, if any pair of
adjacent planes are closer together than the neighbor skin distance
(as specified by the :doc`neigh_modify <neigh_modify>` command), then
(as specified by the :doc:`neigh_modify <neigh_modify>` command), then
the plane positions are shifted to separate them by at least this
amount. This is to prevent particles being lost when dynamics are run
with processor sub-domains that are too narrow in one or more

1
doc/src/commands_list.rst
View File

@ -77,6 +77,7 @@ Commands
pair_style
pair_write
partition
plugin
prd
print
processors

15
doc/src/compute_pressure.rst
View File

@ -46,13 +46,14 @@ system volume (or area in 2d). The second term is the virial, equal to
-dU/dV, computed for all pairwise as well as 2-body, 3-body, 4-body,
many-body, and long-range interactions, where :math:`r_i` and
:math:`f_i` are the position and force vector of atom *i*, and the black
dot indicates a dot product. When periodic boundary conditions are
used, N' necessarily includes periodic image (ghost) atoms outside the
central box, and the position and force vectors of ghost atoms are thus
included in the summation. When periodic boundary conditions are not
used, N' = N = the number of atoms in the system. :doc:`Fixes <fix>`
that impose constraints (e.g. the :doc:`fix shake <fix_shake>` command)
also contribute to the virial term.
dot indicates a dot product. This is computed in parallel for each
sub-domain and then summed over all parallel processes. Thus N'
necessarily includes atoms from neighboring sub-domains (so-called ghost
atoms) and the position and force vectors of ghost atoms are thus
included in the summation. Only when running in serial and without
periodic boundary conditions is N' = N = the number of atoms in the
system. :doc:`Fixes <fix>` that impose constraints (e.g. the :doc:`fix
shake <fix_shake>` command) may also contribute to the virial term.
A symmetric pressure tensor, stored as a 6-element vector, is also
calculated by this compute. The 6 components of the vector are

2
doc/src/dihedral_style.rst
View File

@ -113,7 +113,7 @@ more of (g,i,k,o,t) to indicate which accelerated styles exist.
* :doc:`quadratic <dihedral_quadratic>` - dihedral with quadratic term in angle
* :doc:`spherical <dihedral_spherical>` - dihedral which includes angle terms to avoid singularities
* :doc:`table <dihedral_table>` - tabulated dihedral
* :doc:`table/cut <dihedral_table_cut>` - tabulated dihedral with analytic cutoff
* :doc:`table/cut <dihedral_table>` - tabulated dihedral with analytic cutoff
----------

89
doc/src/dihedral_table.rst
View File

@ -1,19 +1,24 @@
.. index:: dihedral_style table
.. index:: dihedral_style table/omp
.. index:: dihedral_style table/cut
dihedral_style table command
============================
Accelerator Variants: *table/omp*
dihedral_style table/cut command
================================
Syntax
""""""
.. code-block:: LAMMPS
dihedral_style table style Ntable
dihedral_style style interpolation Ntable
* style = *linear* or *spline* = method of interpolation
* style = *table* or *table/cut*
* interpolation = *linear* or *spline* = method of interpolation
* Ntable = size of the internal lookup table
Examples
@ -26,13 +31,21 @@ Examples
dihedral_coeff 1 file.table DIH_TABLE1
dihedral_coeff 2 file.table DIH_TABLE2
dihedral_style table/cut spline 400
dihedral_style table/cut linear 1000
dihedral_coeff 1 aat 1.0 177 180 file.table DIH_TABLE1
dihedral_coeff 2 aat 0.5 170 180 file.table DIH_TABLE2
Description
"""""""""""
The *table* dihedral style creates interpolation tables of length
*Ntable* from dihedral potential and derivative values listed in a
file(s) as a function of the dihedral angle "phi". The files are read
by the :doc:`dihedral_coeff <dihedral_coeff>` command.
The *table* and *table/cut* dihedral styles create interpolation tables
of length *Ntable* from dihedral potential and derivative values listed
in a file(s) as a function of the dihedral angle "phi". The files are
read by the :doc:`dihedral_coeff <dihedral_coeff>` command. For
dihedral style *table/cut* additionally an analytic cutoff that is
quadratic in the bond-angle (theta) is applied in order to regularize
the dihedral interaction.
The interpolation tables are created by fitting cubic splines to the
file values and interpolating energy and derivative values at each of
@ -51,16 +64,53 @@ interpolated table. For a given dihedral angle (phi), the appropriate
coefficients are chosen from this list, and a cubic polynomial is used
to compute the energy and the derivative at this angle.
The following coefficients must be defined for each dihedral type via
the :doc:`dihedral_coeff <dihedral_coeff>` command as in the example
above.
For dihedral style *table* the following coefficients must be defined
for each dihedral type via the :doc:`dihedral_coeff <dihedral_coeff>`
command as in the example above.
* filename
* keyword
The filename specifies a file containing tabulated energy and
derivative values. The keyword specifies a section of the file. The
format of this file is described below.
The filename specifies a file containing tabulated energy and derivative
values. The keyword specifies which section of the file to read. The
format of this file is the same for both dihedral styles and described
below.
For dihedral style *table/cut* the following coefficients must be
defined for each dihedral type via the :doc:`dihedral_coeff
<dihedral_coeff>` command as in the example above.
* style (aat)
* cutoff prefactor
* cutoff angle1
* cutoff angle2
* filename
* keyword
The cutoff dihedral style uses a tabulated dihedral interaction with a
cutoff function:
.. math::
f(\theta) & = K \qquad\qquad\qquad\qquad\qquad\qquad \theta < \theta_1 \\
f(\theta) & = K \left(1-\frac{(\theta - \theta_1)^2}{(\theta_2 - \theta_1)^2}\right) \qquad \theta_1 < \theta < \theta_2
The cutoff specifies an prefactor to the cutoff function. While this
value would ordinarily equal 1 there may be situations where the value
should change.
The cutoff :math:`\theta_1` specifies the angle (in degrees) below which
the dihedral interaction is unmodified, i.e. the cutoff function is 1.
The cutoff function is applied between :math:`\theta_1` and
:math:`\theta_2`, which is the angle at which the cutoff function drops
to zero. The value of zero effectively "turns off" the dihedral
interaction.
The filename specifies a file containing tabulated energy and derivative
values. The keyword specifies which section of the file to read. The
format of this file is the same for both dihedral styles and described
below.
----------
@ -182,18 +232,19 @@ that matches the specified keyword.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This dihedral style writes the settings for the "dihedral_style table"
command to :doc:`binary restart files <restart>`, so a dihedral_style
command does not need to specified in an input script that reads a
restart file. However, the coefficient information is not stored in
the restart file, since it is tabulated in the potential files. Thus,
These dihedral styles write the settings for the "dihedral_style table"
or "dihedral_style table/cut" command to :doc:`binary restart files
<restart>`, so a dihedral_style command does not need to specified in an
input script that reads a restart file. However, the coefficient
information loaded from the table file(s) is not stored in the restart
file, since it is tabulated in the potential files. Thus, suitable
dihedral_coeff commands do need to be specified in the restart input
script.
script after reading the restart file.
Restrictions
""""""""""""
This dihedral style can only be used if LAMMPS was built with the
These dihedral styles can only be used if LAMMPS was built with the
USER-MISC package. See the :doc:`Build package <Build_package>` doc
page for more info.

229
doc/src/dihedral_table_cut.rst
View File

@ -1,229 +0,0 @@
.. index:: dihedral_style table/cut
dihedral_style table/cut command
================================
Syntax
""""""
.. code-block:: LAMMPS
dihedral_style table/cut style Ntable
* style = *linear* or *spline* = method of interpolation
* Ntable = size of the internal lookup table
Examples
""""""""
.. code-block:: LAMMPS
dihedral_style table/cut spline 400
dihedral_style table/cut linear 1000
dihedral_coeff 1 aat 1.0 177 180 file.table DIH_TABLE1
dihedral_coeff 2 aat 0.5 170 180 file.table DIH_TABLE2
Description
"""""""""""
The *table/cut* dihedral style creates interpolation tables of length
*Ntable* from dihedral potential and derivative values listed in a
file(s) as a function of the dihedral angle "phi". In addition, an
analytic cutoff that is quadratic in the bond-angle (theta) is applied
in order to regularize the dihedral interaction. The dihedral table
files are read by the :doc:`dihedral_coeff <dihedral_coeff>` command.
The interpolation tables are created by fitting cubic splines to the
file values and interpolating energy and derivative values at each of
*Ntable* dihedral angles. During a simulation, these tables are used
to interpolate energy and force values on individual atoms as
needed. The interpolation is done in one of 2 styles: *linear* or
*spline*\ .
For the *linear* style, the dihedral angle (phi) is used to find 2
surrounding table values from which an energy or its derivative is
computed by linear interpolation.
For the *spline* style, cubic spline coefficients are computed and
stored at each of the *Ntable* evenly-spaced values in the
interpolated table. For a given dihedral angle (phi), the appropriate
coefficients are chosen from this list, and a cubic polynomial is used
to compute the energy and the derivative at this angle.
The following coefficients must be defined for each dihedral type via
the :doc:`dihedral_coeff <dihedral_coeff>` command as in the example
above.
* style (aat)
* cutoff prefactor
* cutoff angle1
* cutoff angle2
* filename
* keyword
The cutoff dihedral style uses a tabulated dihedral interaction with a
cutoff function:
.. math::
f(\theta) & = K \qquad\qquad\qquad\qquad\qquad\qquad \theta < \theta_1 \\
f(\theta) & = K \left(1-\frac{(\theta - \theta_1)^2}{(\theta_2 - \theta_1)^2}\right) \qquad \theta_1 < \theta < \theta_2
The cutoff specifies an prefactor to the cutoff function. While this value
would ordinarily equal 1 there may be situations where the value should change.
The cutoff :math:`\theta_1` specifies the angle (in degrees) below which the dihedral
interaction is unmodified, i.e. the cutoff function is 1.
The cutoff function is applied between :math:`\theta_1` and :math:`\theta_2`, which is
the angle at which the cutoff function drops to zero. The value of zero effectively
"turns off" the dihedral interaction.
The filename specifies a file containing tabulated energy and
derivative values. The keyword specifies a section of the file. The
format of this file is described below.
----------
The format of a tabulated file is as follows (without the
parenthesized comments). It can begin with one or more comment
or blank lines.
.. parsed-literal::
# Table of the potential and its negative derivative
DIH_TABLE1 (keyword is the first text on line)
N 30 DEGREES (N, NOF, DEGREES, RADIANS, CHECKU/F)
(blank line)
1 -168.0 -1.40351172223 0.0423346818422
2 -156.0 -1.70447981034 0.00811786522531
3 -144.0 -1.62956100432 -0.0184129719987
...
30 180.0 -0.707106781187 0.0719306095245
# Example 2: table of the potential. Forces omitted
DIH_TABLE2
N 30 NOF CHECKU testU.dat CHECKF testF.dat
1 -168.0 -1.40351172223
2 -156.0 -1.70447981034
3 -144.0 -1.62956100432
...
30 180.0 -0.707106781187
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 line can contain additional text, but the
initial text must match the argument specified in the
:doc:`dihedral_coeff <dihedral_coeff>` command. 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.
Following a blank line, the next N lines list the tabulated values. On
each line, the first value is the index from 1 to N, the second value is
the angle value, the third value is the energy (in energy units), and
the fourth is -dE/d(phi) also in energy units). The third term is the
energy of the 4-atom configuration for the specified angle. The fourth
term (when present) is the negative derivative of the energy with
respect to the angle (in degrees, or radians depending on whether the
user selected DEGREES or RADIANS). Thus the units of the last term
are still energy, not force. The dihedral angle values must increase
from one line to the next.
Dihedral table splines are cyclic. There is no discontinuity at 180
degrees (or at any other angle). Although in the examples above, the
angles range from -180 to 180 degrees, in general, the first angle in
the list can have any value (positive, zero, or negative). However
the *range* of angles represented in the table must be *strictly* less
than 360 degrees (2pi radians) to avoid angle overlap. (You may not
supply entries in the table for both 180 and -180, for example.) If
the user's table covers only a narrow range of dihedral angles,
strange numerical behavior can occur in the large remaining gap.
**Parameters:**
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 :doc:`dihedral_style table <dihedral_style>` command.
Let *Ntable* is the number of table entries requested dihedral_style
command, and let *Nfile* be the parameter following "N" in the
tabulated file ("30" in the sparse example above). 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 (which are evenly spaced over a 360 degree range, even if the
angles in the file are not). The resulting tables of length *Ntable*
are then used as described above, when computing energy and force for
individual dihedral angles and their atoms. This means that if you
want the interpolation tables of length *Ntable* to match exactly what
is in the tabulated file (with effectively nopreliminary
interpolation), you should set *Ntable* = *Nfile*\ . To insure the
nodal points in the user's file are aligned with the interpolated
table entries, the angles in the table should be integer multiples of
360/\ *Ntable* degrees, or 2\*PI/\ *Ntable* radians (depending on your
choice of angle units).
The optional "NOF" keyword allows the user to omit the forces
(negative energy derivatives) from the table file (normally located in
the fourth column). In their place, forces will be calculated
automatically by differentiating the potential energy function
indicated by the third column of the table (using either linear or
spline interpolation).
The optional "DEGREES" keyword allows the user to specify angles in
degrees instead of radians (default).
The optional "RADIANS" keyword allows the user to specify angles in
radians instead of degrees. (Note: This changes the way the forces
are scaled in the fourth column of the data file.)
The optional "CHECKU" keyword is followed by a filename. This allows
the user to save all of the *Ntable* different entries in the
interpolated energy table to a file to make sure that the interpolated
function agrees with the user's expectations. (Note: You can
temporarily increase the *Ntable* parameter to a high value for this
purpose. "\ *Ntable*\ " is explained above.)
The optional "CHECKF" keyword is analogous to the "CHECKU" keyword.
It is followed by a filename, and it allows the user to check the
interpolated force table. This option is available even if the user
selected the "NOF" option.
Note that one 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.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This dihedral style writes the settings for the "dihedral_style table/cut"
command to :doc:`binary restart files <restart>`, so a dihedral_style
command does not need to specified in an input script that reads a
restart file. However, the coefficient information is not stored in
the restart file, since it is tabulated in the potential files. Thus,
dihedral_coeff commands do need to be specified in the restart input
script.
Restrictions
""""""""""""
This dihedral style can only be used if LAMMPS was built with the
USER-MISC package. See the :doc:`Build package <Build_package>` doc
page for more info.
Related commands
""""""""""""""""
:doc:`dihedral_coeff <dihedral_coeff>`, :doc:`dihedral_style table <dihedral_table>`
Default
"""""""
none
.. _dihedralcut-Salerno:
**(Salerno)** Salerno, Bernstein, J Chem Theory Comput, --, ---- (2018).

2
doc/src/dump.rst
View File

@ -349,7 +349,7 @@ the box size stored with the snapshot.
The *xtc* style writes XTC files, a compressed trajectory format used
by the GROMACS molecular dynamics package, and described
`here <http://manual.gromacs.org/current/online/xtc.html>`_.
`here <https://manual.gromacs.org/current/reference-manual/file-formats.html#xtc>`_.
The precision used in XTC files can be adjusted via the
:doc:`dump_modify <dump_modify>` command. The default value of 1000
means that coordinates are stored to 1/1000 nanometer accuracy. XTC

8
doc/src/dump_modify.rst
View File

@ -308,9 +308,9 @@ performed with dump style *xtc*\ .
----------
The *format* keyword can be used to change the default numeric format
output by the text-based dump styles: *atom*\ , *custom*\ , *cfg*\ , and
*xyz* styles, and their MPIIO variants. Only the *line* or *none*
The *format* keyword can be used to change the default numeric format output
by the text-based dump styles: *atom*\ , *local*\ , *custom*\ , *cfg*\ , and
*xyz* styles, and their MPIIO variants. Only the *line* or *none*
options can be used with the *atom* and *xyz* styles.
All the specified format strings are C-style formats, e.g. as used by
@ -362,7 +362,7 @@ settings, reverting all values to their default format.
compute 1 all property/local batom1 batom2
dump 1 all local 100 tmp.bonds index c_1[1] c_1[2]
dump_modify 1 format "%d %0.0f %0.0f"
dump_modify 1 format line "%d %0.0f %0.0f"
will output the two atom IDs for atoms in each bond as integers. If
the dump_modify command were omitted, they would appear as

1
doc/src/fix.rst
View File

@ -189,6 +189,7 @@ accelerated styles exist.
* :doc:`bond/react <fix_bond_react>` - apply topology changes to model reactions
* :doc:`bond/swap <fix_bond_swap>` - Monte Carlo bond swapping
* :doc:`box/relax <fix_box_relax>` - relax box size during energy minimization
* :doc:`charge/regulation <fix_charge_regulation>` - Monte Carlo sampling of charge regulation
* :doc:`client/md <fix_client_md>` - MD client for client/server simulations
* :doc:`cmap <fix_cmap>` - enables CMAP cross-terms of the CHARMM force field
* :doc:`colvars <fix_colvars>` - interface to the collective variables "Colvars" library

4
doc/src/fix_ave_chunk.rst
View File

@ -307,7 +307,9 @@ atoms in the chunk. The averaged output value for the chunk on the
average over atoms across the entire *Nfreq* timescale. For the
*density/number* and *density/mass* values, the volume (bin volume or
system volume) used in the final normalization will be the volume at
the final *Nfreq* timestep.
the final *Nfreq* timestep. For the *temp* values, degrees of freedom and
kinetic energy are summed separately across the entire *Nfreq* timescale, and
the output value is calculated by dividing those two sums.
If the *norm* setting is *sample*\ , the chunk value is summed over
atoms for each sample, as is the count, and an "average sample value"

4
doc/src/fix_ave_histo.rst
View File

@ -138,8 +138,8 @@ vector or columns of the array had been listed one by one. E.g. these
.. code-block:: LAMMPS
compute myCOM all com/chunk
fix 1 all ave/histo 100 1 100 c_myCOM[*] file tmp1.com mode vector
fix 2 all ave/histo 100 1 100 c_myCOM[1] c_myCOM[2] c_myCOM[3] file tmp2.com mode vector
fix 1 all ave/histo 100 1 100 -10.0 10.0 100 c_myCOM[*] file tmp1.com mode vector
fix 2 all ave/histo 100 1 100 -10.0 10.0 100 c_myCOM[1] c_myCOM[2] c_myCOM[3] file tmp2.com mode vector
If the fix ave/histo/weight command is used, exactly two values must
be specified. If the values are vectors, they must be the same

2
doc/src/fix_balance.rst
View File

@ -216,7 +216,7 @@ above. It changes the positions of cutting planes between processors
in an iterative fashion, seeking to reduce the imbalance factor.
The *dimstr* argument is a string of characters, each of which must be
an "x" or "y" or "z". Eacn character can appear zero or one time,
an "x" or "y" or "z". Each character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.

276
doc/src/fix_charge_regulation.rst Normal file
View File

@ -0,0 +1,276 @@
.. index:: fix charge/regulation
fix charge/regulation command
=============================
Syntax
""""""
.. parsed-literal::
fix ID group-ID charge/regulation cation_type anion_type keyword value(s)
* ID, group-ID are documented in fix command
* charge/regulation = style name of this fix command
* cation_type = atom type of free cations
* anion_type = atom type of free anions
* zero or more keyword/value pairs may be appended
.. parsed-literal::
keyword = *pH*, *pKa*, *pKb*, *pIp*, *pIm*, *pKs*, *acid_type*, *base_type*, *lunit_nm*, *temp*, *tempfixid*, *nevery*, *nmc*, *xrd*, *seed*, *tag*, *group*, *onlysalt*, *pmcmoves*
*pH* value = pH of the solution
*pKa* value = acid dissociation constant
*pKb* value = base dissociation constant
*pIp* value = chemical potential of free cations
*pIm* value = chemical potential of free anions
*pKs* value = solution self-dissociation constant
*acid_type* = atom type of acid groups
*base_type* = atom type of base groups
*lunit_nm* value = unit length used by LAMMPS (# in the units of nanometers)
*temp* value = temperature
*tempfixid* value = fix ID of temperature thermostat
*nevery* value = invoke this fix every nevery steps
*nmc* value = number of charge regulation MC moves to attempt every nevery steps
*xrd* value = cutoff distance for acid/base reaction
*seed* value = random # seed (positive integer)
*tag* value = yes or no (yes: The code assign unique tags to inserted ions; no: The tag of all inserted ions is "0")
*group* value = group-ID, inserted ions are assigned to group group-ID. Can be used multiple times to assign inserted ions to multiple groups.
*onlysalt* values = flag charge_cation charge_anion.
flag = yes or no (yes: the fix performs only ion insertion/deletion, no: perform acid/base dissociation and ion insertion/deletion)
charge_cation, charge_anion = value of cation/anion charge, must be an integer (only specify if flag = yes)
*pmcmoves* values = pmcA pmcB pmcI - MC move fractions for acid ionization (pmcA), base ionization (pmcB) and free ion exchange (pmcI)
Examples
""""""""
.. code-block:: LAMMPS
fix chareg all charge/regulation 1 2 acid_type 3 base_type 4 pKa 5 pKb 7 lb 1.0 nevery 200 nexchange 200 seed 123 tempfixid fT
fix chareg all charge/regulation 1 2 pIp 3 pIm 3 onlysalt yes 2 -1 seed 123 tag yes temp 1.0
Description
"""""""""""
This fix performs Monte Carlo (MC) sampling of charge regulation and
exchange of ions with a reservoir as discussed in :ref:`(Curk1) <Curk1>`
and :ref:`(Curk2) <Curk2>`. The implemented method is largely analogous
to the grand-reaction ensemble method in :ref:`(Landsgesell)
<Landsgesell>`. The implementation is parallelized, compatible with
existing LAMMPS functionalities, and applicable to any system utilizing
discrete, ionizable groups or surface sites.
Specifically, the fix implements the following three types of MC moves,
which discretely change the charge state of individual particles and
insert ions into the systems: :math:`\mathrm{A} \rightleftharpoons
\mathrm{A}^-+\mathrm{X}^+`, :math:`\mathrm{B} \rightleftharpoons
\mathrm{B}^++\mathrm{X}^-`, and :math:`\emptyset \rightleftharpoons
Z^-\mathrm{X}^{Z^+}+Z^+\mathrm{X}^{-Z^-}`. In the former two types of
reactions, Monte Carlo moves alter the charge value of specific atoms
(:math:`\mathrm{A}`, :math:`\mathrm{B}`) and simultaneously insert a
counterion to preserve the charge neutrality of the system, modeling the
dissociation/association process. The last type of reaction performs
grand canonical MC exchange of ion pairs with a (fictitious) reservoir.
In our implementation "acid" refers to particles that can attain charge
:math:`q=\{0,-1\}` and "base" to particles with :math:`q=\{0,1\}`,
whereas the MC exchange of free ions allows any integer charge values of
:math:`{Z^+}` and :math:`{Z^-}`.
Here we provide several practical examples for modeling charge
regulation effects in solvated systems. An acid ionization reaction
(:math:`\mathrm{A} \rightleftharpoons \mathrm{A}^-+\mathrm{H}^+`) can be
defined via a single line in the input file
.. code-block:: LAMMPS
fix acid_reaction all charge/regulation 2 3 acid_type 1 pH 7.0 pKa 5.0 pIp 7.0 pIm 7.0
where the fix attempts to charge :math:`\mathrm{A}` (discharge
:math:`\mathrm{A}^-`) to :math:`\mathrm{A}^-` (:math:`\mathrm{A}`) and
insert (delete) a proton (atom type 2). Besides, the fix implements
self-ionization reaction of water :math:`\emptyset \rightleftharpoons
\mathrm{H}^++\mathrm{OH}^-`. However, this approach is highly
inefficient at :math:`\mathrm{pH} \approx 7` when the concentration of
both protons and hydroxyl ions is low, resulting in a relatively low
acceptance rate of MC moves.
A more efficient way is to allow salt ions to participate in ionization
reactions, which can be easily achieved via
.. code-block:: LAMMPS
fix acid_reaction all charge/regulation 4 5 acid_type 1 pH 7.0 pKa 5.0 pIp 2.0 pIm 2.0
where particles of atom type 4 and 5 are the salt cations and anions,
both at chemical potential pI=2.0, see :ref:`(Curk1) <Curk1>` and
:ref:`(Landsgesell) <Landsgesell>` for more details.
Similarly, we could have simultaneously added a base ionization reaction
(:math:`\mathrm{B} \rightleftharpoons \mathrm{B}^++\mathrm{OH}^-`)
.. code-block:: LAMMPS
fix base_reaction all charge/regulation 2 3 base_type 6 pH 7.0 pKb 6.0 pIp 7.0 pIm 7.0
where the fix will attempt to charge :math:`\mathrm{B}` (discharge
:math:`\mathrm{B}^+`) to :math:`\mathrm{B}^+` (:math:`\mathrm{B}`) and
insert (delete) a hydroxyl ion :math:`\mathrm{OH}^-` of atom type 3. If
neither the acid or the base type is specified, for example,
.. code-block:: LAMMPS
fix salt_reaction all charge/regulation 4 5 pIp 2.0 pIm 2.0
the fix simply inserts or deletes an ion pair of a free cation (atom
type 4) and a free anion (atom type 5) as done in a conventional
grand-canonical MC simulation.
The fix is compatible with LAMMPS sub-packages such as *molecule* or
*rigid*. That said, the acid and base particles can be part of larger
molecules or rigid bodies. Free ions that are inserted to or deleted
from the system must be defined as single particles (no bonded
interactions allowed) and cannot be part of larger molecules or rigid
bodies. If *molecule* package is used, all inserted ions have a molecule
ID equal to zero.
Note that LAMMPS implicitly assumes a constant number of particles
(degrees of freedom). Since using this fix alters the total number of
particles during the simulation, any thermostat used by LAMMPS, such as
NVT or Langevin, must use a dynamic calculation of system
temperature. This can be achieved by specifying a dynamic temperature
compute (e.g. dtemp) and using it with the desired thermostat, e.g. a
Langevin thermostat:
.. code-block:: LAMMPS
compute dtemp all temp
compute_modify dtemp dynamic yes
fix fT all langevin 1.0 1.0 1.0 123
fix_modify fT temp dtemp
The chemical potential units (e.g. pH) are in the standard log10
representation assuming reference concentration :math:`\rho_0 =
\mathrm{mol}/\mathrm{l}`. Therefore, to perform the internal unit
conversion, the length (in nanometers) of the LAMMPS unit length must be
specified via *lunit_nm* (default is set to the Bjerrum length in water
at room temperature *lunit_nm* = 0.71nm). For example, in the dilute
ideal solution limit, the concentration of free ions will be
:math:`c_\mathrm{I} = 10^{-\mathrm{pIp}}\mathrm{mol}/\mathrm{l}`.
The temperature used in MC acceptance probability is set by *temp*. This
temperature should be the same as the temperature set by the molecular
dynamics thermostat. For most purposes, it is probably best to use
*tempfixid* keyword which dynamically sets the temperature equal to the
chosen MD thermostat temperature, in the example above we assumed the
thermostat fix-ID is *fT*. The inserted particles attain a random
velocity corresponding to the specified temperature. Using *tempfixid*
overrides any fixed temperature set by *temp*.
The *xrd* keyword can be used to restrict the inserted/deleted
counterions to a specific radial distance from an acid or base particle
that is currently participating in a reaction. This can be used to
simulate more realist reaction dynamics. If *xrd* = 0 or *xrd* > *L* /
2, where *L* is the smallest box dimension, the radial restriction is
automatically turned off and free ion can be inserted or deleted
anywhere in the simulation box.
If the *tag yes* is used, every inserted atom gets a unique tag ID,
otherwise, the tag of every inserted atom is set to 0. *tag yes* might
cause an integer overflow in very long simulations since the tags are
unique to every particle and thus increase with every successful
particle insertion.
The *pmcmoves* keyword sets the relative probability of attempting the
three types of MC moves (reactions): acid charging, base charging, and
ion pair exchange. The fix only attempts to perform particle charging
MC moves if *acid_type* or *base_type* is defined. Otherwise fix only
performs free ion insertion/deletion. For example, if *acid_type* is not
defined, *pmcA* is automatically set to 0. The vector *pmcmoves* is
automatically normalized, for example, if set to *pmcmoves* 0 0.33 0.33,
the vector would be normalized to [0,0.5,0.5].
The *only_salt* option can be used to perform multivalent
grand-canonical ion-exchange moves. If *only_salt yes* is used, no
charge exchange is performed, only ion insertion/deletion (*pmcmoves* is
set to [0,0,1]), but ions can be multivalent. In the example above, an
MC move would consist of three ion insertion/deletion to preserve the
charge neutrality of the system.
The *group* keyword can be used to add inserted particles to a specific
group-ID. All inserted particles are automatically added to group *all*.
Output
""""""
This fix computes a global vector of length 8, which can be accessed by
various output commands. The vector values are the following global
quantities:
* 1 = cumulative MC attempts
* 2 = cumulative MC successes
* 3 = current # of neutral acid atoms
* 4 = current # of -1 charged acid atoms
* 5 = current # of neutral base atoms
* 6 = current # of +1 charged base atoms
* 7 = current # of free cations
* 8 = current # of free anions
Restrictions
""""""""""""
This fix is part of the MC package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
The :doc:`atom_style <atom_style>`, used must contain the charge
property, for example, the style could be *charge* or *full*. Only
usable for 3D simulations. Atoms specified as free ions cannot be part
of rigid bodies or molecules and cannot have bonding interactions. The
scheme is limited to integer charges, any atoms with non-integer charges
will not be considered by the fix.
All interaction potentials used must be continuous, otherwise the MD
integration and the particle exchange MC moves do not correspond to the
same equilibrium ensemble. For example, if an lj/cut pair style is used,
the LJ potential must be shifted so that it vanishes at the cutoff. This
can be easily achieved using the :doc:`pair_modify <pair_modify>`
command, i.e., by using: *pair_modify shift yes*.
.. note::
Region restrictions are not yet implemented.
Related commands
""""""""""""""""
:doc:`fix gcmc <fix_gcmc>`,
:doc:`fix atom/swap <fix_atom_swap>`
Default
"""""""
pH = 7.0; pKa = 100.0; pKb = 100.0; pIp = 5.0; pIm = 5.0; pKs = 14.0;
acid_type = -1; base_type = -1; lunit_nm = 0.71; temp = 1.0; nevery =
100; nmc = 100; xrd = 0; seed = 0; tag = no; onlysalt = no, pmcmoves =
[1/3, 1/3, 1/3], group-ID = all
----------
.. _Curk1:
**(Curk1)** T. Curk, J. Yuan, and E. Luijten, "Coarse-grained simulation of charge regulation using LAMMPS", preprint (2021).
.. _Curk2:
**(Curk2)** T. Curk and E. Luijten, "Charge-regulation effects in nanoparticle self-assembly", PRL (2021)
.. _Landsgesell:
**(Landsgesell)** J. Landsgesell, P. Hebbeker, O. Rud, R. Lunkad, P. Kosovan, and C. Holm, "Grand-reaction method for simulations of ionization equilibria coupled to ion partitioning", Macromolecules 53, 3007-3020 (2020).

5
doc/src/fix_cmap.rst
View File

@ -127,6 +127,11 @@ the :doc:`run <run>` command.
The forces due to this fix are imposed during an energy minimization,
invoked by the :doc:`minimize <minimize>` command.
The :doc:`fix_modify <fix_modify>` *respa* option is supported by this
fix. This allows to set at which level of the :doc:`r-RESPA
<run_style>` integrator the fix is adding its forces. Default is the
outermost level.
.. note::
If you want the potential energy associated with the CMAP terms

12
doc/src/fix_halt.rst
View File

@ -115,6 +115,18 @@ The version with "bondmax" will just run somewhat faster, due to less
overhead in computing bond lengths and not storing them in a separate
compute.
A variable can be used to implement a large variety of conditions,
including to stop when a specific file exists. Example:
.. code-block:: LAMMPS
variable exit equal is_file(EXIT)
fix 10 all halt 100 v_exit != 0 error soft
Will stop the current run command when a file ``EXIT`` is created
in the current working directory. The condition can be cleared
by removing the file through the :doc:`shell <shell>` command.
The choice of operators listed above are the usual comparison
operators. The XOR operation (exclusive or) is also included as "\|\^".
In this context, XOR means that if either the attribute or avalue is

34
doc/src/fix_precession_spin.rst
View File

@ -12,7 +12,7 @@ Syntax
* ID, group are documented in :doc:`fix <fix>` command
* precession/spin = style name of this fix command
* style = *zeeman* or *anisotropy* or *cubic*
* style = *zeeman* or *anisotropy* or *cubic* or *stt*
.. parsed-literal::
@ -22,12 +22,12 @@ Syntax
*anisotropy* args = K x y z
K = intensity of the magnetic anisotropy (in eV)
x y z = vector direction of the anisotropy
.. parsed-literal::
*cubic* args = K1 K2c n1x n1y n1x n2x n2y n2z n3x n3y n3z
K1 and K2c = intensity of the magnetic anisotropy (in eV)
n1x to n3z = three direction vectors of the cubic anisotropy
*stt* args = J x y z
J = intensity of the spin-transfer torque field
x y z = vector direction of the field
Examples
""""""""
@ -125,6 +125,11 @@ axis along the :math:`(1 1 1)`-type cube diagonals). :math:`K_2^c >
diagonals. See chapter 2 of :ref:`(Skomski) <Skomski1>` for more
details on cubic anisotropies.
Style *stt* is used to simulate the interaction between the spins and
a spin-transfer torque.
See equation (7) of :ref:`(Chirac) <Chirac1>` for more details about the
implemented spin-transfer torque term.
In all cases, the choice of :math:`(x y z)` only imposes the vector
directions for the forces. Only the direction of the vector is
important; its length is ignored (the entered vectors are
@ -132,6 +137,16 @@ normalized).
Those styles can be combined within one single command line.
.. note::
The norm of all vectors defined with the precession/spin command
have to be non-zero. For example, defining
"fix 1 all precession/spin zeeman 0.1 0.0 0.0 0.0" would result
in an error message.
Since those vector components are used to compute the inverse of the
field (or anisotropy) vector norm, setting a zero-vector would result
in a division by zero.
----------
Restart, fix_modify, output, run start/stop, minimize info
@ -162,11 +177,6 @@ is only enabled if LAMMPS was built with this package, and if the
atom_style "spin" was declared. See the :doc:`Build package
<Build_package>` doc page for more info.
The *precession/spin* style can only be declared once. If more than
one precession type (for example combining an anisotropy and a Zeeman
interactions) has to be declared, they have to be chained in the same
command line (as shown in the examples above).
Related commands
""""""""""""""""
@ -184,3 +194,9 @@ none
**(Skomski)** Skomski, R. (2008). Simple models of magnetism.
Oxford University Press.
.. _Chirac1:
**(Chirac)** Chirac, Théophile, et al. Ultrafast antiferromagnetic
switching in NiO induced by spin transfer torques.
Physical Review B 102.13 (2020): 134415.

125
doc/src/fix_qeq.rst
View File

@ -56,27 +56,28 @@ Examples
Description
"""""""""""
Perform the charge equilibration (QEq) method as described in :ref:`(Rappe and Goddard) <Rappe1>` and formulated in :ref:`(Nakano) <Nakano1>` (also known
as the matrix inversion method) and in :ref:`(Rick and Stuart) <Rick1>` (also
known as the extended Lagrangian method) based on the
electronegativity equilization principle.
Perform the charge equilibration (QEq) method as described in
:ref:`(Rappe and Goddard) <Rappe1>` and formulated in :ref:`(Nakano)
<Nakano1>` (also known as the matrix inversion method) and in
:ref:`(Rick and Stuart) <Rick1>` (also known as the extended Lagrangian
method) based on the electronegativity equilization principle.
These fixes can be used with any :doc:`pair style <pair_style>` in
LAMMPS, so long as per-atom charges are defined. The most typical
use-case is in conjunction with a :doc:`pair style <pair_style>` that
performs charge equilibration periodically (e.g. every timestep), such
as the ReaxFF or Streitz-Mintmire potential.
But these fixes can also be used with
potentials that normally assume per-atom charges are fixed, e.g. a
:doc:`Buckingham <pair_buck>` or :doc:`LJ/Coulombic <pair_lj>` potential.
as the ReaxFF or Streitz-Mintmire potential. But these fixes can also
be used with potentials that normally assume per-atom charges are fixed,
e.g. a :doc:`Buckingham <pair_buck>` or :doc:`LJ/Coulombic <pair_lj>`
potential.
Because the charge equilibration calculation is effectively
independent of the pair style, these fixes can also be used to perform
a one-time assignment of charges to atoms. For example, you could
define the QEq fix, perform a zero-timestep run via the :doc:`run <run>`
command without any pair style defined which would set per-atom
charges (based on the current atom configuration), then remove the fix
via the :doc:`unfix <unfix>` command before performing further dynamics.
Because the charge equilibration calculation is effectively independent
of the pair style, these fixes can also be used to perform a one-time
assignment of charges to atoms. For example, you could define the QEq
fix, perform a zero-timestep run via the :doc:`run <run>` command
without any pair style defined which would set per-atom charges (based
on the current atom configuration), then remove the fix via the
:doc:`unfix <unfix>` command before performing further dynamics.
.. note::
@ -87,11 +88,14 @@ via the :doc:`unfix <unfix>` command before performing further dynamics.
.. note::
The :doc:`fix qeq/comb <fix_qeq_comb>` command must still be used
to perform charge equilibration with the :doc:`COMB potential <pair_comb>`. The :doc:`fix qeq/reax <fix_qeq_reax>`
command can be used to perform charge equilibration with the :doc:`ReaxFF force field <pair_reaxc>`, although fix qeq/shielded yields the
same results as fix qeq/reax if *Nevery*\ , *cutoff*\ , and *tolerance*
are the same. Eventually the fix qeq/reax command will be deprecated.
The :doc:`fix qeq/comb <fix_qeq_comb>` command must still be used to
perform charge equilibration with the :doc:`COMB potential
<pair_comb>`. The :doc:`fix qeq/reax <fix_qeq_reax>` command can be
used to perform charge equilibration with the :doc:`ReaxFF force
field <pair_reaxc>`, although fix qeq/shielded yields the same
results as fix qeq/reax if *Nevery*\ , *cutoff*\ , and *tolerance*
are the same. Eventually the fix qeq/reax command will be
deprecated.
The QEq method minimizes the electrostatic energy of the system (or
equalizes the derivative of energy with respect to charge of all the
@ -134,55 +138,57 @@ usually a good number.
The *qeq/shielded* style describes partial charges on atoms also as
point charges, but uses a shielded Coulomb potential to describe the
interaction between a pair of charged particles. Interaction through
the shielded Coulomb is given by equation (13) of the :ref:`ReaxFF force field <vanDuin>` paper. The shielding accounts for charge overlap
the shielded Coulomb is given by equation (13) of the :ref:`ReaxFF force
field <vanDuin>` paper. The shielding accounts for charge overlap
between charged particles at small separation. This style is the same
as :doc:`fix qeq/reax <fix_qeq_reax>`, and can be used with :doc:`pair_style reax/c <pair_reaxc>`. Only the *chi*\ , *eta*\ , and *gamma*
parameters from the *qfile* file are used. When using the string
*reax/c* as filename, these parameters are extracted directly from
an active *reax/c* pair style. This style solves partial
charges on atoms via the matrix inversion method. A tolerance of
1.0e-6 is usually a good number.
as :doc:`fix qeq/reax <fix_qeq_reax>`, and can be used with
:doc:`pair_style reax/c <pair_reaxc>`. Only the *chi*\ , *eta*\ , and
*gamma* parameters from the *qfile* file are used. When using the string
*reax/c* as filename, these parameters are extracted directly from an
active *reax/c* pair style. This style solves partial charges on atoms
via the matrix inversion method. A tolerance of 1.0e-6 is usually a
good number.
The *qeq/slater* style describes partial charges on atoms as spherical
charge densities centered around atoms via the Slater 1\ *s* orbital, so
that the interaction between a pair of charged particles is the
product of two Slater 1\ *s* orbitals. The expression for the Slater
1\ *s* orbital is given under equation (6) of the
:ref:`Streitz-Mintmire <Streitz1>` paper. Only the *chi*\ , *eta*\ , *zeta*\ , and
*qcore* parameters from the *qfile* file are used. When using the string
that the interaction between a pair of charged particles is the product
of two Slater 1\ *s* orbitals. The expression for the Slater 1\ *s*
orbital is given under equation (6) of the :ref:`Streitz-Mintmire
<Streitz1>` paper. Only the *chi*\ , *eta*\ , *zeta*\ , and *qcore*
parameters from the *qfile* file are used. When using the string
*coul/streitz* as filename, these parameters are extracted directly from
an active *coul/streitz* pair style. This style solves
partial charges on atoms via the matrix inversion method. A tolerance
of 1.0e-6 is usually a good number. Keyword *alpha* can be used to
change the Slater type orbital exponent.
an active *coul/streitz* pair style. This style solves partial charges
on atoms via the matrix inversion method. A tolerance of 1.0e-6 is
usually a good number. Keyword *alpha* can be used to change the Slater
type orbital exponent.
The *qeq/dynamic* style describes partial charges on atoms as point
charges that interact through 1/r, but the extended Lagrangian method
is used to solve partial charges on atoms. Only the *chi* and *eta*
charges that interact through 1/r, but the extended Lagrangian method is
used to solve partial charges on atoms. Only the *chi* and *eta*
parameters from the *qfile* file are used. Note that Coulomb
catastrophe can occur if repulsion between the pair of charged
particles is too weak. A tolerance of 1.0e-3 is usually a good
number. Keyword *qdamp* can be used to change the damping factor, while
keyword *qstep* can be used to change the time step size.
catastrophe can occur if repulsion between the pair of charged particles
is too weak. A tolerance of 1.0e-3 is usually a good number. Keyword
*qdamp* can be used to change the damping factor, while keyword *qstep*
can be used to change the time step size.
The :ref:`\ *qeq/fire*\ <Shan>` style describes the same charge model and charge
solver as the *qeq/dynamic* style, but employs a FIRE minimization
algorithm to solve for equilibrium charges.
Keyword *qdamp* can be used to change the damping factor, while
keyword *qstep* can be used to change the time step size.
The :ref:`\ *qeq/fire*\ <Shan>` style describes the same charge model
and charge solver as the *qeq/dynamic* style, but employs a FIRE
minimization algorithm to solve for equilibrium charges. Keyword
*qdamp* can be used to change the damping factor, while keyword *qstep*
can be used to change the time step size.
Note that *qeq/point*\ , *qeq/shielded*\ , and *qeq/slater* describe
different charge models, whereas the matrix inversion method and the
extended Lagrangian method (\ *qeq/dynamic* and *qeq/fire*\ ) are
different solvers.
Note that *qeq/point*\ , *qeq/dynamic* and *qeq/fire* styles all describe
charges as point charges that interact through 1/r relationship, but
solve partial charges on atoms using different solvers. These three
styles should yield comparable results if
the QEq parameters and *Nevery*\ , *cutoff*\ , and *tolerance* are the
same. Style *qeq/point* is typically faster, *qeq/dynamic* scales
better on larger sizes, and *qeq/fire* is faster than *qeq/dynamic*\ .
Note that *qeq/point*\ , *qeq/dynamic* and *qeq/fire* styles all
describe charges as point charges that interact through 1/r
relationship, but solve partial charges on atoms using different
solvers. These three styles should yield comparable results if the QEq
parameters and *Nevery*\ , *cutoff*\ , and *tolerance* are the same.
Style *qeq/point* is typically faster, *qeq/dynamic* scales better on
larger sizes, and *qeq/fire* is faster than *qeq/dynamic*\ .
.. note::
@ -200,9 +206,11 @@ better on larger sizes, and *qeq/fire* is faster than *qeq/dynamic*\ .
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about these fixes is written to :doc:`binary restart files <restart>`. No global scalar or vector or per-atom
quantities are stored by these fixes for access by various :doc:`output commands <Howto_output>`. No parameter of these fixes can be used
with the *start/stop* keywords of the :doc:`run <run>` command.
No information about these fixes is written to :doc:`binary restart
files <restart>`. No global scalar or vector or per-atom quantities are
stored by these fixes for access by various :doc:`output commands
<Howto_output>`. No parameter of these fixes can be used with the
*start/stop* keywords of the :doc:`run <run>` command.
Thexe fixes are invoked during :doc:`energy minimization <minimize>`.
@ -210,7 +218,8 @@ Restrictions
""""""""""""
These fixes are part of the QEQ package. They are only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
Related commands
""""""""""""""""

4
doc/src/fix_wall_gran.rst
View File

@ -29,6 +29,7 @@ Syntax
gamma_t = damping coefficient for collisions in tangential direction (1/time units or 1/time-distance units - see discussion below)
xmu = static yield criterion (unitless value between 0.0 and 1.0e4)
dampflag = 0 or 1 if tangential damping force is excluded or included
optional keyword = *limit_damping*, limit damping to prevent attractive interaction
.. parsed-literal::
@ -95,7 +96,8 @@ Specifically, delta = radius - r = overlap of particle with wall, m_eff
= mass of particle, and the effective radius of contact = RiRj/Ri+Rj is
set to the radius of the particle.
The parameters *Kn*\ , *Kt*\ , *gamma_n*, *gamma_t*, *xmu* and *dampflag*
The parameters *Kn*\ , *Kt*\ , *gamma_n*, *gamma_t*, *xmu*, *dampflag*,
and the optional keyword *limit_damping*
have the same meaning and units as those specified with the
:doc:`pair_style gran/\* <pair_gran>` commands. This means a NULL can be
used for either *Kt* or *gamma_t* as described on that page. If a

3
doc/src/fix_wall_gran_region.rst
View File

@ -181,7 +181,8 @@ radius - r = overlap of particle with wall, m_eff = mass of particle,
and the effective radius of contact is just the radius of the
particle.
The parameters *Kn*\ , *Kt*\ , *gamma_n*, *gamma_t*, *xmu* and *dampflag*
The parameters *Kn*\ , *Kt*\ , *gamma_n*, *gamma_t*, *xmu*, *dampflag*,
and the optional keyword *limit_damping*
have the same meaning and units as those specified with the
:doc:`pair_style gran/\* <pair_gran>` commands. This means a NULL can be
used for either *Kt* or *gamma_t* as described on that page. If a

14
doc/src/pair_coul.rst
View File

@ -10,6 +10,8 @@
.. index:: pair_style coul/dsf/gpu
.. index:: pair_style coul/dsf/kk
.. index:: pair_style coul/dsf/omp
.. index:: pair_style coul/cut/global
.. index:: pair_style coul/cut/global/omp
.. index:: pair_style coul/long
.. index:: pair_style coul/long/omp
.. index:: pair_style coul/long/kk
@ -40,6 +42,11 @@ pair_style coul/dsf command
Accelerator Variants: *coul/dsf/gpu*, *coul/dsf/kk*, *coul/dsf/omp*
pair_style coul/cut/global command
==================================
Accelerator Variants: *coul/cut/omp*
pair_style coul/long command
============================
@ -76,8 +83,8 @@ Syntax
pair_style coul/cut cutoff
pair_style coul/debye kappa cutoff
pair_style coul/dsf alpha cutoff
pair_style coul/cut/global cutoff
pair_style coul/long cutoff
pair_style coul/long/gpu cutoff
pair_style coul/wolf alpha cutoff
pair_style coul/streitz cutoff keyword alpha
pair_style tip4p/cut otype htype btype atype qdist cutoff
@ -245,6 +252,11 @@ Streitz-Mintmire parameterization for the material being modeled.
----------
Pair style *coul/cut/global* computes the same Coulombic interactions
as style *coul/cut* except that it allows only a single global cutoff
and thus makes it compatible for use in combination with long-range
coulomb styles in :doc:`hybrid pair styles <pair_hybrid>`.
Styles *coul/long* and *coul/msm* compute the same Coulombic
interactions as style *coul/cut* except that an additional damping
factor is applied so it can be used in conjunction with the

2
doc/src/pair_dpd.rst
View File

@ -150,7 +150,7 @@ shifted to be 0.0 at the cutoff distance Rc.
The :doc:`pair_modify <pair_modify>` table option is not relevant
for these pair styles.
These pair style do not support the :doc:`pair_modify <pair_modify>`
These pair styles do not support the :doc:`pair_modify <pair_modify>`
tail option for adding long-range tail corrections to energy and
pressure.

2
doc/src/pair_fep_soft.rst
View File

@ -363,7 +363,7 @@ Mixing, shift, table, tail correction, restart, rRESPA info
The different versions of the *lj/cut/soft* pair styles support mixing. For
atom type pairs I,J and I != J, the :math:`\epsilon` and :math:`\sigma`
coefficients and cutoff distance for these pair style can be mixed. The default
coefficients and cutoff distance for these pair styles can be mixed. The default
mix value is *geometric* for 12-6 styles.
The mixing rule for epsilon and sigma for *lj/class2/soft* 9-6 potentials is to

2
doc/src/pair_gayberne.rst
View File

@ -188,7 +188,7 @@ Restrictions
The *gayberne* style is part of the ASPHERE package. It is only
enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
These pair style require that atoms store torque and a quaternion to
These pair styles require that atoms store torque and a quaternion to
represent their orientation, as defined by the
:doc:`atom_style <atom_style>`. It also require they store a per-type
:doc:`shape <set>`. The particles cannot store a per-particle

17
doc/src/pair_gran.rst
View File

@ -26,7 +26,7 @@ Syntax
.. code-block:: LAMMPS
pair_style style Kn Kt gamma_n gamma_t xmu dampflag
pair_style style Kn Kt gamma_n gamma_t xmu dampflag keyword
* style = *gran/hooke* or *gran/hooke/history* or *gran/hertz/history*
* Kn = elastic constant for normal particle repulsion (force/distance units or pressure units - see discussion below)
@ -36,6 +36,13 @@ Syntax
* xmu = static yield criterion (unitless value between 0.0 and 1.0e4)
* dampflag = 0 or 1 if tangential damping force is excluded or included
* keyword = *limit_damping*
.. parsed-literal::
*limit_damping* value = none
limit damping to prevent attractive interaction
.. note::
Versions of LAMMPS before 9Jan09 had different style names for
@ -54,6 +61,8 @@ Examples
pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 1
pair_style gran/hooke 200000.0 70000.0 50.0 30.0 0.5 0
pair_style gran/hooke 200000.0 70000.0 50.0 30.0 0.5 0 limit_damping
Description
"""""""""""
@ -208,6 +217,12 @@ potential is used as a sub-style of :doc:`pair_style hybrid <pair_hybrid>`, then
pair_coeff command to determine which atoms interact via a granular
potential.
If two particles are moving away from each other while in contact, there
is a possibility that the particles could experience an effective attractive
force due to damping. If the *limit_damping* keyword is used, this option
will zero out the normal component of the force if there is an effective
attractive force.
----------
.. include:: accel_styles.rst

16
doc/src/pair_granular.rst
View File

@ -24,7 +24,7 @@ Examples
pair_coeff * * hooke 1000.0 50.0 tangential linear_history 500.0 1.0 0.4 damping mass_velocity
pair_style granular
pair_coeff * * hertz 1000.0 50.0 tangential mindlin 1000.0 1.0 0.4
pair_coeff * * hertz 1000.0 50.0 tangential mindlin 1000.0 1.0 0.4 limit_damping
pair_style granular
pair_coeff * * hertz/material 1e8 0.3 0.3 tangential mindlin_rescale NULL 1.0 0.4 damping tsuji
@ -623,6 +623,14 @@ Finally, the twisting torque on each particle is given by:
----------
If two particles are moving away from each other while in contact, there
is a possibility that the particles could experience an effective attractive
force due to damping. If the optional *limit_damping* keyword is used, this option
will zero out the normal component of the force if there is an effective
attractive force. This keyword cannot be used with the JKR or DMT models.
----------
The *granular* pair style can reproduce the behavior of the
*pair gran/\** styles with the appropriate settings (some very
minor differences can be expected due to corrections in
@ -657,6 +665,12 @@ then LAMMPS will use that cutoff for the specified atom type
combination, and automatically set pairwise cutoffs for the remaining
atom types.
If two particles are moving away from each other while in contact, there
is a possibility that the particles could experience an effective attractive
force due to damping. If the *limit_damping* keyword is used, this option
will zero out the normal component of the force if there is an effective
attractive force. This keyword cannot be used with the JKR or DMT models.
----------
.. include:: accel_styles.rst

250
doc/src/pair_hybrid.rst
View File

@ -2,6 +2,7 @@
.. index:: pair_style hybrid/kk
.. index:: pair_style hybrid/overlay
.. index:: pair_style hybrid/overlay/kk
.. index:: pair_style hybrid/scaled
pair_style hybrid command
=========================
@ -13,6 +14,9 @@ pair_style hybrid/overlay command
Accelerator Variants: *hybrid/overlay/kk*
pair_style hybrid/scaled command
==================================
Syntax
""""""
@ -20,8 +24,10 @@ Syntax
pair_style hybrid style1 args style2 args ...
pair_style hybrid/overlay style1 args style2 args ...
pair_style hybrid/scaled factor1 style1 args factor2 style 2 args ...
* style1,style2 = list of one or more pair styles and their arguments
* factor1,factor2 = scale factors for pair styles, may be a variable
Examples
""""""""
@ -37,47 +43,73 @@ Examples
pair_coeff * * lj/cut 1.0 1.0
pair_coeff * * coul/long
pair_style hybrid/scaled 0.5 tersoff 0.5 sw
pair_coeff * * tersoff Si.tersoff Si
pair_coeff * * sw Si.sw Si
variable one equal ramp(1.0,0.0)
variable two equal 1.0-v_one
pair_style hybrid/scaled v_one lj/cut 2.5 v_two morse 2.5
pair_coeff 1 1 lj/cut 1.0 1.0 2.5
pair_coeff 1 1 morse 1.0 1.0 1.0 2.5
Description
"""""""""""
The *hybrid* and *hybrid/overlay* styles enable the use of multiple
pair styles in one simulation. With the *hybrid* style, exactly one
pair style is assigned to each pair of atom types. With the
*hybrid/overlay* style, one or more pair styles can be assigned to
each pair of atom types. The assignment of pair styles to type pairs
is made via the :doc:`pair_coeff <pair_coeff>` command.
The *hybrid*, *hybrid/overlay*, and *hybrid/scaled* styles enable the
use of multiple pair styles in one simulation. With the *hybrid* style,
exactly one pair style is assigned to each pair of atom types. With the
*hybrid/overlay* and *hybrid/scaled* styles, one or more pair styles can
be assigned to each pair of atom types. The assignment of pair styles
to type pairs is made via the :doc:`pair_coeff <pair_coeff>` command.
The major difference between the *hybrid/overlay* and *hybrid/scaled*
styles is that the *hybrid/scaled* adds a scale factor for each
sub-style contribution to forces, energies and stresses. Because of the
added complexity, the *hybrid/scaled* style has more overhead and thus
may be slower than *hybrid/overlay*.
Here are two examples of hybrid simulations. The *hybrid* style could
be used for a simulation of a metal droplet on a LJ surface. The
metal atoms interact with each other via an *eam* potential, the
surface atoms interact with each other via a *lj/cut* potential, and
the metal/surface interaction is also computed via a *lj/cut*
potential. The *hybrid/overlay* style could be used as in the second
example above, where multiple potentials are superposed in an additive
fashion to compute the interaction between atoms. In this example,
using *lj/cut* and *coul/long* together gives the same result as if
the *lj/cut/coul/long* potential were used by itself. In this case,
it would be more efficient to use the single combined potential, but
in general any combination of pair potentials can be used together in
to produce an interaction that is not encoded in any single pair_style
be used for a simulation of a metal droplet on a LJ surface. The metal
atoms interact with each other via an *eam* potential, the surface atoms
interact with each other via a *lj/cut* potential, and the metal/surface
interaction is also computed via a *lj/cut* potential. The
*hybrid/overlay* style could be used as in the second example above,
where multiple potentials are superposed in an additive fashion to
compute the interaction between atoms. In this example, using *lj/cut*
and *coul/long* together gives the same result as if the
*lj/cut/coul/long* potential were used by itself. In this case, it
would be more efficient to use the single combined potential, but in
general any combination of pair potentials can be used together in to
produce an interaction that is not encoded in any single pair_style
file, e.g. adding Coulombic forces between granular particles.
If the *hybrid/scaled* style is used instead of *hybrid/overlay*\ ,
contributions from sub-styles are weighted by their scale factors, which
may be fractional or even negative. Furthermore the scale factors may
be variables that may change during a simulation. This enables
switching smoothly between two different pair styles or two different
parameter sets during a run.
All pair styles that will be used are listed as "sub-styles" following
the *hybrid* or *hybrid/overlay* keyword, in any order. Each
sub-style's name is followed by its usual arguments, as illustrated in
the example above. See the doc pages of individual pair styles for a
listing and explanation of the appropriate arguments.
the *hybrid* or *hybrid/overlay* keyword, in any order. In case of the
*hybrid/scaled* pair style, each sub-style is prefixed with a scale
factor. The scale factor is either a floating point number or an equal
style (or equivalent) variable. Each sub-style's name is followed by
its usual arguments, as illustrated in the examples above. See the doc
pages of the individual pair styles for a listing and explanation of the
appropriate arguments for them.
Note that an individual pair style can be used multiple times as a
sub-style. For efficiency this should only be done if your model
requires it. E.g. if you have different regions of Si and C atoms and
wish to use a Tersoff potential for pure Si for one set of atoms, and
a Tersoff potential for pure C for the other set (presumably with some
third potential for Si-C interactions), then the sub-style *tersoff*
could be listed twice. But if you just want to use a Lennard-Jones or
other pairwise potential for several different atom type pairs in your
model, then you should just list the sub-style once and use the
pair_coeff command to assign parameters for the different type pairs.
sub-style. For efficiency reasons this should only be done if your
model requires it. E.g. if you have different regions of Si and C atoms
and wish to use a Tersoff potential for pure Si for one set of atoms,
and a Tersoff potential for pure C for the other set (presumably with
some third potential for Si-C interactions), then the sub-style
*tersoff* could be listed twice. But if you just want to use a
Lennard-Jones or other pairwise potential for several different atom
type pairs in your model, then you should just list the sub-style once
and use the pair_coeff command to assign parameters for the different
type pairs.
.. note::
@ -143,16 +175,16 @@ one sub-style. Just as with a simulation using a single pair style,
if you specify the same atom type pair in a second pair_coeff command,
the previous assignment will be overwritten.
For the *hybrid/overlay* style, each atom type pair I,J can be
assigned to one or more sub-styles. If you specify the same atom type
pair in a second pair_coeff command with a new sub-style, then the
second sub-style is added to the list of potentials that will be
calculated for two interacting atoms of those types. If you specify
the same atom type pair in a second pair_coeff command with a
sub-style that has already been defined for that pair of atoms, then
the new pair coefficients simply override the previous ones, as in the
normal usage of the pair_coeff command. E.g. these two sets of
commands are the same:
For the *hybrid/overlay* and *hybrid/scaled* styles, each atom type pair
I,J can be assigned to one or more sub-styles. If you specify the same
atom type pair in a second pair_coeff command with a new sub-style, then
the second sub-style is added to the list of potentials that will be
calculated for two interacting atoms of those types. If you specify the
same atom type pair in a second pair_coeff command with a sub-style that
has already been defined for that pair of atoms, then the new pair
coefficients simply override the previous ones, as in the normal usage
of the pair_coeff command. E.g. these two sets of commands are the
same:
.. code-block:: LAMMPS
@ -166,42 +198,43 @@ commands are the same:
Coefficients must be defined for each pair of atoms types via the
:doc:`pair_coeff <pair_coeff>` command as described above, or in the
data file or restart files read by the :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` commands, or by mixing as described
below.
data file read by the :doc:`read_data <read_data>` commands, or by
mixing as described below.
For both the *hybrid* and *hybrid/overlay* styles, every atom type
pair I,J (where I <= J) must be assigned to at least one sub-style via
the :doc:`pair_coeff <pair_coeff>` command as in the examples above, or
in the data file read by the :doc:`read_data <read_data>`, or by mixing
as described below.
For all of the *hybrid*, *hybrid/overlay*, and *hybrid/scaled* styles,
every atom type pair I,J (where I <= J) must be assigned to at least one
sub-style via the :doc:`pair_coeff <pair_coeff>` command as in the
examples above, or in the data file read by the :doc:`read_data
<read_data>`, or by mixing as described below. Also all sub-styles
must be used at least once in a :doc:`pair_coeff <pair_coeff>` command.
If you want there to be no interactions between a particular pair of
atom types, you have 3 choices. You can assign the type pair to some
sub-style and use the :doc:`neigh_modify exclude type <neigh_modify>`
command. You can assign it to some sub-style and set the coefficients
so that there is effectively no interaction (e.g. epsilon = 0.0 in a
LJ potential). Or, for *hybrid* and *hybrid/overlay* simulations, you
can use this form of the pair_coeff command in your input script:
so that there is effectively no interaction (e.g. epsilon = 0.0 in a LJ
potential). Or, for *hybrid*, *hybrid/overlay*, or *hybrid/scaled*
simulations, you can use this form of the pair_coeff command in your
input script:
.. code-block:: LAMMPS
pair_coeff 2 3 none
pair_coeff 2 3 none
or this form in the "Pair Coeffs" section of the data file:
.. parsed-literal::
3 none
3 none
If an assignment to *none* is made in a simulation with the
*hybrid/overlay* pair style, it wipes out all previous assignments of
that atom type pair to sub-styles.
*hybrid/overlay* or *hybrid/scaled* pair style, it wipes out all
previous assignments of that pair of atom types to sub-styles.
Note that you may need to use an :doc:`atom_style <atom_style>` hybrid
command in your input script, if atoms in the simulation will need
attributes from several atom styles, due to using multiple pair
potentials.
styles with different requirements.
----------
@ -210,8 +243,9 @@ for applying weightings that change the strength of pairwise
interactions between pairs of atoms that are also 1-2, 1-3, and 1-4
neighbors in the molecular bond topology, as normally set by the
:doc:`special_bonds <special_bonds>` command. Different weights can be
assigned to different pair hybrid sub-styles via the :doc:`pair_modify special <pair_modify>` command. This allows multiple force fields
to be used in a model of a hybrid system, however, there is no consistent
assigned to different pair hybrid sub-styles via the :doc:`pair_modify
special <pair_modify>` command. This allows multiple force fields to be
used in a model of a hybrid system, however, there is no consistent
approach to determine parameters automatically for the interactions
between the two force fields, this is only recommended when particles
described by the different force fields do not mix.
@ -260,7 +294,10 @@ the specific syntax, requirements and restrictions.
----------
The potential energy contribution to the overall system due to an
individual sub-style can be accessed and output via the :doc:`compute pair <compute_pair>` command.
individual sub-style can be accessed and output via the :doc:`compute
pair <compute_pair>` command. Note that in the case of pair style
*hybrid/scaled* this is the **unscaled** potential energy of the
selected sub-style.
----------
@ -282,28 +319,27 @@ Pair_style hybrid allows interactions between type pairs 2-2, 1-2,
could even add a second interaction for 1-1 to be computed by another
pair style, assuming pair_style hybrid/overlay is used.
But you should not, as a general rule, attempt to exclude the
many-body interactions for some subset of the type pairs within the
set of 1,3,4 interactions, e.g. exclude 1-1 or 1-3 interactions. That
is not conceptually well-defined for many-body interactions, since the
But you should not, as a general rule, attempt to exclude the many-body
interactions for some subset of the type pairs within the set of 1,3,4
interactions, e.g. exclude 1-1 or 1-3 interactions. That is not
conceptually well-defined for many-body interactions, since the
potential will typically calculate energies and foces for small groups
of atoms, e.g. 3 or 4 atoms, using the neighbor lists of the atoms to
find the additional atoms in the group. It is typically non-physical
to think of excluding an interaction between a particular pair of
atoms when the potential computes 3-body or 4-body interactions.
find the additional atoms in the group.
However, you can still use the pair_coeff none setting or the
:doc:`neigh_modify exclude <neigh_modify>` command to exclude certain
type pairs from the neighbor list that will be passed to a many-body
sub-style. This will alter the calculations made by a many-body
potential, since it builds its list of 3-body, 4-body, etc
interactions from the pair list. You will need to think carefully as
to whether it produces a physically meaningful result for your model.
potential beyond the specific pairs, since it builds its list of 3-body,
4-body, etc interactions from the pair lists. You will need to think
**carefully** as to whether excluding such pairs produces a physically
meaningful result for your model.
For example, imagine you have two atom types in your model, type 1 for
atoms in one surface, and type 2 for atoms in the other, and you wish
to use a Tersoff potential to compute interactions within each
surface, but not between surfaces. Then either of these two command
surface, but not between the surfaces. Then either of these two command
sequences would implement that model:
.. code-block:: LAMMPS
@ -320,9 +356,9 @@ Either way, only neighbor lists with 1-1 or 2-2 interactions would be
passed to the Tersoff potential, which means it would compute no
3-body interactions containing both type 1 and 2 atoms.
Here is another example, using hybrid/overlay, to use 2 many-body
potentials together, in an overlapping manner. Imagine you have CNT
(C atoms) on a Si surface. You want to use Tersoff for Si/Si and Si/C
Here is another example to use 2 many-body potentials together in an
overlapping manner using hybrid/overlay. Imagine you have CNT (C atoms)
on a Si surface. You want to use Tersoff for Si/Si and Si/C
interactions, and AIREBO for C/C interactions. Si atoms are type 1; C
atoms are type 2. Something like this will work:
@ -333,9 +369,9 @@ atoms are type 2. Something like this will work:
pair_coeff * * airebo CH.airebo NULL C
Note that to prevent the Tersoff potential from computing C/C
interactions, you would need to modify the SiC.tersoff file to turn
off C/C interaction, i.e. by setting the appropriate coefficients to
0.0.
interactions, you would need to **modify** the SiC.tersoff potential
file to turn off C/C interaction, i.e. by setting the appropriate
coefficients to 0.0.
----------
@ -343,18 +379,19 @@ Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page.
page. Pair style *hybrid/scaled* does (currently) not support the
*gpu*, *omp*, *kk*, or *intel* suffix.
Since the *hybrid* and *hybrid/overlay* styles delegate computation to
the individual sub-styles, the suffix versions of the *hybrid* and
*hybrid/overlay* styles are used to propagate the corresponding suffix
to all sub-styles, if those versions exist. Otherwise the
non-accelerated version will be used.
Since the *hybrid*, *hybrid/overlay*, *hybrid/scaled* styles delegate
computation to the individual sub-styles, the suffix versions of the
*hybrid* and *hybrid/overlay* styles are used to propagate the
corresponding suffix to all sub-styles, if those versions
exist. Otherwise the non-accelerated version will be used.
The individual accelerated sub-styles are part of the GPU, USER-OMP
and OPT packages, respectively. They are only enabled if LAMMPS was
built with those packages. See the :doc:`Build package <Build_package>`
doc page for more info.
The individual accelerated sub-styles are part of the GPU, KOKKOS,
USER-INTEL, USER-OMP, and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :doc:`Build
package <Build_package>` doc page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
@ -372,28 +409,31 @@ Any pair potential settings made via the
:doc:`pair_modify <pair_modify>` command are passed along to all
sub-styles of the hybrid potential.
For atom type pairs I,J and I != J, if the sub-style assigned to I,I
and J,J is the same, and if the sub-style allows for mixing, then the
For atom type pairs I,J and I != J, if the sub-style assigned to I,I and
J,J is the same, and if the sub-style allows for mixing, then the
coefficients for I,J can be mixed. This means you do not have to
specify a pair_coeff command for I,J since the I,J type pair will be
assigned automatically to the sub-style defined for both I,I and J,J
and its coefficients generated by the mixing rule used by that
sub-style. For the *hybrid/overlay* style, there is an additional
requirement that both the I,I and J,J pairs are assigned to a single
sub-style. See the "pair_modify" command for details of mixing rules.
See the See the doc page for the sub-style to see if allows for
mixing.
assigned automatically to the sub-style defined for both I,I and J,J and
its coefficients generated by the mixing rule used by that sub-style.
For the *hybrid/overlay* and *hybrid/scaled* style, there is an
additional requirement that both the I,I and J,J pairs are assigned to a
single sub-style. See the :doc:`pair_modify <pair_modify>` command for
details of mixing rules. See the See the doc page for the sub-style to
see if allows for mixing.
The hybrid pair styles supports the :doc:`pair_modify <pair_modify>`
shift, table, and tail options for an I,J pair interaction, if the
associated sub-style supports it.
For the hybrid pair styles, the list of sub-styles and their
respective settings are written to :doc:`binary restart files <restart>`, so a :doc:`pair_style <pair_style>` command does
not need to specified in an input script that reads a restart file.
However, the coefficient information is not stored in the restart
file. Thus, pair_coeff commands need to be re-specified in the
restart input script.
For the hybrid pair styles, the list of sub-styles and their respective
settings are written to :doc:`binary restart files <restart>`, so a
:doc:`pair_style <pair_style>` command does not need to specified in an
input script that reads a restart file. However, the coefficient
information is not stored in the restart file. Thus, pair_coeff
commands need to be re-specified in the restart input script. For pair
style *hybrid/scaled* also the names of any variables used as scale
factors are restored, but not the variables themselves, so those may
need to be redefined when continuing from a restart.
These pair styles support the use of the *inner*\ , *middle*\ , and
*outer* keywords of the :doc:`run_style respa <run_style>` command, if
@ -409,6 +449,12 @@ e.g. *lj/cut/coul/long* or *buck/coul/long*\ . You must insure that the
short-range Coulombic cutoff used by each of these long pair styles is
the same or else LAMMPS will generate an error.
Pair style *hybrid/scaled* currently only works for non-accelerated
pair styles and pair styles from the OPT package.
When using pair styles from the GPU package they must not be listed
multiple times. LAMMPS will detect this and abort.
Related commands
""""""""""""""""

55
doc/src/pair_lj_switch3_coulgauss_long.rst
View File

@ -1,8 +1,12 @@
.. index:: pair_style lj/switch3/coulgauss/long
.. index:: pair_style mm3/switch3/coulgauss/long
pair_style lj/switch3/coulgauss/long command
============================================
pair_style mm3/switch3/coulgauss/long command
=============================================
Syntax
""""""
@ -10,7 +14,7 @@ Syntax
pair_style style args
* style = *lj/switch3/coulgauss/long*
* style = *lj/switch3/coulgauss/long* or *mm3/switch3/coulgauss/long*
* args = list of arguments for a particular style
.. parsed-literal::
@ -20,6 +24,11 @@ Syntax
cutoff2 = global cutoff for Coulombic (optional) (distance units)
width = width parameter of the smoothing function (distance units)
*mm3/switch3/coulgauss/long* args = cutoff (cutoff2) width
cutoff = global cutoff for MM3 (and Coulombic if only 1 arg) (distance units)
cutoff2 = global cutoff for Coulombic (optional) (distance units)
width = width parameter of the smoothing function (distance units)
Examples
""""""""
@ -31,6 +40,12 @@ Examples
pair_style lj/switch3/coulgauss/long 12.0 10.0 3.0
pair_coeff 1 0.2 2.5 1.2
pair_style mm3/switch3/coulgauss/long 12.0 3.0
pair_coeff 1 0.2 2.5 1.2
pair_style mm3/switch3/coulgauss/long 12.0 10.0 3.0
pair_coeff 1 0.2 2.5 1.2
Description
"""""""""""
@ -41,8 +56,17 @@ vdW potential
E = 4\epsilon \left[ \left(\frac{\sigma}{r}\right)^{12}-\left(\frac{\sigma}{r}\right)^{6} \right]
, which goes smoothly to zero at the cutoff r_c as defined
by the switching function
The *mm3/switch3/coulgauss/long* style evaluates the MM3
vdW potential :ref:`(Allinger) <mm3-allinger1989>`
.. math::
E & = \epsilon_{ij} \left[ -2.25 \left(\frac{r_{v,ij}}{r_{ij}}\right)^6 + 1.84(10)^5 \exp\left[-12.0 r_{ij}/r_{v,ij}\right] \right] S_3(r_{ij}) \\
r_{v,ij} & = r_{v,i} + r_{v,j} \\
\epsilon_{ij} & = \sqrt{\epsilon_i \epsilon_j}
Both potentials go smoothly to zero at the cutoff r_c as defined by the
switching function
.. math::
@ -85,14 +109,35 @@ commands:
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
For atom type pairs I,J and I != J, the epsilon and sigma coefficients
and cutoff distance for all of the lj/long pair styles can be mixed.
The default mix value is *geometric*\ . See the "pair_modify" command
for details.
Shifting the potential energy is not necessary because the switching
function ensures that the potential is zero at the cut-off.
These pair styles support the :doc:`pair_modify <pair_modify>` table and
options since they can tabulate the short-range portion of the
long-range Coulombic interactions.
Thes pair styles do not support the :doc:`pair_modify <pair_modify>`
tail option for adding a long-range tail correction to the
Lennard-Jones portion of the energy and pressure.
These pair styles write their information to :doc:`binary restart files <restart>`, so pair_style and pair_coeff commands do not need
to be specified in an input script that reads a restart file.
These pair styles can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. They do not support the
*inner*\ , *middle*\ , *outer* keywords.
Restrictions
""""""""""""
These styles are part of the USER-YAFF package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
These styles are part of the USER-YAFF package. They are only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
Related commands
""""""""""""""""

109
doc/src/pair_mm3_switch3_coulgauss_long.rst
View File

@ -1,109 +0,0 @@
.. index:: pair_style mm3/switch3/coulgauss/long
pair_style mm3/switch3/coulgauss/long command
=============================================
Syntax
""""""
.. code-block:: LAMMPS
pair_style style args
* style = *mm3/switch3/coulgauss/long*
* args = list of arguments for a particular style
.. parsed-literal::
*mm3/switch3/coulgauss/long* args = cutoff (cutoff2) width
cutoff = global cutoff for MM3 (and Coulombic if only 1 arg) (distance units)
cutoff2 = global cutoff for Coulombic (optional) (distance units)
width = width parameter of the smoothing function (distance units)
Examples
""""""""
.. code-block:: LAMMPS
pair_style mm3/switch3/coulgauss/long 12.0 3.0
pair_coeff 1 0.2 2.5 1.2
pair_style mm3/switch3/coulgauss/long 12.0 10.0 3.0
pair_coeff 1 0.2 2.5 1.2
Description
"""""""""""
The *mm3/switch3/coulgauss/long* style evaluates the MM3
vdW potential :ref:`(Allinger) <mm3-allinger1989>`
.. math::
E & = \epsilon_{ij} \left[ -2.25 \left(\frac{r_{v,ij}}{r_{ij}}\right)^6 + 1.84(10)^5 \exp\left[-12.0 r_{ij}/r_{v,ij}\right] \right] S_3(r_{ij}) \\
r_{v,ij} & = r_{v,i} + r_{v,j} \\
\epsilon_{ij} & = \sqrt{\epsilon_i \epsilon_j}
, which goes smoothly to zero at the cutoff r_c as defined
by the switching function
.. math::
S_3(r) = \left\lbrace \begin{array}{ll}
1 & \quad\mathrm{if}\quad r < r_\mathrm{c} - w \\
3x^2 - 2x^3 & \quad\mathrm{if}\quad r < r_\mathrm{c} \quad\mathrm{with\quad} x=\frac{r_\mathrm{c} - r}{w} \\
0 & \quad\mathrm{if}\quad r >= r_\mathrm{c}
\end{array} \right.
where w is the width defined in the arguments. This potential
is combined with Coulomb interaction between Gaussian charge densities:
.. math::
E = \frac{q_i q_j \mathrm{erf}\left( r/\sqrt{\gamma_1^2+\gamma_2^2} \right) }{\epsilon r_{ij}}
where :math:`q_i` and :math:`q_j` are the charges on the 2 atoms,
epsilon is the dielectric constant which can be set by the
:doc:`dielectric <dielectric>` command, ::math:`\gamma_i` and
:math:`\gamma_j` are the widths of the Gaussian charge distribution and
erf() is the error-function. This style has to be used in conjunction
with the :doc:`kspace_style <kspace_style>` command
If one cutoff is specified it is used for both the vdW and Coulomb
terms. If two cutoffs are specified, the first is used as the cutoff
for the vdW terms, and the second is the cutoff for the Coulombic term.
The following coefficients must be defined for each pair of atoms
types via the :doc:`pair_coeff <pair_coeff>` command as in the examples
above, or in the data file or restart files read by the
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands:
* :math:`\epsilon` (energy)
* :math:`r_v` (distance)
* :math:`\gamma` (distance)
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Mixing rules are fixed for this style as defined above.
Shifting the potential energy is not necessary because the switching
function ensures that the potential is zero at the cut-off.
Restrictions
""""""""""""
These styles are part of the USER-YAFF package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`
Default
"""""""
none

114
doc/src/pair_pace.rst Normal file
View File

@ -0,0 +1,114 @@
.. index:: pair_style pace
pair_style pace command
========================
Syntax
""""""
.. code-block:: LAMMPS
pair_style pace ... keyword values ...
* an optional keyword may be appended
* keyword = *product* or *recursive*
.. parsed-literal::
*product* = use product algorithm for basis functions
*recursive* = use recursive algorithm for basis functions
Examples
""""""""
.. code-block:: LAMMPS
pair_style pace
pair_style pace product
pair_coeff * * Cu-PBE-core-rep.ace Cu
Description
"""""""""""
Pair style *pace* computes interactions using the Atomic Cluster
Expansion (ACE), which is a general expansion of the atomic energy in
multi-body basis functions. :ref:`(Drautz) <Drautz20191>`.
The *pace* pair style
provides an efficient implementation that
is described in this paper :ref:`(Lysogorskiy) <Lysogorskiy20211>`.
In ACE, the total energy is decomposed into a sum over
atomic energies. The energy of atom *i* is expressed as a
linear or non-linear function of one or more density functions.
By projecting the
density onto a local atomic base, the lowest order contributions
to the energy can be expressed as a set of scalar polynomials in
basis function contributions summed over neighbor atoms.
Only a single pair_coeff command is used with the *pace* style which
specifies an ACE coefficient file followed by N additional arguments
specifying the mapping of ACE elements to LAMMPS atom types,
where N is the number of LAMMPS atom types:
* ACE coefficient file
* N element names = mapping of ACE elements to atom types
Only a single pair_coeff command is used with the *pace* style which
specifies an ACE file that fully defines the potential.
Note that unlike for other potentials, cutoffs are
not set in the pair_style or pair_coeff command; they are specified in
the ACE file.
The pair_style *pace* command may be followed by an optional keyword
*product* or *recursive*, which determines which of two algorithms
is used for the calculation of basis functions and derivatives.
The default is *recursive*.
See the :doc:`pair_coeff <pair_coeff>` doc page for alternate ways
to specify the path for the ACE coefficient file.
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 with
user-specifiable parameters as described above. You never need to
specify a pair_coeff command with I != J arguments for this style.
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 USER-PACE package. It is only enabled if LAMMPS
was built with that package.
See the :doc:`Build package <Build_package>` doc page for more info.
Related commands
""""""""""""""""
:doc:`pair_style snap <pair_snap>`
Default
"""""""
recursive
.. _Drautz20191:
**(Drautz)** Drautz, Phys Rev B, 99, 014104 (2019).
.. _Lysogorskiy20211:
**(Lysogorskiy)** Lysogorskiy, van der Oord, Bochkarev, Menon, Rinaldi, Hammerschmidt, Mrovec, Thompson, Csanyi, Ortner, Drautz, TBD (2021).

2
doc/src/pair_polymorphic.rst
View File

@ -319,7 +319,7 @@ 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>` doc page for more info.
This pair potential requires the :doc:`newtion <newton>` setting to be
This pair potential requires the :doc:`newton <newton>` setting to be
"on" for pair interactions.
The potential files provided with LAMMPS (see the potentials directory)

9
doc/src/pair_style.rst
View File

@ -95,10 +95,11 @@ accelerated styles exist.
* :doc:`none <pair_none>` - turn off pairwise interactions
* :doc:`hybrid <pair_hybrid>` - multiple styles of pairwise interactions
* :doc:`hybrid/overlay <pair_hybrid>` - multiple styles of superposed pairwise interactions
* :doc:`hybrid/scaled <pair_hybrid>` - multiple styles of scaled superposed pairwise interactions
* :doc:`zero <pair_zero>` - neighbor list but no interactions
* :doc:`adp <pair_adp>` - angular dependent potential (ADP) of Mishin
* :doc:`agni <pair_agni>` - machine learned potential mapping atomic environment to forces
* :doc:`agni <pair_agni>` - AGNI machine-learning potential
* :doc:`airebo <pair_airebo>` - AIREBO potential of Stuart
* :doc:`airebo/morse <pair_airebo>` - AIREBO with Morse instead of LJ
* :doc:`atm <pair_atm>` - Axilrod-Teller-Muto potential
@ -132,6 +133,7 @@ accelerated styles exist.
* :doc:`comb3 <pair_comb>` - charge-optimized many-body (COMB3) potential
* :doc:`cosine/squared <pair_cosine_squared>` - Cooke-Kremer-Deserno membrane model potential
* :doc:`coul/cut <pair_coul>` - cutoff Coulomb potential
* :doc:`coul/cut/global <pair_coul>` - cutoff Coulomb potential
* :doc:`coul/cut/soft <pair_fep_soft>` - Coulomb potential with a soft core
* :doc:`coul/debye <pair_coul>` - cutoff Coulomb potential with Debye screening
* :doc:`coul/diel <pair_coul_diel>` - Coulomb potential with dielectric permittivity
@ -250,7 +252,7 @@ accelerated styles exist.
* :doc:`mgpt <pair_mgpt>` - simplified model generalized pseudopotential theory (MGPT) potential
* :doc:`mesont/tpm <pair_mesont_tpm>` - nanotubes mesoscopic force field
* :doc:`mie/cut <pair_mie>` - Mie potential
* :doc:`mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>` - smoothed MM3 vdW potential with Gaussian electrostatics
* :doc:`mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>` - smoothed MM3 vdW potential with Gaussian electrostatics
* :doc:`momb <pair_momb>` - Many-Body Metal-Organic (MOMB) force field
* :doc:`morse <pair_morse>` - Morse potential
* :doc:`morse/smooth/linear <pair_morse>` - linear smoothed Morse potential
@ -278,6 +280,7 @@ accelerated styles exist.
* :doc:`oxrna2/hbond <pair_oxrna2>` -
* :doc:`oxrna2/stk <pair_oxrna2>` -
* :doc:`oxrna2/xstk <pair_oxrna2>` -
* :doc:`pace <pair_pace>` - Atomic Cluster Expansion (ACE) machine-learning potential
* :doc:`peri/eps <pair_peri>` - peridynamic EPS potential
* :doc:`peri/lps <pair_peri>` - peridynamic LPS potential
* :doc:`peri/pmb <pair_peri>` - peridynamic PMB potential
@ -296,7 +299,7 @@ accelerated styles exist.
* :doc:`smd/ulsph <pair_smd_ulsph>` -
* :doc:`smtbq <pair_smtbq>` -
* :doc:`mliap <pair_mliap>` - Multiple styles of machine-learning potential
* :doc:`snap <pair_snap>` - SNAP quantum-accurate potential
* :doc:`snap <pair_snap>` - SNAP machine-learning potential
* :doc:`soft <pair_soft>` - Soft (cosine) potential
* :doc:`sph/heatconduction <pair_sph_heatconduction>` -
* :doc:`sph/idealgas <pair_sph_idealgas>` -

2
doc/src/pair_vashishta.rst
View File

@ -217,7 +217,7 @@ This pair style can only be used via the *pair* keyword of the
Restrictions
""""""""""""
These pair style are part of the MANYBODY package. They is only
These pair styles are part of the MANYBODY package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
These pair styles requires the :doc:`newton <newton>` setting to be "on"

90
doc/src/plugin.rst Normal file
View File

@ -0,0 +1,90 @@
.. index:: plugin
plugin command
==============
Syntax
""""""
.. parsed-literal::
plugin command args
* command = *load* or *unload* or *list* or *clear*
* args = list of arguments for a particular plugin command
.. parsed-literal::
*load* file = load plugin(s) from shared object in *file*
*unload* style name = unload plugin *name* of style *style*
*style* = *pair* or *bond* or *angle* or *dihedral* or *improper* or *compute* or *fix* or *region* or *command*
*list* = print a list of currently loaded plugins
*clear* = unload all currently loaded plugins
Examples
""""""""
.. code-block:: LAMMPS
plugin load morse2plugin.so
plugin unload pair morse2/omp
plugin unload command hello
plugin list
plugin clear
Description
"""""""""""
The plugin command allows to load (and unload) additional styles and
commands into a LAMMPS binary from so-called dynamic shared object (DSO)
files. This enables to add new functionality to an existing LAMMPS
binary without having to recompile and link the entire executable.
The *load* command will load and initialize all plugins contained in the
plugin DSO with the given filename. A message with information the
plugin style and name and more will be printed. Individual DSO files
may contain multiple plugins. More details about how to write and
compile the plugin DSO is given in programmer's guide part of the manual
under :doc:`Developer_plugins`.
The *unload* command will remove the given style or the given name from
the list of available styles. If the plugin style is currently in use,
that style instance will be deleted.
The *list* command will print a list of the loaded plugins and their
styles and names.
The *clear* command will unload all currently loaded plugins.
Restrictions
""""""""""""
The *plugin* command is part of the PLUGIN package. It is
only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` doc page for
more info. Plugins are not available on Windows.
For the loading of plugins to work the LAMMPS library must be
:ref:`compiled as a shared library <library>`. If plugins
access functions or classes from a package, LAMMPS must have
been compiled with that package included.
Plugins are dependent on the LAMMPS binary interface (ABI)
and particularly the MPI library used. So they are not guaranteed
to work when the plugin was compiled with a different MPI library
or different compilation settings or a different LAMMPS version.
There are no checks, so if there is a mismatch the plugin object
will either not load or data corruption and crashes may happen.
Related commands
""""""""""""""""
none
Default
"""""""
none

9
doc/src/rerun.rst
View File

@ -15,7 +15,7 @@ Syntax
.. parsed-literal::
keyword = *first* or *last* or *every* or *skip* or *start* or *stop* or *dump*
keyword = *first* or *last* or *every* or *skip* or *start* or *stop* or *post* or *dump*
*first* args = Nfirst
Nfirst = dump timestep to start on
*last* args = Nlast
@ -28,6 +28,7 @@ Syntax
Nstart = timestep on which pseudo run will start
*stop* args = Nstop
Nstop = timestep to which pseudo run will end
*post* value = *yes* or *no*
*dump* args = same as :doc:`read_dump <read_dump>` command starting with its field arguments
Examples
@ -154,6 +155,10 @@ Also note that an error will occur if you read a snapshot from the
dump file with a timestep value larger than the *stop* setting you
have specified.
The *post* keyword can be used to minimize the output to the screen that
happens after a *rerun* command, similar to the post keyword of the
:doc:`run command <run>`. It is set to *no* by default.
The *dump* keyword is required and must be the last keyword specified.
Its arguments are passed internally to the :doc:`read_dump <read_dump>`
command. The first argument following the *dump* keyword should be
@ -226,4 +231,4 @@ Default
The option defaults are first = 0, last = a huge value (effectively
infinity), start = same as first, stop = same as last, every = 0, skip
= 1;
= 1, post = no;

2
doc/src/units.rst
View File

@ -87,7 +87,7 @@ energy is a derived unit (in SI units you equivalently have the relation
* charge = reduced LJ charge, where :math:`q^* = q \frac{1}{\sqrt{4 \pi \varepsilon_0 \sigma \epsilon}}`
* dipole = reduced LJ dipole, moment where :math:`\mu^* = \mu \frac{1}{\sqrt{4 \pi \varepsilon_0 \sigma^3 \epsilon}}`
* electric field = force/charge, where :math:`E^* = E \frac{\sqrt{4 \pi \varepsilon_0 \sigma \epsilon} \sigma}{\epsilon}`
* density = mass/volume, where :math:`\rho^* = \rho \sigma^{dim}`
* density = mass/volume, where :math:`\rho^* = \rho \frac{\sigma^{dim}}{m}`
Note that for LJ units, the default mode of thermodynamic output via
the :doc:`thermo_style <thermo_style>` command is to normalize all

10
doc/src/variable.rst
View File

@ -65,8 +65,8 @@ Syntax
bound(group,dir,region), gyration(group,region), ke(group,reigon),
angmom(group,dim,region), torque(group,dim,region),
inertia(group,dimdim,region), omega(group,dim,region)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x)
feature functions = is_active(category,feature,exact), is_defined(category,id,exact)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name)
feature functions = is_available(category,feature), is_active(category,feature), is_defined(category,id)
atom value = id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i]
atom vector = id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q
compute references = c_ID, c_ID[i], c_ID[i][j], C_ID, C_ID[i]
@ -429,7 +429,7 @@ argument. For *equal*\ -style variables the formula computes a scalar
quantity, which becomes the value of the variable whenever it is
evaluated. For *vector*\ -style variables the formula must compute a
vector of quantities, which becomes the value of the variable whenever
it is evaluated. The calculated vector can be on length one, but it
it is evaluated. The calculated vector can be of length one, but it
cannot be a simple scalar value like that produced by an equal-style
compute. I.e. the formula for a vector-style variable must have at
least one quantity in it that refers to a global vector produced by a
@ -821,6 +821,10 @@ Special Functions
Special functions take specific kinds of arguments, meaning their
arguments cannot be formulas themselves.
The is_file(x) function is a test whether 'x' is a (readable) file
and returns 1 in this case, otherwise it returns 0. For that 'x'
is taken as a literal string and must not have any blanks in it.
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