Merge branch 'lammps:master' into bond/react-custom_constraint

doc/src/Build_extras.rst

@@ -1253,8 +1253,8 @@ be built for the most part with all major versions of the C++ language.
 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 
+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/>`_
 
@@ -1276,8 +1276,8 @@ at: `https://github.com/ICAMS/lammps-user-pace/ <https://github.com/ICAMS/lammps
    .. 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. 
+      in one step from the ``lammps/src`` dir, using these commands,
+      which invoke the ``lib/pace/Install.py`` script.
 
       .. code-block:: bash
 

doc/src/Commands_pair.rst

@@ -87,6 +87,8 @@ OPT.
    * :doc:`coul/wolf/cs <pair_cs>`
    * :doc:`dpd (gio) <pair_dpd>`
    * :doc:`dpd/fdt <pair_dpd_fdt>`
+   * :doc:`dpd/ext <pair_dpd_ext>`
+   * :doc:`dpd/ext/tstat <pair_dpd_ext>`
    * :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>`
    * :doc:`dpd/tstat (go) <pair_dpd>`
    * :doc:`dsmc <pair_dsmc>`

doc/src/Developer_org.rst

@@ -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.

doc/src/Developer_plugins.rst

@@ -59,31 +59,25 @@ Members of ``lammpsplugin_t``
    * - author
      - String with the name and email of the author
    * - creator.v1
-     - Pointer to factory function for pair, bond, angle, dihedral, or improper styles
+     - 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
-   * - creator.v3
-     - Pointer to factory function for command 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.
-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.
-The "creator.v3" element takes the same arguments as "creator.v3" but is
-specific to creating command styles: the factory function has to instantiate
-the command style locally passing the LAMMPS pointer as argument and then
-call its "command" member function with the number and list of arguments.
-The factory function pointer needs to be cast to the
-``lammpsplugin_factory3`` type before assignment.
+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
 ^^^^^^^^^^^^^^^^^^
@@ -123,12 +117,12 @@ function would look like this:
 
 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`` pointer type.  It returns a
+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``, must be unique inside
-the entire LAMMPS executable.
+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
 ^^^^^^^^^^^^^^^^^
@@ -169,9 +163,9 @@ Below is an example for that:
 
 Command style example
 ^^^^^^^^^^^^^^^^^^^^^
-For command styles there is a third variant of factory function as
+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 also be within the same
+implementation of the plugin class may be within the same source
 file as the plugin interface code:
 
 .. code-block:: C++
@@ -180,15 +174,15 @@ file as the plugin interface code:
 
    #include "comm.h"
    #include "error.h"
-   #include "pointers.h"
+   #include "command.h"
    #include "version.h"
 
    #include <cstring>
 
    namespace LAMMPS_NS {
-     class Hello : protected Pointers {
+     class Hello : public Command {
       public:
-       Hello(class LAMMPS *lmp) : Pointers(lmp) {};
+       Hello(class LAMMPS *lmp) : Command(lmp) {};
        void command(int, char **);
      };
    }
@@ -202,10 +196,9 @@ file as the plugin interface code:
         utils::logmesg(lmp,fmt::format("Hello, {}!\n",argv[0]));
    }
 
-   static void hellocreator(LAMMPS *lmp, int argc, char **argv)
+   static void hellocreator(LAMMPS *lmp)
    {
-     Hello hello(lmp);
-     hello.command(argc,argv);
+     return new Hello(lmp);
    }
 
    extern "C" void lammpsplugin_init(void *lmp, void *handle, void *regfunc)
@@ -216,9 +209,9 @@ file as the plugin interface code:
      plugin.version = LAMMPS_VERSION;
      plugin.style   = "command";
      plugin.name    = "hello";
-     plugin.info    = "Hello world command v1.0";
+     plugin.info    = "Hello world command v1.1";
      plugin.author  = "Axel Kohlmeyer (akohlmey@gmail.com)";
-     plugin.creator.v3 = (lammpsplugin_factory3 *) &hellocreator;
+     plugin.creator.v1 = (lammpsplugin_factory1 *) &hellocreator;
      plugin.handle  = handle;
      (*register_plugin)(&plugin,lmp);
    }

doc/src/Developer_utils.rst

@@ -9,14 +9,29 @@ reading or writing to files with error checking or translation of
 strings into specific types of numbers with checking for validity.  This
 reduces redundant implementations and encourages consistent behavior.
 
-I/O with status check
-^^^^^^^^^^^^^^^^^^^^^
+I/O with status check and similar functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-These are wrappers around the corresponding C library calls like
-``fgets()`` or ``fread()``.  They will check if there were errors
-on reading or an unexpected end-of-file state was reached.  In that
-case, the functions will stop the calculation with an error message,
-indicating the name of the problematic file, if possible.
+The the first two functions are wrappers around the corresponding C
+library calls ``fgets()`` or ``fread()``.  They will check if there
+were errors on reading or an unexpected end-of-file state was reached.
+In that case, the functions will stop with an error message, indicating
+the name of the problematic file, if possible unless the *error* argument
+is a NULL pointer.
+
+The :cpp:func:`fgets_trunc` function will work similar for ``fgets()``
+but it will read in a whole line (i.e. until the end of line or end
+of file), but store only as many characters as will fit into the buffer
+including a final newline character and the terminating NULL byte.
+If the line in the file is longer it will thus be truncated in the buffer.
+This function is used by :cpp:func:`read_lines_from_file` to read individual
+lines but make certain they follow the size constraints.
+
+The :cpp:func:`read_lines_from_file` function will read the requested
+number of lines of a maximum length into a buffer and will return 0
+if successful or 1 if not. It also guarantees that all lines are
+terminated with a newline character and the entire buffer with a
+NULL character.
 
 ----------
 
@@ -26,6 +41,12 @@ indicating the name of the problematic file, if possible.
 .. doxygenfunction:: sfread
    :project: progguide
 
+.. doxygenfunction:: fgets_trunc
+   :project: progguide
+
+.. doxygenfunction:: read_lines_from_file
+   :project: progguide
+
 ----------
 
 String to number conversions with validity check
@@ -164,7 +185,10 @@ Argument processing
 Convenience functions
 ^^^^^^^^^^^^^^^^^^^^^
 
-.. doxygenfunction:: logmesg
+.. doxygenfunction:: logmesg(LAMMPS *lmp, const S &format, Args&&... args)
+   :project: progguide
+
+.. doxygenfunction:: logmesg(LAMMPS *lmp, const std::string &mesg)
    :project: progguide
 
 .. doxygenfunction:: getsyserror

doc/src/Howto_drude2.rst

@@ -9,6 +9,8 @@ USER-DRUDE package activated. Then, the data file and input scripts
 have to be modified to include the Drude dipoles and how to handle
 them.
 
+Example input scripts available: examples/USER/drude
+
 ----------
 
 **Overview of Drude induced dipoles**

doc/src/Howto_spins.rst

@@ -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

doc/src/Modify_command.rst

@@ -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:
 

doc/src/Tools.rst

@@ -94,6 +94,7 @@ Miscellaneous tools
    * :ref:`kate <kate>`
    * :ref:`LAMMPS shell <lammps_shell>`
    * :ref:`LAMMPS magic patterns for file(1) <magic>`
+   * :ref:`Offline build tool <offline>`
    * :ref:`singularity <singularity_tool>`
    * :ref:`SWIG interface <swig>`
    * :ref:`vim <vim>`
@@ -756,6 +757,103 @@ See the README file in the tools/msi2lmp folder for more information.
 
 ----------
 
+.. _offline:
+
+Scripts for building LAMMPS when offline
+----------------------------------------
+
+In some situations it might be necessary to build LAMMPS on a system
+without direct internet access. The scripts in ``tools/offline`` folder
+allow you to pre-load external dependencies for both the documentation
+build and for building LAMMPS with CMake.
+
+It does so by
+
+ #. downloading necessary ``pip`` packages,
+ #. cloning ``git`` repositories
+ #. downloading tarballs
+
+to a designated cache folder.
+
+As of April 2021, all of these downloads make up around 600MB. By
+default, the offline scripts will download everything into the
+``$HOME/.cache/lammps`` folder, but this can be changed by setting the
+``LAMMPS_CACHING_DIR`` environment variable.
+
+Once the caches have been initialized, they can be used for building the
+LAMMPS documentation or compiling LAMMPS using CMake on an offline
+system.
+
+The ``use_caches.sh`` script must be sourced into the current shell
+to initialize the offline build environment. Note that it must use
+the same ``LAMMPS_CACHING_DIR``. This script does the following:
+
+ #. Set up environment variables that modify the behavior of both,
+    ``pip`` and ``git``
+ #. Start a simple local HTTP server using Python to host files for CMake
+
+Afterwards, it will print out instruction on how to modify the CMake
+command line to make sure it uses the local HTTP server.
+
+To undo the environment changes and shutdown the local HTTP server,
+run the ``deactivate_caches`` command.
+
+Examples
+^^^^^^^^
+
+For all of the examples below, you first need to create the cache, which
+requires an internet connection.
+
+.. code-block:: bash
+
+   ./tools/offline/init_caches.sh
+
+Afterwards, you can disconnect or copy the contents of the
+``LAMMPS_CACHING_DIR`` folder to an offline system.
+
+Documentation Build
+^^^^^^^^^^^^^^^^^^^
+
+The documentation build will create a new virtual environment that
+typically first installs dependencies from ``pip``. With the offline
+environment loaded, these installations will instead grab the necessary
+packages from your local cache.
+
+.. code-block:: bash
+
+   # if LAMMPS_CACHING_DIR is different from default, make sure to set it first
+   # export LAMMPS_CACHING_DIR=path/to/folder
+   source tools/offline/use_caches.sh
+   cd doc/
+   make html
+
+   deactivate_caches
+
+CMake Build
+^^^^^^^^^^^
+
+When compiling certain packages with external dependencies, the CMake
+build system will download necessary files or sources from the web. For
+more flexibility the CMake configuration allows users to specify the URL
+of each of these dependencies.  What the ``init_caches.sh`` script does
+is create a CMake "preset" file, which sets the URLs for all of the known
+dependencies and redirects the download to the local cache.
+
+.. code-block:: bash
+
+   # if LAMMPS_CACHING_DIR is different from default, make sure to set it first
+   # export LAMMPS_CACHING_DIR=path/to/folder
+   source tools/offline/use_caches.sh
+
+   mkdir build
+   cd build
+   cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake ../cmake
+   make -j 8
+
+   deactivate_caches
+
+----------
+
 .. _phonon:
 
 phonon tool

doc/src/atom_style.rst

@@ -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
 """"""""

doc/src/balance.rst

@@ -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

doc/src/compute_fep.rst

@@ -48,6 +48,8 @@ Examples
    compute 1 all fep 298 pair lj/cut epsilon 1 * v_delta pair lj/cut sigma 1 * v_delta volume yes
    compute 1 all fep 300 atom charge 2 v_delta
 
+Example input scripts available: examples/USER/fep
+
 Description
 """""""""""
 

doc/src/compute_temp_drude.rst

@@ -20,6 +20,8 @@ Examples
 
    compute TDRUDE all temp/drude
 
+Example input scripts available: examples/USER/drude
+
 Description
 """""""""""
 

doc/src/fix_adapt_fep.rst

@@ -56,6 +56,9 @@ Examples
    fix 1 all adapt/fep 1 pair lj/cut epsilon * * v_scale1 coul/cut scale 3 3 v_scale2 scale yes reset yes
    fix 1 all adapt/fep 10 atom diameter 1 v_size
 
+
+Example input scripts available: examples/USER/fep
+
 Description
 """""""""""
 

doc/src/fix_balance.rst

@@ -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.

doc/src/fix_drude.rst

@@ -22,6 +22,8 @@ Examples
    fix 1 all drude 1 1 0 1 0 2 2 2
    fix 1 all drude C C N C N D D D
 
+Example input scripts available: examples/USER/drude
+
 Description
 """""""""""
 

doc/src/fix_drude_transform.rst

@@ -25,6 +25,8 @@ Examples
    fix 3 all drude/transform/direct
    fix 1 all drude/transform/inverse
 
+Example input scripts available: examples/USER/drude
+
 Description
 """""""""""
 

doc/src/fix_langevin_drude.rst

@@ -35,6 +35,8 @@ Examples
    fix 3 all langevin/drude 300.0 100.0 19377 1.0 20.0 83451
    fix 1 all langevin/drude 298.15 100.0 19377 5.0 10.0 83451 zero yes
 
+Example input scripts available: examples/USER/drude
+
 Description
 """""""""""
 

doc/src/fix_precession_spin.rst

@@ -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, Theophile, et al.  Ultrafast antiferromagnetic
+switching in NiO induced by spin transfer torques.
+Physical Review B 102.13 (2020): 134415.

doc/src/fix_qeq.rst

@@ -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
 """"""""""""""""

doc/src/fix_tgnh_drude.rst

@@ -62,6 +62,8 @@ Examples
    fix 2 jello tgnpt/drude temp 300.0 300.0 100.0 1.0 20.0 tri 5.0 5.0 1000.0
    fix 2 ice tgnpt/drude temp 250.0 250.0 100.0 1.0 20.0 x 1.0 1.0 0.5 y 2.0 2.0 0.5 z 3.0 3.0 0.5 yz 0.1 0.1 0.5 xz 0.2 0.2 0.5 xy 0.3 0.3 0.5 nreset 1000
 
+Example input scripts available: examples/USER/drude
+
 Description
 """""""""""
 

doc/src/pair_coul_tt.rst

@@ -29,6 +29,7 @@ Examples
    pair_coeff 1 2  coul/tt 4.0 1.0 4 12.0
    pair_coeff 1 3* coul/tt 4.5 1.0 4
 
+Example input scripts available: examples/USER/drude
 
 Description
 """""""""""

doc/src/pair_dpd_ext.rst

@@ -0,0 +1,138 @@
+.. index:: pair_style dpd/ext
+.. index:: pair_style dpd/ext/tstat
+
+pair_style dpd/ext command
+==========================
+
+pair_style dpd/ext/tstat command
+================================
+
+Syntax
+""""""
+
+
+.. code-block:: LAMMPS
+
+   pair_style dpd/ext T cutoff seed
+   pair_style dpd/ext/tstat Tstart Tstop cutoff seed
+
+* T = temperature (temperature units)
+* Tstart,Tstop = desired temperature at start/end of run (temperature units)
+* cutoff = global cutoff for DPD interactions (distance units)
+* seed = random # seed (positive integer)
+
+Examples
+""""""""
+
+
+.. code-block:: LAMMPS
+
+   pair_style dpd/ext 1.0 2.5 34387
+   pair_coeff 1 1 25.0 4.5 4.5 0.5 0.5 1.2
+   pair_coeff 1 2 40.0 4.5 4.5 0.5 0.5 1.2
+
+   pair_style dpd/ext/tstat 1.0 1.0 2.5 34387
+   pair_coeff 1 1 4.5 4.5 0.5 0.5 1.2
+   pair_coeff 1 2 4.5 4.5 0.5 0.5 1.2
+
+Description
+"""""""""""
+
+The style *dpd/ext* computes an extended force field for dissipative particle dynamics (DPD) following the exposition in :ref:`(Groot) <Groot>`, :ref:`(Junghans) <Junghans>`.
+
+Style *dpd/ext/tstat* invokes an extended DPD thermostat on pairwise interactions, equivalent to the non-conservative portion of the extended DPD force field. To use *dpd/ext/tstat* as a thermostat for another pair style, use the :doc:`pair_style hybrid/overlay <pair_hybrid>` command to compute both the desired pair interaction and the thermostat for each pair of particles.
+
+For the style *dpd/ext*\ , the force on atom I due to atom J is given as a sum
+of 3 terms
+
+.. math::
+
+   \mathbf{f}  = & f^C + f^D + f^R \qquad \qquad r < r_c \\
+   f^C      = & A_{ij} w(r) \hat{\mathbf{r}}_{ij} \\
+   f^D      = & - \gamma_{\parallel} w_{\parallel}^2(r) (\hat{\mathbf{r}}_{ij} \cdot \mathbf{v}_{ij}) \hat{\mathbf{r}}_{ij}  - \gamma_{\perp} w_{\perp}^2 (r) ( \mathbf{I} - \hat{\mathbf{r}}_{ij} \hat{\mathbf{r}}_{ij}^{\rm T} ) \mathbf{v}_{ij} \\
+   f^R      = & \sigma_{\parallel} w_{\parallel}(r) \frac{\alpha}{\sqrt{\Delta t}} \hat{\mathbf{r}}_{ij}  + \sigma_{\perp} w_{\perp} (r) ( \mathbf{I} - \hat{\mathbf{r}}_{ij} \hat{\mathbf{r}}_{ij}^{\rm T} ) \frac{\mathbf{\xi}_{ij}}{\sqrt{\Delta t}}\\
+   w(r)     = & 1 - r/r_c \\
+
+where :math:`\mathbf{f}^C` is a conservative force, :math:`\mathbf{f}^D` is a dissipative force, and :math:`\mathbf{f}^R` is a random force. :math:`A_{ij}` is the maximum repulsion between the two atoms, :math:`\hat{\mathbf{r}}_{ij}` is a unit vector in the direction :math:`\mathbf{r}_i - \mathbf{r}_j`, :math:`\mathbf{v}_{ij} = \mathbf{v}_i - \mathbf{v}_j` is the vector difference in velocities of the two atoms, :math:`\alpha` and :math:`\mathbf{\xi}_{ij}` are Gaussian random numbers with zero mean and unit variance, :math:`\Delta t` is the timestep, :math:`w (r) = 1 - r / r_c` is a weight function for the conservative interactions that varies between 0 and 1, :math:`r_c` is the corresponding cutoff, :math:`w_{\alpha} ( r ) = ( 1 - r / \bar{r}_c )^{s_{\alpha}}`, :math:`\alpha \equiv ( \parallel, \perp )`, are weight functions with coefficients :math:`s_\alpha` that vary between 0 and 1, :math:`\bar{r}_c` is the corresponding cutoff, :math:`\mathbf{I}` is the unit matrix, :math:`\sigma_{\alpha} = \sqrt{2 k T \gamma_{\alpha}}`, where :math:`k` is the Boltzmann constant and :math:`T` is the temperature in the pair\_style command.
+
+For the style *dpd/ext/tstat*\ , the force on atom I due to atom J is the same as the above equation, except that the conservative :math:`\mathbf{f}^C` term is dropped. Also, during the run, T is set each timestep to a ramped value from Tstart to Tstop.
+
+For the style *dpd/ext*\ , the pairwise energy associated with style *dpd/ext* is only due to the conservative force term :math:`\mathbf{f}^C`, and is shifted to be zero at the cutoff distance :math:`r_c`. The pairwise virial is calculated using all three terms. There is no pairwise energy for style *dpd/ext/tstat*, but the last two terms of the formula contribute the virial.
+
+For the style *dpd/ext/tstat*, the force on atom I due to atom J is the same as the above equation, except that the conservative :math:`\mathbf{f}^C` term is dropped. Also, during the run, T is set each timestep to a ramped value from Tstart to Tstop.
+
+For the style *dpd/ext*\ , the pairwise energy associated with style *dpd/ext* is only due to the conservative force term :math:`\mathbf{f}^C`, and is shifted to be zero at the cutoff distance :math:`r_c`. The pairwise virial is calculated using all three terms. There is no pairwise energy for style *dpd/ext/tstat*, but the last two terms of the formula contribute the virial.
+
+For the style *dpd/ext*, 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:
+
+* A (force units)
+* :math:`\gamma_{\perp}` (force/velocity units)
+* :math:`\gamma_{\parallel}` (force/velocity units)
+* :math:`s_{\perp}` (unitless)
+* :math:`s_{\parallel}` (unitless)
+* :math:`r_c` (distance units)
+
+The last coefficient is optional. If not specified, the global DPD cutoff is used. Note that :math:`\sigma`'s are set equal to :math:`\sqrt{2 k T \gamma}`, where :math:`T` is the temperature set by the :doc:`pair_style <pair_style>` command so it does not need to be specified.
+
+
+For the style *dpd/ext/tstat*, the coefficients defined for each pair of atoms types via the :doc:`pair_coeff <pair_coeff>` command is the same, except that A is not included.
+
+.. note::
+
+ If you are modeling DPD polymer chains, you may want to use the :doc:`pair_style srp <pair_srp>` command in conjunction with these pair styles. It is a soft segmental repulsive potential (SRP) that can prevent DPD polymer chains from crossing each other.
+
+.. note::
+
+ The virial calculation for pressure when using this pair style includes all the components of force listed above, including the random force.
+
+----------
+
+
+**Mixing, shift, table, tail correction, restart, rRESPA info**\ :
+
+The style *dpd/ext* does not support mixing. Thus, coefficients for all I,J pairs must be specified explicitly.
+
+The pair styles do not support the :doc:`pair_modify <pair_modify>` shift option for the energy of the pair interaction. Note that as discussed above, the energy due to the conservative :math:`\mathbf{f}^C` term is already shifted to be zero at the cutoff distance :math:`r_c`.
+
+The :doc:`pair_modify <pair_modify>` table option is not relevant for the style *dpd/ext*.
+
+The style *dpd/ext* does not support the :doc:`pair_modify <pair_modify>` tail option for adding long-range tail corrections to energy and pressure.
+
+The 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*\ , and *outer*\  keywords.
+
+The style *dpd/ext/tstat* can ramp its target temperature over multiple runs, using the start and stop keywords of the :doc:`run <run>` command. See the :doc:`run <run>` command for details of how to do this.
+
+----------
+
+
+Restrictions
+""""""""""""
+
+The default frequency for rebuilding neighbor lists is every 10 steps (see the :doc:`neigh_modify <neigh_modify>` command). This may be too infrequent for style *dpd/ext* simulations since particles move rapidly and can overlap by large amounts. If this setting yields a non-zero number of \say{dangerous} reneighborings (printed at the end of a simulation), you should experiment with forcing reneighboring more often and see if system energies/trajectories change.
+
+The pair styles require to use the :doc:`comm_modify vel yes <comm_modify>` command so that velocities are stored by ghost atoms.
+
+The pair styles will not restart exactly when using the :doc:`read_restart <read_restart>` command, though they should provide statistically similar results. This is because the forces they compute depend on atom velocities. See the :doc:`read_restart <read_restart>` command for more details.
+
+Related commands
+""""""""""""""""
+
+:doc:`pair_style dpd <pair_dpd>`, :doc:`pair_coeff <pair_coeff>`, :doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`, :doc:`pair_style srp <pair_srp>`
+
+**Default:** none
+
+
+----------
+
+
+.. _Groot:
+
+
+
+**(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997).
+
+.. _Junghans:
+
+
+
+**(Junghans)** Junghans, Praprotnik and Kremer, Soft Matter 4, 156, 1119-1128 (2008).

