Merge pull request #2296 from akohlmey/next_patch_version

Update version strings for next patch release

.gitattributes

@@ -0,0 +1,3 @@
+.gitattributes export-ignore
+.gitignore export-ignore
+.github export-ignore

.github/codecov.yml

@@ -0,0 +1,29 @@
+comment: false
+coverage:
+  notify:
+    slack:
+      default:
+        url: "secret:HWZbvgtc6OD7F3v3PfrK3/rzCJvScbh69Fi1CkLwuHK0+wIBIHVR+Q5i7q6F9Ln4OChbiRGtYAEUUsT8/jmBu4qDpIi8mx746codc0z/Z3aafLd24pBrCEPLvdCfIZxqPnw3TuUgGhwmMDZf0+thg8YNUr/MbOZ7Li2L6+ZbYuA="
+        threshold: 10%
+        only_pulls: false
+        branches:
+          - "master"
+        flags:
+          - "unit"
+        paths:
+          - "src"
+  status:
+    project:
+        default:
+            branches:
+              - "master"
+            paths:
+              - "src"
+            informational: true
+    patch:
+        default:
+            branches:
+              - "master"
+            paths:
+              - "src"
+            informational: true

cmake/CMakeLists.txt

@@ -69,18 +69,10 @@ if(${CMAKE_CXX_COMPILER_ID} STREQUAL "Intel")
   endif()
 endif()
 
-if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
-  set(CMAKE_TUNE_DEFAULT "-march=native")
-endif()
-
-if(${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang")
-  set(CMAKE_TUNE_DEFAULT "-march=native")
-endif()
-
 # we require C++11 without extensions
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
-set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_CXX_EXTENSIONS OFF CACHE BOOL "Use compiler extensions")
 
 ########################################################################
 # User input options                                                   #
@@ -193,7 +185,7 @@ if(NOT ${LAMMPS_MEMALIGN} STREQUAL "0")
   target_compile_definitions(lammps PRIVATE -DLAMMPS_MEMALIGN=${LAMMPS_MEMALIGN})
 endif()
 
-option(LAMMPS_EXCEPTIONS "enable the use of C++ exceptions for error messages (useful for library interface)" OFF)
+option(LAMMPS_EXCEPTIONS "enable the use of C++ exceptions for error messages (useful for library interface)" ${ENABLE_TESTING})
 if(LAMMPS_EXCEPTIONS)
   target_compile_definitions(lammps PUBLIC -DLAMMPS_EXCEPTIONS)
 endif()
@@ -366,7 +358,7 @@ foreach(PKG_WITH_INCL KSPACE PYTHON VORONOI USER-COLVARS USER-MOLFILE USER-NETCD
   endif()
 endforeach()
 
-set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler specific optimization or instrumentation")
+set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine specific optimization flags (compilation only)")
 separate_arguments(CMAKE_TUNE_FLAGS)
 foreach(_FLAG ${CMAKE_TUNE_FLAGS})
   target_compile_options(lammps PRIVATE ${_FLAG})
@@ -755,6 +747,12 @@ if (${_index} GREATER -1)
 endif()
 message(STATUS "<<< Linker flags: >>>")
 message(STATUS "Executable name:  ${LAMMPS_BINARY}")
+if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.13)
+  get_target_property(OPTIONS lammps LINK_OPTIONS)
+  if(OPTIONS)
+    message(STATUS "Linker options:   ${OPTIONS}")
+  endif()
+endif()
 if(CMAKE_EXE_LINKER_FLAGS)
   message(STATUS "Executable linker flags: ${CMAKE_EXE_LINKER_FLAGS}")
 endif()

cmake/Modules/Documentation.cmake

@@ -29,8 +29,8 @@ if(BUILD_DOC)
     OUTPUT requirements.txt
     DEPENDS docenv
     COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt
-    COMMAND ${DOCENV_BINARY_DIR}/pip install -r requirements.txt --upgrade
     COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
+    COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r requirements.txt --upgrade
   )
 
   # download mathjax distribution and unpack to folder "mathjax"

cmake/Modules/GTest.cmake

@@ -7,9 +7,11 @@ else()
 endif()
 
 include(ExternalProject)
+set(GTEST_URL "https://github.com/google/googletest/archive/release-1.10.0.tar.gz" CACHE STRING "URL for GTest tarball")
+mark_as_advanced(GTEST_URL)
 ExternalProject_Add(googletest
-                    GIT_REPOSITORY  https://github.com/google/googletest.git
-                    GIT_TAG         release-1.10.0
+                    URL ${GTEST_URL}
+                    URL_MD5         ecd1fa65e7de707cd5c00bdac56022cd
                     SOURCE_DIR      "${CMAKE_BINARY_DIR}/gtest-src"
                     BINARY_DIR      "${CMAKE_BINARY_DIR}/gtest-build"
                     CMAKE_ARGS      ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_GTEST_OPTS}
