big update

doc/Makefile

@@ -83,7 +83,7 @@ html: $(ANCHORCHECK) $(MATHJAX)
 	@rm -rf html/JPG
 	@cp -r src/PDF html/PDF
 	@mkdir -p html/JPG
-	@cp `grep -A2 '\.\. .*\(image\|figure\)::' src/*.rst | grep ':target:' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/
+	@cp `grep -A2 '\.\. .*\(image\|figure\)::' src/*.rst | grep ':target: JPG' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/
 	@rm -rf html/PDF/.[sg]*
 	@mkdir -p html/_static/mathjax
 	@cp -r $(MATHJAX)/es5 html/_static/mathjax/
@@ -194,9 +194,7 @@ $(VENV):
 		$(VIRTUALENV) -p $(PYTHON) $(VENV); \
 		. $(VENV)/bin/activate; \
 		pip install --upgrade pip; \
-		pip install Sphinx; \
+		pip install --use-feature=2020-resolver -r requirements.txt; \
-		pip install sphinxcontrib-spelling ;\
-		pip install breathe; \
 		deactivate;\
 	)
 

doc/github-development-workflow.md

@@ -25,10 +25,10 @@ In the interest of consistency, ONLY ONE of the core LAMMPS developers
 should doing the merging itself.  This is currently
 [@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer).
 If this assignment needs to be changed, it shall be done right after a
-stable release.  If the currently assigned developer cannot merge outstanding pull 
+stable release.  If the currently assigned developer cannot merge outstanding pull
-requests in a timely manner, or in other extenuating circumstances, 
+requests in a timely manner, or in other extenuating circumstances,
 other core LAMMPS developers with merge rights can merge pull requests,
-when necessary. 
+when necessary.
 
 ## Pull Requests
 

doc/include-file-conventions.md

@@ -65,7 +65,7 @@ Header files will typically contain the definition of a (single) class.
 These header files should have as few include statements as possible.
 This is particularly important for classes that implement a "style" and
 thus use a macro of the kind `SomeStyle(some/name,SomeName)`. These will
-all be included in the auto-generated `"some_style.h"` files which 
+all be included in the auto-generated `"some_style.h"` files which
 results in a high potential for direct or indirect symbol name clashes.
 
 In the ideal case, the header would only include one file defining the

doc/lammps.1

@@ -1,4 +1,4 @@
-.TH LAMMPS "15 April 2020" "2020-04-15"
+.TH LAMMPS "21 August 2020" "2020-08-21"
 .SH NAME
 .B LAMMPS
 \- Molecular Dynamics Simulator.

doc/requirements.txt

@@ -0,0 +1,4 @@
+Sphinx
+sphinxcontrib-spelling
+breathe
+Pygments

doc/src/Build_basics.rst

@@ -193,14 +193,17 @@ compiler and any :doc:`accelerator packages <Speed_packages>` you have
 included in the build.
 
 You can tell CMake to look for a specific compiler with setting CMake
-variable during configuration.  For a few common choices, there are also
+variables (listed below) during configuration.  For a few common
-presets in the ``cmake/presets`` folder.  For convenience, there is a
+choices, there are also presets in the ``cmake/presets`` folder.  For
-``CMAKE_TUNE_FLAGS`` variable that can be set to apply global compiler
+convenience, there is a ``CMAKE_TUNE_FLAGS`` variable that can be set to
-options.  More on that below, but you can also specify the corresponding
+apply global compiler options (applied to compilation only), to be used
-``CMAKE_*_FLAGS`` variables individually if you want to experiment with
+for adding compiler or host specific optimization flags in addition to
-alternate optimization flags.  You should specify all 3 compilers, so
+the "flags" variables listed below. You may also specify the
-that the (few) LAMMPS source files written in C or Fortran are built
+corresponding ``CMAKE_*_FLAGS`` variables individually, if you want to
-with a compiler consistent with the one used for the C++ files:
+experiment with alternate optimization flags.  You should specify all 3
+compilers, so that the (few) LAMMPS source files written in C or Fortran
+are built with a compiler consistent with the one used for the C++
+files:
 
 .. code-block:: bash
 
@@ -225,15 +228,11 @@ A few example command lines are:
 
 For compiling with the Clang/LLVM compilers a CMake preset is provided that
 can be loaded with `-C ../cmake/presets/clang.cmake`.  Similarly,
-`-C ../cmake/presets/intel.cmake` should switch the 
+`-C ../cmake/presets/intel.cmake` should switch the
 
 In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
 compiler flags to tune for optimal performance on given hosts. By
-default these are initialized to some compiler specific flags, to
+default this variable is empty.
-optimize the LAMMPS executable with optimizations and instructions
-available on the host where LAMMPS is compiled. For example, for Intel
-compilers this would be ``-xHost`` and for GNU compilers this would be
-``-march=native``. To turn these flags off, do ``-D CMAKE_TUNE_FLAGS=``.
 
 .. note::
 
@@ -372,7 +371,8 @@ it.  The build step will also create generic soft links, named
 ``liblammps.a`` and ``liblammps.so``\ , which point to the specific
 ``liblammps_machine.a/so`` files.
 
-**CMake and make info**\ :
+CMake and make info
+^^^^^^^^^^^^^^^^^^^
 
 Note that for creating a shared library, all the libraries it depends on
 must be compiled to be compatible with shared libraries.  This should be
@@ -462,7 +462,8 @@ tool.  The actual translation is then done via make commands.
 .. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
 .. _sphinx: https://sphinx-doc.org
 
-**Documentation make option**\ :
+Documentation make option
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following make commands can be issued in the doc folder of the
 LAMMPS source distribution.
@@ -489,7 +490,8 @@ your system.
    current LAMMPS version (HTML and PDF files), from the website
    `download page <https://lammps.sandia.gov/download.html>`_.
 
-**CMake build option**\ :
+CMake build option
+^^^^^^^^^^^^^^^^^^
 
 It is also possible to create the HTML version of the manual within
 the :doc:`CMake build directory <Build_cmake>`.  The reason for this
@@ -512,7 +514,8 @@ Build LAMMPS tools
 Some tools described in :doc:`Auxiliary tools <Tools>` can be built directly
 using CMake or Make.
 
-**CMake build3**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -521,7 +524,8 @@ using CMake or Make.
 The generated binaries will also become part of the LAMMPS installation
 (see below).
 
-**Traditional make**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -545,7 +549,8 @@ a globally visible place on your system, for others to access.  Note
 that you may need super-user privileges (e.g. sudo) if the directory
 you want to copy files to is protected.
 
-**CMake build**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -553,7 +558,8 @@ you want to copy files to is protected.
    make                        # perform make after CMake command
    make install                # perform the installation into prefix
 
-**Traditional make**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 There is no "install" option in the ``src/Makefile`` for LAMMPS.  If
 you wish to do this you will need to first build LAMMPS, then manually

doc/src/Build_cmake.rst

@@ -107,7 +107,7 @@ re-compile and relink the LAMMPS executable with ``cmake --build .`` (or
 ``cmake .`` and then compile again. The included dependency tracking
 should make certain that only the necessary subset of files are
 re-compiled.  You can also delete compiled objects, libraries and
-executables with ``cmake --build . clean`` (or ``make clean``).
+executables with ``cmake --build . --target clean`` (or ``make clean``).
 
 After compilation, you may optionally install the LAMMPS executable into
 your system with:

doc/src/Build_development.rst

@@ -8,8 +8,8 @@ useful during development, testing or debugging.
 
 .. _compilation:
 
-Verify compilation flags
+Monitor compilation flags
-------------------------
+-------------------------
 
 Sometimes it is necessary to verify the complete sequence of compilation flags
 generated by the CMake build. To enable a more verbose output during
@@ -19,7 +19,8 @@ compilation you can use the following option.
 
    -D CMAKE_VERBOSE_MAKEFILE=value    # value = no (default) or yes
 
-Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1:
+Another way of doing this without reconfiguration is calling make with
+variable VERBOSE set to 1:
 
 .. code-block:: bash
 
@@ -33,77 +34,385 @@ Address, Undefined Behavior, and Thread Sanitizer Support
 ---------------------------------------------------------
 
 Compilers such as GCC and Clang support generating instrumented binaries
-which use different sanitizer libraries to detect problems in code
+which use different sanitizer libraries to detect problems in the code
 during run-time. They can detect issues like:
 
  - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_
  - `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_
  - `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_
 
-Please note that this kind of instrumentation usually comes with a small
+Please note that this kind of instrumentation usually comes with a
-performance hit (much less than using tools like `Valgrind
+performance hit (but much less than using tools like `Valgrind
-<https://valgrind.org>`_).  The to enable these features additional
+<https://valgrind.org>`_ with a more low level approach).  The to enable
-compiler flags need to be added to the compilation and linking stages.
+these features additional compiler flags need to be added to the
-This is most easily done through setting the ``CMAKE_TUNE_FLAGS``
+compilation and linking stages.  This is done through setting the
-variable during configuration. Examples:
+``ENABLE_SANITIZER`` variable during configuration. Examples:
 
 .. code-block:: bash
 
-   -D CMAKE_TUNE_FLAGS=-fsanitize=address    # enable address sanitizer / memory leak checker
+   -D ENABLE_SANITIZER=none       # no sanitizer active (default)
-   -D CMAKE_TUNE_FLAGS=-fsanitize=undefined  # enable undefined behavior sanitizer
+   -D ENABLE_SANITIZER=address    # enable address sanitizer / memory leak checker
-   -D CMAKE_TUNE_FLAGS=-fsanitize=thread     # enable thread sanitizer
+   -D ENABLE_SANITIZER=leak       # enable memory leak checker (only)
+   -D ENABLE_SANITIZER=undefined  # enable undefined behavior sanitizer
+   -D ENABLE_SANITIZER=thread     # enable thread sanitizer
 
 ----------
 
 .. _testing:
 
-Code Coverage and Testing
+Code Coverage and Unit Testing
----------------------------------------
+------------------------------
 
-We do extensive regression testing of the LAMMPS code base on a continuous
+The LAMMPS code is subject to multiple levels of automated testing
-basis. Some of the logic to do this has been added to the CMake build so
+during development: integration testing (i.e. whether the code compiles
-developers can run the tests directly on their workstation.
+on various platforms and with a variety of settings), unit testing
+(i.e. whether certain individual parts of the code produce the expected
+results for given inputs), run testing (whether selected complete input
+decks run without crashing for multiple configurations), and regression
+testing (i.e. whether selected input examples reproduce the same
+results over a given number of steps and operations within a given
+error margin).  The status of this automated testing can be viewed on
+`https://ci.lammps.org <https://ci.lammps.org>`_.
+
+The unit testing facility is integrated into the CMake build process
+of the LAMMPS source code distribution itself.  It can be enabled by
+setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.
+It requires the `YAML <http://pyyaml.org/>`_ library and development
+headers to compile and will download and compile a recent version of the
+`Googletest <https://github.com/google/googletest/>`_ C++ test framework
+for implementing the tests.
+
+After compilation is complete, the unit testing is started in the build
+folder using the ``ctest`` command, which is part of the CMake software.
+The output of this command will be looking something like this::
+
+   [...]$ ctest
+   Test project /home/akohlmey/compile/lammps/build-testing
+         Start  1: MolPairStyle:hybrid-overlay
+   1/109 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec
+         Start  2: MolPairStyle:hybrid
+   2/109 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec
+         Start  3: MolPairStyle:lj_class2
+    [...]
+         Start 107: PotentialFileReader
+ 107/109 Test #107: PotentialFileReader ................   Passed    0.04 sec
+         Start 108: EIMPotentialFileReader
+ 108/109 Test #108: EIMPotentialFileReader .............   Passed    0.03 sec
+         Start 109: TestSimpleCommands
+ 109/109 Test #109: TestSimpleCommands .................   Passed    0.02 sec
+
+   100% tests passed, 0 tests failed out of 26
+
+   Total Test time (real) =  25.57 sec
+
+
+The ``ctest`` command has many options, the most important ones are:
+
+.. list-table::
+
+   * - Option
+     - Function
+   * - -V
+     - verbose output: display output of individual test runs
+   * - -j <num>
+     - parallel run: run <num> tests in parallel
+   * - -R <regex>
+     - run subset of tests matching the regular expression <regex>
+   * - -E <regex>
+     - exclude subset of tests matching the regular expression <regex>
+   * - -N
+     - dry-run: display list of tests without running them
+   * - -T memcheck
+     - run tests with valgrind memory checker (if available)
+
+In its full implementation, the unit test framework will consist of multiple
+kinds of tests implemented in different programming languages (C++, C, Python,
+Fortran) and testing different aspects of the LAMMPS software and its features.
+At the moment only tests for "force styles" are implemented. More on those
+in the next section.
 
 .. note::
 
-   this is incomplete and only represents a small subset of tests that we run
+   The unit test framework is new and still under development.
+   The coverage is only minimal and will be expanded over time.
+   Tests styles of the same kind of style (e.g. pair styles or
+   bond styles) are performed with the same executable using
+   different input files in YAML format.  So to add a test for
+   another pair style can be done by copying the YAML file and
+   editing the style settings and then running the individual test
+   program with a flag to update the computed reference data.
+   Detailed documentation about how to add new test program and
+   the contents of the YAML files for existing test programs
+   will be provided in time as well.
+
+Unit tests for force styles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A large part of LAMMPS are different "styles" for computing non-bonded
+and bonded interactions selected through the :doc:`pair_style`,
+:doc:`bond_style`, :doc:`angle_style`, :doc:`dihedral_style`,
+:doc:`improper_style`, and :doc:`kspace_style`.  Since these all share
+common interfaces, it is possible to write generic test programs that
+will call those common interfaces for small test systems with less than
+100 atoms and compare the results with pre-recorded reference results.
+A test run is then a a collection multiple individual test runs each
+with many comparisons to reference results based on template input
+files, individual command settings, relative error margins, and
+reference data stored in a YAML format file with ``.yaml``
+suffix. Currently the programs ``test_pair_style``, ``test_bond_style``, and
+``test_angle_style`` are implemented.  They will compare forces, energies and
+(global) stress for all atoms after a ``run 0`` calculation and after a
+few steps of MD with :doc:`fix nve <fix_nve>`, each in multiple variants
+with different settings and also for multiple accelerated styles. If a
+prerequisite style or package is missing, the individual tests are
+skipped.  All tests will be executed on a single MPI process, so using
+the CMake option ``-D BUILD_MPI=off`` can significantly speed up testing,
+since this will skip the MPI initialization for each test run.
+Below is an example command and output:
+
+.. parsed-literal::
+
+   [tests]$ test_pair_style mol-pair-lj_cut.yaml
+   [==========] Running 6 tests from 1 test suite.
+   [----------] Global test environment set-up.
+   [----------] 6 tests from PairStyle
+   [ RUN      ] PairStyle.plain
+   [       OK ] PairStyle.plain (24 ms)
+   [ RUN      ] PairStyle.omp
+   [       OK ] PairStyle.omp (18 ms)
+   [ RUN      ] PairStyle.intel
+   [       OK ] PairStyle.intel (6 ms)
+   [ RUN      ] PairStyle.opt
+   [  SKIPPED ] PairStyle.opt (0 ms)
+   [ RUN      ] PairStyle.single
+   [       OK ] PairStyle.single (7 ms)
+   [ RUN      ] PairStyle.extract
+   [       OK ] PairStyle.extract (6 ms)
+   [----------] 6 tests from PairStyle (62 ms total)
+
+   [----------] Global test environment tear-down
+   [==========] 6 tests from 1 test suite ran. (63 ms total)
+   [  PASSED  ] 5 tests.
+   [  SKIPPED ] 1 test, listed below:
+   [  SKIPPED ] PairStyle.opt
+
+In this particular case, 5 out of 6 sets of tests were conducted, the
+tests for the ``lj/cut/opt`` pair style was skipped, since the tests
+executable did not include it.  To learn what individual tests are performed,
+you (currently) need to read the source code.  You can use code coverage
+recording (see next section) to confirm how well the tests cover the code
+paths in the individual source files.
+
+The force style test programs have a common set of options:
+
+.. list-table::
+
+   * - Option
+     - Function
+   * - -g <newfile>
+     - regenerate reference data in new YAML file
+   * - -u
+     - update reference data in the original YAML file
+   * - -s
+     - print error statistics for each group of comparisons
+   * - -v
+     - verbose output: also print the executed LAMMPS commands
+
+The ``ctest`` tool has no mechanism to directly pass flags to the individual
+test programs, but a workaround has been implemented where these flags can be
+set in an environment variable ``TEST_ARGS``. Example:
 
 .. code-block:: bash
 
-   -D ENABLE_TESTING=value               # enable simple run tests of LAMMPS, value = no (default) or yes
+   env TEST_ARGS=-s ctest -V -R BondStyle
-   -D LAMMPS_TESTING_SOURCE_DIR=path     # path to lammps-testing repository (option if in custom location)
-   -D LAMMPS_TESTING_GIT_TAG=value       # version of lammps-testing repository that should be used, value = master (default) or custom git commit or tag
 
-If you enable testing in the CMake build it will create an additional
+To add a test for a style that is not yet covered, it is usually best
-target called "test". You can run them with:
+to copy a YAML file for a similar style to a new file, edit the details
+of the style (how to call it, how to set its coefficients) and then
+run test command with either the *-g* and the replace the initial
+test file with the regenerated one or the *-u* option.  The *-u* option
+will destroy the original file, if the generation run does not complete,
+so using *-g* is recommended unless the YAML file is fully tested
+and working.
+
+.. admonition:: Recommendations and notes for YAML files
+   :class: note
+
+   - The reference results should be recorded without any code
+     optimization or related compiler flags enabled.
+   - The ``epsilon`` parameter defines the relative precision with which
+     the reference results must be met.  The test geometries often have
+     high and low energy parts and thus a significant impact from
+     floating-point math truncation errors is to be expected. Some
+     functional forms and potentials are more noisy than others, so this
+     parameter needs to be adjusted. Typically a value around 1.0e-13
+     can be used, but it may need to be as large as 1.0e-8 in some
+     cases.
+   - The tests for pair styles from OPT, USER-OMP and USER-INTEL are
+     performed with automatically rescaled epsilon to account for
+     additional loss of precision from code optimizations and different
+     summation orders.
+   - When compiling with (aggressive) compiler optimization, some tests
+     are likely to fail.  It is recommended to inspect the individual
+     tests in detail to decide, whether the specific error for a specific
+     property is acceptable (it often is), or this may be an indication
+     of mis-compiled code (or an undesired large loss of precision due
+     to significant reordering of operations and thus less error cancellation).
+
+Unit tests for timestepping related fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A substantial subset of :doc:`fix styles <fix>` are invoked regularly
+during MD timestepping and manipulate per-atom properties like
+positions, velocities, and forces.  For those fix styles, testing can be
+done in a very similar fashion as for force fields and thus there is a
+test program `test_fix_timestep` that shares a lot of code, properties,
+and command line flags with the force field style testers described in
+the previous section.
+
+This tester will set up a small molecular system run with verlet run
+style for 4 MD steps, then write a binary restart and continue for
+another 4 MD steps. At this point coordinates and velocities are
+recorded and compared to reference data. Then the system is cleared,
+restarted and running the second 4 MD steps again and the data is
+compared to the same reference. That is followed by another restart
+after which per atom type masses are replaced with per-atom masses and
+the second 4 MD steps are repeated again and compared to the same
+reference.  Also global scalar and vector data of the fix is recorded
+and compared.  If the fix is a thermostat and thus the internal property
+``t_target`` can be extracted, then this is compared to the reference
+data.  The tests are repeated with the respa run style.
+
+If the fix has a multi-threaded version in the USER-OMP package, then
+the entire set of tests is repeated for that version as well.
+
+For this to work, some additional conditions have to be met by the
+YAML format test inputs.
+
+- The fix to be tested (and only this fix), should be listed in the
+  ``prerequisites:`` section
+- The fix to be tested must be specified in the ``post_commands:``
+  section with the fix-ID ``test``.  This section may contain other
+  commands and other fixes (e.g. an instance of fix nve for testing
+  a thermostat or force manipulation fix)
+- For fixes that can tally contributions to the global virial, the
+  line ``fix_modify test virial yes`` should be included in the
+  ``post_commands:`` section of the test input.
+- For thermostat fixes the target temperature should be ramped from
+  an arbitrary value (e.g. 50K) to a pre-defined target temperature
+  entered as ``${t_target}``.
+- For fixes that have thermostatting support included, but do not
+  have it enabled in the input (e.g. fix rigid with default settings),
+  the ``post_commands:`` section should contain the line
+  ``variable t_target delete`` to disable the target temperature ramp
+  check to avoid false positives.
+
+Use custom linker for faster link times when ENABLE_TESTING is active
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When compiling LAMMPS with enabled tests, most test executables will
+need to be linked against the LAMMPS library.  Since this can be a very
+large library with many C++ objects when many packages are enabled, link
+times can become very long on machines that use the GNU BFD linker (e.g.
+Linux systems).  Alternatives like the ``lld`` linker of the LLVM project
+or the ``gold`` linker available with GNU binutils can speed up this step
+substantially. CMake will by default test if any of the two can be
+enabled and use it when ``ENABLE_TESTING`` is active.  It can also be
+selected manually through the ``CMAKE_CUSTOM_LINKER`` CMake variable.
+Allowed values are ``lld``, ``gold``, ``bfd``, or ``default``.  The
+``default`` option will use the system default linker otherwise, the
+linker is chosen explicitly.  This option is only available for the
+GNU or Clang C++ compiler.
+
+Tests for other components and utility functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Additional tests that validate utility functions or specific components
+of LAMMPS are implemented as standalone executable which may, or may not
+require creating a suitable LAMMPS instance.  These tests are more specific
+and do not require YAML format input files.  To add a test, either an
+existing source file needs to be extended or a new file added, which in turn
+requires additions to the ``CMakeLists.txt`` file in the source folder.
+
+Collect and visualize code coverage metrics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also collect code coverage metrics while running LAMMPS or the
+tests by enabling code coverage support during the CMake configuration:
 
 .. code-block:: bash
 
-   cmake --build . test
+   -D ENABLE_COVERAGE=on  # enable coverage measurements (off by default)
 
-The test cases used come from the lammps-testing repository. They are
+This will instrument all object files to write information about which
-derivatives of the examples folder with some modifications to make the
+lines of code were accessed during execution in files next to the
-run faster.
+corresponding object files.  These can be post-processed to visually
+show the degree of coverage and which code paths are accessed and which
+are not taken.  When working on unit tests (see above), this can be
+extremely helpful to determine which parts of the code are not executed
+and thus what kind of tests are still missing. The coverage data is
+cumulative, i.e. new data is added with each new run.
 
-You can also collect code coverage metrics while running the tests by
+Enabling code coverage will also add the following build targets to
-enabling coverage support during building.
+generate coverage reports after running the LAMMPS executable or the
+unit tests:
 
 .. code-block:: bash
 
-   -D ENABLE_COVERAGE=value  # enable coverage measurements, value = no (default) or yes
+   make gen_coverage_html   # generate coverage report in HTML format
+   make gen_coverage_xml    # generate coverage report in XML format
+   make clean_coverage_html # delete folder with HTML format coverage report
+   make reset_coverage      # delete all collected coverage data and HTML output
 
-This will also add the following targets to generate coverage reports
+These reports require `GCOVR <https://gcovr.com/>`_ to be installed. The easiest way
-after running the LAMMPS executable:
+to do this to install it via pip:
-
-.. code-block:: bash
-
-   make test               # run tests first!
-   make gen_coverage_html  # generate coverage report in HTML format
-   make gen_coverage_xml   # generate coverage report in XML format
-
-These reports require GCOVR to be installed. The easiest way to do this
-to install it via pip:
 
 .. code-block:: bash
 
    pip install git+https://github.com/gcovr/gcovr.git
+
+After post-processing with ``gen_coverage_html`` the results are in
+a folder ``coverage_html`` and can be viewed with a web browser.
+The images below illustrate how the data is presented.
+
+.. list-table::
+
+      * - .. figure:: JPG/coverage-overview-top.png
+             :target: JPG/coverage-overview-top.png
+
+          Top of the overview page
+
+        - .. figure:: JPG/coverage-overview-manybody.png
+             :target: JPG/coverage-overview-manybody.png
+
+          Styles with good coverage
+
+        - .. figure:: JPG/coverage-file-top.png
+             :target: JPG/coverage-file-top.png
+
+          Top of individual source page
+
+        - .. figure:: JPG/coverage-file-branches.png
+             :target: JPG/coverage-file-branches.png
+
+          Source page with branches
+
+Coding style utilities
+----------------------
+
+To aid with enforcing some of the coding style conventions in LAMMPS
+some additional build targets have been added. These require Python 3.5
+or later and will only work on Unix-like operating and file systems.
+The following options are available.
+
+.. code-block:: bash
+
+   make check-whitespace    # generate coverage report in HTML format
+   make fix-whitespace      # generate coverage report in XML format
+   make check-permissions   # delete folder with HTML format coverage report
+   make fix-permissions     # delete all collected coverage data and HTML output
+
+For the code in the ``unittest`` tree we are using the `clang-format`
+tool (Clang version 8.0 or later is required). If available, the source
+code files in the ``unittest`` tree can be updated to conform to the
+formatting settings using ``make format-tests``.

doc/src/Build_link.rst

@@ -1,12 +1,12 @@
 Link LAMMPS as a library to another code
 ========================================
 
-LAMMPS is designed as a library of C++ objects and can thus be
+LAMMPS is designed as a library of C++ objects that can be
 integrated into other applications including Python scripts.
 The files ``src/library.cpp`` and ``src/library.h`` define a
 C-style API for using LAMMPS as a library.  See the :doc:`Howto
-library <Howto_library>` doc page for a description of the interface
+library <Howto_library>` page for a description of the interface
-and how to extend it for your needs.
+and how to use it for your needs.
 
 The :doc:`Build basics <Build_basics>` doc page explains how to build
 LAMMPS as either a shared or static library.  This results in a file
@@ -31,18 +31,18 @@ the suffix ``.so.0`` (or some other number).
    communicator with a subset of MPI ranks to the function creating the
    LAMMPS instance.
 
-----------
+Link with LAMMPS as a static library
-
+------------------------------------
-**Link with LAMMPS as a static library**\ :
 
 The calling application can link to LAMMPS as a static library with
 compilation and link commands as in the examples shown below.  These
-are examples for a code written in C in the file *caller.c*.
+are examples for a code written in C in the file ``caller.c``.
 The benefit of linking to a static library is, that the resulting
 executable is independent of that library since all required
 executable code from the library is copied into the calling executable.
 
-*CMake build*\ :
+CMake build
+^^^^^^^^^^^
 
 This assumes that LAMMPS has been configured without setting a
 ``LAMMPS_MACHINE`` name, installed with "make install", and the
@@ -55,7 +55,8 @@ The commands to compile and link a coupled executable are then:
    mpicc -c -O $(pkgconf liblammps --cflags) caller.c
    mpicxx -o caller caller.o -$(pkgconf liblammps --libs)
 
-*Traditional make*\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 This assumes that LAMMPS has been compiled in the folder
 ``${HOME}/lammps/src`` with "make mpi". The commands to compile and link
@@ -83,20 +84,20 @@ LAMMPS library without any optional packages that depend on libraries
 need to include all flags, libraries, and paths for the coupled
 executable, that are also required to link the LAMMPS executable.
 
-*CMake build*\ :
+CMake build
+^^^^^^^^^^^
 
 When using CMake, additional libraries with sources in the lib folder
 are built, but not included in ``liblammps.a`` and (currently) not
-installed with "make install" and not included in the *pkgconfig*
+installed with ``make install`` and not included in the ``pkgconfig``
 configuration file.  They can be found in the top level build folder,
 but you have to determine the necessary link flags manually.  It is
 therefore recommended to either use the traditional make procedure to
 build and link with a static library or build and link with a shared
 library instead.
 
-.. TODO: this needs to be updated to reflect that latest CMake changes after they are complete.
+Traditional make
-
+^^^^^^^^^^^^^^^^
-*Traditional make*\ :
 
 After you have compiled a static LAMMPS library using the conventional
 build system for example with "make mode=static serial". And you also
@@ -110,10 +111,10 @@ change to:
    g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
      -L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src -llammps_serial -lpoems -lmpi_stubs
 
-Note, that you need to link with "g++" instead of "gcc", since the
+Note, that you need to link with ``g++`` instead of ``gcc`` even if you have
-LAMMPS library is C++ code.  You can display the currently applied
+written your code in C, since LAMMPS itself is C++ code.  You can display the
-settings for building LAMMPS for the "serial" machine target by using
+currently applied settings for building LAMMPS for the "serial" machine target
-the command:
+by using the command:
 
 .. code-block:: bash
 
@@ -123,25 +124,24 @@ Which should output something like:
 
 .. code-block:: bash
 
-   # Compiler: 
+   # Compiler:
    CXX=g++
-   # Linker: 
+   # Linker:
    LD=g++
-   # Compilation: 
+   # Compilation:
    CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS
-   # Linking: 
+   # Linking:
    LDFLAGS=-g -O
-   # Libraries: 
+   # Libraries:
    LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs
 
 From this you can gather the necessary paths and flags.  With
 makefiles for other *machine* configurations you need to do the
-equivalent and replace "serial" with the corresponding *machine* name
+equivalent and replace "serial" with the corresponding "machine" name
 of the makefile.
 
-----------
+Link with LAMMPS as a shared library
-
+------------------------------------
-**Link with LAMMPS as a shared library**\ :
 
 When linking to LAMMPS built as a shared library, the situation becomes
 much simpler, as all dependent libraries and objects are either included
@@ -151,7 +151,8 @@ linking the calling executable.  Only the *-I* flags are needed.  So the
 example case from above of the serial version static LAMMPS library with
 the POEMS package installed becomes:
 
-*CMake build*\ :
+CMake build
+^^^^^^^^^^^
 
 The commands with a shared LAMMPS library compiled with the CMake
 build process are the same as for the static library.
@@ -161,10 +162,11 @@ build process are the same as for the static library.
    mpicc -c -O $(pkgconf liblammps --cflags) caller.c
    mpicxx -o caller caller.o -$(pkgconf --libs)
 
-*Traditional make*\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 The commands with a shared LAMMPS library compiled with the
-traditional make build using "make mode=shared serial" becomes:
+traditional make build using ``make mode=shared serial`` becomes:
 
 .. code-block:: bash
 
@@ -231,29 +233,3 @@ If a required library is missing, you would get a 'not found' entry:
         libc.so.6 => /usr/lib64/libc.so.6 (0x00007fb7c7b5d000)
         /lib64/ld-linux-x86-64.so.2 (0x00007fb7c80a2000)
 
-----------
-
-**Calling the LAMMPS library**\ :
-
-Either flavor of library (static or shared) allows one or more LAMMPS
-objects to be instantiated from the calling program. When used from a
-C++ program, most of the symbols and functions in LAMMPS are wrapped
-in a ``LAMMPS_NS`` namespace; you can safely use any of its classes and
-methods from within the calling code, as needed, and you will not incur
-conflicts with functions and variables in your code that share the name.
-This, however, does not extend to all additional libraries bundled with
-LAMMPS in the lib folder and some of the low-level code of some packages.
-
-To be compatible with C, Fortran, Python programs, the library has a simple
-C-style interface, provided in ``src/library.cpp`` and ``src/library.h``.
-
-See the :doc:`Python library <Python_library>` doc page for a
-description of the Python interface to LAMMPS, which wraps the C-style
-interface from a shared library through the `ctypes python module <ctypes_>`_.
-
-See the sample codes in ``examples/COUPLE/simple`` for examples of C++ and
-C and Fortran codes that invoke LAMMPS through its library interface.
-Other examples in the COUPLE directory use coupling ideas discussed on
-the :doc:`Howto couple <Howto_couple>` doc page.
-
-.. _ctypes: https://docs.python.org/3/library/ctypes.html

doc/src/Build_package.rst

@@ -45,7 +45,8 @@ packages:
 The mechanism for including packages is simple but different for CMake
 versus make.
 
-**CMake build**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: csh
 
@@ -72,7 +73,8 @@ once with CMake.
    invoke cmake.  CMake will give an error if that is not the case,
    indicating how you can un-install all packages in the src dir.
 
-**Traditional make**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -108,7 +110,8 @@ once with make.
    within the same command.  You can include or exclude multiple packages
    in a single make command, e.g. make yes-colloid no-manybody.
 
-**CMake and make info**\ :
+CMake and make info
+^^^^^^^^^^^^^^^^^^^
 
 Any package can be included or excluded in a LAMMPS build, independent
 of all other packages.  However, some packages include files derived
@@ -132,7 +135,7 @@ src directory.
 
 .. _cmake_presets:
 
-**CMake shortcuts for installing many packages**\ :
+CMake presets for installing many packages
 
 Instead of specifying all the CMake options via the command-line,
 CMake allows initializing its settings cache using script files.
@@ -148,13 +151,14 @@ one of them as a starting point and customize it to your needs.
 
 .. code-block:: bash
 
-    cmake -C ../cmake/presets/minimal.cmake [OPTIONS] ../cmake  # enable just a few core packages
+    cmake -C ../cmake/presets/minimal.cmake  [OPTIONS] ../cmake  # enable just a few core packages
-    cmake -C ../cmake/presets/most.cmake    [OPTIONS] ../cmake  # enable most packages
+    cmake -C ../cmake/presets/most.cmake     [OPTIONS] ../cmake  # enable most packages
-    cmake -C ../cmake/presets/nolib.cmake   [OPTIONS] ../cmake  # disable packages that do require extra libraries or tools
+    cmake -C ../cmake/presets/download.cmake [OPTIONS] ../cmake  # enable packages which download sources or potential files
-    cmake -C ../cmake/presets/clang.cmake   [OPTIONS] ../cmake  # change settings to use the Clang compilers by default
+    cmake -C ../cmake/presets/nolib.cmake    [OPTIONS] ../cmake  # disable packages that do require extra libraries or tools
-    cmake -C ../cmake/presets/intel.cmake   [OPTIONS] ../cmake  # change settings to use the Intel compilers by default
+    cmake -C ../cmake/presets/clang.cmake    [OPTIONS] ../cmake  # change settings to use the Clang compilers by default
-    cmake -C ../cmake/presets/all_on.cmake  [OPTIONS] ../cmake  # enable all packages
+    cmake -C ../cmake/presets/intel.cmake    [OPTIONS] ../cmake  # change settings to use the Intel compilers by default
-    cmake -C ../cmake/presets/all_off.cmake [OPTIONS] ../cmake  # disable all packages
+    cmake -C ../cmake/presets/all_on.cmake   [OPTIONS] ../cmake  # enable all packages
+    cmake -C ../cmake/presets/all_off.cmake  [OPTIONS] ../cmake  # disable all packages
     mingw64-cmake -C ../cmake/presets/mingw-cross.cmake [OPTIONS] ../cmake  #  compile with MinGW cross compilers
 
 .. note::
@@ -184,7 +188,8 @@ one of them as a starting point and customize it to your needs.
 
 ----------
 
-**Make shortcuts for installing many packages**\ :
+Make shortcuts for installing many packages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following commands are useful for managing package source files
 and their installation when building LAMMPS via traditional make.

doc/src/Build_settings.rst

@@ -44,7 +44,8 @@ require use of an FFT library to compute 1d FFTs.  The KISS FFT
 library is included with LAMMPS but other libraries can be faster.
 LAMMPS can use them if they are available on your system.
 
-**CMake variables**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -74,7 +75,12 @@ to assist:
    -D FFT_MKL_THREADS=on       # enable using threaded FFTs with MKL libraries
    -D MKL_LIBRARIES=path
 
-**Makefile.machine settings**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
+
+To change the FFT library to be used and its options, you have to edit
+your machine Makefile. Below are examples how the makefile variables
+could be changed.
 
 .. code-block:: make
 
@@ -104,7 +110,8 @@ As with CMake, you do not need to set paths in ``FFT_INC`` or ``FFT_PATH``, if
 the compiler can find the FFT header and library files in its default search path.
 You must specify ``FFT_LIB`` with the appropriate FFT libraries to include in the link.
 
-**CMake and make info**\ :
+CMake build
+^^^^^^^^^^^
 
 The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS
 distribution.  It is portable across all platforms.  Depending on the size
@@ -127,7 +134,7 @@ download it from `www.fftw.org <http://www.fftw.org>`_.  LAMMPS requires
 version 3.X; the legacy version 2.1.X is no longer supported.
 
 Building FFTW for your box should be as simple as ``./configure; make;
-make install``\ .  The install command typically requires root privileges
+make install``.  The install command typically requires root privileges
 (e.g. invoke it via sudo), unless you specify a local directory with
 the "--prefix" option of configure.  Type ``./configure --help`` to see
 various options.
@@ -169,20 +176,25 @@ ARRAY mode.
 
 .. _size:
 
-Size of LAMMPS data types
+Size of LAMMPS integer types
 ------------------------------------
 
-LAMMPS has a few integer data types which can be defined as 4-byte or
+LAMMPS has a few integer data types which can be defined as either
-8-byte integers.  The default setting of "smallbig" is almost always
+4-byte (= 32-bit) or 8-byte (= 64-bit) integers at compile time.
-adequate.
+The default setting of "smallbig" is almost always adequate.
 
-**CMake variable**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
    -D LAMMPS_SIZES=value   # smallbig (default) or bigbig or smallsmall
 
-**Makefile.machine setting**\ :
+Traditional build
+^^^^^^^^^^^^^^^^^
+
+If you want a setting different from the default, you need to edit your
+machine Makefile.
 
 .. code-block:: make
 
@@ -190,7 +202,8 @@ adequate.
 
 The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified
 
-**CMake and make info**\ :
+CMake and make info
+^^^^^^^^^^^^^^^^^^^
 
 The default "smallbig" setting allows for simulations with:
 
@@ -251,7 +264,8 @@ PNG image files.  Likewise the :doc:`dump movie <dump_image>` command
 outputs movie files in MPEG format.  Using these options requires the
 following settings:
 
-**CMake variables**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -276,7 +290,8 @@ variables:
    -D ZLIB_LIBRARIES=path      # path to libz.a (.so) file
    -D FFMPEG_EXECUTABLE=path   # path to ffmpeg executable
 
-**Makefile.machine settings**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 .. code-block:: make
 
@@ -295,7 +310,8 @@ with a list of graphics libraries to include in the link.  You must
 insure ffmpeg is in a directory where LAMMPS can find it at runtime,
 that is a directory in your PATH environment variable.
 
-**CMake and make info**\ :
+CMake and make info
+^^^^^^^^^^^^^^^^^^^
 
 Using ``ffmpeg`` to output movie files requires that your machine
 supports the "popen" function in the standard runtime library.
@@ -318,7 +334,8 @@ If this option is enabled, large files can be read or written with
 gzip compression by several LAMMPS commands, including
 :doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`.
 
-**CMake variables**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -326,13 +343,15 @@ gzip compression by several LAMMPS commands, including
                             # default is yes if CMake can find gzip, else no
    -D GZIP_EXECUTABLE=path  # path to gzip executable if CMake cannot find it
 
-**Makefile.machine setting**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 .. code-block:: make
 
    LMP_INC = -DLAMMPS_GZIP
 
-**CMake and make info**\ :
+CMake and make info
+^^^^^^^^^^^^^^^^^^^
 
 This option requires that your machine supports the "popen()" function
 in the standard runtime library and that a gzip executable can be
@@ -363,7 +382,8 @@ pointers that are aligned to 16-byte boundaries. Using SSE vector
 instructions efficiently, however, requires memory blocks being
 aligned on 64-byte boundaries.
 
-**CMake variable**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
@@ -374,7 +394,8 @@ and revert to using the malloc() C-library function instead.  When
 compiling LAMMPS for Windows systems, malloc() will always be used
 and this setting ignored.
 
-**Makefile.machine setting**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 .. code-block:: make
 
@@ -398,13 +419,15 @@ types, the following setting will be needed.  It converts "long long"
 to a "long" data type, which should be the desired 8-byte integer on
 those systems:
 
-**CMake variable**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
    -D LAMMPS_LONGLONG_TO_LONG=value     # yes or no (default)
 
-**Makefile.machine setting**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 .. code-block:: make
 
@@ -420,17 +443,26 @@ Exception handling when using LAMMPS as a library
 This setting is useful when external codes drive LAMMPS as a library.
 With this option enabled, LAMMPS errors do not kill the calling code.
 Instead, the call stack is unwound and control returns to the caller,
-e.g. to Python. Of course the calling code has to be set up to
+e.g. to Python. Of course, the calling code has to be set up to
-*catch* exceptions from within LAMMPS.
+*catch* exceptions thrown from within LAMMPS.
 
-**CMake variable**\ :
+CMake build
+^^^^^^^^^^^
 
 .. code-block:: bash
 
    -D LAMMPS_EXCEPTIONS=value        # yes or no (default)
 
-**Makefile.machine setting**\ :
+Traditional make
+^^^^^^^^^^^^^^^^
 
 .. code-block:: make
 
    LMP_INC = -DLAMMPS_EXCEPTIONS
+
+.. note::
+
+   When LAMMPS is running in parallel, it is not always possible to
+   cleanly recover from an exception since not all parallel ranks may
+   throw an exception and thus other MPI ranks may get stuck waiting for
+   messages from the ones with errors.

doc/src/Build_windows.rst

@@ -38,7 +38,7 @@ optional Windows feature allows you to run the bash shell from Ubuntu
 from within Windows and from there on, you can pretty much use that
 shell like you are running on an Ubuntu Linux machine (e.g. installing
 software via apt-get and more). For more details on that, please
-see :doc:`this tutorial <Howto_bash>`
+see :doc:`this tutorial <Howto_wsl>`
 
 .. _gnu:
 

doc/src/Commands_all.rst

@@ -46,13 +46,6 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`dimension <dimension>`
    * :doc:`displace_atoms <displace_atoms>`
    * :doc:`dump <dump>`
-   * :doc:`dump atom/adios <dump_adios>`
-   * :doc:`dump custom/adios <dump_adios>`
-   * :doc:`dump image <dump_image>`
-   * :doc:`dump movie <dump_image>`
-   * :doc:`dump netcdf <dump_netcdf>`
-   * :doc:`dump netcdf/mpiio <dump_netcdf>`
-   * :doc:`dump vtk <dump_vtk>`
    * :doc:`dump_modify <dump_modify>`
    * :doc:`dynamical_matrix <dynamical_matrix>`
    * :doc:`echo <echo>`
@@ -94,6 +87,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`package <package>`
    * :doc:`pair_coeff <pair_coeff>`
    * :doc:`pair_modify <pair_modify>`
+   * :doc:`pair_style <pair_style>`
    * :doc:`pair_write <pair_write>`
    * :doc:`partition <partition>`
    * :doc:`prd <prd>`
@@ -107,7 +101,8 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`region <region>`
    * :doc:`replicate <replicate>`
    * :doc:`rerun <rerun>`
-   * :doc:`reset_ids <reset_ids>`
+   * :doc:`reset_atom_ids <reset_atom_ids>`
+   * :doc:`reset_mol_ids <reset_mol_ids>`
    * :doc:`reset_timestep <reset_timestep>`
    * :doc:`restart <restart>`
    * :doc:`run <run>`

doc/src/Commands_bond.rst

@@ -46,6 +46,7 @@ OPT.
    * :doc:`oxdna2/fene <bond_oxdna>`
    * :doc:`oxrna2/fene <bond_oxdna>`
    * :doc:`quartic (o) <bond_quartic>`
+   * :doc:`special <bond_special>`
    * :doc:`table (o) <bond_table>`
 
 .. _angle:

doc/src/Commands_compute.rst

@@ -42,7 +42,7 @@ KOKKOS, o = USER-OMP, t = OPT.
    * :doc:`com <compute_com>`
    * :doc:`com/chunk <compute_com_chunk>`
    * :doc:`contact/atom <compute_contact_atom>`
-   * :doc:`coord/atom <compute_coord_atom>`
+   * :doc:`coord/atom (k) <compute_coord_atom>`
    * :doc:`damage/atom <compute_damage_atom>`
    * :doc:`dihedral <compute_dihedral>`
    * :doc:`dihedral/local <compute_dihedral_local>`
@@ -79,9 +79,8 @@ KOKKOS, o = USER-OMP, t = OPT.
    * :doc:`ke/atom/eff <compute_ke_atom_eff>`
    * :doc:`ke/eff <compute_ke_eff>`
    * :doc:`ke/rigid <compute_ke_rigid>`
-   * :doc:`meso/e/atom <compute_meso_e_atom>`
+   * :doc:`mesont <compute_mesont>`
-   * :doc:`meso/rho/atom <compute_meso_rho_atom>`
+   * :doc:`mliap <compute_mliap>`
-   * :doc:`meso/t/atom <compute_meso_t_atom>`
    * :doc:`momentum <compute_momentum>`
    * :doc:`msd <compute_msd>`
    * :doc:`msd/chunk <compute_msd_chunk>`
@@ -124,6 +123,7 @@ KOKKOS, o = USER-OMP, t = OPT.
    * :doc:`smd/tlsph/strain/rate <compute_smd_tlsph_strain_rate>`
    * :doc:`smd/tlsph/stress <compute_smd_tlsph_stress>`
    * :doc:`smd/triangle/vertices <compute_smd_triangle_vertices>`
+   * :doc:`smd/ulsph/effm <compute_smd_ulsph_effm>`
    * :doc:`smd/ulsph/num/neighs <compute_smd_ulsph_num_neighs>`
    * :doc:`smd/ulsph/strain <compute_smd_ulsph_strain>`
    * :doc:`smd/ulsph/strain/rate <compute_smd_ulsph_strain_rate>`
@@ -133,6 +133,9 @@ KOKKOS, o = USER-OMP, t = OPT.
    * :doc:`sna/atom <compute_sna_atom>`
    * :doc:`snad/atom <compute_sna_atom>`
    * :doc:`snav/atom <compute_sna_atom>`
+   * :doc:`sph/e/atom <compute_sph_e_atom>`
+   * :doc:`sph/rho/atom <compute_sph_rho_atom>`
+   * :doc:`sph/t/atom <compute_sph_t_atom>`
    * :doc:`spin <compute_spin>`
    * :doc:`stress/atom <compute_stress_atom>`
    * :doc:`stress/mop <compute_stress_mop>`
@@ -161,5 +164,6 @@ KOKKOS, o = USER-OMP, t = OPT.
    * :doc:`torque/chunk <compute_torque_chunk>`
    * :doc:`vacf <compute_vacf>`
    * :doc:`vcm/chunk <compute_vcm_chunk>`
+   * :doc:`viscosity/cos <compute_viscosity_cos>`
    * :doc:`voronoi/atom <compute_voronoi_atom>`
    * :doc:`xrd <compute_xrd>`

doc/src/Commands_fix.rst

@@ -22,6 +22,7 @@ OPT.
 .. table_from_list::
    :columns: 5
 
+   * :doc:`accelerate/cos <fix_accelerate_cos>`
    * :doc:`adapt <fix_adapt>`
    * :doc:`adapt/fep <fix_adapt_fep>`
    * :doc:`addforce <fix_addforce>`
@@ -41,6 +42,7 @@ OPT.
    * :doc:`bocs <fix_bocs>`
    * :doc:`bond/break <fix_bond_break>`
    * :doc:`bond/create <fix_bond_create>`
+   * :doc:`bond/create/angle <fix_bond_create>`
    * :doc:`bond/react <fix_bond_react>`
    * :doc:`bond/swap <fix_bond_swap>`
    * :doc:`box/relax <fix_box_relax>`
@@ -94,10 +96,9 @@ OPT.
    * :doc:`lb/viscous <fix_lb_viscous>`
    * :doc:`lineforce <fix_lineforce>`
    * :doc:`manifoldforce <fix_manifoldforce>`
-   * :doc:`meso <fix_meso>`
    * :doc:`meso/move <fix_meso_move>`
-   * :doc:`meso/stationary <fix_meso_stationary>`
    * :doc:`momentum (k) <fix_momentum>`
+   * :doc:`momentum/chunk <fix_momentum>`
    * :doc:`move <fix_move>`
    * :doc:`mscg <fix_mscg>`
    * :doc:`msst <fix_msst>`
@@ -148,6 +149,7 @@ OPT.
    * :doc:`oneway <fix_oneway>`
    * :doc:`orient/bcc <fix_orient>`
    * :doc:`orient/fcc <fix_orient>`
+   * :doc:`orient/eco <fix_orient_eco>`
    * :doc:`pafi <fix_pafi>`
    * :doc:`phonon <fix_phonon>`
    * :doc:`pimd <fix_pimd>`
@@ -202,6 +204,8 @@ OPT.
    * :doc:`smd/move_tri_surf <fix_smd_move_triangulated_surface>`
    * :doc:`smd/setvel <fix_smd_setvel>`
    * :doc:`smd/wall_surface <fix_smd_wall_surface>`
+   * :doc:`sph <fix_sph>`
+   * :doc:`sph/stationary <fix_sph_stationary>`
    * :doc:`spring <fix_spring>`
    * :doc:`spring/chunk <fix_spring_chunk>`
    * :doc:`spring/rg <fix_spring_rg>`
@@ -242,3 +246,4 @@ OPT.
    * :doc:`wall/region <fix_wall_region>`
    * :doc:`wall/region/ees <fix_wall_ees>`
    * :doc:`wall/srd <fix_wall_srd>`
+   * :doc:`widom <fix_widom>`

doc/src/Commands_input.rst

@@ -31,9 +31,9 @@ does something different than this sequence:
    run      100
 
 In the first case, the specified timestep (0.5 fs) is used for two
-simulations of 100 timesteps each.  In the 2nd case, the default
+simulations of 100 timesteps each.  In the second case, the default
-timestep (1.0 fs) is used for the 1st 100 step simulation and a 0.5 fs
+timestep (1.0 fs) is used for the first 100 step simulation and a 0.5 fs
-timestep is used for the 2nd one.
+timestep is used for the second one.
 
 (2) Some commands are only valid when they follow other commands.  For
 example you cannot set the temperature of a group of atoms until atoms

doc/src/Commands_pair.rst

@@ -78,7 +78,7 @@ OPT.
    * :doc:`coul/long/soft (o) <pair_fep_soft>`
    * :doc:`coul/msm (o) <pair_coul>`
    * :doc:`coul/slater/cut <pair_coul_slater>`
-   * :doc:`coul/slater/long <pair_coul_slater>`   
+   * :doc:`coul/slater/long <pair_coul_slater>`
    * :doc:`coul/shield <pair_coul_shield>`
    * :doc:`coul/streitz <pair_coul>`
    * :doc:`coul/wolf (ko) <pair_coul>`
@@ -92,8 +92,8 @@ OPT.
    * :doc:`drip <pair_drip>`
    * :doc:`eam (gikot) <pair_eam>`
    * :doc:`eam/alloy (gikot) <pair_eam>`
-   * :doc:`eam/cd (o) <pair_eam>`
+   * :doc:`eam/cd <pair_eam>`
-   * :doc:`eam/cd/old (o) <pair_eam>`
+   * :doc:`eam/cd/old <pair_eam>`
    * :doc:`eam/fs (gikot) <pair_eam>`
    * :doc:`edip (o) <pair_edip>`
    * :doc:`edip/multi <pair_edip>`
@@ -136,22 +136,22 @@ OPT.
    * :doc:`lj/class2/soft <pair_fep_soft>`
    * :doc:`lj/cubic (go) <pair_lj_cubic>`
    * :doc:`lj/cut (gikot) <pair_lj>`
-   * :doc:`lj/cut/coul/cut (gko) <pair_lj>`
+   * :doc:`lj/cut/coul/cut (gko) <pair_lj_cut_coul>`
    * :doc:`lj/cut/coul/cut/soft (o) <pair_fep_soft>`
-   * :doc:`lj/cut/coul/debye (gko) <pair_lj>`
+   * :doc:`lj/cut/coul/debye (gko) <pair_lj_cut_coul>`
-   * :doc:`lj/cut/coul/dsf (gko) <pair_lj>`
+   * :doc:`lj/cut/coul/dsf (gko) <pair_lj_cut_coul>`
-   * :doc:`lj/cut/coul/long (gikot) <pair_lj>`
+   * :doc:`lj/cut/coul/long (gikot) <pair_lj_cut_coul>`
    * :doc:`lj/cut/coul/long/cs <pair_cs>`
    * :doc:`lj/cut/coul/long/soft (o) <pair_fep_soft>`
-   * :doc:`lj/cut/coul/msm (go) <pair_lj>`
+   * :doc:`lj/cut/coul/msm (go) <pair_lj_cut_coul>`
-   * :doc:`lj/cut/coul/wolf (o) <pair_lj>`
+   * :doc:`lj/cut/coul/wolf (o) <pair_lj_cut_coul>`
    * :doc:`lj/cut/dipole/cut (go) <pair_dipole>`
    * :doc:`lj/cut/dipole/long (g) <pair_dipole>`
    * :doc:`lj/cut/dipole/sf (go) <pair_dipole>`
    * :doc:`lj/cut/soft (o) <pair_fep_soft>`
    * :doc:`lj/cut/thole/long (o) <pair_thole>`
-   * :doc:`lj/cut/tip4p/cut (o) <pair_lj>`
+   * :doc:`lj/cut/tip4p/cut (o) <pair_lj_cut_tip4p>`
-   * :doc:`lj/cut/tip4p/long (got) <pair_lj>`
+   * :doc:`lj/cut/tip4p/long (got) <pair_lj_cut_tip4p>`
    * :doc:`lj/cut/tip4p/long/soft (o) <pair_fep_soft>`
    * :doc:`lj/expand (gko) <pair_lj_expand>`
    * :doc:`lj/expand/coul/long (g) <pair_lj_expand>`
@@ -180,8 +180,10 @@ OPT.
    * :doc:`meam/spline (o) <pair_meam_spline>`
    * :doc:`meam/sw/spline <pair_meam_sw_spline>`
    * :doc:`mesocnt <pair_mesocnt>`
+   * :doc:`mesont/tpm <pair_mesont_tpm>`
    * :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:`momb <pair_momb>`
    * :doc:`morse (gkot) <pair_morse>`
@@ -227,7 +229,6 @@ OPT.
    * :doc:`smd/ulsph <pair_smd_ulsph>`
    * :doc:`smtbq <pair_smtbq>`
    * :doc:`snap (k) <pair_snap>`
-   * :doc:`snap (k) <pair_snap>`
    * :doc:`soft (go) <pair_soft>`
    * :doc:`sph/heatconduction <pair_sph_heatconduction>`
    * :doc:`sph/idealgas <pair_sph_idealgas>`

doc/src/Developer/developer.tex

@@ -142,7 +142,7 @@ follows:
   minimize.
 
 \item The Special class walks the bond topology of a molecular system
-  to find 1st, 2nd, 3rd neighbors of each atom.  It is invoked by
+  to find first, second, third neighbors of each atom.  It is invoked by
   several commands, like read\_data, read\_restart, and replicate.
 
 \item The Atom class stores all per-atom arrays.  More precisely, they

doc/src/Errors_debug.rst

@@ -23,7 +23,7 @@ We use it to show how to identify the origin of a segmentation fault.
      double *special_lj = force->special_lj;
      int newton_pair = force->newton_pair;
   +  double comx = 0.0;
-   
+
      inum = list->inum;
      ilist = list->ilist;
   @@ -134,8 +135,10 @@ void PairLJCut::compute(int eflag, int vflag)
@@ -31,7 +31,7 @@ We use it to show how to identify the origin of a segmentation fault.
          }
        }
   -  }
-   
+
   +    comx += atom->rmass[i]*x[i][0]; /* BUG */
   +  }
   +  printf("comx = %g\n",comx);