doc/src/pair_fep_soft.rst

@@ -182,6 +182,8 @@ Examples
    pair_coeff * * 100.0 2.0 1.5 1.0
    pair_coeff 1 1 100.0 2.0 1.5 1.0 3.0
 
+Example input scripts available: examples/USER/fep
+
 Description
 """""""""""
 

doc/src/pair_hybrid.rst

@@ -257,7 +257,7 @@ then overrides them with 0.0 only for CHARMM:
 .. code-block:: LAMMPS
 
    special_bonds amber
-   pair_hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
+   pair_style hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
    pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0
 
 The this input achieves the same effect:
@@ -265,7 +265,7 @@ The this input achieves the same effect:
 .. code-block:: LAMMPS
 
    special_bonds 0.0 0.0 0.1
-   pair_hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
+   pair_style hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
    pair_modify pair lj/cut/coul/long special lj 0.0 0.0 0.5
    pair_modify pair lj/cut/coul/long special coul 0.0 0.0 0.83333333
    pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0
@@ -279,7 +279,7 @@ effectively *lj/coul 0.0 0.0 0.5* as required for OPLS/AA:
 .. code-block:: LAMMPS
 
    special_bonds lj/coul 1e-20 1e-20 0.5
-   pair_hybrid tersoff lj/cut/coul/long 12.0
+   pair_style hybrid tersoff lj/cut/coul/long 12.0
    pair_modify pair tersoff special lj/coul 1.0 1.0 1.0
 
 For use with the various :doc:`compute \*/tally <compute_tally>`
@@ -417,7 +417,11 @@ 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
+single sub-style.  If this requirement is not met, no I,J coeffs will be
+generated, even if the sub-styles support mixing, and I,J pair
+coefficients must be explicitly defined.
+
+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.
 
@@ -452,6 +456,9 @@ 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
 """"""""""""""""
 