@@ -52,26 +54,26 @@ add_library(GTest::GTest UNKNOWN IMPORTED)
 set_target_properties(GTest::GTest PROPERTIES
         IMPORTED_LOCATION ${GTEST_LIBRARY_PATH}
         INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
-        IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
+        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
 add_dependencies(GTest::GTest googletest)
 
 add_library(GTest::GMock UNKNOWN IMPORTED)
 set_target_properties(GTest::GMock PROPERTIES
         IMPORTED_LOCATION ${GMOCK_LIBRARY_PATH}
         INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
-        IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
+        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
 add_dependencies(GTest::GMock googletest)
 
 add_library(GTest::GTestMain UNKNOWN IMPORTED)
 set_target_properties(GTest::GTestMain PROPERTIES
         IMPORTED_LOCATION ${GTEST_MAIN_LIBRARY_PATH}
         INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
-        IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
+        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
 add_dependencies(GTest::GTestMain googletest)
 
 add_library(GTest::GMockMain UNKNOWN IMPORTED)
 set_target_properties(GTest::GMockMain PROPERTIES
         IMPORTED_LOCATION ${GMOCK_MAIN_LIBRARY_PATH}
         INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
-        IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
+        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
 add_dependencies(GTest::GMockMain googletest)

cmake/Modules/Packages/GPU.cmake

@@ -64,30 +64,41 @@ if(GPU_API STREQUAL "CUDA")
 
   # build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
   # --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
-  set(GPU_CUDA_GENCODE "-arch=${GPU_ARCH} ")
+  set(GPU_CUDA_GENCODE "-arch=${GPU_ARCH}")
   # Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
-  if((CUDA_VERSION VERSION_GREATER "3.1") AND (CUDA_VERSION VERSION_LESS "9.0"))
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_20,code=[sm_20,compute_20] ")
+  if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20] ")
   endif()
-  # Kepler (GPU Arch 3.x) is supported by CUDA 5 and later
-  if(CUDA_VERSION VERSION_GREATER "4.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35] ")
+  # Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
+  if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] ")
+  endif()
+  # Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11
+  if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35]")
   endif()
   # Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
-  if(CUDA_VERSION VERSION_GREATER "5.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52] ")
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52]")
   endif()
   # Pascal (GPU Arch 6.x) is supported by CUDA 8 and later
-  if(CUDA_VERSION VERSION_GREATER "7.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61] ")
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "8.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61]")
   endif()
   # Volta (GPU Arch 7.0) is supported by CUDA 9 and later
-  if(CUDA_VERSION VERSION_GREATER "8.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_70,code=[sm_70,compute_70] ")
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "9.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_70,code=[sm_70,compute_70]")
   endif()
   # Turing (GPU Arch 7.5) is supported by CUDA 10 and later
-  if(CUDA_VERSION VERSION_GREATER "9.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_75,code=[sm_75,compute_75] ")
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "10.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_75,code=[sm_75,compute_75]")
+  endif()
+  # Ampere (GPU Arch 8.0) is supported by CUDA 11 and later
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
+  endif()
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+    message(WARNING "Unsupported CUDA version. Use at your own risk.")
   endif()
 
   cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC}
@@ -226,30 +237,41 @@ elseif(GPU_API STREQUAL "HIP")
 
     # build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
     # --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
-    set(HIP_CUDA_GENCODE "-arch=${HIP_ARCH} ")
+    set(HIP_CUDA_GENCODE "-arch=${HIP_ARCH}")
     # Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
-    if((CUDA_VERSION VERSION_GREATER "3.1") AND (CUDA_VERSION VERSION_LESS "9.0"))
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_20,code=[sm_20,compute_20] ")
+    if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20]")
     endif()
-    # Kepler (GPU Arch 3.x) is supported by CUDA 5 and later
-    if(CUDA_VERSION VERSION_GREATER "4.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35] ")
+    # Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
+    if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30]")
+    endif()
+    # Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11.0
+    if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_35,code=[sm_35,compute_35]")
     endif()
     # Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
-    if(CUDA_VERSION VERSION_GREATER "5.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52] ")
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52]")
     endif()
     # Pascal (GPU Arch 6.x) is supported by CUDA 8 and later
-    if(CUDA_VERSION VERSION_GREATER "7.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61] ")
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "8.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61]")
     endif()
     # Volta (GPU Arch 7.0) is supported by CUDA 9 and later
-    if(CUDA_VERSION VERSION_GREATER "8.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_70,code=[sm_70,compute_70] ")
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "9.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_70,code=[sm_70,compute_70]")
     endif()
     # Turing (GPU Arch 7.5) is supported by CUDA 10 and later