@@ -42,7 +42,7 @@ After recompiling LAMMPS and running the input you should get something like thi
 
 .. code-block:
 
-   $ ./lmp -in in.melt 
+   $ ./lmp -in in.melt
    LAMMPS (19 Mar 2020)
    OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:94)
      using 1 OpenMP thread(s) per MPI task
@@ -98,11 +98,11 @@ drop back to the GDB prompt.
      Unit style    : lj
      Current step  : 0
      Time step     : 0.005
-   
+
    Program received signal SIGSEGV, Segmentation fault.
    0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x829740, eflag=1, vflag=<optimized out>) at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139
    139      comx += atom->rmass[i]*x[i][0]; /* BUG */
-   (gdb) 
+   (gdb)
 
 Now typing the command "where" will show the stack of functions starting from
 the current function back to "main()".
@@ -119,7 +119,7 @@ the current function back to "main()".
    #4  0x0000000000410ad3 in LAMMPS_NS::Input::execute_command (this=0x7d1410) at /home/akohlmey/compile/lammps/src/input.cpp:864
    #5  0x00000000004111fb in LAMMPS_NS::Input::file (this=0x7d1410) at /home/akohlmey/compile/lammps/src/input.cpp:229
    #6  0x000000000040933a in main (argc=<optimized out>, argv=<optimized out>) at /home/akohlmey/compile/lammps/src/main.cpp:65