doc/src/pair_style.rst

@@ -150,6 +150,8 @@ accelerated styles exist.
 * :doc:`coul/wolf <pair_coul>` - Coulomb via Wolf potential
 * :doc:`coul/wolf/cs <pair_cs>` - Coulomb via Wolf potential with core/shell adjustments
 * :doc:`dpd <pair_dpd>` - dissipative particle dynamics (DPD)
+* :doc:`dpd/ext <pair_dpd_ext>` - generalized force field for DPD
+* :doc:`dpd/ext/tstat <pair_dpd_ext>` - pair-wise DPD thermostatting  with generalized force field
 * :doc:`dpd/fdt <pair_dpd_fdt>` - DPD for constant temperature and pressure
 * :doc:`dpd/fdt/energy <pair_dpd_fdt>` - DPD for constant energy and enthalpy
 * :doc:`dpd/tstat <pair_dpd>` - pair-wise DPD thermostatting

doc/src/pair_thole.rst

@@ -42,6 +42,8 @@ Examples
 
    pair_style lj/cut/thole/long 2.6 12.0
 
+Example input scripts available: examples/USER/drude
+
 Description
 """""""""""
 

doc/src/read_data.rst

@@ -223,6 +223,9 @@ The structure of the data file is important, though many settings and
 sections are optional or can come in any order.  See the examples
 directory for sample data files for different problems.
 
+The file will be read line by line, but there is a limit of 254
+characters per line and characters beyond that limit will be ignored.
+
 A data file has a header and a body.  The header appears first.  The
 first line of the header is always skipped; it typically contains a
 description of the file.  Then lines are read one at a time.  Lines

doc/src/thermo_modify.rst

@@ -11,12 +11,13 @@ Syntax
    thermo_modify keyword value ...
 
 * one or more keyword/value pairs may be listed
-* keyword = *lost* or *lost/bond* or *norm* or *flush* or *line* or *format* or *temp* or *press*
+* keyword = *lost* or *lost/bond* or *warn* or *norm* or *flush* or *line* or *format* or *temp* or *press*
 
   .. parsed-literal::
 
        *lost* value = *error* or *warn* or *ignore*
        *lost/bond* value = *error* or *warn* or *ignore*
+       *warn* value = *ignore* or *reset* or *default* or a number
        *norm* value = *yes* or *no*
        *flush* value = *yes* or *no*
        *line* value = *one* or *multi*
@@ -75,6 +76,43 @@ are drifting out of the box through a fixed boundary condition (see
 the :doc:`boundary <boundary>` command).  In this case one atom may be
 deleted before the rest of the molecule is, on a later timestep.
 
+The *warn* keyword allows you to control whether LAMMPS will print
+warning messages and how many of them.  Most warning messages are only
+printed by MPI rank 0.  They are usually pointing out important issues
+that should be investigated, but LAMMPS cannot determine for
+certain whether they are an indication of an error.
+
+Some warning messages are printed during a run (or immediately before)
+each time a specific MPI rank encounters the issue, e.g. bonds that are
+stretched too far or dihedrals in extreme configurations. These number
+of these can quickly blow up the size of the log file and screen output.
+Thus a limit of 100 warning messages is applied by default.  The warning
+count is applied to the entire input unless reset with a ``thermo_modify
+warn reset`` command.  If there are more warnings than the limit, LAMMPS
+will print one final warning that it will not print any additional
+warning messages.
+
+.. note::
+
+   The warning limit is enforced on either the per-processor count or
+   the total count across all processors. For efficiency reasons,
+   however, the total count is only updated at steps with thermodynamic
+   output. Thus when running on a large number of processors in
+   parallel, the total number of warnings printed can be significantly
+   larger than the given limit.
+
+Any number after the keyword *warn* will change the warning limit
+accordingly.  With the value *ignore* all warnings will be suppressed,
+with the value *always* no limit will be applied and warnings will
+always be printed, with the value *reset* the internal warning counter
+will be reset to zero, and with the value *default*, the counter is
+reset and the limit set to 100.  An example usage of either *reset* or
+*default* would be to re-enable warnings that were disabled or have
+reached the limit during equilibration, where the warnings would be
+acceptable while the system is still adjusting, but then change
+to all warnings for the production run, where they would indicate
+problems that would require a closer look at what is causing them.
+
 The *norm* keyword determines whether various thermodynamic output
 values are normalized by the number of atoms or not, depending on
 whether it is set to *yes* or *no*\ .  Different unit styles have
@@ -183,9 +221,9 @@ Related commands
 Default
 """""""
 
-The option defaults are lost = error, norm = yes for unit style of
-*lj*\ , norm = no for unit style of *real* and *metal*\ , flush = no,
-and temp/press = compute IDs defined by thermo_style.
+The option defaults are lost = error, warn = 100, norm = yes for unit
+style of *lj*\ , norm = no for unit style of *real* and *metal*\ ,
+flush = no, and temp/press = compute IDs defined by thermo_style.
 
 The defaults for the line and format options depend on the thermo
 style.  For styles "one" and "custom", the line and format defaults

doc/src/variable.rst

@@ -363,12 +363,14 @@ variable, as discussed below.
 
 The rules for formatting the file are as follows.  Each time a set of
 per-atom values is read, a non-blank line is searched for in the file.
-A comment character "#" can be used anywhere on a line; text starting
-with the comment character is stripped.  Blank lines are skipped.  The
-first "word" of a non-blank line, delimited by white-space, is read as
-the count N of per-atom lines to immediately follow.  N can be the
-total number of atoms in the system, or only a subset.  The next N
-lines have the following format
+The file is read line by line but only up to 254 characters are used.
+The rest are ignored.  A comment character "#" can be used anywhere
+on a line and all text following and the "#" character are ignored;
+text starting with the comment character is stripped.  Blank lines
+are skipped.  The first "word" of a non-blank line, delimited by
+white-space, is read as the count N of per-atom lines to immediately
+follow.  N can be the total number of atoms in the system, or only a
+subset.  The next N lines have the following format
 
 .. parsed-literal::