-    if(CUDA_VERSION VERSION_GREATER "9.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_75,code=[sm_75,compute_75] ")
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "10.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_75,code=[sm_75,compute_75]")
+    endif()
+    # Ampere (GPU Arch 8.0) is supported by CUDA 11 and later
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
+    endif()
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+      message(WARNING "Unsupported CUDA version. Use at your own risk.")
     endif()
   endif()
 

cmake/Modules/Packages/USER-SMD.cmake

@@ -9,8 +9,8 @@ if(DOWNLOAD_EIGEN3)
   message(STATUS "Eigen3 download requested - we will build our own")
   include(ExternalProject)
   ExternalProject_Add(Eigen3_build
-    URL https://bitbucket.org/eigen/eigen/get/3.3.7.tar.gz
-    URL_MD5 f2a417d083fe8ca4b8ed2bc613d20f07
+    URL https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.tar.gz
+    URL_MD5 9e30f67e8531477de4117506fe44669b
     CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
   )
   ExternalProject_get_property(Eigen3_build SOURCE_DIR)

cmake/Modules/Testing.cmake

@@ -16,6 +16,36 @@ if(ENABLE_TESTING)
   set(MEMORYCHECK_COMMAND "${VALGRIND_BINARY}" CACHE FILEPATH "Memory Check Command")
   set(MEMORYCHECK_COMMAND_OPTIONS "${VALGRIND_DEFAULT_OPTIONS}" CACHE STRING "Memory Check Command Options")
 