-   (gdb) 
+   (gdb)
 
 You can also print the value of variables and see if there is anything
 unexpected.  Segmentation faults, for example, commonly happen when a
@@ -189,12 +189,12 @@ the console are not mixed.
 
 .. code-block::
 
-   $ valgrind ./lmp -in in.melt 
+   $ valgrind ./lmp -in in.melt
    ==1933642== Memcheck, a memory error detector
    ==1933642== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.
    ==1933642== Using Valgrind-3.15.0 and LibVEX; rerun with -h for copyright info
    ==1933642== Command: ./lmp -in in.melt
-   ==1933642== 
+   ==1933642==
    LAMMPS (19 Mar 2020)
    OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:94)
      using 1 OpenMP thread(s) per MPI task
@@ -228,7 +228,7 @@ the console are not mixed.
    ==1933642==    by 0x4111FA: LAMMPS_NS::Input::file() (input.cpp:229)
    ==1933642==    by 0x409339: main (main.cpp:65)
    ==1933642==  Address 0x0 is not stack'd, malloc'd or (recently) free'd
-   ==1933642== 
+   ==1933642==
 
 As you can see, the stack trace information is similar to that obtained
 from GDB. In addition you get a more specific hint about what cause the

doc/src/Errors_messages.rst

@@ -381,7 +381,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    are defined.
 
 *Bond atom missing in box size check*
-   The 2nd atoms needed to compute a particular bond is missing on this
+   The second atom needed to compute a particular bond is missing on this
    processor.  Typically this is because the pairwise cutoff is set too
    short or the bond has blown apart and an atom is too far away.
 
@@ -391,7 +391,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    the atoms are too far apart to make a valid bond.
 
 *Bond atom missing in image check*
-   The 2nd atom in a particular bond is missing on this processor.
+   The second atom in a particular bond is missing on this processor.
    Typically this is because the pairwise cutoff is set too short or the
    bond has blown apart and an atom is too far away.
 
@@ -401,12 +401,12 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    are too far apart to make a valid bond.
 
 *Bond atoms %d %d missing on proc %d at step %ld*
-   The 2nd atom needed to compute a particular bond is missing on this
+   The second atom needed to compute a particular bond is missing on this
    processor.  Typically this is because the pairwise cutoff is set too
    short or the bond has blown apart and an atom is too far away.
 
 *Bond atoms missing on proc %d at step %ld*
-   The 2nd atom needed to compute a particular bond is missing on this
+   The second atom needed to compute a particular bond is missing on this
    processor.  Typically this is because the pairwise cutoff is set too
    short or the bond has blown apart and an atom is too far away.
 
@@ -1374,7 +1374,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    template does not qualify.
 
 *Cannot use fix box/relax on a 2nd non-periodic dimension*
-   When specifying an off-diagonal pressure component, the 2nd of the two
+   When specifying an off-diagonal pressure component, the second of the two
    dimensions must be periodic.  E.g. if the xy component is specified,
    then the y dimension must be periodic.
 
@@ -1388,7 +1388,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    also keyword tri or xy, this is wrong.
 
 *Cannot use fix box/relax with tilt factor scaling on a 2nd non-periodic dimension*
-   When specifying scaling on a tilt factor component, the 2nd of the two
+   When specifying scaling on a tilt factor component, the second of the two
    dimensions must be periodic.  E.g. if the xy component is specified,
    then the y dimension must be periodic.
 
@@ -1429,7 +1429,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    This would be changing the same box dimension twice.
 
 *Cannot use fix nvt/npt/nph on a 2nd non-periodic dimension*
-   When specifying an off-diagonal pressure component, the 2nd of the two
+   When specifying an off-diagonal pressure component, the second of the two
    dimensions must be periodic.  E.g. if the xy component is specified,
    then the y dimension must be periodic.
 
@@ -1447,13 +1447,13 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    Self-explanatory.
 
 *Cannot use fix nvt/npt/nph with xy scaling when y is non-periodic dimension*
-   The 2nd dimension in the barostatted tilt factor must be periodic.
+   The second dimension in the barostatted tilt factor must be periodic.
 
 *Cannot use fix nvt/npt/nph with xz scaling when z is non-periodic dimension*
-   The 2nd dimension in the barostatted tilt factor must be periodic.
+   The second dimension in the barostatted tilt factor must be periodic.
 
 *Cannot use fix nvt/npt/nph with yz scaling when z is non-periodic dimension*
-   The 2nd dimension in the barostatted tilt factor must be periodic.
+   The second dimension in the barostatted tilt factor must be periodic.
 
 *Cannot use fix pour rigid and not molecule*
    Self-explanatory.
@@ -1908,6 +1908,12 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 
 *Compute for fix pafi must have 9 fields per atom*
    Self-explanatory.
+ 
+*Compute ID for compute chunk /atom does not exist*
+   Self-explanatory.
+
+*Compute ID for compute chunk/atom does not exist*
+   Self-explanatory.
 
 *Compute gyration ID does not exist for compute gyration/shape*
    Self-explanatory. Provide a valid compute ID.
@@ -1915,12 +1921,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Compute gyration/shape compute ID does not point to a gyration compute*
    Self-explanatory. Provide and ID of a compute gyration command.
 
-*Compute ID for compute chunk /atom does not exist*
-   Self-explanatory.
-
-*Compute ID for compute chunk/atom does not exist*
-   Self-explanatory.
-
 *Compute ID for compute reduce does not exist*
    Self-explanatory.
 
@@ -1945,9 +1945,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Compute ID for fix numdiff does not exist*
    Self-explanatory.
 
-*Compute ID for fix pafi does not exist*
-   Self-explanatory.
-
 *Compute ID for fix store/state does not exist*
    Self-explanatory.
 
@@ -2123,8 +2120,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Compute hexorder/atom requires a pair style be defined*
    Self-explanatory.
 
-
-
 *Compute improper/local used when impropers are not allowed*
    The atom style does not support impropers.
 
@@ -3881,9 +3876,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    error occurs, it is likely a bug, so send an email to the
    `developers <https://lammps.sandia.gov/authors.html>`_.
 
-*Fix pafi requires a damped dynamics minimizer*
-   Use a different minimization style.
-
 *Fix peri neigh does not exist*
    Somehow a fix that the pair style defines has been deleted.
 
@@ -7206,7 +7198,7 @@ keyword to allow for additional bonds to be formed
    does not exist.
 
 *Replacing a fix, but new style != old style*
-   A fix ID can be used a 2nd time, but only if the style matches the
+   A fix ID can be used a second time, but only if the style matches the
    previous fix.  In this case it is assumed you with to reset a fix's
    parameters.  This error may mean you are mistakenly re-using a fix ID
    when you do not intend to.

doc/src/Errors_warnings.rst

@@ -43,17 +43,17 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
    Self-explanatory.
 
 *Bond atom missing in box size check*
-   The 2nd atoms needed to compute a particular bond is missing on this
+   The second atom needed to compute a particular bond is missing on this
    processor.  Typically this is because the pairwise cutoff is set too
    short or the bond has blown apart and an atom is too far away.
 
 *Bond atom missing in image check*
-   The 2nd atom in a particular bond is missing on this processor.
+   The second atom in a particular bond is missing on this processor.
    Typically this is because the pairwise cutoff is set too short or the
    bond has blown apart and an atom is too far away.
 
 *Bond atoms missing at step %ld*
-   The 2nd atom needed to compute a particular bond is missing on this
+   The second atom needed to compute a particular bond is missing on this
    processor.  Typically this is because the pairwise cutoff is set too
    short or the bond has blown apart and an atom is too far away.
 
@@ -118,6 +118,24 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
    incorrect periodic images of atoms in interaction lists.  To avoid, either use
    :doc:`pair style zero <pair_zero>` with a suitable cutoff or use :doc:`comm_modify cutoff <comm_modify>`.
 
+*Communication cutoff is shorter than a bond length based estimate. This may lead to errors.*
+
+   Since LAMMPS stores topology data with individual atoms, all atoms
+   comprising a bond, angle, dihedral or improper must be present on any
+   sub-domain that "owns" the atom with the information, either as a
+   local or a ghost atom. The communication cutoff is what determines up
+   to what distance from a sub-domain boundary ghost atoms are created.
+   The communication cutoff is by default the largest non-bonded cutoff
+   plus the neighbor skin distance, but for short or non-bonded cutoffs
+   and/or long bonds, this may not be sufficient. This warning indicates
+   that there is an increased risk of a simulation stopping unexpectedly
+   because of Bond/Angle/Dihedral/Improper atoms missing.  It can be
+   silenced by manually setting the communication cutoff via
+   :doc:`comm_modify cutoff <comm_modify>`.  However, since the
+   heuristic used to determine the estimate is not always accurate, it
+   is not changed automatically and the warning may be ignored depending
+   on the specific system being simulated.
+
 *Communication cutoff is too small for SNAP micro load balancing, increased to %lf*
    Self-explanatory.
 
@@ -486,7 +504,7 @@ This will most likely cause errors in kinetic fluctuations.
    a new style.
 
 *No Kspace calculation with verlet/split*
-   The 2nd partition performs a kspace calculation so the kspace_style
+   The second partition performs a kspace calculation so the kspace_style
    command must be used.
 
 *No automatic unit conversion to XTC file format conventions possible for units lj*

doc/src/Examples.rst

@@ -163,7 +163,7 @@ Here is how you can run and visualize one of the sample problems:
 
 Running the simulation produces the files *dump.indent* and
 *log.lammps*\ .  You can visualize the dump file of snapshots with a
-variety of 3rd-party tools highlighted on the
+variety of third-party tools highlighted on the
 `Visualization <https://lammps.sandia.gov/viz.html>`_ page of the LAMMPS
 web site.
 

doc/src/Howto.rst

@@ -19,7 +19,7 @@ Tutorials howto
    Howto_cmake
    Howto_github
    Howto_pylammps
-   Howto_bash
+   Howto_wsl
 
 General howto
 =============

doc/src/Howto_bioFF.rst

@@ -102,8 +102,8 @@ documentation for the formula it computes.
 * :doc:`pair_style <pair_buck>` buck/coul/cut
 * :doc:`pair_style <pair_buck>` buck/coul/long
 * :doc:`pair_style <pair_lj>` lj/cut
-* :doc:`pair_style <pair_lj>` lj/cut/coul/cut
+* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/cut
-* :doc:`pair_style <pair_lj>` lj/cut/coul/long
+* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/long
 
 * :doc:`pair_style <pair_hbond_dreiding>` hbond/dreiding/lj
 * :doc:`pair_style <pair_hbond_dreiding>` hbond/dreiding/morse

doc/src/Howto_body.rst

@@ -9,13 +9,15 @@ surface meshes of discrete points, collections of sub-particles,
 deformable objects, etc.  Note that other kinds of finite-size
 spherical and aspherical particles are also supported by LAMMPS, such
 as spheres, ellipsoids, line segments, and triangles, but they are
-simpler entities that body particles.  See the :doc:`Howto spherical <Howto_spherical>` doc page for a general overview of all
+simpler entities than body particles.  See the :doc:`Howto spherical
-these particle types.
+<Howto_spherical>` doc page for a general overview of all these
+particle types.
 
 Body particles are used via the :doc:`atom_style body <atom_style>`
 command.  It takes a body style as an argument.  The current body
 styles supported by LAMMPS are as follows.  The name in the first