+  # check if a faster linker is available.
+  # only verified with GNU and Clang compilers and new CMake
+  if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.13)
+    if((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
+        OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang"))
+      include(CheckCXXCompilerFlag)
+      set(CMAKE_CUSTOM_LINKER_DEFAULT default)
+      check_cxx_compiler_flag(-fuse-ld=lld HAVE_LLD_LINKER_FLAG)
+      check_cxx_compiler_flag(-fuse-ld=gold HAVE_GOLD_LINKER_FLAG)
+      check_cxx_compiler_flag(-fuse-ld=bfd HAVE_BFD_LINKER_FLAG)
+      find_program(HAVE_LLD_LINKER_BIN lld ld.lld)
+      find_program(HAVE_GOLD_LINKER_BIN ld.gold)
+      find_program(HAVE_BFD_LINKER_BIN ld.bfd)
+      if(HAVE_LLD_LINKER_FLAG AND HAVE_LLD_LINKER_BIN)
+        set(CMAKE_CUSTOM_LINKER_DEFAULT lld)
+      elseif(HAVE_GOLD_LINKER_FLAG AND HAVE_GOLD_LINKER_BIN)
+        set(CMAKE_CUSTOM_LINKER_DEFAULT gold)
+      elseif(HAVE_BFD_LINKER_FLAG AND HAVE_BFD_LINKER_BIN)
+        set(CMAKE_CUSTOM_LINKER_DEFAULT bfd)
+      endif()
+      set(CMAKE_CUSTOM_LINKER_VALUES lld gold bfd default)
+      set(CMAKE_CUSTOM_LINKER ${CMAKE_CUSTOM_LINKER_DEFAULT} CACHE STRING "Choose a custom linker for faster linking (lld, gold, bfd, default)")
+      validate_option(CMAKE_CUSTOM_LINKER CMAKE_CUSTOM_LINKER_VALUES)
+      mark_as_advanced(CMAKE_CUSTOM_LINKER)
+      if(NOT "${CMAKE_CUSTOM_LINKER}" STREQUAL "default")
+        target_link_options(lammps PUBLIC -fuse-ld=${CMAKE_CUSTOM_LINKER})
+      endif()
+    endif()
+  endif()
+
   include(CTest)
 
   enable_testing()

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 sphinxcontrib-spelling ;\
-		pip install breathe; \
+		pip install --use-feature=2020-resolver -r requirements.txt; \
 		deactivate;\
 	)
 

doc/lammps.1

@@ -1,4 +1,4 @@
-.TH LAMMPS "30 June 2020" "2020-06-30"
+.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
-presets in the ``cmake/presets`` folder.  For convenience, there is a
-``CMAKE_TUNE_FLAGS`` variable that can be set to apply global compiler
-options.  More on that below, but you can also specify the corresponding
-``CMAKE_*_FLAGS`` variables individually if you want to 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:
+variables (listed below) during configuration.  For a few common
+choices, there are also presets in the ``cmake/presets`` folder.  For
+convenience, there is a ``CMAKE_TUNE_FLAGS`` variable that can be set to
+apply global compiler options (applied to compilation only), to be used
+for adding compiler or host specific optimization flags in addition to
+the "flags" variables listed below. You may also specify the
+corresponding ``CMAKE_*_FLAGS`` variables individually, if you want to
+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
 
@@ -229,11 +232,7 @@ can be loaded with `-C ../cmake/presets/clang.cmake`.  Similarly,
 
 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
-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=``.
+default this variable is empty.
 
 .. note::
 

doc/src/Build_development.rst

@@ -159,8 +159,8 @@ 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 ``pair_style``, ``bond_style``, and
-``angle_style`` are implemented.  They will compare forces, energies and
+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
@@ -172,7 +172,7 @@ Below is an example command and output:
 
 .. parsed-literal::
 
-   [tests]$ pair_style mol-pair-lj_cut.yaml
+   [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
@@ -259,6 +259,71 @@ and working.
      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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/src/Build_extras.rst

@@ -105,10 +105,10 @@ CMake build
                                 # generic (default) or intel (Intel CPU) or fermi, kepler, cypress (NVIDIA)
    -D GPU_ARCH=value            # primary GPU hardware choice for GPU_API=cuda
                                 # value = sm_XX, see below
-                                # default is sm_30
+                                # default is sm_50
    -D HIP_ARCH=value            # primary GPU hardware choice for GPU_API=hip
                                 # value depends on selected HIP_PLATFORM
-                                # default is 'gfx906' for HIP_PLATFORM=hcc and 'sm_30' for HIP_PLATFORM=nvcc
+                                # default is 'gfx906' for HIP_PLATFORM=hcc and 'sm_50' for HIP_PLATFORM=nvcc
    -D HIP_USE_DEVICE_SORT=value # enables GPU sorting
                                 # value = yes (default) or no
    -D CUDPP_OPT=value           # optimization setting for GPU_API=cuda
@@ -1255,6 +1255,15 @@ also typically :ref:`install the USER-OMP package <user-omp>`, as it can be
 used in tandem with the USER-INTEL package to good effect, as explained
 on the :doc:`Speed intel <Speed_intel>` doc page.
 
+When using Intel compilers version 16.0 or later is required.  You can
+also use the GNU or Clang compilers and they will provide performance
+improvements over regular styles and USER-OMP styles, but less so than
+with the Intel compilers.  Please also note, that some compilers have
+been found to apply memory alignment constraints incompletely or
+incorrectly and thus can cause segmentation faults in otherwise correct
+code when using features from the USER-INTEL package.
+
+
 CMake build
 ^^^^^^^^^^^
 

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>`
@@ -108,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

@@ -80,6 +80,7 @@ KOKKOS, o = USER-OMP, t = OPT.
    * :doc:`ke/eff <compute_ke_eff>`
    * :doc:`ke/rigid <compute_ke_rigid>`
    * :doc:`mesont <compute_mesont>`
+   * :doc:`mliap <compute_mliap>`
    * :doc:`momentum <compute_momentum>`
    * :doc:`msd <compute_msd>`
    * :doc:`msd/chunk <compute_msd_chunk>`
@@ -122,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>`

doc/src/Commands_fix.rst

@@ -42,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>`
@@ -97,6 +98,7 @@ OPT.
    * :doc:`manifoldforce <fix_manifoldforce>`
    * :doc:`meso/move <fix_meso_move>`
    * :doc:`momentum (k) <fix_momentum>`
+   * :doc:`momentum/chunk <fix_momentum>`
    * :doc:`move <fix_move>`
    * :doc:`mscg <fix_mscg>`
    * :doc:`msst <fix_msst>`
@@ -243,3 +245,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_pair.rst

@@ -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/dsf (gko) <pair_lj>`
-   * :doc:`lj/cut/coul/long (gikot) <pair_lj>`
+   * :doc:`lj/cut/coul/debye (gko) <pair_lj_cut_coul>`
+   * :doc:`lj/cut/coul/dsf (gko) <pair_lj_cut_coul>`
+   * :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/wolf (o) <pair_lj>`
+   * :doc:`lj/cut/coul/msm (go) <pair_lj_cut_coul>`
+   * :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/long (got) <pair_lj>`
+   * :doc:`lj/cut/tip4p/cut (o) <pair_lj_cut_tip4p>`
+   * :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>`

doc/src/Errors_warnings.rst

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

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_bash.rst

@@ -1,264 +0,0 @@
-Using LAMMPS with Bash on Windows
-=================================
-
-**written by Richard Berger**
-
-----------
-
-Starting with Windows 10 you can install Linux tools directly in Windows. This
-allows you to compile LAMMPS following the same procedure as on a real Ubuntu
-Linux installation. Software can be easily installed using the package manager
-via apt-get and all files are accessible in both the Windows Explorer and your
-Linux shell (bash). This avoids switching to a different operating system or
-installing a virtual machine. Everything runs on Windows.
-
-.. seealso::
-
-   You can find more detailed information at the `Windows Subsystem for Linux Installation Guide for Windows 10 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_.
-
-Installing Bash on Windows
---------------------------
-
-Prerequisites
-^^^^^^^^^^^^^
-
-* Windows 10 (64bit only)
-* Latest updates installed
-
-Enable developer mode
-^^^^^^^^^^^^^^^^^^^^^
-
-You enable this feature by first opening Windows Settings and enabling
-Developer mode. Go to the Windows settings and search for "developer". This
-will allow you to install software which comes from outside of the Windows
-Store.  You might be prompted to reboot your compute. Please do so.
-
-.. image:: JPG/bow_tutorial_01_small.png
-   :target: JPG/bow_tutorial_01.png
-
-.. image:: JPG/bow_tutorial_02_small.png
-   :target: JPG/bow_tutorial_02.png
-
-.. image:: JPG/bow_tutorial_03_small.png
-   :target: JPG/bow_tutorial_03.png
-
-Install Windows Subsystem for Linux
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Next you must ensure that the Window Subsystem for Linux is installed. Again,
-search for "enable windows features" in the Settings dialog. This opens a
-dialog with a list of features you can install. Add a checkmark to Windows
-Subsystem for Linux (Beta) and press OK.
-
-.. image:: JPG/bow_tutorial_04_small.png
-   :target: JPG/bow_tutorial_04.png
-
-.. image:: JPG/bow_tutorial_05.png
-   :target: JPG/bow_tutorial_05.png
-
-Install Bash for Windows
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-After installation completes, type "bash" in the Windows Start menu search.
-Select the first found option. This will launch a command-line window which
-will prompt you about installing Ubuntu on Windows. Confirm with "y" and press
-enter. This will then download Ubuntu for Windows.
-
-.. image:: JPG/bow_tutorial_06.png
-
-.. image:: JPG/bow_tutorial_07.png
-
-During installation, you will be asked for a new password. This will be used
-for installing new software and running commands with sudo.
-
-.. image:: JPG/bow_tutorial_08.png
-
-Type exit to close the command-line window.
-
-Go to the Start menu and type "bash" again. This time you will see a "Bash on
-Ubuntu on Windows" Icon. Start this program.
-
-.. image:: JPG/bow_tutorial_09.png
-
-Congratulations, you have installed **Bash on Ubuntu on Windows**\ .
-
-.. image:: JPG/bow_tutorial_10.png
-
-----------
-
-Compiling LAMMPS in Bash on Windows
------------------------------------
-
-The installation of LAMMPS in this environment is identical to working inside
-of a real Ubuntu Linux installation. At the time writing, it uses Ubuntu 16.04.
-
-Installing prerequisite packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-First upgrade all existing packages using
-
-.. code-block:: bash
-
-   sudo apt update
-   sudo apt upgrade -y
-
-Next install the following packages, which include compilers and libraries
-needed for various LAMMPS features:
-
-.. code-block:: bash
-
-   sudo apt install -y build-essential ccache gfortran openmpi-bin libopenmpi-dev libfftw3-dev libjpeg-dev libpng-dev python-dev python-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev hdf5-tools
-
-Files in Ubuntu on Windows
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When you launch "Bash on Ubuntu on Windows" you will start out in your Linux
-user home directory /home/[username]\ . You can access your Windows user directory
-using the /mnt/c/Users/[username] folder.
-
-Download LAMMPS
-^^^^^^^^^^^^^^^
-
-Obtain a copy of the LAMMPS code and go into it using "cd"
-
-Option 1: Downloading LAMMPS tarball using wget
-"""""""""""""""""""""""""""""""""""""""""""""""
-
-.. code-block:: bash
-
-   wget https://lammps.sandia.gov/tars/lammps-stable.tar.gz
-   tar xvzf lammps-stable.tar.gz
-   cd lammps-31Mar17
-
-Option 2: Obtaining LAMMPS code from GitHub
-"""""""""""""""""""""""""""""""""""""""""""
-
-.. code-block:: bash
-
-   git clone https://github.com/lammps/lammps.git
-   cd lammps
-
-Compiling LAMMPS
-^^^^^^^^^^^^^^^^
-
-At this point you can compile LAMMPS like on Ubuntu Linux.
-
-Compiling serial version
-""""""""""""""""""""""""
-
-.. code-block:: bash
-
-   cd src/
-   make -j 4 serial
-
-This will create an executable called lmp_serial in the src/ directory
-
-Compiling MPI version
-"""""""""""""""""""""
-
-.. code-block:: bash
-
-   cd src/
-   make -j 4 mpi
-
-This will create an executable called lmp_mpi in the src/ directory
-
-----------
-
-Finally, please note the absolute path of your src folder. You can get this using
-
-.. code-block:: bash
-
-   pwd
-
-or
-
-.. code-block:: bash
-
-   echo $PWD
-
-To run any examples you need the location of the executable. For now, let us
-save this location in a temporary variable
-
-.. code-block:: bash
-
-   LAMMPS_DIR=$PWD
-
-----------
-
-Running an example script
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Once compiled you can execute some of the LAMMPS examples. Switch into the
-examples/melt folder
-
-.. code-block:: bash
-
-   cd ../examples/melt
-
-The full path of the serial executable is $LAMMPS_DIR/lmp_serial, while the mpi
-version is $LAMMPS_DIR/lmp_mpi. You can run the melt example with either
-version as follows:
-
-.. code-block:: bash
-
-   $LAMMPS_DIR/lmp_serial -in in.melt
-
-or
-
-.. code-block:: bash
-
-   mpirun -np 4 $LAMMPS_DIR/lmp_mpi -in in.melt
-
-Note the use of our variable $LAMMPS_DIR, which expands into the full path of
-the LAMMPS src folder we saved earlier.
-
-Adding your executable directory to your PATH
-"""""""""""""""""""""""""""""""""""""""""""""
-
-You can avoid having to type the full path of your LAMMPS binary by adding its
-parent folder to the PATH environment variable as follows:
-
-.. code-block:: bash
-
-   export PATH=$LAMMPS_DIR:$PATH
-
-Input scripts can then be run like this:
-
-.. code-block:: bash
-
-   lmp_serial -in in.melt
-
-or
-
-.. code-block:: bash
-
-   mpirun -np 4 lmp_mpi -in in.melt
-
-However, this PATH variable will not persist if you close your bash window.
-To persist this setting edit the $HOME/.bashrc file using your favorite editor
-and add this line
-
-.. code-block:: bash
-
-   export PATH=/full/path/to/your/lammps/src:$PATH
-
-**Example:**
-
-For an executable lmp_serial with a full path
-
-.. code-block:: bash
-
-   /home/richard/lammps/src/lmp_serial
-
-the PATH variable should be
-
-.. code-block:: bash
-
-   export PATH=/home/richard/lammps/src:$PATH
-
-.. note::
-
-   This should give you a jump start when trying to run LAMMPS on Windows.
-   To become effective in this environment I encourage you to look into Linux
-   tutorials explaining Bash and Basic Unix commands (e.g., `Linux Journey <https://linuxjourney.com>`_)

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>` lj/cut/coul/long
+* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/cut
+* :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
-these particle types.
+simpler entities than body particles.  See the :doc:`Howto spherical
+<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
-style to the code.
+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 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,
-it would need to loop over the entire collection of interactions
-between pairs of simple particles within the two bodies, each time a
-single body/body interaction was computed.
+such a pair style were to mimic the :doc:`fix rigid <fix_rigid>`
+model, it would need to loop over the entire collection of
+interactions between pairs of simple particles within the two bodies,
+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
-body particle.
+where M = 6 + 3\*N + 1, and N is the number of vertices in the body
+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,
-followed by a single diameter value = the rounded diameter of the
-circle 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 :doc:`read_data <read_data>` command
-for more details.
+a diameter value = the rounded diameter of the circle 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 :doc:`read_data <read_data>` command 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
-the body particle, E = number of edges, F = number of faces.
+where M = 6 + 3\*N + 2\*E + 4\*F + 1, and N is the number of vertices
+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
-:doc:`read_data <read_data>` command for more details.  Because the
-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.
+listed on as many lines as you wish; see the :doc:`read_data
+<read_data>` command for more details.
 
-The ordering of the 4 vertices within a face should follow
-the right-hand rule so that the normal vector of the face points
-outwards from the center of mass.
+Note that vertices are numbered from 0 to N-1 inclusive.  The order of
+the 2 vertices in each edge does not matter.  Faces can be triangles
+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
-   2
+   1 3 13
+   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
+   1 3 10
+   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
-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.
+The number of edges and faces for a rod or sphere must be listed,
+but is ignored.
+
+The :doc:`pair_style body/rounded/polhedron
+<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>`
-commands, this body style produces one datum for each of the N
-sub-particles in a body particle.  The datum has 3 values:
+**Output specifics for all body styles:**
+
+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
-*body* keyword is set, then each body particle is drawn as a polygon
-consisting of N line segments.  Note that the line segments are drawn
-between the N vertices, which does not correspond exactly to the
-physical extent of the body (because the :doc:`pair_style rounded/polygon <pair_body_rounded_polygon>` defines finite-size
-spheres at those point and the line segments between the spheres are
-tangent to the spheres).  The drawn diameter of each line segment is
-determined by the *bflag1* parameter for the *body* keyword.  The
-*bflag2* argument is ignored.
+The :doc:`dump image <dump_image>` command and its *body* keyword can
+be used to render body particles.
+
+For the *nparticle* body style, each body 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.
+
+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_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.
@@ -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``

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
-  of quantities printed every few timesteps to the screen and logfile.
+* :doc:`Thermodynamic output <thermo_style>`, which is a list of
+  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
-  :doc:`variables <variable>`.  Fix print can also output to the
-  screen.
+* 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
+  :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_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_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
-operating system.
+up-to-date with the current stable version of LAMMPS by simply updating
+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/Packages_details.rst

@@ -306,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:**
 

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
-   :target: JPG/screenshot_gl.jpg
+.. |pyex1| image:: img/screenshot_gl.jpg
+   :width: 24%
 
-.. image:: JPG/screenshot_atomeye_small.jpg
-   :target: JPG/screenshot_atomeye.jpg
+.. |pyex2| image:: img/screenshot_atomeye.jpg
+   :width: 24%
 
-.. image:: JPG/screenshot_pymol_small.jpg
-   :target: JPG/screenshot_pymol.jpg
+.. |pyex3| image:: img/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_test.rst

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

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
-recommended version of the Intel compiler is 14.0.1.106 or
-versions 15.0.2.044 and higher.
+co-processor and an Intel compiler are required.
 
 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

@@ -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
-internally; hence the units of :math:`K` are in energy/radian\^2.
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
+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
-bond-angle term.  :math:`\theta_0` is the equilibrium angle and :math:`r_1` and :math:`r_2` are
-the equilibrium bond lengths.
+where :math:`E_a` is the angle term, :math:`E_{bb}` is a bond-bond
+term, and :math:`E_{ba}` is a bond-angle term.  :math:`\theta_0` is
+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
-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.
+Coefficients for the :math:`E_a`, :math:`E_{bb}`, and :math:`E_{ba}`
+formulas 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.
 
 These are the 4 coefficients for the :math:`E_a` formula:
 
 * :math:`\theta_0` (degrees)
-* :math:`K_2` (energy/radian\^2)
-* :math:`K_3` (energy/radian\^3)
-* :math:`K_4` (energy/radian\^4)
+* :math:`K_2` (energy)
+* :math:`K_3` (energy)
+* :math:`K_4` (energy)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
-internally; hence the units of the various :math:`K` are in per-radian.
+: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.
 
 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
-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.
+.. include:: accel_styles.rst
 
 ----------
 
@@ -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_3` (energy/radian\^3)
-* :math:`K_4` (energy/radian\^4)
-* :math:`K_5` (energy/radian\^5)
-* :math:`K_6` (energy/radian\^6)
+* :math:`K_2` (energy)
+* :math:`K_3` (energy)
+* :math:`K_4` (energy)
+* :math:`K_5` (energy)
+* :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_cosine.rst

@@ -44,23 +44,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

doc/src/angle_cosine_delta.rst

@@ -46,23 +46,7 @@ internally.
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

doc/src/angle_cosine_periodic.rst

@@ -54,23 +54,7 @@ geometry.
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

doc/src/angle_cosine_squared.rst

@@ -46,23 +46,7 @@ internally.
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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_{BS1}` (energy/distance/rad)
+* :math:`K_{BS0}` (energy/distance)
+* :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
-internally; hence the units of :math:`K_{BS0}` and :math:`K_{BS1}` are in energy/distance/radian.
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
+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
-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.
+.. include:: accel_styles.rst
 
 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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-internally; hence the units of :math:`K` are in energy/radian\^2.
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
+radians internally; hence :math:`K` is effectively energy per
+radian\^2.
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-prefactor. The anharmonic prefactors have units :math:`\deg^{-n}`, for example
-:math:`-0.014 \deg^{-1}`, :math:`5.6 \cdot 10^{-5} \deg^{-2}`, ...
+where :math:`\theta_0` is the equilibrium value of the angle, and
+:math:`K` is a prefactor. The anharmonic prefactors have units
+: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
-internally; hence the units of :math:`K` are in energy/radian\^2.
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
+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_3` (energy/radian\^3)
-* :math:`K_4` (energy/radian\^4)
+* :math:`K_2` (energy)
+* :math:`K_3` (energy)
+* :math:`K_4` (energy)
 
-:math:`\theta_0` is specified in degrees, but LAMMPS converts it to radians
-internally; hence the units of :math:`K` are in energy/radian\^2.
+: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.
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-internally; hence the units of :math:`K` are in energy/radian\^2.
-The also required *lj/sdk* parameters will be extracted automatically
-from the pair_style.
+:math:`\theta_0` is specified in degrees, but LAMMPS converts it to
+radians internally; hence :math:`K` is effectively energy per
+radian\^2.
+
+The required *lj/sdk* parameters are extracted automatically from the
+pair_style.
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

doc/src/angle_table.rst

@@ -126,23 +126,7 @@ one that matches the specified keyword.
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-          :target: JPG/balance_uniform.jpg
+.. |balance2| image:: img/balance_nonuniform.jpg
+   :width: 32%
 
-     - .. figure:: JPG/balance_nonuniform_small.jpg
-          :target: JPG/balance_nonuniform.jpg
+.. |balance3| image:: img/balance_rcb.jpg
+   :width: 32%
 
-     - .. figure:: JPG/balance_rcb_small.jpg
-          :target: JPG/balance_rcb.jpg
+|balance1|  |balance2|  |balance3|
 
 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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

doc/src/bond_fene.rst

@@ -54,23 +54,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

doc/src/bond_fene_expand.rst

@@ -52,23 +52,7 @@ or :doc:`read_restart <read_restart>` commands:
 
 ----------
 
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

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
-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.
+.. include:: accel_styles.rst
 
 ----------
 

doc/src/bond_special.rst

@@ -0,0 +1,106 @@
+.. index:: bond_style special
+
+bond_style special command
+=================================
+
+Syntax
+""""""
+
+
+.. code-block:: LAMMPS
+
+   bond_style special
+
+Examples
+""""""""
+
+
+.. code-block:: LAMMPS
+
+   bond_style special
+   bond_coeff 0.5 0.5
+
+Description
+"""""""""""
+
+The *special* bond style can be used to create conceptual bonds which
+effectively impose weightings on the pairwise Lennard Jones and/or
+Coulombic interactions between selected pairs of particles in the
+system.  The form of the pairwise interaction will be whatever is
+computed by the :doc:`pair_style <pair_style>` command defined for the
+system; this command defines the weightings for its two terms.
+
+This command can thus be useful to apply weightings that cannot be
+handled by the :doc:`special_bonds <special_bonds>` command, such as
+on 1-5 or 1-6 interactions.  Or it can be used to add pairwise forces
+between one or more pairs of atoms that otherwise would not be include
+in the :doc:`pair_style <pair_style>` computation.
+
+The potential for this bond style has the form
+
+.. math::
+
+   E =  w_{LJ} E_{LJ} + w_{Coul} E_{Coul}
+
+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
+the data file or restart files read by the :doc:`read_data <read_data>`
+or :doc:`read_restart <read_restart>` commands:
+
+* :math:`w_{LJ}` weight (0.0 to 1.0) on pairwise Lennard-Jones interactions
+
+* :math:`w_{Coul}` weight (0.0 to 1.0) on pairwise Coulombic interactions
+
+----------
+
+Normally this bond style should be used in conjunction with one (or
+more) other bond styles which compute forces between atoms directly
+bonded to each other in a molecule.  This means the :doc:`bond_style
+hybrid <bond_hybrid>` command should be used with bond_style special
+as one of its sub-styles.
+
+Note that the same as for any other bond style, pairs of bonded atoms
+must be enumerated in the data file read by the :doc:`read_data
+<read_data>` command.  Thus if this command is used to weight all 1-5
+interactions in the system, all the 1-5 pairs of atoms must be listed
+in the "Bonds" section of the data file.
+
+This bond style imposes strict requirements on settings made with the
+:doc:`special_bonds <special_bonds>` command.  These requirements
+ensure that the new bonds created by this style do not create spurious
+1-2, 1-3, or 1-4 interactions within the molecular topology.
+
+Specifically 1-2 interactions must have weights of zero, 1-3
+interactions must either have weights of unity or :doc:`special_bonds
+angle yes <special_bonds>` must be used, and 1-4 interactions must
+have weights of unity or :doc:`special_bonds dihedral yes <special_bonds>`
+must be used.
+
+If this command is used to create bonded interactions between
+particles that are further apart than usual (e.g. 1-5 or 1-6
+interactions), this style may require an increase in the communication
+cutoff via the :doc:`comm_modify cutoff <comm_modify>` command.  If
+LAMMPS cannot find a partner atom in a bond, an error will be issued.
+
+Restrictions
+""""""""""""
+
+This bond style can only be used if LAMMPS was built with the
+USER-MISC package.  See the :doc:`Build package <Build_package>` doc
+page for more info.
+
+This bond style requires the use of a :doc:`pair_style <pair_style>` which
+computes a pairwise additive interaction and provides the ability to
+compute interactions for individual pairs of atoms.  Manybody potentials
+are not compatible in general, but also some other pair styles are missing
+the required functionality and thus will cause an error.
+
+This command is not compatible with long-range Coulombic interactions. If a
+`kspace_style <kspace_style>` is declared, an error will be issued.
+
+Related commands
+""""""""""""""""
+
+:doc:`bond_coeff <bond_coeff>`, :doc:`special_bonds <special_bonds>`
+
+**Default:** none

doc/src/bond_style.rst

@@ -98,6 +98,7 @@ accelerated styles exist.
 * :doc:`oxdna2/fene <bond_oxdna>` - same as oxdna but used with different pair styles
 * :doc:`oxrna2/fene <bond_oxdna>` - modified FENE bond suitable for RNA modeling
 * :doc:`quartic <bond_quartic>` - breakable quartic bond
+* :doc:`special <bond_special>` - enable special bond exclusions for 1-5 pairs and beyond
 * :doc:`table <bond_table>` - tabulated by bond length
 
 ----------