-column is used as the *bstyle* argument for the :doc:`atom_style body <atom_style>` command.
+column is used as the *bstyle* argument for the :doc:`atom_style body
+<atom_style>` command.
 
 +----------------------+---------------------------------------------------+
 | *nparticle*          | rigid body with N sub-particles                   |
@@ -30,8 +32,9 @@ thus how they can be used to compute pairwise body/body or
 bond/non-body (point particle) interactions.  More details of each
 style are described below.
 
-More styles may be added in the future.  See the :doc:`Modify body <Modify_body>` doc page for details on how to add a new body
+More styles may be added in the future.  See the :doc:`Modify body
-style to the code.
+<Modify_body>` doc page for details on how to add a new body style to
+the code.
 
 ----------
 
@@ -55,10 +58,10 @@ interactions, building neighbor lists, migrating particles between
 processors, output of particles to a dump file, etc.  This means that
 interactions between pairs of bodies or between a body and non-body
 (point) particle need to be encoded in an appropriate pair style.  If
-such a pair style were to mimic the :doc:`fix rigid <fix_rigid>` model,
+such a pair style were to mimic the :doc:`fix rigid <fix_rigid>`
-it would need to loop over the entire collection of interactions
+model, it would need to loop over the entire collection of
-between pairs of simple particles within the two bodies, each time a
+interactions between pairs of simple particles within the two bodies,
-single body/body interaction was computed.
+each time a single body/body interaction was computed.
 
 Thus it only makes sense to use body particles and develop such a pair
 style, when particle/particle interactions are more complex than what
@@ -160,27 +163,6 @@ of the body particle.
 The :doc:`pair_style body/nparticle <pair_body_nparticle>` command can be used
 with this body style to compute body/body and body/non-body interactions.
 
-For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
-commands, this body style produces one datum for each of the N
-sub-particles in a body particle.  The datum has 3 values:
-
-.. parsed-literal::
-
-   1 = x position of sub-particle
-   2 = y position of sub-particle
-   3 = z position of sub-particle
-
-These values are the current position of the sub-particle within the
-simulation domain, not a displacement from the center-of-mass (COM) of
-the body particle itself.  These values are calculated using the
-current COM and orientation of the body particle.
-
-For images created by the :doc:`dump image <dump_image>` command, if the
-*body* keyword is set, then each body particle is drawn as a
-collection of spheres, one for each sub-particle.  The size of each
-sphere is determined by the *bflag1* parameter for the *body* keyword.
-The *bflag2* argument is ignored.
-
 ----------
 
 **Specifics of body style rounded/polygon:**
@@ -208,7 +190,7 @@ The Nmin and Nmax arguments are used to bound the size of data
 structures used internally by each particle.
 
 When the :doc:`read_data <read_data>` command reads a data file for this
-body style, the following information must be provided for each entry
+body style, the following information must be provided for each body
 in the *Bodies* section of the data file:
 
 .. parsed-literal::
@@ -219,21 +201,25 @@ in the *Bodies* section of the data file:
    x1 y1 z1
    ...
    xN yN zN
-   i j j k k ...
    diameter
 
-where M = 6 + 3\*N + 2\*N + 1, and N is the number of vertices in the
+where M = 6 + 3\*N + 1, and N is the number of vertices in the body
-body particle.
+particle.
 
 The integer line has a single value N.  The floating point line(s)
-list 6 moments of inertia followed by the coordinates of the N
+list 6 moments of inertia, followed by the coordinates of the N
 vertices (x1 to zN) as 3N values (with z = 0.0 for each), followed by
-2N vertex indices corresponding to the end points of the N edges,
+a diameter value = the rounded diameter of the circle that surrounds
-followed by a single diameter value = the rounded diameter of the
+each vertex. The diameter value can be different for each body
-circle that surrounds each vertex. The diameter value can be different
+particle. These floating-point values can be listed on as many lines
-for each body particle. These floating-point values can be listed on
+as you wish; see the :doc:`read_data <read_data>` command for more
-as many lines as you wish; see the :doc:`read_data <read_data>` command
+details.
-for more details.
+
+.. note::
+
+  It is important that the vertices for each polygonal body particle be
+  listed in order around its perimeter, so that edges can be inferred.
+  LAMMPS does not check that this is the case.
 
 The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
 values consistent with the current orientation of the rigid body
@@ -260,10 +246,6 @@ is consistent with the 6 moments of inertia: ixx iyy izz ixy ixz iyz =
    -0.7071 0.7071 0
    0.7071 0.7071 0
    0.7071 -0.7071 0
-   0 1
-   1 2
-   2 3
-   3 0
    1.0
 
 A rod in 2D, whose length is 4.0, mass 1.0, rounded at two ends
@@ -345,8 +327,10 @@ in the *Bodies* section of the data file:
    1 2 3 4
    diameter
 
-where M = 6 + 3\*N + 2\*E + 4\*F + 1, and N is the number of vertices in
+where M = 6 + 3\*N + 2\*E + 4\*F + 1, and N is the number of vertices
-the body particle, E = number of edges, F = number of faces.
+in the body particle, E = number of edges, F = number of faces.  For N
+= 1 or 2, the format is simpler.  E and F are ignored and no edges or
+faces are listed, so that M = 6 + 3\*N + 1.
 
 The integer line has three values: number of vertices (N), number of
 edges (E) and number of faces (F). The floating point line(s) list 6
@@ -356,16 +340,26 @@ the end points of the E edges, then 4\*F vertex indices defining F
 faces.  The last value is the diameter value = the rounded diameter of
 the sphere that surrounds each vertex. The diameter value can be
 different for each body particle. These floating-point values can be
-listed on as many lines as you wish; see the
+listed on as many lines as you wish; see the :doc:`read_data
-:doc:`read_data <read_data>` command for more details.  Because the
+<read_data>` command for more details.
-maximum number of vertices per face is hard-coded to be 4
-(i.e. quadrilaterals), faces with more than 4 vertices need to be
-split into triangles or quadrilaterals.  For triangular faces, the
-last vertex index should be set to -1.
 
-The ordering of the 4 vertices within a face should follow
+Note that vertices are numbered from 0 to N-1 inclusive.  The order of
-the right-hand rule so that the normal vector of the face points
+the 2 vertices in each edge does not matter.  Faces can be triangles
-outwards from the center of mass.
+or quadrilaterals.  In both cases 4 vertices must be specified.  For a
+triangle the 4th vertex is -1.  The 4 vertices within each triangle or
+quadrilateral face should be ordered by the right-hand rule so that
+the normal vector of the face points outwards from the center of mass.
+For polyhedron with faces with more than 4 vertices, you should split
+the complex face into multiple simple faces, each of which is a
+triangle or quadrilateral.
+
+.. note::
+
+  If a face is a quadrilateral then its 4 vertices must be co-planar.
+  LAMMPS does not check that this is the case.  If you have a quad-face
+  of a polyhedron that is not planar (e.g. a cube whose vertices have
+  been randomly displaced), then you should represent the single quad
+  face as two triangle faces instead.
 
 The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
 values consistent with the current orientation of the rigid body
@@ -421,8 +415,8 @@ by circles of diameter 0.5, is specified as follows:
 
 .. parsed-literal::
 
-   1 1 13
+   1 3 13
-   2
+   2 1 1
    0 1.33333 1.33333 0 0 0
    -2 0 0
    2 0 0
@@ -432,27 +426,34 @@ A sphere whose diameter is 3.0 and mass 1.0, is specified as follows:
 
 .. parsed-literal::
 
-   1 1 10
+   1 3 10
-   1
+   1 1 1
    0.9 0.9 0.9 0 0 0
    0 0 0
    3.0
 
-The :doc:`pair_style body/rounded/polhedron <pair_body_rounded_polyhedron>` command can
+The number of edges and faces for a rod or sphere must be listed,
-be used with this body style to compute body/body interactions.  The
+but is ignored.
-:doc:`fix wall/body/polyhedron <fix_wall_body_polygon>` command can be
+
-used with this body style to compute the interaction of body particles
+The :doc:`pair_style body/rounded/polhedron
-with a wall.
+<pair_body_rounded_polyhedron>` command can be used with this body
+style to compute body/body interactions.  The :doc:`fix
+wall/body/polyhedron <fix_wall_body_polygon>` command can be used with
+this body style to compute the interaction of body particles with a
+wall.
 
 ----------
 
-For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
+**Output specifics for all body styles:**
-commands, this body style produces one datum for each of the N
+
-sub-particles in a body particle.  The datum has 3 values:
+For the :doc:`compute body/local <compute_body_local>` and :doc:`dump
+local <dump>` commands, all 3 of the body styles described on his page
+produces one datum for each of the N vertices (of sub-particles) in a
+body particle.  The datum has 3 values:
 
 .. parsed-literal::
 
-   1 = x position of vertex
+   1 = x position of vertex (or sub-particle)
    2 = y position of vertex
    3 = z position of vertex
 
@@ -461,15 +462,29 @@ simulation domain, not a displacement from the center-of-mass (COM) of
 the body particle itself.  These values are calculated using the
 current COM and orientation of the body particle.
 
-For images created by the :doc:`dump image <dump_image>` command, if the
+The :doc:`dump image <dump_image>` command and its *body* keyword can
-*body* keyword is set, then each body particle is drawn as a polygon
+be used to render body particles.
-consisting of N line segments.  Note that the line segments are drawn
+
-between the N vertices, which does not correspond exactly to the
+For the *nparticle* body style, each body is drawn as a
-physical extent of the body (because the :doc:`pair_style rounded/polygon <pair_body_rounded_polygon>` defines finite-size
+collection of spheres, one for each sub-particle.  The size of each
-spheres at those point and the line segments between the spheres are
+sphere is determined by the *bflag1* parameter for the *body* keyword.
-tangent to the spheres).  The drawn diameter of each line segment is
+The *bflag2* argument is ignored.
-determined by the *bflag1* parameter for the *body* keyword.  The
+
-*bflag2* argument is ignored.
+For the *rounded/polygon* body style, each body is drawn as a polygon
+with N line segments.  For the *rounded/polyhedron* body style, each
+face of each body is drawn as a polygon with N line segments.  The
+drawn diameter of each line segment is determined by the *bflag1*
+parameter for the *body* keyword.  The *bflag2* argument is ignored.
+
+Note that for both the *rounded/polygon* and *rounded/polyhedron*
+styles, line segments are drawn between the pairs of vertices.
+Depending on the diameters of the line segments this may be slightly
+different than the physical extent of the body as calculated by the
+:doc:`pair_style rounded/polygon <pair_body_rounded_polygon>` or
+:doc:`pair_style rounded/polyhedron <pair_body_rounded_polyhedron>`
+commands.  Conceptually, the pair styles define the surface of a 2d or
+3d body by lines or planes that are tangent to the finite-size spheres
+of specified diameter which are placed on each vertex position.
 
 ----------
 

doc/src/Howto_chunk.rst

@@ -197,7 +197,7 @@ compress individual polymer chains (molecules) in a mixture, is
 explained on the :doc:`compute chunk/spread/atom <compute_chunk_spread_atom>` command doc page.
 
 (7) An example for using one set of per-chunk values for molecule
-chunks, to create a 2nd set of micelle-scale chunks (clustered
+chunks, to create a second set of micelle-scale chunks (clustered
 molecules, due to hydrophobicity), is explained on the :doc:`compute chunk/reduce <compute_reduce_chunk>` command doc page.
 
 (8) An example for using one set of per-chunk values (dipole moment

doc/src/Howto_cmake.rst

@@ -47,7 +47,7 @@ using a shell like Bash.
 
 - Linux: any Terminal window will work
 - MacOS X: launch the Terminal application.
-- Windows 10: install and run the :doc:`Windows subsystem for Linux <Howto_bash>`
+- Windows 10: install and run the :doc:`Windows Subsystem for Linux <Howto_wsl>`
 
 We also assume that you have downloaded and unpacked a recent LAMMPS source code package
 or used Git to create a clone of the LAMMPS sources on your compilation machine.
@@ -114,19 +114,19 @@ summary screen will look like this:
    -- Detecting CXX compiler ABI info - done
    -- Detecting CXX compile features
    -- Detecting CXX compile features - done
-   -- Found Git: /usr/bin/git (found version "2.25.2") 
+   -- Found Git: /usr/bin/git (found version "2.25.2")
    -- Running check for auto-generated files from make-based build system
-   -- Found MPI_CXX: /usr/lib64/mpich/lib/libmpicxx.so (found version "3.1") 
+   -- Found MPI_CXX: /usr/lib64/mpich/lib/libmpicxx.so (found version "3.1")
-   -- Found MPI: TRUE (found version "3.1")  
+   -- Found MPI: TRUE (found version "3.1")
    -- Looking for C++ include omp.h
    -- Looking for C++ include omp.h - found
-   -- Found OpenMP_CXX: -fopenmp (found version "4.5") 
+   -- Found OpenMP_CXX: -fopenmp (found version "4.5")
-   -- Found OpenMP: TRUE (found version "4.5")  
+   -- Found OpenMP: TRUE (found version "4.5")
-   -- Found JPEG: /usr/lib64/libjpeg.so (found version "62") 
+   -- Found JPEG: /usr/lib64/libjpeg.so (found version "62")
-   -- Found PNG: /usr/lib64/libpng.so (found version "1.6.37") 
+   -- Found PNG: /usr/lib64/libpng.so (found version "1.6.37")
-   -- Found ZLIB: /usr/lib64/libz.so (found version "1.2.11") 
+   -- Found ZLIB: /usr/lib64/libz.so (found version "1.2.11")
-   -- Found GZIP: /usr/bin/gzip  
+   -- Found GZIP: /usr/bin/gzip
-   -- Found FFMPEG: /usr/bin/ffmpeg  
+   -- Found FFMPEG: /usr/bin/ffmpeg
    -- Performing Test COMPILER_SUPPORTS-ffast-math
    -- Performing Test COMPILER_SUPPORTS-ffast-math - Success
    -- Performing Test COMPILER_SUPPORTS-march=native
@@ -143,7 +143,7 @@ summary screen will look like this:
     * JPEG
     * PNG
     * ZLIB
-   
+
    -- <<< Build configuration >>>
       Build type:       RelWithDebInfo
       Install path:     /home/akohlmey/.local
@@ -157,7 +157,7 @@ summary screen will look like this:
          Options:       -ffast-math;-march=native
    -- <<< Linker flags: >>>
    -- Executable name:  lmp
-   -- Static library flags:    
+   -- Static library flags:
    -- <<< MPI flags >>>
    -- MPI includes:     /usr/include/mpich-x86_64
    -- MPI libraries:    /usr/lib64/mpich/lib/libmpicxx.so;/usr/lib64/mpich/lib/libmpi.so;
@@ -291,7 +291,7 @@ Some common CMake variables
 
 .. list-table::
    :header-rows: 1
-   
+
    * - Variable
      - Description
    * - ``CMAKE_INSTALL_PREFIX``
@@ -313,13 +313,13 @@ Some common CMake variables
      - Fortran compiler to be used for compilation (default: system specific, ``gfortran`` on Linux)
    * - ``CXX_COMPILER_LAUNCHER``
      - tool to launch the C++ compiler, e.g. ``ccache`` or ``distcc`` for faster compilation (default: empty)
-       
+
 Some common LAMMPS specific variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. list-table::
    :header-rows: 1
-   
+
    * - Variable
      - Description
    * - ``BUILD_MPI``
@@ -331,7 +331,7 @@ Some common LAMMPS specific variables
    * - ``BUILD_DOC``
      - include building the HTML format documentation for packaging/installing (default: ``off``)
    * - ``CMAKE_TUNE_FLAGS``
-     - common compiler flags, for optimization or instrumentation (default: compiler specific)
+     - common compiler flags, for optimization or instrumentation (default:)
    * - ``LAMMPS_MACHINE``
      - when set to ``name`` the LAMMPS executable and library will be called ``lmp_name`` and ``liblammps_name.a``
    * - ``LAMMPS_EXCEPTIONS``
@@ -415,8 +415,10 @@ This is particularly convenient, if you have set a custom build command
 via the ``CMAKE_MAKE_PROGRAM`` variable.
 
 When calling the build program, you can also select which "target" is to
-be build through appending the name of the target to the build command.
+be build through appending the ``--target`` flag and the name of the target
-Example: ``cmake --build . all``. The following abstract targets are available:
+to the build command.  When using ``make`` as build tool, you can just append
+the target name to the command. Example: ``cmake --build . --target all`` or
+``make all``.  The following abstract targets are available:
 
 .. list-table::
    :header-rows: 1
@@ -432,11 +434,11 @@ Example: ``cmake --build . all``. The following abstract targets are available:
    * - ``install``
      - install all target files into folders in ``CMAKE_INSTALL_PREFIX``
    * - ``test``
-     - run some simple tests (if configured with ``-D ENABLE_TESTING=on``)
+     - run some tests (if configured with ``-D ENABLE_TESTING=on``)
    * - ``clean``
      - remove all generated files
 
-   
+
 Choosing generators
 -------------------
 

doc/src/Howto_coreshell.rst

@@ -119,7 +119,7 @@ non-polarized ions (ions without an attached satellite particle).  The
 groups, one for the core atoms, another for the shell atoms.
 Non-polarized ions which might also be included in the treated system
 should not be included into either of these groups, they are taken
-into account by the *group-ID* (2nd argument) of the compute.  The
+into account by the *group-ID* (second argument) of the compute.  The
 groups can be defined using the :doc:`group *type*\ <group>` command.
 Note that to perform thermostatting using this definition of
 temperature, the :doc:`fix modify temp <fix_modify>` command should be

doc/src/Howto_multiple.rst

@@ -91,4 +91,4 @@ With these modifications, the 8 simulations of each script would run
 on the 3 partitions one after the other until all were finished.
 Initially, 3 simulations would be started simultaneously, one on each
 partition.  When one finished, that partition would then start
-the 4th simulation, and so forth, until all 8 were completed.
+the fourth simulation, and so forth, until all 8 were completed.

doc/src/Howto_output.rst

@@ -3,13 +3,15 @@ Output from LAMMPS (thermo, dumps, computes, fixes, variables)
 
 There are four basic kinds of LAMMPS output:
 
-* :doc:`Thermodynamic output <thermo_style>`, which is a list
+* :doc:`Thermodynamic output <thermo_style>`, which is a list of
-  of quantities printed every few timesteps to the screen and logfile.
+  quantities printed every few timesteps to the screen and logfile.
 * :doc:`Dump files <dump>`, which contain snapshots of atoms and various
   per-atom values and are written at a specified frequency.
-* Certain fixes can output user-specified quantities to files: :doc:`fix ave/time <fix_ave_time>` for time averaging, :doc:`fix ave/chunk <fix_ave_chunk>` for spatial or other averaging, and :doc:`fix print <fix_print>` for single-line output of
+* Certain fixes can output user-specified quantities to files:
-  :doc:`variables <variable>`.  Fix print can also output to the
+  :doc:`fix ave/time <fix_ave_time>` for time averaging,
-  screen.
+  :doc:`fix ave/chunk <fix_ave_chunk>` for spatial or other averaging, and
+  :doc:`fix print <fix_print>` for single-line output of
+  :doc:`variables <variable>`.  Fix print can also output to the screen.
 * :doc:`Restart files <restart>`.
 
 A simulation prints one set of thermodynamic output and (optionally)
@@ -41,7 +43,7 @@ to output and the kind of data they operate on and produce:
 .. _global:
 
 Global/per-atom/local data
----------------------------------------
+--------------------------
 
 Various output-related commands work with three different styles of
 data: global, per-atom, or local.  A global datum is one or more
@@ -54,7 +56,7 @@ bond distances.
 .. _scalar:
 
 Scalar/vector/array data
--------------------------------------
+------------------------
 
 Global, per-atom, and local datums can each come in three kinds: a
 single scalar value, a vector of values, or a 2d array of values.  The
@@ -81,10 +83,27 @@ the dimension twice (array -> scalar).  Thus a command that uses
 scalar values as input can typically also process elements of a vector
 or array.
 
+.. _disambiguation:
+
+Disambiguation
+--------------
+
+Some computes and fixes produce data in multiple styles, e.g. a global
+scalar and a per-atom vector. Usually the context in which the input
+script references the data determines which style is meant. Example: if
+a compute provides both a global scalar and a per-atom vector, the
+former will be accessed by using ``c_ID`` in an equal-style variable,
+while the latter will be accessed by using ``c_ID`` in an atom-style
+variable.  Note that atom-style variable formulas can also access global
+scalars, but in this case it is not possible to do directly because of
+the ambiguity.  Instead, an equal-style variable can be defined which
+accesses the global scalar, and that variable used in the atom-style
+variable formula in place of ``c_ID``.
+
 .. _thermo:
 
 Thermodynamic output
----------------------------------
+--------------------
 
 The frequency and format of thermodynamic output is set by the
 :doc:`thermo <thermo>`, :doc:`thermo_style <thermo_style>`, and
@@ -112,7 +131,7 @@ intensive result.
 .. _dump:
 
 Dump file output
----------------------------
+----------------
 
 Dump file output is specified by the :doc:`dump <dump>` and
 :doc:`dump_modify <dump_modify>` commands.  There are several
@@ -138,7 +157,7 @@ command.
 .. _fixoutput:
 
 Fixes that write output files
----------------------------------------------
+-----------------------------
 
 Several fixes take various quantities as input and can write output
 files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk <fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`,
@@ -192,7 +211,7 @@ from normal thermodynamic or dump file output.
 .. _computeoutput:
 
 Computes that process output quantities
------------------------------------------------------------
+---------------------------------------
 
 The :doc:`compute reduce <compute_reduce>` and :doc:`compute reduce/region <compute_reduce>` commands take one or more per-atom
 or local vector quantities as inputs and "reduce" them (sum, min, max,
@@ -219,7 +238,7 @@ output commands.
 .. _fixprocoutput:
 
 Fixes that process output quantities
---------------------------------------------------------
+------------------------------------
 
 The :doc:`fix vector <fix_vector>` command can create global vectors as
 output from global scalars as input, accumulating them one element at
@@ -244,7 +263,7 @@ The output of this fix can be used as input to other output commands.
 .. _compute:
 
 Computes that generate values to output
------------------------------------------------------
+---------------------------------------
 
 Every :doc:`compute <compute>` in LAMMPS produces either global or
 per-atom or local values.  The values can be scalars or vectors or
@@ -257,7 +276,7 @@ without the word "atom" or "local" produce global values.
 .. _fix:
 
 Fixes that generate values to output
-----------------------------------------------
+------------------------------------
 
 Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom or
 local values which can be accessed by other commands.  The values can
@@ -269,7 +288,7 @@ describes them.
 .. _variable:
 
 Variables that generate values to output
--------------------------------------------------------
+----------------------------------------
 
 :doc:`Variables <variable>` defined in an input script can store one or
 more strings.  But equal-style, vector-style, and atom-style or
@@ -284,7 +303,7 @@ commands described in this section.
 .. _table:
 
 Summary table of output options and data flow between commands
---------------------------------------------------------------------------
+--------------------------------------------------------------
 
 This table summarizes the various commands that can be used for
 generating output from LAMMPS.  Each command produces output data of

doc/src/Howto_restart.rst

@@ -28,7 +28,7 @@ scripts are based on.  If that script had the line
 added to it, it would produce 2 binary restart files (tmp.restart.50
 and tmp.restart.100) as it ran.
 
-This script could be used to read the 1st restart file and re-run the
+This script could be used to read the first restart file and re-run the
 last 50 timesteps:
 
 .. code-block:: LAMMPS

doc/src/Howto_tip4p.rst

@@ -11,11 +11,11 @@ angle style of *harmonic* or *charmm* should also be used.
 A TIP4P model is run with LAMMPS using either this command
 for a cutoff model:
 
-* :doc:`pair_style lj/cut/tip4p/cut <pair_lj>`
+* :doc:`pair_style lj/cut/tip4p/cut <pair_lj_cut_tip4p>`
 
 or these two commands for a long-range model:
 
-* :doc:`pair_style lj/cut/tip4p/long <pair_lj>`
+* :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>`
 * :doc:`kspace_style pppm/tip4p <kspace_style>`
 
 For both models, the bond lengths and bond angles should be held fixed
@@ -95,7 +95,7 @@ typically best in an efficiency sense to use a LJ cutoff >= Coulomb
 cutoff + 2\*(OM distance), to shrink the size of the neighbor list.
 This leads to slightly larger cost for the long-range calculation, so
 you can test the trade-off for your model.  The OM distance and the LJ
-and Coulombic cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long <pair_lj>` command.
+and Coulombic cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>` command.
 
 Wikipedia also has a nice article on `water models <http://en.wikipedia.org/wiki/Water_model>`_.
 

doc/src/Howto_triclinic.rst

@@ -85,7 +85,7 @@ where *V* is the volume of the box, **X** is the original vector quantity and
 **x** is the vector in the LAMMPS basis.
 
 There is no requirement that a triclinic box be periodic in any
-dimension, though it typically should be in at least the 2nd dimension
+dimension, though it typically should be in at least the second dimension
 of the tilt (y in xy) if you want to enforce a shift in periodic
 boundary conditions across that boundary.  Some commands that work
 with triclinic boxes, e.g. the :doc:`fix deform <fix_deform>` and :doc:`fix npt <fix_nh>` commands, require periodicity or non-shrink-wrap
@@ -120,7 +120,7 @@ The 9 parameters, as well as lx,ly,lz, can be output via the
 To avoid extremely tilted boxes (which would be computationally
 inefficient), LAMMPS normally requires that no tilt factor can skew
 the box more than half the distance of the parallel box length, which
-is the 1st dimension in the tilt factor (x for xz).  This is required
+is the first dimension in the tilt factor (x for xz).  This is required
 both when the simulation box is created, e.g. via the
 :doc:`create_box <create_box>` or :doc:`read_data <read_data>` commands,
 as well as when the box shape changes dynamically during a simulation,
@@ -137,7 +137,7 @@ limit during a dynamics run (e.g. via the :doc:`fix deform <fix_deform>`
 command), then the box is "flipped" to an equivalent shape with a tilt
 factor within the bounds, so the run can continue.  See the :doc:`fix deform <fix_deform>` doc page for further details.
 
-One exception to this rule is if the 1st dimension in the tilt
+One exception to this rule is if the first dimension in the tilt
 factor (x for xy) is non-periodic.  In that case, the limits on the
 tilt factor are not enforced, since flipping the box in that dimension
 does not change the atom positions due to non-periodicity.  In this

doc/src/Howto_viscosity.rst

@@ -1,10 +1,11 @@
 Calculate viscosity
 ===================
 
-The shear viscosity eta of a fluid can be measured in at least 5 ways
+The shear viscosity eta of a fluid can be measured in at least 6 ways
 using various options in LAMMPS.  See the examples/VISCOSITY directory
 for scripts that implement the 5 methods discussed here for a simple
-Lennard-Jones fluid model.  Also, see the :doc:`Howto kappa <Howto_kappa>` doc page for an analogous discussion for
+Lennard-Jones fluid model and 1 method for SPC/E water model.
+Also, see the :doc:`Howto kappa <Howto_kappa>` doc page for an analogous discussion for
 thermal conductivity.
 
 Eta is a measure of the propensity of a fluid to transmit momentum in
@@ -130,9 +131,25 @@ time-integrated momentum fluxes play the role of Cartesian
 coordinates, whose mean-square displacement increases linearly
 with time at sufficiently long times.
 
+The sixth is periodic perturbation method. It is also a non-equilibrium MD method.
+However, instead of measure the momentum flux in response of applied velocity gradient,
+it measures the velocity profile in response of applied stress.
+A cosine-shaped periodic acceleration is added to the system via the
+:doc:`fix accelerate/cos <fix_accelerate_cos>` command,
+and the :doc:`compute viscosity/cos<compute_viscosity_cos>` command is used to monitor the
+generated velocity profile and remove the velocity bias before thermostatting.
+
+.. note::
+
+    An article by :ref:`(Hess) <Hess3>` discussed the accuracy and efficiency of these methods.
+
 ----------
 
 .. _Daivis-viscosity:
 
 **(Daivis and Todd)** Daivis and Todd, Nonequilibrium Molecular Dynamics (book),
 Cambridge University Press, https://doi.org/10.1017/9781139017848, (2017).
+
+.. _Hess3:
+
+**(Hess)** Hess, B. The Journal of Chemical Physics 2002, 116 (1), 209-217.

doc/src/Howto_wsl.rst

@@ -0,0 +1,359 @@
+Using LAMMPS on Windows 10 with WSL
+###################################
+
+**written by Richard Berger**
+
+----------
+
+It's always been tricky for us to have LAMMPS users and developers work on
+Windows. We primarily develop LAMMPS to run on Linux clusters. To teach
+LAMMPS in workshop settings, we had to redirect Windows users to
+Linux Virtual Machines such as VirtualBox or Unix-like compilation with
+Cygwin.
+
+With the latest updates in Windows 10 (Version 2004, Build 19041 or higher),
+Microsoft has added a new way to work on Linux-based code. The Windows
+Subsystem for Linux (WSL). With WSL Version 2, you now get a Linux Virtual
+Machine that transparently integrates into Windows. All you need is to ensure
+you have the latest Windows updates installed and enable this new feature.
+Linux VMs are then easily installed using the Microsoft Store.
+
+In this tutorial, I'll show you how to set up and compile LAMMPS for both serial
+and MPI usage in WSL2.
+
+Installation
+============
+
+Upgrade to the latest Windows 10
+--------------------------------
+
+Type "Updates" in Windows Start and select "Check for Updates".
+
+.. image:: img/wsl_tutorial/updates.png
+   :scale: 50%
+
+Install all pending updates and reboot your system as many times as
+necessary. Continue until your Windows installation is updated.
+
+.. image:: img/wsl_tutorial/windows_update.png
+   :scale: 50%
+
+Verify your system has at least **version 2004 and build 19041 or later**. You
+can find this information by clicking on "OS build info".
+
+.. image:: img/wsl_tutorial/osinfo.png
+   :scale: 50%
+
+Enable WSL
+----------
+Next, we must install two additional Windows features to enable WSL support.
+Open a PowerShell window as an administrator. Type "PowerShell" in Windows
+Start and select "Run as Administrator".
+
+.. image:: img/wsl_tutorial/powershell.png
+   :scale: 50%
+
+Windows will ask you for administrator access. After you accept a new command
+line window will appear. Type in the following command to install WSL:
+
+.. code-block::
+
+   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
+
+.. image:: img/wsl_tutorial/wsl_install1.png
+
+Next, enable the VirtualMachinePlatform feature using the following command:
+
+.. code-block::
+
+   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
+
+.. image:: img/wsl_tutorial/wsl_install2.png
+
+Finally, reboot your system.
+
+Update WSL kernel component
+---------------------------
+
+Download and install the :download:`WSL Kernel Component Update <https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi>`.
+Afterwards, reboot your system.
+
+Set WSL2 as default
+-------------------
+
+Again, open PowerShell as administrator and run the following command:
+
+.. code-block:: powershell
+
+   wsl --set-default-version 2
+
+This command ensures that all future Linux installations will use WSL version 2.
+
+.. image:: img/wsl_tutorial/wsl_install3.png
+
+Install a Linux Distribution
+----------------------------
+Next, we need to install a Linux distribution via the Microsoft Store.
+Install `Ubuntu 20.04 LTS <ms-windows-store://pdp/?ProductId=9n6svws3rx71>`_.
+Once installed, you can launch it like any other application from the Start
+Menu.
+
+.. image:: img/wsl_tutorial/ubuntu_in_store.png
+   :scale: 50%
+
+Initial Setup
+^^^^^^^^^^^^^
+The first time you launch the Ubuntu Linux console, it will prompt you for a
+UNIX username and password. You will need this password to perform :code:`sudo`
+commands later. Once completed, your Linux shell is ready for use. All your
+actions and commands will run as the Linux user you specified.
+
+.. image:: img/wsl_tutorial/first_login.png
+   :scale: 50%
+
+Windows Explorer / WSL integration
+==================================
+
+Your Linux installation will have its own Linux filesystem, which contains
+the Ubuntu files. Your Linux user will have a regular Linux home directory in
+:code:`/home/<USERNAME>`. This directory is different from your Windows User
+directory. Windows and Linux filesystems are connected through WSL.
+
+All hard drives in Windows are accessible in the :code:`/mnt` directory in Linux.
+E.g., WSL maps the :code:`C` hard drive to the :code:`/mnt/c` directory. That means you
+can access your Windows User directory in :code:`/mnt/c/Users/<WINDOWS_USERNAME>`.
+
+The Windows Explorer can also access the Linux filesystem. To illustrate this
+integration, open an Ubuntu console and navigate to a directory of your
+choice. To view this location in Windows Explorer, use the :code:`explorer.exe .`
+command (do not forget the final dot!).
+
+.. image:: img/wsl_tutorial/wsl_integration.png
+   :scale: 50%
+
+--------
+
+Compiling LAMMPS
+================
+
+You now have a fully functioning Ubuntu installation and can follow most
+guides to install LAMMPS on a Linux system. Here are some of the essential
+steps to follow:
+
+Install prerequisite packages
+-----------------------------
+
+Before we can begin, we need to download the necessary compiler toolchain and
+libraries to compile LAMMPS. In our Ubuntu-based Linux installation, we will
+use the :code:`apt` package manager to install additional packages.
+
+First, upgrade all existing packages using :code:`apt update` and :code:`apt upgrade`.
+
+.. code-block:: bash
+
+   sudo apt update
+   sudo apt upgrade -y
+
+Next, install the following packages with :code:`apt install`:
+
+
+.. code-block:: bash
+
+   sudo apt install -y cmake build-essential ccache gfortran openmpi-bin libopenmpi-dev \
+                       libfftw3-dev libjpeg-dev libpng-dev python3-dev python3-pip \
+                       python3-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev \
+                       hdf5-tools
+
+Download LAMMPS
+---------------
+
+Obtain a copy of the LAMMPS source code and go into it using the :code:`cd` command.
+
+Option 1: Download a LAMMPS tarball using wget
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   wget https://github.com/lammps/lammps/archive/stable_3Mar2020.tar.gz
+   tar xvzf stable_3Mar2020.tar.gz
+   cd lammps
+
+Option 2: Download a LAMMPS development version from GitHub
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   git clone --depth=1 https://github.com/lammps/lammps.git
+   cd lammps
+
+
+Configure and Compile LAMMPS with CMake
+---------------------------------------
+
+A beginner-friendly way to compile LAMMPS is to use CMake. Create a :code:`build`
+directory to compile LAMMPS and move into it. This directory will store the
+build configuration and any binaries generated during compilation.
+
+.. code-block:: bash
+
+   mkdir build
+   cd build
+
+There are countless ways to compile LAMMPS. It is beyond the scope of this
+tutorial. If you want to find out more about what can be enabled, please
+consult the extensive `documentation <https://lammps.sandia.gov/doc/Build_cmake.html>`_.
+
+To compile a minimal version of LAMMPS, we're going to use a preset.
+Presets are a way to specify a collection of CMake options using a file.
+
+.. code-block:: bash
+
+   cmake ../cmake/presets/minimal.cmake ../cmake
+
+This command configures the build and generates the necessary Makefiles. To compile the binary, run the make command.
+
+.. code-block:: bash
+
+   make -j 4
+
+The :code:`-j` option specifies how many parallel processes will perform the
+compilation. This option can significantly speed up compilation times. Use a
+number that corresponds to the number of processors in your system.
+
+After the compilation completes successfully, you will have an executable
+called :code:`lmp` in the :code:`build` directory.
+
+.. image:: img/wsl_tutorial/compilation_result.png
+   :scale: 50%
+
+Please take note of the absolute path of your :code:`build` directory. You will
+need to know the location to execute the LAMMPS binary later.
+
+One way of getting the absolute path of the current directory is through the
+:code:`$PWD` variable:
+
+.. code-block:: bash
+
+   # prints out the current value of the PWD variable
+   echo $PWD
+
+Let us save this value in a temporary variable :code:`LAMMPS_BUILD_DIR` for future use:
+
+.. code-block:: bash
+
+   LAMMPS_BUILD_DIR=$PWD
+
+The full path of the LAMMPS binary then is :code:`$LAMMPS_BUILD_DIR/lmp`.
+
+------------
+
+Running an example script
+=========================
+
+Now that we have a LAMMPS binary, we will run a script from the examples folder.
+
+Switch into the :code:`examples/melt` folder:
+
+.. code-block::
+
+   cd ../examples/melt
+
+To run this example in serial, use the following command line:
+
+.. code-block::
+
+   $LAMMPS_BUILD_DIR/lmp -in in.melt
+
+To run the same script in parallel using MPI with 4 processes, do the following:
+
+.. code-block:: bash
+
+   mpirun -np 4 $LAMMPS_BUILD_DIR/lmp -in in.melt
+
+If you run LAMMPS for the first time, the Windows Firewall might prompt you
+to confirm access. LAMMPS is accessing the network stack to enable parallel
+computation. Allow the access.
+
+.. image:: img/wsl_tutorial/windows_firewall.png
+   :scale: 75%
+
+In either serial or MPI case, LAMMPS executes and will output something similar to this:
+
+.. code-block::
+
+   LAMMPS (30 Jun 2020)
+   ...
+   ...
+   ...
+   Total # of neighbors = 151513
+   Ave neighs/atom = 37.878250
+   Neighbor list builds = 12
+   Dangerous builds not checked
+   Total wall time: 0:00:00
+
+**Congratulations! You've successfully compiled and executed LAMMPS on WSL!**
+
+Final steps
+===========
+
+It is cumbersome to always specify the path of your LAMMPS binary. You can
+avoid this by adding the absolute path of your :code:`build` directory to your PATH
+environment variable.
+
+.. code-block:: bash
+
+   export PATH=$LAMMPS_BUILD_DIR:$PATH
+
+You can then run LAMMPS input scripts like this:
+
+.. code-block:: bash
+
+   lmp -in in.melt
+
+or
+
+.. code-block:: bash
+
+   mpirun -np 4 lmp -in in.melt
+
+.. note::
+
+   The value of this :code:`PATH` variable will disappear once you close your
+   console window. To persist this setting edit the :code:`$HOME/.bashrc` file using your
+   favorite text editor and add this line:
+
+   .. code-block:: bash
+
+      export PATH=/full/path/to/your/lammps/build:$PATH
+
+   **Example:**
+   If the LAMMPS executable `lmp` has the following absolute path:
+
+   .. code-block:: bash
+
+      /home/<USERNAME>/lammps/build/lmp
+
+   the :code:`PATH` variable should be:
+
+
+   .. code-block:: bash
+
+      export PATH=/home/<USERNAME>/lammps/build:$PATH
+
+   Once set up, all your Ubuntu consoles will always have access to your :code:`lmp`
+   binary without having to specify its location.
+
+Conclusion
+==========
+I hope this gives you good overview on how to start compiling and running LAMMPS on
+Windows. WSL makes preparing and running scripts on Windows a much better
+experience.
+
+If you are completely new to Linux, I highly recommend investing some time in
+studying Linux online tutorials. E.g., tutorials about Bash Shell and Basic
+Unix commands (e.g., `Linux Journey <https://linuxjourney.com/>`_). Acquiring
+these skills will make you much more productive in this environment.
+
+.. seealso::
+
+   * `Windows Subsystem for Linux Documentation <https://docs.microsoft.com/en-us/windows/wsl/>`_

doc/src/Install_linux.rst

@@ -21,8 +21,14 @@ Pre-built Ubuntu Linux executables
 A pre-built LAMMPS executable suitable for running on the latest
 Ubuntu Linux versions, can be downloaded as a Debian package.  This
 allows you to install LAMMPS with a single command, and stay
-up-to-date with the current version of LAMMPS by simply updating your
+up-to-date with the current stable version of LAMMPS by simply updating
-operating system.
+your operating system.  Please note, that the repository below offers
+two LAMMPS packages, ``lammps-daily`` and ``lammps-stable``.  The
+LAMMPS developers recommend to use the ``lammps-stable`` package for
+any production simulations.  The ``lammps-daily`` package is built
+from the LAMMPS development sources, and those versions may have known
+issues and bugs when new features are added and the software has not
+undergone full release testing.
 
 To install the appropriate personal-package archives (PPAs), do the
 following once:
@@ -37,16 +43,16 @@ To install LAMMPS do the following once:
 
 .. code-block:: bash
 
-   $ sudo apt-get install lammps-daily
+   $ sudo apt-get install lammps-stable
 
-This downloads an executable named ``lmp_daily`` to your box, which
+This downloads an executable named ``lmp_stable`` to your box, which
 can then be used in the usual way to run input scripts:
 
 .. code-block:: bash
 
-   $ lmp_daily -in in.lj
+   $ lmp_stable -in in.lj
 
-To update LAMMPS to the most current version, do the following:
+To update LAMMPS to the most current stable version, do the following:
 
 .. code-block:: bash
 
@@ -58,25 +64,25 @@ To get a copy of the current documentation and examples:
 
 .. code-block:: bash
 
-   $ sudo apt-get install lammps-daily-doc
+   $ sudo apt-get install lammps-stable-doc
 
 which will download the doc files in
-``/usr/share/doc/lammps-daily-doc/doc`` and example problems in
+``/usr/share/doc/lammps-stable-doc/doc`` and example problems in
 ``/usr/share/doc/lammps-doc/examples``.
 
 To get a copy of the current potentials files:
 
 .. code-block:: bash
 
-   $ sudo apt-get install lammps-daily-data
+   $ sudo apt-get install lammps-stable-data
 
 which will download the potentials files to
-``/usr/share/lammps-daily/potentials``.  The ``lmp_daily`` binary is
+``/usr/share/lammps-stable/potentials``.  The ``lmp_stable`` binary is
 hard-coded to look for potential files in this directory (it does not
 use the `LAMMPS_POTENTIALS` environment variable, as described
 in :doc:`pair_coeff <pair_coeff>` command).
 
-The ``lmp_daily`` binary is built with the :ref:`KIM package <kim>` which
+The ``lmp_stable`` binary is built with the :ref:`KIM package <kim>` which
 results in the above command also installing the `kim-api` binaries when LAMMPS
 is installed.  In order to use potentials from `openkim.org <openkim_>`_, you
 can install the `openkim-models` package
@@ -89,9 +95,9 @@ To un-install LAMMPS, do the following:
 
 .. code-block:: bash
 
-   $ sudo apt-get remove lammps-daily
+   $ sudo apt-get remove lammps-stable
 
-Please use ``lmp_daily -help`` to see which compilation options, packages,
+Please use ``lmp_stable -help`` to see which compilation options, packages,
 and styles are included in the binary.
 
 Thanks to Anton Gladky (gladky.anton at gmail.com) for setting up this

doc/src/Intro_nonfeatures.rst

@@ -34,7 +34,7 @@ Here are suggestions on how to perform these tasks:
   molecular builder that will generate complex molecular models.  See
   the :doc:`Tools <Tools>` doc page for details on tools packaged with
   LAMMPS.  The `Pre/post processing page <http:/lammps.sandia.gov/prepost.html>`_ of the LAMMPS website
-  describes a variety of 3rd party tools for this task.  Furthermore,
+  describes a variety of third party tools for this task.  Furthermore,
   some LAMMPS internal commands allow to reconstruct, or selectively add
   topology information, as well as provide the option to insert molecule
   templates instead of atoms for building bulk molecular systems.

doc/src/Manual.rst

@@ -32,11 +32,12 @@ a brief description of the basic code structure of LAMMPS.
 
 ----------
 
-Once you are familiar with LAMMPS, you may want to bookmark :doc:`this page <Commands>` since it gives quick access to a doc page for
+Once you are familiar with LAMMPS, you may want to bookmark :doc:`this page <Commands_all>` since it gives quick access to a doc page for
 every LAMMPS command.
 
 .. _lws: https://lammps.sandia.gov
 
+.. _user_documentation:
 .. toctree::
    :maxdepth: 2
    :numbered: 3

doc/src/Manual_build.rst

@@ -1,60 +1,62 @@
 Building the LAMMPS manual
 **************************
 
-Depending on how you obtained LAMMPS, the doc directory has up
+Depending on how you obtained LAMMPS and whether you have built the
-to 6 sub-directories, 2 Nroff files, and optionally 2 PDF files
+manual yourself, this directory has a number of sub-directories and
-plus 2 e-book format files:
+files. Here is a list with descriptions:
 
 .. code-block:: bash
 
-   src             # content files for LAMMPS documentation
+   README           # brief info about the documentation
-   html            # HTML version of the LAMMPS manual (see html/Manual.html)
+   src              # content files for LAMMPS documentation
-   utils           # tools and settings for building the documentation
+   html             # HTML version of the LAMMPS manual (see html/Manual.html)
-   docenv          # virtualenv for processing the manual sources
+   utils            # tools and settings for building the documentation
-   doctrees        # temporary data from processing the manual
+   lammps.1         # man page for the lammps command
-   mathjax         # code and fonts for rendering math in html
+   msi2lmp.1        # man page for the msi2lmp command
-   Manual.pdf      # large PDF version of entire manual
+   Manual.pdf       # large PDF version of entire manual
-   Developer.pdf   # small PDF with info about how LAMMPS is structured
+   Developer.pdf    # small PDF with info about how LAMMPS is structured
-   LAMMPS.epub     # Manual in ePUB e-book format
+   LAMMPS.epub      # Manual in ePUB e-book format
-   LAMMPS.mobi     # Manual in MOBI e-book format
+   LAMMPS.mobi      # Manual in MOBI e-book format
-   lammps.1        # man page for the lammps command
+   docenv           # virtualenv folder for processing the manual sources
-   msi2lmp.1       # man page for the msi2lmp command
+   doctrees         # temporary data from processing the manual
+   mathjax          # code and fonts for rendering math in html
+   doxygen          # doxygen configuration and output
+   .gitignore       # list of files and folders to be ignored by git
+   doxygen-warn.log # logfile with warnings from running doxygen
+   github-development-workflow.md   # notes on the LAMMPS development workflow
+   include-file-conventions.md      # notes on LAMMPS' include file conventions
 
-If you downloaded LAMMPS as a tarball from the web site, the html folder
+If you downloaded LAMMPS as a tarball from `the LAMMPS website <lws_>`_,
-and the PDF files should be included.
+the html folder and the PDF files should be included.
 
 If you downloaded LAMMPS from the public git repository, then the HTML
 and PDF files are not included.  Instead you need to create them, in one
 of two ways:
 
 a. You can "fetch" the current HTML and PDF files from the LAMMPS web
-   site.  Just type "make fetch".  This should download a html_www
+   site.  Just type ``make fetch``.  This should download a html_www
    directory and Manual_www.pdf/Developer_www.pdf files.  Note that if
    new LAMMPS features have been added more recently than the date of
    your LAMMPS version, the fetched documentation will include those
    changes (but your source code will not, unless you update your local
    repository).
 
-b. You can build the HTML or PDF files yourself, by typing "make html"
+b. You can build the HTML or PDF files yourself, by typing ``make html``
-   or "make pdf".  This requires various tools including Sphinx, git,
+   or ``make pdf``.  This requires various tools and files.  Some of them
-   and the MathJax javascript library, which the build process will attempt
+   have to be installed (more on that below). For the rest the build
-   to download automatically into a virtual environment in the folder
+   process will attempt to download and install them into a python
-   doc/docenv and the folder mathjax, respectively, if not already available.
+   virtual environment and local folders.  This download is required
-   This download is required only once, unless you type "make clean-all".
+   only once, unless you type ``make clean-all``.  After that, viewing and
-   After that, viewing and  processing of the documentation can be done
+   processing of the documentation can be done without internet access.
-   without internet access.  To generate the PDF version of the manual,
-   the PDFLaTeX software and several LaTeX packages are required as well.
-   However, those cannot be installed automatically at the moment.
 
 ----------
 
-The generation of all documentation is managed by the Makefile in
+The generation of all documentation is managed by the Makefile in the
-the doc directory.
+doc directory. The following documentation related make commands are
+available:
 
 .. code-block:: bash
 
-   Documentation Build Options:
-
    make html          # generate HTML in html dir using Sphinx
    make pdf           # generate 2 PDF files (Manual.pdf,Developer.pdf)
                       #   in doc dir via htmldoc and pdflatex
@@ -62,8 +64,10 @@ the doc directory.
                       #   as a tarball and unpack into html dir and 2 PDFs
    make epub          # generate LAMMPS.epub in ePUB format using Sphinx
    make mobi          # generate LAMMPS.mobi in MOBI format using ebook-convert
+
    make clean         # remove intermediate RST files created by HTML build
    make clean-all     # remove entire build folder and any cached data
+
    make anchor_check  # check for duplicate anchor labels
    make style_check   # check for complete and consistent style lists
    make package_check # check for complete and consistent package lists
@@ -74,29 +78,30 @@ the doc directory.
 Installing prerequisites for HTML build
 =======================================
 
-To run the HTML documentation build toolchain, Python 3 and virtualenv
+To run the HTML documentation build toolchain, python 3, git, doxygen,
-have to be installed.  Here are instructions for common setups:
+and virtualenv have to be installed locally.  Here are instructions for
+common setups:
 
 Ubuntu
 ------
 
 .. code-block:: bash
 
-   sudo apt-get install python-virtualenv
+   sudo apt-get install python-virtualenv git doxygen
 
 Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x)
 ------------------------------------------------------------------------------------
 
 .. code-block:: bash
 
-   sudo yum install python3-virtualenv
+   sudo yum install python3-virtualenv git doxygen
 
 Fedora (since version 22)
 -------------------------
 
 .. code-block:: bash
 
-   sudo dnf install python3-virtualenv
+   sudo dnf install python3-virtualenv git doxygen
 
 MacOS X
 -------
@@ -120,22 +125,92 @@ Once Python 3 is installed, open a Terminal and type
 
 This will install virtualenv from the Python Package Index.
 
-----------
+Installing prerequisites for PDF build
+======================================
 
-Installing prerequisites for epub build
+In addition to the tools needed for building the HTML format manual,
-=======================================
+a working LaTeX installation with support for PDFLaTeX and a selection
+of LaTeX styles/packages are required.
 
-ePUB
+Installing prerequisites for e-book reader builds
-----
+=================================================
 
-Same as for HTML. This uses mostly the same tools and configuration
+In addition to the tools needed for building the HTML format manual,
-files as the HTML tree. In addition it uses LaTeX to convert embedded
+a working LaTeX installation with a few add-on LaTeX packages
+as well as the ``dvipng`` tool are required to convert embedded
 math expressions transparently into embedded images.
 
-For converting the generated ePUB file to a MOBI format file
+For converting the generated ePUB file to a MOBI format file (for e-book
-(for e-book readers, like Kindle, that cannot read ePUB), you
+readers, like Kindle, that cannot read ePUB), you also need to have the
-also need to have the 'ebook-convert' tool from the "calibre"
+``ebook-convert`` tool from the "calibre" software
-software installed. `http://calibre-ebook.com/ <http://calibre-ebook.com/>`_
+installed. `http://calibre-ebook.com/ <http://calibre-ebook.com/>`_
-You first create the ePUB file and then convert it with 'make mobi'
+Typing ``make mobi`` will first create the ePUB file and then convert
-On the Kindle readers in particular, you also have support for
+it.  On the Kindle readers in particular, you also have support for PDF
-PDF files, so you could download and view the PDF version as an alternative.
+files, so you could download and view the PDF version as an alternative.
+
+
+Instructions for Developers
+===========================
+
+When adding new styles or options to the LAMMPS code, corresponding
+documentation is required and either existing files in the ``src``
+folder need to be updated or new files added. These files are written
+in `reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
+
+Before contributing any documentation, please check that both the HTML
+and the PDF format documentation can translate without errors. Please also
+check the output to the console for any warnings or problems.  There will
+be multiple tests run automatically:
+
+- A test for correctness of all anchor labels and their references
+
+- A test that all LAMMPS packages (= folders with sources in
+  ``lammps/src``) are documented and listed.  A typical warning shows
+  the name of the folder with the suspected new package code and the
+  documentation files where they need to be listed:
+
+  .. parsed-literal::
+
+     Found 33 standard and 41 user packages
+     Standard package NEWPACKAGE missing in Packages_standard.rst
+     Standard package NEWPACKAGE missing in Packages_details.rst
+
+- A test that only standard, printable ASCII text characters are used.
+  This runs the command ``env LC_ALL=C grep -n '[^ -~]' src/*.rst`` and
+  thus prints all offending lines with filename and line number
+  prepended to the screen.  Special characters like the Angstrom
+  :math:`\mathrm{\mathring{A}}` should be typeset with embedded math
+  (like this ``:math:`\mathrm{\mathring{A}}```\ ).
+
+- A test whether all styles are documented and listed in their
+  respective overview pages.  A typical output with warnings looks like this:
+
+  .. parsed-literal::
+
+     Parsed style names w/o suffixes from C++ tree in ../src:
+        Angle styles:      21    Atom styles:       24
+        Body styles:        3    Bond styles:       17
+        Command styles:    41    Compute styles:   143
+        Dihedral styles:   16    Dump styles:       26
+        Fix styles:       223    Improper styles:   13
+        Integrate styles:   4    Kspace styles:     15
+        Minimize styles:    9    Pair styles:      234
+        Reader styles:      4    Region styles:      8
+     Compute style entry newcomp is missing or incomplete in Commands_compute.rst
+     Compute style entry newcomp is missing or incomplete in compute.rst
+     Fix style entry newfix is missing or incomplete in Commands_fix.rst
+     Fix style entry newfix is missing or incomplete in fix.rst
+     Pair style entry new is missing or incomplete in Commands_pair.rst
+     Pair style entry new is missing or incomplete in pair_style.rst
+     Found 6 issue(s) with style lists
+
+
+In addition, there is the option to run a spellcheck on the entire
+manual with ``make spelling``.  This requires `a library called enchant
+<https://github.com/AbiWord/enchant>`_.  To avoid printing out *false
+positives* (e.g. keywords, names, abbreviations) those can be added to
+the file ``lammps/doc/utils/sphinx-config/false_positives.txt``.
+
+.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
+
+.. _lws: https://lammps.sandia.gov

doc/src/Modify_atom.rst

@@ -3,115 +3,169 @@ Atom styles
 
 Classes that define an :doc:`atom style <atom_style>` are derived from
 the AtomVec class and managed by the Atom class.  The atom style
-determines what attributes are associated with an atom.  A new atom
+determines what attributes are associated with an atom and
-style can be created if one of the existing atom styles does not
+communicated when it is a ghost atom or migrates to a new processor.
-define all the attributes you need to store and communicate with
+A new atom style can be created if one of the existing atom styles
-atoms.
+does not define all the attributes you need to store and communicate
+with atoms.
 
-Atom_vec_atomic.cpp is a simple example of an atom style.
+Atom_vec_atomic.cpp is the simplest example of an atom style.
+Examining the code for others will make these instructions more clear.
 
-Here is a brief description of methods you define in your new derived
+Note that the :doc:`atom style hybrid <atom_style>` command can be
-class.  See atom_vec.h for details.
+used to define atoms or particles which have the union of properties
+of individual styles.  Also the :doc:`fix property/atom <fix_property_atom>`
+command can be used to add a single property (e.g. charge
+or a molecule ID) to a style that does not have it.  It can also be
+used to add custom properties to an atom, with options to communicate
+them with ghost atoms or read them from a data file.  Other LAMMPS
+commands can access these custom properties, as can new pair, fix,
+compute styles that are written to work with these properties.  For
+example, the :doc:`set <set>` command can be used to set the values of
+custom per-atom properties from an input script.  All of these methods
+are less work than writing code for a new atom style.
 
-+-------------------------+--------------------------------------------------------------------------------+
+If you follow these directions your new style will automatically work
-| init                    | one time setup (optional)                                                      |
+in tandem with others via the :doc:`atom_style hybrid <atom_style>`
-+-------------------------+--------------------------------------------------------------------------------+
+command.
-| grow                    | re-allocate atom arrays to longer lengths (required)                           |
-+-------------------------+--------------------------------------------------------------------------------+
-| grow_reset              | make array pointers in Atom and AtomVec classes consistent (required)          |
-+-------------------------+--------------------------------------------------------------------------------+
-| copy                    | copy info for one atom to another atom's array locations (required)            |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_comm               | store an atom's info in a buffer communicated every timestep (required)        |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_comm_vel           | add velocity info to communication buffer (required)                           |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_comm_hybrid        | store extra info unique to this atom style (optional)                          |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_comm             | retrieve an atom's info from the buffer (required)                             |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_comm_vel         | also retrieve velocity info (required)                                         |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_comm_hybrid      | retrieve extra info unique to this atom style (optional)                       |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_reverse            | store an atom's info in a buffer communicating partial forces  (required)      |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_reverse_hybrid     | store extra info unique to this atom style (optional)                          |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_reverse          | retrieve an atom's info from the buffer (required)                             |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_reverse_hybrid   | retrieve extra info unique to this atom style (optional)                       |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_border             | store an atom's info in a buffer communicated on neighbor re-builds (required) |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_border_vel         | add velocity info to buffer (required)                                         |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_border_hybrid      | store extra info unique to this atom style (optional)                          |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_border           | retrieve an atom's info from the buffer (required)                             |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_border_vel       | also retrieve velocity info (required)                                         |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_border_hybrid    | retrieve extra info unique to this atom style (optional)                       |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_exchange           | store all an atom's info to migrate to another processor (required)            |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_exchange         | retrieve an atom's info from the buffer (required)                             |
-+-------------------------+--------------------------------------------------------------------------------+
-| size_restart            | number of restart quantities associated with proc's atoms (required)           |
-+-------------------------+--------------------------------------------------------------------------------+
-| pack_restart            | pack atom quantities into a buffer (required)                                  |
-+-------------------------+--------------------------------------------------------------------------------+
-| unpack_restart          | unpack atom quantities from a buffer (required)                                |
-+-------------------------+--------------------------------------------------------------------------------+
-| create_atom             | create an individual atom of this style (required)                             |
-+-------------------------+--------------------------------------------------------------------------------+
-| data_atom               | parse an atom line from the data file (required)                               |
-+-------------------------+--------------------------------------------------------------------------------+
-| data_atom_hybrid        | parse additional atom info unique to this atom style (optional)                |
-+-------------------------+--------------------------------------------------------------------------------+
-| data_vel                | parse one line of velocity information from data file (optional)               |
-+-------------------------+--------------------------------------------------------------------------------+
-| data_vel_hybrid         | parse additional velocity data unique to this atom style (optional)            |
-+-------------------------+--------------------------------------------------------------------------------+
-| memory_usage            | tally memory allocated by atom arrays (required)                               |
-+-------------------------+--------------------------------------------------------------------------------+
 
-The constructor of the derived class sets values for several variables
+The first step is to define a set of strings in the constructor of the
-that you must set when defining a new atom style, which are documented
+new derived class.  Each string will have zero or more space-separated
-in atom_vec.h.  New atom arrays are defined in atom.cpp.  Search for
+variable names which are identical to those used in the atom.h header
-the word "customize" and you will find locations you will need to
+file for per-atom properties.  Note that some represent per-atom
-modify.
+vectors (q, molecule) while other are per-atom arrays (x,v).  For all
+but the last 2 strings you do not need to specify any of
+(id,type,x,v,f).  Those are included automatically as needed in the
+other strings.
 
-.. note::
+.. list-table::
 
-   It is possible to add some attributes, such as a molecule ID, to
+   * - fields_grow
-   atom styles that do not have them via the :doc:`fix property/atom <fix_property_atom>` command.  This command also
+     - full list of properties which is allocated and stored
-   allows new custom attributes consisting of extra integer or
+   * - fields_copy
-   floating-point values to be added to atoms.  See the :doc:`fix property/atom <fix_property_atom>` doc page for examples of cases
+     - list of properties to copy atoms are rearranged on-processor
-   where this is useful and details on how to initialize, access, and
+   * - fields_comm
-   output the custom values.
+     - list of properties communicated to ghost atoms every step
+   * - fields_comm_vel
+     - additional properties communicated if :doc:`comm_modify vel <atom_style>` is used
+   * - fields_reverse
+     - list of properties summed from ghost atoms every step
+   * - fields_border
+     - list of properties communicated with ghost atoms every reneighboring step
+   * - fields_border_vel
+     - additional properties communicated if :doc:`comm_modify vel <atom_style>` is used
+   * - fields_exchange
+     - list of properties communicated when an atom migrates to another processor
+   * - fields_restart
+     - list of properties written/read to/from a restart file
+   * - fields_create
+     - list of properties defined when an atom is created by :doc:`create_atoms <create_atoms>`
+   * - fields_data_atom
+     - list of properties (in order) in the Atoms section of a data file, as read by :doc:`read_data <read_data>`
+   * - fields_data_vel
+     - list of properties (in order) in the Velocities section of a data file, as read by :doc:`read_data <read_data>`
 
-New :doc:`pair styles <pair_style>`, :doc:`fixes <fix>`, or
+In these strings you can list variable names which LAMMPS already
-:doc:`computes <compute>` can be added to LAMMPS, as discussed below.
+defines (in some other atom style), or you can create new variable
-The code for these classes can use the per-atom properties defined by
+names.  You should not re-use a LAMMPS variable for something with
-fix property/atom.  The Atom class has a find_custom() method that is
+different meaning in your atom style.  If the meaning is related, but
-useful in this context:
+interpreted differently by your atom style, then using the same
+variable name means a user should not use your style and the other
+style together in a :doc:`atom_style hybrid <atom_style>` command.
+Because there will only be one value of the variable and different
+parts of LAMMPS will then likely use it differently.  LAMMPS has
+no way of checking for this.
 
-.. code-block:: c++
+If you are defining new variable names then make them descriptive and
+unique to your new atom style.  For example choosing "e" for energy is
+a bad choice; it is too generic.  A better choice would be "e_foo",
+where "foo" is specific to your style.
 
-   int index = atom->find_custom(char *name, int &flag);
+If any of the variable names in your new atom style do not exist in
+LAMMPS, you need to add them to the src/atom.h and atom.cpp files.
 
-The "name" of a custom attribute, as specified in the :doc:`fix property/atom <fix_property_atom>` command, is checked to verify
+Search for the word "customize" or "customization" in these 2 files to
-that it exists and its index is returned.  The method also sets flag =
+see where to add your variable.  Adding a flag to the 2nd
-0/1 depending on whether it is an integer or floating-point attribute.
+customization section in atom.h is only necessary if your code (e.g. a
-The vector of values associated with the attribute can then be
+pair style) needs to check that a per-atom property is defined.  These
-accessed using the returned index as
+flags should also be set in the constructor of the atom style child
+class.
 
-.. code-block:: c++
+In atom.cpp, aside from the constructor and destructor, there are 3
+methods that a new variable name or flag needs to be added to.
 
-   int *ivector = atom->ivector[index];
+In Atom::peratom_create() when using the add_peratom() method, a
-   double *dvector = atom->dvector[index];
+final length argument of 0 is for per-atom vectors, a length > 1 is
+for per-atom arrays.  Note the use of an extra per-thread flag and the
+add_peratom_vary() method when last dimension of the array is
+variable-length.
 
-Ivector or dvector are vectors of length Nlocal = # of owned atoms,
+Adding the variable name to Atom::extract() enable the per-atom data
-which store the attributes of individual atoms.
+to be accessed through the :doc:`LAMMPS library interface
+<Howto_library>` by a calling code, including from :doc:`Python
+<Python_head>`.
+
+The constructor of the new atom style will also typically set a few
+flags which are defined at the top of atom_vec.h.  If these are
+unclear, see how other atom styles use them.
+
+The grow_pointers() method is also required to make
+a copy of peratom data pointers, as explained in the code.
+
+There are a number of other optional methods which your atom style can
+implement.  These are only needed if you need to do something
+out-of-the-ordinary which the default operation of the AtomVec parent
+class does not take care of.  The best way to figure out why they are
+sometimes useful is to look at how other atom styles use them.
+
+* process_args = use if the atom style has arguments
+* init = called before each run
+* force_clear = called before force computations each timestep
+
+A few atom styles define "bonus" data associated with some or all of
+their particles, such as :doc:`atom_style ellipsoid or tri
+<atom_style>`.  These methods work with that data:
+
+* copy_bonus
+* clear_bonus
+* pack_comm_bonus
+* unpack_comm_bonus
+* pack_border_bonus
+* unpack_border_bonus
+* pack_exchange_bonus
+* unpack_exchange_bonus
+* size_restart_bonus
+* pack_restart_bonus
+* unpack_restart_bonus
+* data_atom_bonus
+* memory_usage_bonus
+
+The :doc:`atom_style body <atom_style>` command can define a particle
+geometry with an arbitrary number of values.  This method reads it
+from a data file:
+
+* data_body
+
+These methods are called before or after operations handled by the
+parent AtomVec class.  They allow an atom style to do customized
+operations on the per-atom values.  For example :doc:`atom_style
+sphere <atom_style>` reads a diameter and density of each particle
+from a data file.  But these need to be converted internally to a
+radius and mass.  That operation is done in the data_atom_post()
+method.
+
+* pack_restart_pre
+* pack_restart_post
+* unpack_restart_init
+* create_atom_post
+* data_atom_post
+* pack_data_pre
+* pack_data_post
+
+These methods enable the :doc:`compute property/atom <compute_property_atom>`
+command to access per-atom variables it does not
+already define as arguments, so that they can be written to a dump
+file or used by other LAMMPS commands.
+
+* property_atom
+* pack_property_atom

doc/src/Modify_contribute.rst

@@ -1,37 +1,51 @@
 Submitting new features for inclusion in LAMMPS
 ===============================================
 
-We encourage users to submit new features or modifications for LAMMPS
+We encourage users to submit new features or modifications for LAMMPS to
-to `the core developers <https://lammps.sandia.gov/authors.html>`_ so they
+`the core developers <https://lammps.sandia.gov/authors.html>`_ so they
-can be added to the LAMMPS distribution. The preferred way to manage
+can be added to the LAMMPS distribution. The preferred way to manage and
-and coordinate this is as of Fall 2016 via the LAMMPS project on
+coordinate this is via the LAMMPS project on `GitHub
-`GitHub <https://github.com/lammps/lammps>`_. An alternative is to
+<https://github.com/lammps/lammps>`_.  Please see the :doc:`GitHub
-contact the LAMMPS developers or the indicated developer of a package
+Tutorial <Howto_github>` for a demonstration on how to do that.  An
-or feature directly and send in your contribution via e-mail.
+alternative is to contact the LAMMPS developers or the indicated
+developer of a package or feature directly and send in your contribution
+via e-mail, but that can add a significant delay on getting your
+contribution included, depending on how busy the developer is you
+contact, how complex a task it would be to integrate that code, and how
+many - if any - changes are required before the code can be included.
 
-For any larger modifications or programming project, you are
+For any larger modifications or programming project, you are encouraged
-encouraged to contact the LAMMPS developers ahead of time, in order to
+to contact the LAMMPS developers ahead of time, in order to discuss
-discuss implementation strategies and coding guidelines, that will
+implementation strategies and coding guidelines, that will make it
-make it easier to integrate your contribution and result in less work
+easier to integrate your contribution and result in less work for
-for everybody involved. You are also encouraged to search through the
+everybody involved. You are also encouraged to search through the list
-list of `open issues on GitHub <https://github.com/lammps/lammps/issues>`_ and submit a new issue
+of `open issues on GitHub <https://github.com/lammps/lammps/issues>`_
-for a planned feature, so you would not duplicate the work of others
+and submit a new issue for a planned feature, so you would not duplicate
-(and possibly get scooped by them) or have your work duplicated by
+the work of others (and possibly get scooped by them) or have your work
-others.
+duplicated by others.
 
-How quickly your contribution will be integrated depends largely on
+For informal communication with (some of) the LAMMPS developers you may
-how much effort it will cause to integrate and test it, how much it
+ask to join the `LAMMPS developers on Slack <https://lammps.slack.com>`_.
-requires changes to the core codebase, and of how much interest it is
+This slack work space is by invitation only. Thus for access, please
-to the larger LAMMPS community.  Please see below for a checklist of
+send an e-mail to ``slack@lammps.org`` explaining what part of LAMMPS
-typical requirements. Once you have prepared everything, see the
+you are working on.  Only discussions related to LAMMPS development are
-:doc:`Using GitHub with LAMMPS Howto <Howto_github>` doc page for instructions on how to
+tolerated, so this is **NOT** for people that look for help with compiling,
-submit your changes or new files through a GitHub pull request. If you
+installing, or using LAMMPS. Please contact the `lammps-users mailing
-prefer to submit patches or full files, you should first make certain,
+list <https://lammps.sandia.gov>`_ for those purposes instead.
-that your code works correctly with the latest patch-level version of
+
-LAMMPS and contains all bug fixes from it. Then create a gzipped tar
+How quickly your contribution will be integrated depends largely on how
-file of all changed or added files or a corresponding patch file using
+much effort it will cause to integrate and test it, how much it requires
-'diff -u' or 'diff -c' and compress it with gzip. Please only use gzip
+changes to the core codebase, and of how much interest it is to the
-compression, as this works well on all platforms.
+larger LAMMPS community.  Please see below for a checklist of typical
+requirements. Once you have prepared everything, see the :doc:`Using
+GitHub with LAMMPS Howto <Howto_github>` doc page for instructions on
+how to submit your changes or new files through a GitHub pull
+request. If you prefer to submit patches or full files, you should first
+make certain, that your code works correctly with the latest patch-level
+version of LAMMPS and contains all bug fixes from it. Then create a
+gzipped tar file of all changed or added files or a corresponding patch
+file using 'diff -u' or 'diff -c' and compress it with gzip. Please only
+use gzip compression, as this works well on all platforms.
 
 If the new features/files are broadly useful we may add them as core
 files to LAMMPS or as part of a :doc:`standard package <Packages_standard>`.  Else we will add them as a

doc/src/Modify_fix.rst

@@ -27,7 +27,7 @@ derived class.  See fix.h for details.
 +---------------------------+--------------------------------------------------------------------------------------------+
 | setup_pre_force           | called before force computation in setup (optional)                                        |
 +---------------------------+--------------------------------------------------------------------------------------------+
-| setup                     | called immediately before the 1st timestep and after forces are computed (optional)        |
+| setup                     | called immediately before the first timestep and after forces are computed (optional)      |
 +---------------------------+--------------------------------------------------------------------------------------------+
 | min_setup_pre_force       | like setup_pre_force, but for minimizations instead of MD runs (optional)                  |
 +---------------------------+--------------------------------------------------------------------------------------------+

doc/src/Modify_kspace.rst

@@ -10,12 +10,12 @@ Ewald.cpp is an example of computing K-space interactions.
 Here is a brief description of methods you define in your new derived
 class.  See kspace.h for details.
 
-+---------------+----------------------------------------------+
++---------------+------------------------------------------------+
-| init          | initialize the calculation before a run      |
+| init          | initialize the calculation before a run        |
-+---------------+----------------------------------------------+
++---------------+------------------------------------------------+
-| setup         | computation before the 1st timestep of a run |
+| setup         | computation before the first timestep of a run |
-+---------------+----------------------------------------------+
++---------------+------------------------------------------------+
-| compute       | every-timestep computation                   |
+| compute       | every-timestep computation                     |
-+---------------+----------------------------------------------+
++---------------+------------------------------------------------+
-| memory_usage  | tally of memory usage                        |
+| memory_usage  | tally of memory usage                          |
-+---------------+----------------------------------------------+
++---------------+------------------------------------------------+

doc/src/Packages_details.rst

@@ -44,6 +44,7 @@ page gives those details.
    * :ref:`MC <PKG-MC>`
    * :ref:`MESSAGE <PKG-MESSAGE>`
    * :ref:`MISC <PKG-MISC>`
+   * :ref:`MLIAP <PKG-MLIAP>`
    * :ref:`MOLECULE <PKG-MOLECULE>`
    * :ref:`MPIIO <PKG-MPIIO>`
    * :ref:`MSCG <PKG-MSCG>`
@@ -81,6 +82,7 @@ page gives those details.
    * :ref:`USER-MANIFOLD <PKG-USER-MANIFOLD>`
    * :ref:`USER-MEAMC <PKG-USER-MEAMC>`
    * :ref:`USER-MESODPD <PKG-USER-MESODPD>`
+   * :ref:`USER-MESONT <PKG-USER-MESONT>`
    * :ref:`USER-MGPT <PKG-USER-MGPT>`
    * :ref:`USER-MISC <PKG-USER-MISC>`
    * :ref:`USER-MOFFF <PKG-USER-MOFFF>`
@@ -304,7 +306,8 @@ gpu" or "-suffix gpu" :doc:`command-line switches <Run_options>`.  See
 also the :ref:`KOKKOS <PKG-KOKKOS>` package, which has GPU-enabled styles.
 
 **Authors:** Mike Brown (Intel) while at Sandia and ORNL and Trung Nguyen
-(Northwestern U) while at ORNL.
+(Northwestern U) while at ORNL and later. AMD HIP support by Evgeny
+Kuznetsov, Vladimir Stegailov, and Vsevolod Nikolskiy (HSE University).
 
 **Install:**
 
@@ -489,7 +492,7 @@ interactions.  These include Ewald, particle-particle particle-mesh
 
 Building with this package requires a 1d FFT library be present on
 your system for use by the PPPM solvers.  This can be the KISS FFT
-library provided with LAMMPS, 3rd party libraries like FFTW, or a
+library provided with LAMMPS, third party libraries like FFTW, or a
 vendor-supplied FFT library.  See the :doc:`Build settings <Build_settings>` doc page for details on how to select
 different FFT options for your LAMPMS build.
 
@@ -651,6 +654,29 @@ listing, "ls src/MISC", to see the list of commands.
 
 ----------
 
+.. _PKG-MLIAP:
+
+MLIAP package
+-------------
+
+**Contents:**
+
+A general interface for machine-learning interatomic potentials.
+
+**Install:**
+
+To use this package, also the :ref:`SNAP package<PKG-SNAP>` needs to be installed.
+
+**Author:** Aidan Thompson (Sandia).
+
+**Supporting info:**
+
+* src/MLIAP: filenames -> commands
+* :doc:`pair_style mliap <pair_mliap>`
+* examples/mliap
+
+----------
+
 .. _PKG-MOLECULE:
 
 MOLECULE package
@@ -1712,6 +1738,56 @@ algorithm.
 * examples/USER/mesodpd
 * https://lammps.sandia.gov/movies.html#mesodpd
 
+* examples/USER/meso
+* http://lammps.sandia.gov/movies.html#mesodpd
+
+----------
+
+.. _PKG-USER-MESONT:
+
+USER-MESONT package
+-------------------
+
+**Contents:**
+
+USER-MESONT is a LAMMPS package for simulation of nanomechanics of
+nanotubes (NTs). The model is based on a coarse-grained representation
+of NTs as "flexible cylinders" consisting of a variable number of
+segments. Internal interactions within a NT and the van der Waals
+interaction between the tubes are described by a mesoscopic force field
+designed and parameterized based on the results of atomic-level
+molecular dynamics simulations. The description of the force field is
+provided in the papers listed below. This package contains two
+independent implementations of this model: :doc:`pair_style mesocnt
+<pair_mesocnt>` is a (minimal) C++ implementation, and :doc:`pair_style
+mesont/tpm <pair_mesont_tpm>` is a more general and feature rich
+implementation based on a Fortran library in the ``lib/mesont`` folder.
+
+**Download of potential files:**
+
+The potential files for these pair styles are *very* large and thus
+are not included in the regular downloaded packages of LAMMPS or the
+git repositories.  Instead, they will be automatically downloaded
+from a web server when the package is installed for the first time.
+
+**Authors of the *mesont* styles:**
+
+Maxim V. Shugaev (University of Virginia), Alexey N. Volkov (University of Alabama), Leonid V. Zhigilei (University of Virginia)
+
+**Author of the *mesocnt* pair style:**
+Philipp Kloza (U Cambridge)
+
+**Supporting info:**
+
+* src/USER-MESONT: filenames -> commands
+* src/USER-MESONT/README
+* :doc:`atom_style mesont <atom_style>`
+* :doc:`pair_style mesont/tpm <pair_mesont_tpm>`
+* :doc:`compute mesont <compute_mesont>`
+* :doc:`pair_style mesocnt <pair_mesocnt>`
+* examples/USER/mesont
+* tools/mesont
+
 ----------
 
 .. _PKG-USER-MOFFF:
@@ -2064,7 +2140,7 @@ molecules, and chiral-sensitive reactions.
 * examples/USER/reaction
 * `2017 LAMMPS Workshop <https://lammps.sandia.gov/workshops/Aug17/pdf/gissinger.pdf>`_
 * `2019 LAMMPS Workshop <https://lammps.sandia.gov/workshops/Aug19/talk_gissinger.pdf>`_
-* disarmmd.org
+* reacter.org
 
 ----------
 

doc/src/Packages_standard.rst

@@ -59,6 +59,8 @@ package:
 +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`MISC <PKG-MISC>`           | miscellaneous single-file commands   | n/a                                                | no                                                   | no      |
 +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
+| :ref:`MLIAP <PKG-MLIAP>`         | multiple machine learning potentials | :doc:`pair_style mliap <pair_mliap>`               | mliap                                                | no      |
++----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`MOLECULE <PKG-MOLECULE>`   | molecular system force fields        | :doc:`Howto bioFF <Howto_bioFF>`                   | peptide                                              | no      |
 +----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`MPIIO <PKG-MPIIO>`         | MPI parallel I/O dump and restart    | :doc:`dump <dump>`                                 | n/a                                                  | no      |

doc/src/Packages_user.rst

@@ -67,6 +67,8 @@ package:
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-MESODPD <PKG-USER-MESODPD>`         | mesoscale DPD models                                            | :doc:`pair_style edpd <pair_mesodpd>`                                         | USER/mesodpd                                         | no      |
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
+| :ref:`USER-MESONT <PKG-USER-MESONT>`           | mesoscopic tubular potential model for nanotubes                | pair style :doc:`mesont/tpm <pair_mesont_tpm>`, :doc:`mesocnt <pair_mesocnt>` | USER/mesont                                          | int     |
++------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-MGPT <PKG-USER-MGPT>`               | fast MGPT multi-ion potentials                                  | :doc:`pair_style mgpt <pair_mgpt>`                                            | USER/mgpt                                            | no      |
 +------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
 | :ref:`USER-MISC <PKG-USER-MISC>`               | single-file contributions                                       | USER-MISC/README                                                              | USER/misc                                            | no      |

doc/src/Python_examples.rst

@@ -80,16 +80,23 @@ See the python/README file for instructions on how to run them and the
 source code for individual scripts for comments about what they do.
 
 Here are screenshots of the vizplotgui_tool.py script in action for
-different visualization package options.  Click to see larger images:
+different visualization package options:
 
-.. image:: JPG/screenshot_gl_small.jpg
+.. |pyex1| image:: img/screenshot_gl.jpg
-   :target: JPG/screenshot_gl.jpg
+   :width: 24%
 
-.. image:: JPG/screenshot_atomeye_small.jpg
+.. |pyex2| image:: img/screenshot_atomeye.jpg
-   :target: JPG/screenshot_atomeye.jpg
+   :width: 24%
 
-.. image:: JPG/screenshot_pymol_small.jpg
+.. |pyex3| image:: img/screenshot_pymol.jpg
-   :target: JPG/screenshot_pymol.jpg
+   :width: 24%
+
+.. |pyex4| image:: img/screenshot_vmd.jpg
+   :width: 24%
+
+|pyex1|  |pyex2|  |pyex3|  |pyex4|
+
+.. raw:: html
+
+   Click to see larger versions of the images.
 
-.. image:: JPG/screenshot_vmd_small.jpg
-   :target: JPG/screenshot_vmd.jpg

doc/src/Python_library.rst

@@ -254,12 +254,3 @@ following steps:
 * You should now be able to invoke the new interface function from a
   Python script.
 
-----------
-
-.. autoclass:: lammps.lammps
-   :members:
-   :no-undoc-members:
-
-.. autoclass:: lammps.NeighList
-   :members:
-   :no-undoc-members:

doc/src/Python_test.rst

@@ -10,7 +10,7 @@ and type:
    >>> lmp = lammps()
 
 If you get no errors, you're ready to use LAMMPS from Python.  If the
-2nd command fails, the most common error to see is
+second command fails, the most common error to see is
 
 .. parsed-literal::
 
@@ -78,7 +78,7 @@ above, create a test.py file containing these lines:
    pypar.finalize()
 
 To run LAMMPS in parallel, assuming you have installed the
-`mpi4py <https://bitbucket.org/mpi4py/mpi4py>`_ package as discussed
+`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
 above, create a test.py file containing these lines:
 
 .. code-block:: python

doc/src/Run_options.rst

@@ -324,17 +324,17 @@ physical processors is done by MPI before LAMMPS begins.  It may be
 useful in some cases to alter the rank order.  E.g. to insure that
 cores within each node are ranked in a desired order.  Or when using
 the :doc:`run_style verlet/split <run_style>` command with 2 partitions
-to insure that a specific Kspace processor (in the 2nd partition) is
+to insure that a specific Kspace processor (in the second partition) is
-matched up with a specific set of processors in the 1st partition.
+matched up with a specific set of processors in the first partition.
 See the :doc:`Speed tips <Speed_tips>` doc page for more details.
 
 If the keyword *nth* is used with a setting *N*\ , then it means every
 Nth processor will be moved to the end of the ranking.  This is useful
 when using the :doc:`run_style verlet/split <run_style>` command with 2
 partitions via the -partition command-line switch.  The first set of
-processors will be in the first partition, the 2nd set in the 2nd
+processors will be in the first partition, the second set in the second
 partition.  The -reorder command-line switch can alter this so that
-the 1st N procs in the 1st partition and one proc in the 2nd partition
+the first N procs in the first partition and one proc in the second partition
 will be ordered consecutively, e.g. as the cores on one physical node.
 This can boost performance.  For example, if you use "-reorder nth 4"
 and "-partition 9 3" and you are running on 12 processors, the

doc/src/Speed_gpu.rst

@@ -50,6 +50,10 @@ but this can be overridden using the device option of the :doc:`package <package
 command. run lammps/lib/gpu/ocl_get_devices to get a list of available
 platforms and devices with a suitable ICD available.
 
+To compute and use this package in HIP mode, you have to have the AMD ROCm
+software installed. Versions of ROCm older than 3.5 are currently deprecated
+by AMD.
+
 **Building LAMMPS with the GPU package:**
 
 See the :ref:`Build extras <gpu>` doc page for
@@ -88,7 +92,7 @@ GPUs/node to 1.
 
 Using the "-pk" switch explicitly allows for setting of the number of
 GPUs/node to use and additional options.  Its syntax is the same as
-same as the "package gpu" command.  See the :doc:`package <package>`
+the "package gpu" command.  See the :doc:`package <package>`
 command doc page for details, including the default values used for
 all its options if it is not specified.
 

doc/src/Speed_intel.rst

@@ -138,10 +138,10 @@ For Intel Xeon Phi co-processors (Offload):
 
 **Required hardware/software:**
 
+When using Intel compilers version 16.0 or later is required.
+
 In order to use offload to co-processors, an Intel Xeon Phi
-co-processor and an Intel compiler are required. For this, the
+co-processor and an Intel compiler are required.
-recommended version of the Intel compiler is 14.0.1.106 or
-versions 15.0.2.044 and higher.
 
 Although any compiler can be used with the USER-INTEL package,
 currently, vectorization directives are disabled by default when

doc/src/accel_styles.rst

@@ -0,0 +1,17 @@
+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.  The accelerated styles take the same arguments and should
+produce the same results, except for round-off and precision issues.
+
+These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
+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
+:doc:`suffix <suffix>` command in your input script.
+
+See the :doc:`Speed packages <Speed_packages>` doc page for more
+instructions on how to use the accelerated styles effectively.

doc/src/angle_charmm.rst

@@ -37,7 +37,7 @@ The *charmm* angle style uses the potential
    E = K (\theta - \theta_0)^2 + K_{ub} (r - r_{ub})^2
 
 with an additional Urey_Bradley term based on the distance :math:`r` between
-the 1st and 3rd atoms in the angle.  :math:`K`, :math:`\theta_0`,
+the first and third atoms in the angle.  :math:`K`, :math:`\theta_0`,
 :math:`K_{ub}`, and :math:`R_{ub}` are coefficients defined for each angle
 type.
 
@@ -49,13 +49,14 @@ The following coefficients must be defined for each angle type via the
 the data file or restart files read by the :doc:`read_data <read_data>`
 or :doc:`read_restart <read_restart>` commands:
 
-* :math:`K` (energy/radian\^2)
+* :math:`K` (energy)
 * :math:`\theta_0` (degrees)
 * :math:`K_{ub}` (energy/distance\^2)
 * :math:`r_{ub}` (distance)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
-internally; hence the units of :math:`K` are in energy/radian\^2.
+radians internally; hence :math:`K` is effectively energy per
+radian\^2.
 
 ----------
 

doc/src/angle_class2.rst

@@ -41,27 +41,29 @@ The *class2* angle style uses the potential
    E_{bb} & = M (r_{ij} - r_1) (r_{jk} - r_2) \\
    E_{ba} & = N_1 (r_{ij} - r_1) (\theta - \theta_0) + N_2(r_{jk} - r_2)(\theta - \theta_0)
 
-where :math:`E_a` is the angle term, :math:`E_{bb}` is a bond-bond term, and :math:`E_{ba}` is a
+where :math:`E_a` is the angle term, :math:`E_{bb}` is a bond-bond
-bond-angle term.  :math:`\theta_0` is the equilibrium angle and :math:`r_1` and :math:`r_2` are
+term, and :math:`E_{ba}` is a bond-angle term.  :math:`\theta_0` is
-the equilibrium bond lengths.
+the equilibrium angle and :math:`r_1` and :math:`r_2` are the
+equilibrium bond lengths.
 
 See :ref:`(Sun) <angle-Sun>` for a description of the COMPASS class2 force field.
 
-Coefficients for the :math:`E_a`, :math:`E_{bb}`, and :math:`E_{ba}` formulas must be defined for
+Coefficients for the :math:`E_a`, :math:`E_{bb}`, and :math:`E_{ba}`
-each angle type via the :doc:`angle_coeff <angle_coeff>` command as in
+formulas must be defined for each angle type via the :doc:`angle_coeff
-the example above, or in the data file or restart files read by the
+<angle_coeff>` command as in the example above, or in the data file or
-:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
+restart files read by the :doc:`read_data <read_data>` or
-commands.
+:doc:`read_restart <read_restart>` commands.
 
 These are the 4 coefficients for the :math:`E_a` formula:
 
 * :math:`\theta_0` (degrees)
-* :math:`K_2` (energy/radian\^2)
+* :math:`K_2` (energy)
-* :math:`K_3` (energy/radian\^3)
+* :math:`K_3` (energy)
-* :math:`K_4` (energy/radian\^4)
+* :math:`K_4` (energy)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
-internally; hence the units of the various :math:`K` are in per-radian.
+radians internally; hence the various :math:`K` are effectively energy
+per radian\^2 or radian\^3 or radian\^4.
 
 For the :math:`E_{bb}` formula, each line in a :doc:`angle_coeff <angle_coeff>`
 command in the input script lists 4 coefficients, the first of which
@@ -93,23 +95,7 @@ since it is the same value from the :math:`E_a` formula.
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 
@@ -122,11 +108,15 @@ The *class2/p6* angle style uses the *class2* potential expanded to sixth order:
 In this expanded term 6 coefficients for the :math:`E_a` formula need to be set:
 
 * :math:`\theta_0` (degrees)
-* :math:`K_2` (energy/radian\^2)
+* :math:`K_2` (energy)
-* :math:`K_3` (energy/radian\^3)
+* :math:`K_3` (energy)
-* :math:`K_4` (energy/radian\^4)
+* :math:`K_4` (energy)
-* :math:`K_5` (energy/radian\^5)
+* :math:`K_5` (energy)
-* :math:`K_6` (energy/radian\^6)
+* :math:`K_6` (energy)
+
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
+radians internally; hence the various :math:`K` are effectively energy
+per radian\^2 or radian\^3 or radian\^4 or radian\^5 or radian\^6.
 
 The bond-bond and bond-angle terms remain unchanged.
 

doc/src/angle_coeff.rst

@@ -31,7 +31,7 @@ Angle coefficients can also be set in the data file read by the
 :doc:`read_data <read_data>` command or in a restart file.
 
 N can be specified in one of two ways.  An explicit numeric value can
-be used, as in the 1st example above.  Or a wild-card asterisk can be
+be used, as in the first example above.  Or a wild-card asterisk can be
 used to set the coefficients for multiple angle types.  This takes the
 form "\*" or "\*n" or "n\*" or "m\*n".  If N = the number of angle types,
 then an asterisk with no numeric values means all types from 1 to N.  A
@@ -53,7 +53,7 @@ same format as the arguments of the :doc:`angle_coeff <angle_coeff>` command in
 script, except that wild-card asterisks should not be used since
 coefficients for all N types must be listed in the file.  For example,
 under the "Angle Coeffs" section of a data file, the line that
-corresponds to the 1st example above would be listed as
+corresponds to the first example above would be listed as
 
 .. parsed-literal::
 

doc/src/angle_cosine.rst

@@ -44,23 +44,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_cosine_delta.rst

@@ -46,23 +46,7 @@ internally.
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_cosine_periodic.rst

@@ -54,23 +54,7 @@ geometry.
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_cosine_shift.rst

@@ -45,23 +45,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_cosine_shift_exp.rst

@@ -56,23 +56,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_cosine_squared.rst

@@ -46,23 +46,7 @@ internally.
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_cross.rst

@@ -40,14 +40,15 @@ the data file or restart files read by the :doc:`read_data <read_data>`
 or :doc:`read_restart <read_restart>` commands:
 
 * :math:`K_{SS}` (energy/distance\^2)
-* :math:`K_{BS0}` (energy/distance/rad)
+* :math:`K_{BS0}` (energy/distance)
-* :math:`K_{BS1}` (energy/distance/rad)
+* :math:`K_{BS1}` (energy/distance)
 * :math:`r_{12,0}` (distance)
 * :math:`r_{32,0}` (distance)
 * :math:`\theta_0` (degrees)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
-internally; hence the units of :math:`K_{BS0}` and :math:`K_{BS1}` are in energy/distance/radian.
+radians internally; hence the :math:`K_{BS0}` and :math:`K_{BS1}` are
+effectively energy/distance per radian.
 
 Restrictions
 """"""""""""

doc/src/angle_dipole.rst

@@ -82,23 +82,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 Restrictions
 """"""""""""

doc/src/angle_fourier.rst

@@ -42,23 +42,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_fourier_simple.rst

@@ -41,23 +41,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_harmonic.rst

@@ -44,31 +44,16 @@ The following coefficients must be defined for each angle type via the
 the data file or restart files read by the :doc:`read_data <read_data>`
 or :doc:`read_restart <read_restart>` commands:
 
-* :math:`K` (energy/radian\^2)
+* :math:`K` (energy)
 * :math:`\theta_0` (degrees)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
-internally; hence the units of :math:`K` are in energy/radian\^2.
+radians internally; hence :math:`K` is effectively energy per
+radian\^2.
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_mm3.rst

@@ -28,20 +28,22 @@ as defined in :ref:`(Allinger) <mm3-allinger1989>`
 
    E = K (\theta - \theta_0)^2 \left[ 1 - 0.014(\theta - \theta_0) + 5.6(10)^{-5} (\theta - \theta_0)^2 - 7.0(10)^{-7} (\theta - \theta_0)^3 + 9(10)^{-10} (\theta - \theta_0)^4 \right]
 
-where :math:`\theta_0` is the equilibrium value of the angle, and :math:`K` is a
+where :math:`\theta_0` is the equilibrium value of the angle, and
-prefactor. The anharmonic prefactors have units :math:`\deg^{-n}`, for example
+:math:`K` is a prefactor. The anharmonic prefactors have units
-:math:`-0.014 \deg^{-1}`, :math:`5.6 \cdot 10^{-5} \deg^{-2}`, ...
+:math:`\deg^{-n}`, for example :math:`-0.014 \deg^{-1}`, :math:`5.6
+\cdot 10^{-5} \deg^{-2}`, ...
 
 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>`
 or :doc:`read_restart <read_restart>` commands:
 
-* :math:`K` (energy/radian\^2)
+* :math:`K` (energy)
 * :math:`\theta_0` (degrees)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
-internally; hence the units of :math:`K` are in energy/radian\^2.
+radians internally; hence :math:`K` is effectively energy per
+radian\^2.
 
 Restrictions
 """"""""""""

doc/src/angle_quartic.rst

@@ -39,32 +39,17 @@ the data file or restart files read by the :doc:`read_data <read_data>`
 or :doc:`read_restart <read_restart>` commands:
 
 * :math:`\theta_0` (degrees)
-* :math:`K_2` (energy/radian\^2)
+* :math:`K_2` (energy)
-* :math:`K_3` (energy/radian\^3)
+* :math:`K_3` (energy)
-* :math:`K_4` (energy/radian\^4)
+* :math:`K_4` (energy)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
-internally; hence the units of :math:`K` are in energy/radian\^2.
+radians internally; hence the various :math:`K` are effectively energy
+per radian\^2 or radian\^3 or radian\^4.
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_sdk.rst

@@ -44,33 +44,19 @@ is included in :math:`K`.
 The following coefficients must be defined for each angle type via the
 :doc:`angle_coeff <angle_coeff>` command as in the example above:
 
-* :math:`K` (energy/radian\^2)
+* :math:`K` (energy)
 * :math:`\theta_0` (degrees)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
-internally; hence the units of :math:`K` are in energy/radian\^2.
+radians internally; hence :math:`K` is effectively energy per
-The also required *lj/sdk* parameters will be extracted automatically
+radian\^2.
-from the pair_style.
+
+The required *lj/sdk* parameters are extracted automatically from the
+pair_style.
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/angle_table.rst

@@ -75,7 +75,7 @@ parenthesized comments):
    ...
    181 180.0 0.0 0.0
 
-A section begins with a non-blank line whose 1st character is not a
+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
@@ -99,7 +99,7 @@ is in the tabulated file (with effectively no preliminary
 interpolation), you should set Ntable = Nfile.
 
 The "FP" parameter is optional.  If used, it is followed by two values
-fplo and fphi, which are the 2nd derivatives at the innermost and
+fplo and fphi, which are the second derivatives at the innermost and
 outermost angle settings.  These values are needed by the spline
 construction routines.  If not specified by the "FP" parameter, they
 are estimated (less accurately) by the first two and last two
@@ -110,9 +110,9 @@ equilibrium angle value, which is used, for example, by the :doc:`fix shake <fix
 set to 180.0.
 
 Following a blank line, the next N lines list the tabulated values.
-On each line, the 1st value is the index from 1 to N, the 2nd value is
+On each line, the first value is the index from 1 to N, the second value is
-the angle value (in degrees), the 3rd value is the energy (in energy
+the angle value (in degrees), the third value is the energy (in energy
-units), and the 4th is -dE/d(theta) (also in energy units).  The 3rd
+units), and the fourth is -dE/d(theta) (also in energy units).  The third
 term is the energy of the 3-atom configuration for the specified
 angle.  The last term is the derivative of the energy with respect to
 the angle (in degrees, not radians).  Thus the units of the last term
@@ -126,23 +126,7 @@ one that matches the specified keyword.
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/atc_control_momentum.rst

@@ -15,7 +15,7 @@ Syntax
    fix_modify AtC control momentum glc_velocity
    fix_modify AtC control momentum hoover
    fix_modify AtC control momentum flux [faceset face_set_id, interpolate]
-   
+
 * AtC fixID = ID of :doc:`fix atc <fix_atc>` instance
 * control = name of the AtC sub-command
 * physics_type = *thermal* or *momentum*
@@ -52,7 +52,7 @@ the finite element temperature.  *flux* is a similar mode, but rather
 adds energy to the atoms based on conservation of energy.
 
 *correction_max_iterations* sets the maximum number of iterations to
-compute the 2nd order in time correction term for lambda with the
+compute the second order in time correction term for lambda with the
 fractional step method. The method uses the same tolerance as the
 controller's matrix solver.
 

doc/src/atc_control_thermal.rst

@@ -56,7 +56,7 @@ adds energy to the atoms based on conservation of energy. *hoover* and
 atoms.
 
 *correction_max_iterations* sets the maximum number of iterations to
-compute the 2nd order in time correction term for lambda with the
+compute the second order in time correction term for lambda with the
 fractional step method. The method uses the same tolerance as the
 controller's matrix solver.
 

doc/src/atc_hardy_fields.rst

@@ -25,8 +25,8 @@ Syntax
   - temperature : temperature derived from the relative atomic kinetic energy
   - kinetic_temperature : temperature derived from the full kinetic energy
   - number_density : simple kernel estimation of number of atoms per unit volume
-  - stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or 1st Piola-Kirchhoff stress tensor for lagrangian analysis
+  - stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or first Piola-Kirchhoff stress tensor for lagrangian analysis
-  - transformed_stress : 1st Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or Cauchy stress tensor for lagrangian analysis
+  - transformed_stress : first Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or Cauchy stress tensor for lagrangian analysis
   - heat_flux : spatial heat flux vector for eulerian, or referential heat flux vector for lagrangian
   - potential_energy : potential energy per unit volume
   - kinetic_energy : kinetic energy per unit volume
@@ -37,7 +37,7 @@ Syntax
   - eshelby_stress : configurational stress (energy-momentum) tensor defined by [Eshelby]_
   - vacancy_concentration : volume fraction of vacancy content
   - type_concentration : volume fraction of a specific atom type
-  
+
 Examples
 """"""""
 

doc/src/atc_hardy_gradients.rst

@@ -23,8 +23,8 @@ Syntax
   - temperature : temperature derived from the relative atomic kinetic energy
   - kinetic_temperature : temperature derived from the full kinetic energy
   - number_density : simple kernel estimation of number of atoms per unit volume
-  - stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or 1st Piola-Kirchhoff stress tensor for lagrangian analysis
+  - stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or first Piola-Kirchhoff stress tensor for lagrangian analysis
-  - transformed_stress : 1st Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or Cauchy stress tensor for lagrangian analysis
+  - transformed_stress : first Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or Cauchy stress tensor for lagrangian analysis
   - heat_flux : spatial heat flux vector for eulerian, or referential heat flux vector for lagrangian
   - potential_energy : potential energy per unit volume
   - kinetic_energy : kinetic energy per unit volume

doc/src/atc_hardy_kernel.rst

@@ -25,7 +25,7 @@ Syntax
   - *quartic_bar* : <half_width>
   - *quartic_cylinder* : <radius>
   - *quartic_sphere* : <radius>
-    
+
 
 
 Examples

doc/src/atc_hardy_rates.rst

@@ -23,8 +23,8 @@ Syntax
   - temperature : temperature derived from the relative atomic kinetic energy
   - kinetic_temperature : temperature derived from the full kinetic energy
   - number_density : simple kernel estimation of number of atoms per unit volume
-  - stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or 1st Piola-Kirchhoff stress tensor for lagrangian analysis
+  - stress : Cauchy stress tensor for eulerian analysis (atom_element_map), or first Piola-Kirchhoff stress tensor for lagrangian analysis
-  - transformed_stress : 1st Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or Cauchy stress tensor for lagrangian analysis
+  - transformed_stress : first Piola-Kirchhoff stress tensor for eulerian analysis (atom_element_map), or Cauchy stress tensor for lagrangian analysis
   - heat_flux : spatial heat flux vector for eulerian, or referential heat flux vector for lagrangian
   - potential_energy : potential energy per unit volume
   - kinetic_energy : kinetic energy per unit volume

doc/src/atc_remove_species.rst

@@ -38,7 +38,7 @@ Related AtC commands
 - :doc:`fix_modify AtC add_species <atc_add_species>`
 - :doc:`fix_modify AtC add_molecule <atc_add_molecule>`
 - :doc:`fix_modify AtC remove_molecule <atc_remove_molecule>`
-  
+
 Default
 """""""
 

doc/src/atc_set_reference_pe.rst

@@ -22,7 +22,7 @@ Examples
 
    fix_modify AtC set reference_potential_energy
    fix_modify AtC set reference_potential_energy -0.05
-   fix_modify AtC set reference_potential_energy myPEvalues 
+   fix_modify AtC set reference_potential_energy myPEvalues
 
 Description
 """""""""""

doc/src/atc_time_integration.rst

@@ -33,11 +33,11 @@ Command to select the thermal or momentum time integration.
 Options for thermal time integration:
 
 *gear*
-  atomic velocity update with 2nd order Verlet, nodal temperature update
+  atomic velocity update with second order Verlet, nodal temperature update
-  with 3rd or 4th order Gear, thermostats based on controlling power
+  with third or fourth order Gear, thermostats based on controlling power
 
 *fractional_step*
-  atomic velocity update with 2nd order Verlet, mixed nodal temperature
+  atomic velocity update with second order Verlet, mixed nodal temperature
   update, 3/4 Gear for continuum and 2 Verlet for atomic contributions,
   thermostats based on controlling discrete energy changes
 
@@ -46,18 +46,18 @@ Options for thermal time integration:
 Options for momentum time integration:
 
 *verlet*
-  atomic velocity update with 2nd order Verlet, nodal temperature update
+  atomic velocity update with second order Verlet, nodal temperature update
-  with 2nd order Verlet, kinetostats based on controlling force
+  with second order Verlet, kinetostats based on controlling force
 
 *fractional_step*
-  atomic velocity update with 2nd order Verlet, mixed nodal momentum
+  atomic velocity update with second order Verlet, mixed nodal momentum
-  update, 2nd order Verlet for continuum and exact 2nd order Verlet for
+  update, second order Verlet for continuum and exact second order Verlet for
   atomic contributions, kinetostats based on controlling discrete
   momentum changes
 
 *gear*
-  atomic velocity update with 2nd order Verlet, nodal temperature update
+  atomic velocity update with second order Verlet, nodal temperature update
-  with 3rd or 4th order Gear, kinetostats based on controlling power.
+  with third or fourth order Gear, kinetostats based on controlling power.
 
 ---------
 

doc/src/atom_style.rst

@@ -10,7 +10,7 @@ Syntax
 
    atom_style style args
 
-* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or         *dpd* or *edpd* or *mdpd* or *tdpd* or *electron* or *ellipsoid* or         *full* or *line* or *meso* or *molecular* or *peri* or *smd* or         *sphere* or *spin* or *tri* or *template* or *hybrid*
+* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or  *dpd* or *edpd* or *electron* or *ellipsoid* or *full* or *line* or *mdpd* or *molecular* or *peri* or *smd* or *sph* or *sphere* or *spin* or *tdpd* or *tri* or *template* or *hybrid*
 
   .. parsed-literal::
 
@@ -18,7 +18,9 @@ Syntax
          *body* args = bstyle bstyle-args
            bstyle = style of body particles
            bstyle-args = additional arguments specific to the bstyle
-                         see the :doc:`Howto body <Howto_body>` doc page for details
+                         see the :doc:`Howto body <Howto_body>` doc
+                         page for details
+         *sphere* arg = 0/1 (optional) for static/dynamic particle radii
          *tdpd* arg = Nspecies
            Nspecies = # of chemical species
          *template* arg = template-ID
@@ -91,10 +93,6 @@ quantities.
 +--------------+-----------------------------------------------------+--------------------------------------+
 | *edpd*       | temperature and heat capacity                       | eDPD particles                       |
 +--------------+-----------------------------------------------------+--------------------------------------+
-| *mdpd*       | density                                             | mDPD particles                       |
-+--------------+-----------------------------------------------------+--------------------------------------+
-| *tdpd*       | chemical concentration                              | tDPD particles                       |
-+--------------+-----------------------------------------------------+--------------------------------------+
 | *electron*   | charge and spin and eradius                         | electronic force field               |
 +--------------+-----------------------------------------------------+--------------------------------------+
 | *ellipsoid*  | shape, quaternion, angular momentum                 | aspherical particles                 |
@@ -103,7 +101,9 @@ quantities.
 +--------------+-----------------------------------------------------+--------------------------------------+
 | *line*       | end points, angular velocity                        | rigid bodies                         |
 +--------------+-----------------------------------------------------+--------------------------------------+
-| *meso*       | rho, e, cv                                          | SPH particles                        |
+| *mdpd*       | density                                             | mDPD particles                       |
++--------------+-----------------------------------------------------+--------------------------------------+
+| *mesont*     | mass, radius, length, buckling, connections, tube id| mesoscopic nanotubes                 |
 +--------------+-----------------------------------------------------+--------------------------------------+
 | *molecular*  | bonds, angles, dihedrals, impropers                 | uncharged molecules                  |
 +--------------+-----------------------------------------------------+--------------------------------------+
@@ -111,10 +111,14 @@ quantities.
 +--------------+-----------------------------------------------------+--------------------------------------+
 | *smd*        | volume, kernel diameter, contact radius, mass       | solid and fluid SPH particles        |
 +--------------+-----------------------------------------------------+--------------------------------------+
+| *sph*        | rho, esph, cv                                       | SPH particles                        |
++--------------+-----------------------------------------------------+--------------------------------------+
 | *sphere*     | diameter, mass, angular velocity                    | granular models                      |
 +--------------+-----------------------------------------------------+--------------------------------------+
 | *spin*       | magnetic moment                                     | system with magnetic particles       |
 +--------------+-----------------------------------------------------+--------------------------------------+
+| *tdpd*       | chemical concentration                              | tDPD particles                       |
++--------------+-----------------------------------------------------+--------------------------------------+
 | *template*   | template index, template atom                       | small molecules with fixed topology  |
 +--------------+-----------------------------------------------------+--------------------------------------+
 | *tri*        | corner points, angular momentum                     | rigid bodies                         |
@@ -144,9 +148,16 @@ basis.
 For the *sphere* style, the particles are spheres and each stores a
 per-particle diameter and mass.  If the diameter > 0.0, the particle
 is a finite-size sphere.  If the diameter = 0.0, it is a point
-particle.  Note that by use of the *disc* keyword with the :doc:`fix nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere <fix_nvt_sphere>`,
+particle.  Note that by use of the *disc* keyword with the :doc:`fix
-:doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix npt/sphere <fix_npt_sphere>` commands, spheres can be effectively
+nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere <fix_nvt_sphere>`,
-treated as 2d discs for a 2d simulation if desired.  See also the :doc:`set density/disc <set>` command.
+:doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix npt/sphere
+<fix_npt_sphere>` commands, spheres can be effectively treated as 2d
+discs for a 2d simulation if desired.  See also the :doc:`set
+density/disc <set>` command.  The *sphere* style takes an optional 0
+or 1 argument.  A value of 0 means the radius of each sphere is
+constant for the duration of the simulation.  A value of 1 means the
+radii may vary dynamically during the simulation, e.g. due to use of
+the :doc:`fix adapt <fix_adapt>` command.
 
 For the *ellipsoid* style, the particles are ellipsoids and each
 stores a flag which indicates whether it is a finite-size ellipsoid or
@@ -189,8 +200,8 @@ particles which store a set of chemical concentration. An integer
 "cc_species" is required to specify the number of chemical species
 involved in a tDPD system.
 
-The *meso* style is for smoothed particle hydrodynamics (SPH)
+The *sph* style is for smoothed particle hydrodynamics (SPH)
-particles which store a density (rho), energy (e), and heat capacity
+particles which store a density (rho), energy (esph), and heat capacity
 (cv).
 
 The *smd* style is for a general formulation of Smooth Particle
@@ -335,9 +346,11 @@ for energy-conserving dissipative particle dynamics (eDPD), many-body
 dissipative particle dynamics (mDPD), and transport dissipative particle
 dynamics (tDPD), respectively.
 
-The *meso* style is part of the USER-SPH package for smoothed particle
+The *sph* style is part of the USER-SPH package for smoothed particle
 hydrodynamics (SPH).  See `this PDF guide <USER/sph/SPH_LAMMPS_userguide.pdf>`_ to using SPH in LAMMPS.
 
+The *mesont* style is part of the USER-MESONT package.
+
 The *spin* style is part of the SPIN package.
 
 The *wavepacket* style is part of the USER-AWPMD package for the
@@ -351,7 +364,8 @@ Related commands
 Default
 """""""
 
-atom_style atomic
+The default atom style is atomic.  If atom_style sphere is used its
+default argument is 0.
 
 ----------
 

doc/src/balance.rst

@@ -177,16 +177,16 @@ volume (area in 2d) assigned to each processor, as in the following 2d
 diagram where processor sub-domains are shown and particles are
 colored by the processor that owns them.
 
-.. list-table::
+.. |balance1| image:: img/balance_uniform.jpg
+   :width: 32%
 
-   * - .. figure:: JPG/balance_uniform_small.jpg
+.. |balance2| image:: img/balance_nonuniform.jpg
-          :target: JPG/balance_uniform.jpg
+   :width: 32%
 
-     - .. figure:: JPG/balance_nonuniform_small.jpg
+.. |balance3| image:: img/balance_rcb.jpg
-          :target: JPG/balance_nonuniform.jpg
+   :width: 32%
 
-     - .. figure:: JPG/balance_rcb_small.jpg
+|balance1|  |balance2|  |balance3|
-          :target: JPG/balance_rcb.jpg
 
 The leftmost diagram is the default partitioning of the simulation box
 across processors (one sub-box for each of 16 processors); the middle

doc/src/bond_class2.rst

@@ -49,23 +49,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_coeff.rst

@@ -32,7 +32,7 @@ Bond coefficients can also be set in the data file read by the
 :doc:`read_data <read_data>` command or in a restart file.
 
 N can be specified in one of two ways.  An explicit numeric value can
-be used, as in the 1st example above.  Or a wild-card asterisk can be
+be used, as in the first example above.  Or a wild-card asterisk can be
 used to set the coefficients for multiple bond types.  This takes the
 form "\*" or "\*n" or "n\*" or "m\*n".  If N = the number of bond types,
 then an asterisk with no numeric values means all types from 1 to N.  A
@@ -54,7 +54,7 @@ same format as the arguments of the bond_coeff command in an input
 script, except that wild-card asterisks should not be used since
 coefficients for all N types must be listed in the file.  For example,
 under the "Bond Coeffs" section of a data file, the line that
-corresponds to the 1st example above would be listed as
+corresponds to the first example above would be listed as
 
 .. parsed-literal::
 

doc/src/bond_fene.rst

@@ -38,8 +38,8 @@ The *fene* bond style uses the potential
 
 to define a finite extensible nonlinear elastic (FENE) potential
 :ref:`(Kremer) <fene-Kremer>`, used for bead-spring polymer models.  The first
-term is attractive, the 2nd Lennard-Jones term is repulsive.  The
+term is attractive, the second Lennard-Jones term is repulsive.  The
-first term extends to :math:`R_0`, the maximum extent of the bond.  The 2nd
+first term extends to :math:`R_0`, the maximum extent of the bond.  The second
 term is cutoff at :math:`2^\frac{1}{6} \sigma`, the minimum of the LJ potential.
 
 The following coefficients must be defined for each bond type via the
@@ -54,23 +54,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_fene_expand.rst

@@ -32,12 +32,12 @@ The *fene/expand* bond style uses the potential
 
 to define a finite extensible nonlinear elastic (FENE) potential
 :ref:`(Kremer) <feneexpand-Kremer>`, used for bead-spring polymer models.  The first
-term is attractive, the 2nd Lennard-Jones term is repulsive.
+term is attractive, the second Lennard-Jones term is repulsive.
 
 The *fene/expand* bond style is similar to *fene* except that an extra
 shift factor of :math:`\Delta` (positive or negative) is added to :math:`r` to
 effectively change the bead size of the bonded atoms.  The first term
-now extends to :math:`R_0 + \Delta` and the 2nd term is cutoff at :math:`2^\frac{1}{6} \sigma + \Delta`.
+now extends to :math:`R_0 + \Delta` and the second term is cutoff at :math:`2^\frac{1}{6} \sigma + \Delta`.
 
 The following coefficients must be defined for each bond type via the
 :doc:`bond_coeff <bond_coeff>` command as in the example above, or in
@@ -52,23 +52,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_gromos.rst

@@ -43,23 +43,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_harmonic.rst

@@ -49,23 +49,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_harmonic_shift.rst

@@ -48,23 +48,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_harmonic_shift_cut.rst

@@ -46,23 +46,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_morse.rst

@@ -44,23 +44,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_none.rst

@@ -13,7 +13,7 @@ Syntax
 Examples
 """"""""
 
-.. code-blocK:: LAMMPS
+.. code-block:: LAMMPS
 
    bond_style none
 

doc/src/bond_nonlinear.rst

@@ -44,23 +44,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------
 

doc/src/bond_quartic.rst

@@ -88,23 +88,7 @@ status of broken bonds or permanently delete them, e.g.:
 
 ----------
 
-Styles with a *gpu*\ , *intel*\ , *kk*\ , *omp*\ , or *opt* suffix are
+.. include:: accel_styles.rst
-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.  The accelerated styles take the same arguments and should
-produce the same results, except for round-off and precision issues.
-
-These accelerated styles are part of the GPU, USER-INTEL, KOKKOS,
-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
-:doc:`suffix <suffix>` command in your input script.
-
-See the :doc:`Speed packages <Speed_packages>` doc page for more
-instructions on how to use the accelerated styles effectively.
 
 ----------