Merge pull request #2305 from akohlmey/next_patch_version

Update version strings for updated patch release

.gitattributes

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

.github/CODEOWNERS

@@ -119,6 +119,8 @@ src/utils.*               @akohlmey @rbberger
 tools/msi2lmp/*       @akohlmey
 tools/emacs/*         @HaoZeke
 tools/singularity/*   @akohlmey @rbberger
+tools/code_standard/* @rbberger
+tools/valgrind/*      @akohlmey
 
 # tests
 unittest/*            @akohlmey @rbberger

.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

@@ -57,7 +57,6 @@ check_for_autogen_files(${LAMMPS_SOURCE_DIR})
 # compiler tests
 # these need ot be done early (before further tests).
 #####################################################################
-include(CheckCCompilerFlag)
 include(CheckIncludeFileCXX)
 
 # set required compiler flags and compiler/CPU arch specific optimizations
@@ -70,27 +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)
-
-# GNU compiler specific features for testing
-if (${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
-  option(ENABLE_COVERAGE "Enable collecting code coverage data" OFF)
-  mark_as_advanced(ENABLE_COVERAGE)
-  if(ENABLE_COVERAGE)
-    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")
-  endif()
-endif()
+set(CMAKE_CXX_EXTENSIONS OFF CACHE BOOL "Use compiler extensions")
 
 ########################################################################
 # User input options                                                   #
@@ -122,8 +104,8 @@ install(TARGETS lmp EXPORT LAMMPS_Targets DESTINATION ${CMAKE_INSTALL_BINDIR})
 option(CMAKE_VERBOSE_MAKEFILE "Generate verbose Makefiles" OFF)
 
 set(STANDARD_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS DIPOLE
-  GRANULAR KSPACE LATTE MANYBODY MC MESSAGE MISC MOLECULE PERI POEMS QEQ
-  REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
+  GRANULAR KSPACE LATTE MANYBODY MC MESSAGE MISC MLIAP MOLECULE PERI POEMS
+  QEQ REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
   USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-MESODPD USER-CGSDK USER-COLVARS
   USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD USER-LB
   USER-MANIFOLD USER-MEAMC USER-MESONT USER-MGPT USER-MISC USER-MOFFF USER-MOLFILE
@@ -203,13 +185,14 @@ 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()
 
 # "hard" dependencies between packages resulting
 # in an error instead of skipping over files
+pkg_depends(MLIAP SNAP)
 pkg_depends(MPIIO MPI)
 pkg_depends(USER-ATC MANYBODY)
 pkg_depends(USER-LB MPI)
@@ -248,6 +231,48 @@ if(BUILD_OMP)
   target_link_libraries(lammps PRIVATE OpenMP::OpenMP_CXX)
 endif()
 
+# Compiler specific features for testing
+if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
+  option(ENABLE_COVERAGE "Enable collecting code coverage data" OFF)
+  mark_as_advanced(ENABLE_COVERAGE)
+  if(ENABLE_COVERAGE)
+    if(CMAKE_VERSION VERSION_LESS 3.13)
+      if(CMAKE_CXX_FLAGS)
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")
+      else()
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} --coverage")
+      endif()
+    else()
+      target_compile_options(lammps PUBLIC --coverage)
+      target_link_options(lammps PUBLIC --coverage)
+    endif()
+  endif()
+endif()
+
+set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, leak, thread, undefined)")
+mark_as_advanced(ENABLE_SANITIZER)
+set(ENABLE_SANITIZER_VALUES none address leak thread undefined)
+set_property(CACHE ENABLE_SANITIZER PROPERTY STRINGS ${ENABLE_SANITIZER_VALUES})
+validate_option(ENABLE_SANITIZER ENABLE_SANITIZER_VALUES)
+string(TOLOWER ${ENABLE_SANITIZER} ENABLE_SANITIZER)
+if(NOT ENABLE_SANITIZER STREQUAL "none")
+  if((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU") OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang"))
+    if(CMAKE_VERSION VERSION_LESS 3.13)
+      if(CMAKE_CXX_FLAGS)
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=${ENABLE_SANITIZER}")
+      else()
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} -fsanitize=${ENABLE_SANITIZER}")
+      endif()
+    else()
+      target_compile_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})
+      target_link_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})
+    endif()
+  else()
+    message(WARNING "ENABLE_SANITIZER option not supported by ${CMAKE_CXX_COMPILER_ID} compilers. Ignoring.")
+    set(ENABLE_SANITIZER "none")
+  endif()
+endif()
+
 if(PKG_MSCG OR PKG_USER-ATC OR PKG_USER-AWPMD OR PKG_USER-QUIP OR PKG_LATTE)
   enable_language(C)
   find_package(LAPACK)
@@ -333,17 +358,10 @@ 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)
-include(CheckCXXCompilerFlag)
 foreach(_FLAG ${CMAKE_TUNE_FLAGS})
-  string(REGEX REPLACE "[=\"]" "" _FLAGX ${_FLAG})
-  check_cxx_compiler_flag("${_FLAG}" COMPILER_SUPPORTS${_FLAGX})
-  if(COMPILER_SUPPORTS${_FLAGX})
-    target_compile_options(lammps PRIVATE ${_FLAG})
-  else()
-    message(WARNING "${_FLAG} found in CMAKE_TUNE_FLAGS, but not supported by the compiler, skipping")
-  endif()
+  target_compile_options(lammps PRIVATE ${_FLAG})
 endforeach()
 ########################################################################
 # Basic system tests (standard libraries, headers, functions, types)   #
@@ -729,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()
 
@@ -268,10 +290,17 @@ elseif(GPU_API STREQUAL "HIP")
     if(HIP_PLATFORM STREQUAL "hcc")
         configure_file(${CU_FILE} ${CU_CPP_FILE} COPYONLY)
 
-        add_custom_command(OUTPUT ${CUBIN_FILE}
-          VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
-          DEPENDS ${CU_CPP_FILE}
-          COMMENT "Generating ${CU_NAME}.cubin")
+        if(HIP_COMPILER STREQUAL "clang")
+          add_custom_command(OUTPUT ${CUBIN_FILE}
+            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
+            DEPENDS ${CU_CPP_FILE}
+            COMMENT "Generating ${CU_NAME}.cubin")
+        else()
+          add_custom_command(OUTPUT ${CUBIN_FILE}
+            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
+            DEPENDS ${CU_CPP_FILE}
+            COMMENT "Generating ${CU_NAME}.cubin")
+        endif()
     elseif(HIP_PLATFORM STREQUAL "nvcc")
         add_custom_command(OUTPUT ${CUBIN_FILE}
           VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --fatbin --use_fast_math -DUSE_HIP -D_${GPU_PREC_SETTING} ${HIP_CUDA_GENCODE} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_FILE}

cmake/Modules/Packages/USER-INTEL.cmake

@@ -77,7 +77,7 @@ else()
     foreach(_FLAG -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high -qno-offload -fno-alias -ansi-alias -restrict)
       check_cxx_compiler_flag("${_FLAG}" COMPILER_SUPPORTS${_FLAG})
       if(COMPILER_SUPPORTS${_FLAG})
-	  target_compile_options(lammps PRIVATE ${_FLAG})
+          target_compile_options(lammps PRIVATE ${_FLAG})
       endif()
     endforeach()
   endif()

cmake/Modules/Packages/USER-SCAFACOS.cmake

@@ -14,40 +14,23 @@ endif()
 option(DOWNLOAD_SCAFACOS "Download ScaFaCoS library instead of using an already installed one" ${DOWNLOAD_SCAFACOS_DEFAULT})
 if(DOWNLOAD_SCAFACOS)
   message(STATUS "ScaFaCoS download requested - we will build our own")
-  # create variables to pass our compiler flags along to the subsystem compile
-  # need to apply -fallow-argument-mismatch, if the fortran compiler supports it
-  include(CheckFortranCompilerFlag)
-  check_fortran_compiler_flag("-fallow-argument-mismatch" GNUFortran_ARGUMENT_MISMATCH_FLAG)
-  if(GNUFortran_ARGUMENT_MISMATCH_FLAG)
-    set(APPEND_Fortran_FLAG "-fallow-argument-mismatch")
-  endif()
-  if(CMAKE_Fortran_FLAGS)
-    set(SCAFACOS_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} ${APPEND_Fortran_FLAG}")
-  else()
-    set(SCAFACOS_Fortran_FLAGS "${CMAKE_Fortran_${CMAKE_BUILD_TYPE}_FLAGS} ${APPEND_Fortran_FLAG}")
-  endif()
-  if(CMAKE_CXX_FLAGS)
-      set(SCAFACOS_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
-    else()
-      set(SCAFACOS_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS}")
-  endif()
-  if(CMAKE_C_FLAGS)
-      set(SCAFACOS_C_FLAGS "${CMAKE_C_FLAGS}")
-    else()
-      set(SCAFACOS_C_FLAGS "${CMAKE_C_${CMAKE_BUILD_TYPE}_FLAGS}")
-  endif()
+
+  # version 1.0.1 needs a patch to compile and linke cleanly with GCC 10 and later.
+  file(DOWNLOAD https://download.lammps.org/thirdparty/scafacos-1.0.1-fix.diff ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
+          EXPECTED_HASH MD5=4baa1333bb28fcce102d505e1992d032)
 
   include(ExternalProject)
   ExternalProject_Add(scafacos_build
     URL https://github.com/scafacos/scafacos/releases/download/v1.0.1/scafacos-1.0.1.tar.gz
     URL_MD5 bd46d74e3296bd8a444d731bb10c1738
+    PATCH_COMMAND patch -p1 < ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
     CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR> --disable-doc
                                              --enable-fcs-solvers=fmm,p2nfft,direct,ewald,p3m
                                              --with-internal-fftw --with-internal-pfft
                                              --with-internal-pnfft ${CONFIGURE_REQUEST_PIC}
-                                             FC=${CMAKE_MPI_Fortran_COMPILER} FCFLAGS=${SCAFACOS_Fortran_FLAGS}
-                                             CXX=${CMAKE_MPI_CXX_COMPILER} CXXFLAGS=${SCAFACOS_CXX_FLAGS}
-                                             CC=${CMAKE_MPI_C_COMPILER} CFLAGS=${SCAFACOS_C_FLAGS}
+                                             FC=${CMAKE_MPI_Fortran_COMPILER}
+                                             CXX=${CMAKE_MPI_CXX_COMPILER}
+                                             CC=${CMAKE_MPI_C_COMPILER}
                                              F77=
     BUILD_BYPRODUCTS
       <INSTALL_DIR>/lib/libfcs.a

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

@@ -3,6 +3,51 @@
 ###############################################################################
 option(ENABLE_TESTING "Enable testing" OFF)
 if(ENABLE_TESTING)
+  find_program(VALGRIND_BINARY NAMES valgrind)
+  # generate custom suppression file
+  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/lammps.supp "\n")
+  file(GLOB VALGRIND_SUPPRESSION_FILES ${LAMMPS_TOOLS_DIR}/valgrind/[^.]*.supp)
+  foreach(SUPP ${VALGRIND_SUPPRESSION_FILES})
+    file(READ ${SUPP} SUPPRESSIONS)
+    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/lammps.supp "${SUPPRESSIONS}")
+  endforeach()
+  set(VALGRIND_DEFAULT_OPTIONS "--leak-check=full --show-leak-kinds=all --track-origins=yes --suppressions=${CMAKE_BINARY_DIR}/lammps.supp")
+
+  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()
   get_filename_component(LAMMPS_UNITTEST_DIR ${LAMMPS_SOURCE_DIR}/../unittest ABSOLUTE)
   get_filename_component(LAMMPS_UNITTEST_BIN ${CMAKE_BINARY_DIR}/unittest ABSOLUTE)

cmake/presets/mingw-cross.cmake

@@ -1,6 +1,6 @@
 set(WIN_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE GPU
-                 GRANULAR KSPACE LATTE MANYBODY MC MISC MOLECULE OPT PERI
-                 POEMS QEQ REPLICA RIGID SHOCK SNAP SPIN SRD VORONOI
+                 GRANULAR KSPACE LATTE MANYBODY MC MISC MLIAP MOLECULE OPT
+                 PERI POEMS QEQ REPLICA RIGID SHOCK SNAP SPIN SRD VORONOI
                  USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK
                  USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF
                  USER-FEP USER-INTEL USER-MANIFOLD USER-MEAMC USER-MESODPD

cmake/presets/most.cmake

@@ -2,8 +2,8 @@
 # external libraries. Compared to all_on.cmake some more unusual packages
 # are removed. The resulting binary should be able to run most inputs.
 
-set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL
-        DIPOLE GRANULAR KSPACE MANYBODY MC MISC MOLECULE OPT PERI
+set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE
+        GRANULAR KSPACE MANYBODY MC MISC MLIAP MOLECULE OPT PERI
         POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN SRD VORONOI
         USER-BOCS USER-CGDNA USER-CGSDK USER-COLVARS USER-DIFFRACTION
         USER-DPD USER-DRUDE USER-EFF USER-FEP USER-MEAMC USER-MESODPD

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/github-development-workflow.md

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

doc/include-file-conventions.md

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

doc/lammps.1

@@ -1,4 +1,4 @@
-.TH LAMMPS "15 June 2020" "2020-06-15"
+.TH LAMMPS "24 August 2020" "2020-08-24"
 .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

@@ -8,8 +8,8 @@ useful during development, testing or debugging.
 
 .. _compilation:
 
-Verify compilation flags
-------------------------
+Monitor compilation flags
+-------------------------
 
 Sometimes it is necessary to verify the complete sequence of compilation flags
 generated by the CMake build. To enable a more verbose output during
@@ -19,7 +19,8 @@ compilation you can use the following option.
 
    -D CMAKE_VERBOSE_MAKEFILE=value    # value = no (default) or yes
 
-Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1:
+Another way of doing this without reconfiguration is calling make with
+variable VERBOSE set to 1:
 
 .. code-block:: bash
 
@@ -33,25 +34,27 @@ Address, Undefined Behavior, and Thread Sanitizer Support
 ---------------------------------------------------------
 
 Compilers such as GCC and Clang support generating instrumented binaries
-which use different sanitizer libraries to detect problems in code
+which use different sanitizer libraries to detect problems in the code
 during run-time. They can detect issues like:
 
  - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_
  - `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_
  - `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_
 
-Please note that this kind of instrumentation usually comes with a small
-performance hit (much less than using tools like `Valgrind
-<https://valgrind.org>`_).  The to enable these features additional
-compiler flags need to be added to the compilation and linking stages.
-This is most easily done through setting the ``CMAKE_TUNE_FLAGS``
-variable during configuration. Examples:
+Please note that this kind of instrumentation usually comes with a
+performance hit (but much less than using tools like `Valgrind
+<https://valgrind.org>`_ with a more low level approach).  The to enable
+these features additional compiler flags need to be added to the
+compilation and linking stages.  This is done through setting the
+``ENABLE_SANITIZER`` variable during configuration. Examples:
 
 .. code-block:: bash
 
-   -D CMAKE_TUNE_FLAGS=-fsanitize=address    # enable address sanitizer / memory leak checker
-   -D CMAKE_TUNE_FLAGS=-fsanitize=undefined  # enable undefined behavior sanitizer
-   -D CMAKE_TUNE_FLAGS=-fsanitize=thread     # enable thread sanitizer
+   -D ENABLE_SANITIZER=none       # no sanitizer active (default)
+   -D ENABLE_SANITIZER=address    # enable address sanitizer / memory leak checker
+   -D ENABLE_SANITIZER=leak       # enable memory leak checker (only)
+   -D ENABLE_SANITIZER=undefined  # enable undefined behavior sanitizer
+   -D ENABLE_SANITIZER=thread     # enable thread sanitizer
 
 ----------
 
@@ -86,19 +89,21 @@ The output of this command will be looking something like this::
    [...]$ ctest
    Test project /home/akohlmey/compile/lammps/build-testing
          Start  1: MolPairStyle:hybrid-overlay
-    1/26 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec
+   1/109 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec
          Start  2: MolPairStyle:hybrid
-    2/26 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec
+   2/109 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec
          Start  3: MolPairStyle:lj_class2
     [...]
-         Start 25: AngleStyle:harmonic
-   25/26 Test #25: AngleStyle:harmonic .................   Passed    0.01 sec
-         Start 26: AngleStyle:zero
-   26/26 Test #26: AngleStyle:zero .....................   Passed    0.01 sec
+         Start 107: PotentialFileReader
+ 107/109 Test #107: PotentialFileReader ................   Passed    0.04 sec
+         Start 108: EIMPotentialFileReader
+ 108/109 Test #108: EIMPotentialFileReader .............   Passed    0.03 sec
+         Start 109: TestSimpleCommands
+ 109/109 Test #109: TestSimpleCommands .................   Passed    0.02 sec
 
    100% tests passed, 0 tests failed out of 26
 
-   Total Test time (real) =   0.27 sec
+   Total Test time (real) =  25.57 sec
 
 
 The ``ctest`` command has many options, the most important ones are:
@@ -117,6 +122,8 @@ The ``ctest`` command has many options, the most important ones are:
      - exclude subset of tests matching the regular expression <regex>
    * - -N
      - dry-run: display list of tests without running them
+   * - -T memcheck
+     - run tests with valgrind memory checker (if available)
 
 In its full implementation, the unit test framework will consist of multiple
 kinds of tests implemented in different programming languages (C++, C, Python,
@@ -152,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
@@ -165,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
@@ -193,8 +200,8 @@ In this particular case, 5 out of 6 sets of tests were conducted, the
 tests for the ``lj/cut/opt`` pair style was skipped, since the tests
 executable did not include it.  To learn what individual tests are performed,
 you (currently) need to read the source code.  You can use code coverage
-recording (see next section) to confirm how well the tests cover the individual
-source files.
+recording (see next section) to confirm how well the tests cover the code
+paths in the individual source files.
 
 The force style test programs have a common set of options:
 
@@ -211,6 +218,14 @@ The force style test programs have a common set of options:
    * - -v
      - verbose output: also print the executed LAMMPS commands
 
+The ``ctest`` tool has no mechanism to directly pass flags to the individual
+test programs, but a workaround has been implemented where these flags can be
+set in an environment variable ``TEST_ARGS``. Example:
+
+.. code-block:: bash
+
+   env TEST_ARGS=-s ctest -V -R BondStyle
+
 To add a test for a style that is not yet covered, it is usually best
 to copy a YAML file for a similar style to a new file, edit the details
 of the style (how to call it, how to set its coefficients) and then
@@ -244,6 +259,81 @@ 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Additional tests that validate utility functions or specific components
+of LAMMPS are implemented as standalone executable which may, or may not
+require creating a suitable LAMMPS instance.  These tests are more specific
+and do not require YAML format input files.  To add a test, either an
+existing source file needs to be extended or a new file added, which in turn
+requires additions to the ``CMakeLists.txt`` file in the source folder.
+
 Collect and visualize code coverage metrics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -306,3 +396,23 @@ The images below illustrate how the data is presented.
              :target: JPG/coverage-file-branches.png
 
           Source page with branches
+
+Coding style utilities
+----------------------
+
+To aid with enforcing some of the coding style conventions in LAMMPS
+some additional build targets have been added. These require Python 3.5
+or later and will only work on Unix-like operating and file systems.
+The following options are available.
+
+.. code-block:: bash
+
+   make check-whitespace    # generate coverage report in HTML format
+   make fix-whitespace      # generate coverage report in XML format
+   make check-permissions   # delete folder with HTML format coverage report
+   make fix-permissions     # delete all collected coverage data and HTML output
+
+For the code in the ``unittest`` tree we are using the `clang-format`
+tool (Clang version 8.0 or later is required). If available, the source
+code files in the ``unittest`` tree can be updated to conform to the
+formatting settings using ``make format-tests``.

doc/src/Build_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_package.rst

@@ -136,6 +136,7 @@ src directory.
 .. _cmake_presets:
 
 CMake presets for installing many packages
+""""""""""""""""""""""""""""""""""""""""""
 
 Instead of specifying all the CMake options via the command-line,
 CMake allows initializing its settings cache using script files.
@@ -168,7 +169,8 @@ one of them as a starting point and customize it to your needs.
    in a single cmake run, or change settings incrementally by running
    cmake with new flags.
 
-**Example:**
+Example
+"""""""
 
 .. code-block:: bash
 

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>`
@@ -183,6 +183,7 @@ OPT.
    * :doc:`mesont/tpm <pair_mesont_tpm>`
    * :doc:`mgpt <pair_mgpt>`
    * :doc:`mie/cut (g) <pair_mie>`
+   * :doc:`mliap <pair_mliap>`
    * :doc:`mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>`
    * :doc:`momb <pair_momb>`
    * :doc:`morse (gkot) <pair_morse>`
@@ -228,7 +229,6 @@ OPT.
    * :doc:`smd/ulsph <pair_smd_ulsph>`
    * :doc:`smtbq <pair_smtbq>`
    * :doc:`snap (k) <pair_snap>`
-   * :doc:`snap (k) <pair_snap>`
    * :doc:`soft (go) <pair_soft>`
    * :doc:`sph/heatconduction <pair_sph_heatconduction>`
    * :doc:`sph/idealgas <pair_sph_idealgas>`

doc/src/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

@@ -44,6 +44,7 @@ page gives those details.
    * :ref:`MC <PKG-MC>`
    * :ref:`MESSAGE <PKG-MESSAGE>`
    * :ref:`MISC <PKG-MISC>`
+   * :ref:`MLIAP <PKG-MLIAP>`
    * :ref:`MOLECULE <PKG-MOLECULE>`
    * :ref:`MPIIO <PKG-MPIIO>`
    * :ref:`MSCG <PKG-MSCG>`
@@ -305,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:**
 
@@ -652,6 +654,29 @@ listing, "ls src/MISC", to see the list of commands.
 
 ----------
 
+.. _PKG-MLIAP:
+
+MLIAP package
+-------------
+
+**Contents:**
+
+A general interface for machine-learning interatomic potentials.
+
+**Install:**
+
+To use this package, also the :ref:`SNAP package<PKG-SNAP>` needs to be installed.
+
+**Author:** Aidan Thompson (Sandia).
+
+**Supporting info:**
+
+* src/MLIAP: filenames -> commands
+* :doc:`pair_style mliap <pair_mliap>`
+* examples/mliap
+
+----------
+
 .. _PKG-MOLECULE:
 
 MOLECULE package

doc/src/Packages_standard.rst

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

doc/src/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
@@ -88,7 +92,7 @@ GPUs/node to 1.
 
 Using the "-pk" switch explicitly allows for setting of the number of
 GPUs/node to use and additional options.  Its syntax is the same as
-same as the "package gpu" command.  See the :doc:`package <package>`
+the "package gpu" command.  See the :doc:`package <package>`
 command doc page for details, including the default values used for
 all its options if it is not specified.
 

doc/src/Speed_intel.rst

@@ -12,7 +12,8 @@ When offloading to a co-processor from a CPU, the same routine is run
 twice, once on the CPU and once with an offload flag. This allows
 LAMMPS to run on the CPU cores and co-processor cores simultaneously.
 
-**Currently Available USER-INTEL Styles:**
+Currently Available USER-INTEL Styles
+"""""""""""""""""""""""""""""""""""""
 
 * Angle Styles: charmm, harmonic
 * Bond Styles: fene, fourier, harmonic
@@ -31,9 +32,10 @@ LAMMPS to run on the CPU cores and co-processor cores simultaneously.
    support computing per-atom stress.  If any compute or fix in your
    input requires it, LAMMPS will abort with an error message.
 
-**Speed-ups to expect:**
+Speed-up to expect
+"""""""""""""""""""
 
-The speedups will depend on your simulation, the hardware, which
+The speedup will depend on your simulation, the hardware, which
 styles are used, the number of atoms, and the floating-point
 precision mode. Performance improvements are shown compared to
 LAMMPS *without using other acceleration packages* as these are
@@ -59,7 +61,8 @@ instructions to reproduce.
 
 ----------
 
-**Accuracy and order of operations:**
+Accuracy and order of operations
+""""""""""""""""""""""""""""""""
 
 In most molecular dynamics software, parallelization parameters
 (# of MPI, OpenMP, and vectorization) can change the results due
@@ -96,7 +99,8 @@ mode should not be used without appropriate validation.
 
 ----------
 
-**Quick Start for Experienced Users:**
+Quick Start for Experienced Users
+"""""""""""""""""""""""""""""""""
 
 LAMMPS should be built with the USER-INTEL package installed.
 Simulations should be run with 1 MPI task per physical *core*\ ,
@@ -136,12 +140,13 @@ For Intel Xeon Phi co-processors (Offload):
 
 ----------
 
-**Required hardware/software:**
+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
@@ -159,7 +164,8 @@ For best performance, we recommend that the MCDRAM is configured in
 "Cache" mode can also be used, although the performance might be
 slightly lower.
 
-**Notes about Simultaneous Multithreading:**
+Notes about Simultaneous Multithreading
+"""""""""""""""""""""""""""""""""""""""
 
 Modern CPUs often support Simultaneous Multithreading (SMT). On
 Intel processors, this is called Hyper-Threading (HT) technology.
@@ -196,7 +202,8 @@ this information can normally be obtained with:
 
    cat /proc/cpuinfo
 
-**Building LAMMPS with the USER-INTEL package:**
+Building LAMMPS with the USER-INTEL package
+"""""""""""""""""""""""""""""""""""""""""""
 
 See the :ref:`Build extras <user-intel>` doc page for
 instructions.  Some additional details are covered here.
@@ -263,7 +270,8 @@ recommended CCFLAG options for best performance are "-O2 -fno-alias
    in most of the example Makefiles is to use "-xHost", however this
    should not be used when cross-compiling.
 
-**Running LAMMPS with the USER-INTEL package:**
+Running LAMMPS with the USER-INTEL package
+""""""""""""""""""""""""""""""""""""""""""
 
 Running LAMMPS with the USER-INTEL package is similar to normal use
 with the exceptions that one should 1) specify that LAMMPS should use
@@ -304,7 +312,8 @@ almost all cases.
    recommended, especially when running on a machine with Intel
    Hyper-Threading technology disabled.
 
-**Run with the USER-INTEL package from the command line:**
+Run with the USER-INTEL package from the command line
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 To enable USER-INTEL optimizations for all available styles used in
 the input script, the "-sf intel" :doc:`command-line switch <Run_options>` can be used without any requirement for
@@ -339,7 +348,8 @@ launching MPI applications):
    mpirun -np 72 -ppn 36 lmp_machine -sf intel -in in.script                                 # 2 nodes, 36 MPI tasks/node, $OMP_NUM_THREADS OpenMP Threads
    mpirun -np 72 -ppn 36 lmp_machine -sf intel -in in.script -pk intel 0 omp 2 mode double   # Don't use any co-processors that might be available, use 2 OpenMP threads for each task, use double precision
 
-**Or run with the USER-INTEL package by editing an input script:**
+Or run with the USER-INTEL package by editing an input script
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 As an alternative to adding command-line arguments, the input script
 can be edited to enable the USER-INTEL package. This requires adding
@@ -361,7 +371,8 @@ Alternatively, the :doc:`suffix intel <suffix>` command can be added to
 the input script to enable USER-INTEL styles for the commands that
 follow in the input script.
 
-**Tuning for Performance:**
+Tuning for Performance
+""""""""""""""""""""""
 
 .. note::
 
@@ -431,7 +442,8 @@ series processors will always perform better using MCDRAM. Please
 consult your system documentation for the best approach to specify
 that MPI runs are performed in MCDRAM.
 
-**Tuning for Offload Performance:**
+Tuning for Offload Performance
+""""""""""""""""""""""""""""""
 
 The default settings for offload should give good performance.
 
@@ -521,7 +533,8 @@ the pair styles in the USER-INTEL package currently support the
 :doc:`run_style respa <run_style>` command; only the "pair" option is
 supported.
 
-**References:**
+References
+""""""""""
 
 * Brown, W.M., Carrillo, J.-M.Y., Mishra, B., Gavhane, N., Thakkar, F.M., De Kraker, A.R., Yamada, M., Ang, J.A., Plimpton, S.J., "Optimizing Classical Molecular Dynamics in LAMMPS," in Intel Xeon Phi Processor High Performance Programming: Knights Landing Edition, J. Jeffers, J. Reinders, A. Sodani, Eds. Morgan Kaufmann.
 * Brown, W. M., Semin, A., Hebenstreit, M., Khvostov, S., Raman, K., Plimpton, S.J. `Increasing Molecular Dynamics Simulation Rates with an 8-Fold Increase in Electrical Power Efficiency. <http://dl.acm.org/citation.cfm?id=3014915>`_ 2016 High Performance Computing, Networking, Storage and Analysis, SC16: International Conference (pp. 82-95).

doc/src/Speed_omp.rst

@@ -8,18 +8,21 @@ improper), several Kspace styles, and a few fix styles.  It uses
 the OpenMP interface for multi-threading, but can also be compiled
 without OpenMP support, providing optimized serial styles in that case.
 
-**Required hardware/software:**
+Required hardware/software
+""""""""""""""""""""""""""
 
 To enable multi-threading, your compiler must support the OpenMP interface.
 You should have one or more multi-core CPUs, as multiple threads can only be
 launched by each MPI task on the local node (using shared memory).
 
-**Building LAMMPS with the USER-OMP package:**
+Building LAMMPS with the USER-OMP package
+"""""""""""""""""""""""""""""""""""""""""
 
 See the :ref:`Build extras <user-omp>` doc page for
 instructions.
 
-**Run with the USER-OMP package from the command line:**
+Run with the USER-OMP package from the command line
+"""""""""""""""""""""""""""""""""""""""""""""""""""
 
 These examples assume one or more 16-core nodes.
 
@@ -52,7 +55,8 @@ details, including the default values used if it is not specified.  It
 also gives more details on how to set the number of threads via the
 OMP_NUM_THREADS environment variable.
 
-**Or run with the USER-OMP package by editing an input script:**
+Or run with the USER-OMP package by editing an input script
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 The discussion above for the mpirun/mpiexec command, MPI tasks/node,
 and threads/MPI task is the same.
@@ -70,7 +74,8 @@ per MPI task to use.  The command doc page explains other options and
 how to set the number of threads via the OMP_NUM_THREADS environment
 variable.
 
-**Speed-ups to expect:**
+Speed-up to expect
+""""""""""""""""""
 
 Depending on which styles are accelerated, you should look for a
 reduction in the "Pair time", "Bond time", "KSpace time", and "Loop
@@ -92,7 +97,8 @@ sub-section.
 A description of the multi-threading strategy used in the USER-OMP
 package and some performance examples are `presented here <http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&d=1>`_
 
-**Guidelines for best performance:**
+Guidelines for best performance
+"""""""""""""""""""""""""""""""
 
 For many problems on current generation CPUs, running the USER-OMP
 package with a single thread/task is faster than running with multiple

doc/src/Speed_opt.rst

@@ -7,15 +7,18 @@ Technologies).  It contains a handful of pair styles whose compute()
 methods were rewritten in C++ templated form to reduce the overhead
 due to if tests and other conditional code.
 
-**Required hardware/software:**
+Required hardware/software
+""""""""""""""""""""""""""
 
-None.
+Any hardware. Any compiler.
 
-**Building LAMMPS with the OPT package:**
+Building LAMMPS with the OPT package
+""""""""""""""""""""""""""""""""""""
 
 See the :ref:`Build extras <opt>` doc page for instructions.
 
-**Run with the OPT package from the command line:**
+Run with the OPT package from the command line
+""""""""""""""""""""""""""""""""""""""""""""""
 
 .. code-block:: bash
 
@@ -25,7 +28,8 @@ See the :ref:`Build extras <opt>` doc page for instructions.
 Use the "-sf opt" :doc:`command-line switch <Run_options>`, which will
 automatically append "opt" to styles that support it.
 
-**Or run with the OPT package by editing an input script:**
+Or run with the OPT package by editing an input script
+""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 Use the :doc:`suffix opt <suffix>` command, or you can explicitly add an
 "opt" suffix to individual styles in your input script, e.g.
@@ -34,13 +38,15 @@ Use the :doc:`suffix opt <suffix>` command, or you can explicitly add an
 
    pair_style lj/cut/opt 2.5
 
-**Speed-ups to expect:**
+Speed-up to expect
+""""""""""""""""""
 
 You should see a reduction in the "Pair time" value printed at the end
 of a run.  On most machines for reasonable problem sizes, it will be a
 5 to 20% savings.
 
-**Guidelines for best performance:**
+Guidelines for best performance
+"""""""""""""""""""""""""""""""
 
 Just try out an OPT pair style to see how it performs.
 

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.
 
 ----------
 
@@ -91,7 +92,10 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none
 
 ----------
 

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.
 
@@ -145,7 +135,10 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none
 
 ----------
 

doc/src/angle_coeff.rst

@@ -92,4 +92,7 @@ Related commands
 
 :doc:`angle_style <angle_style>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -76,4 +60,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

doc/src/angle_cosine_buck6d.rst

@@ -68,4 +68,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -78,4 +62,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`, :doc:`angle_style cosine/squared <angle_cosine_squared>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -86,7 +70,10 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none
 
 ----------
 

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
 
 ----------
 
@@ -77,4 +61,7 @@ Related commands
 :doc:`angle_coeff <angle_coeff>`,
 :doc:`angle_style cosine/shift/exp <angle_cosine_shift_exp>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -90,4 +74,7 @@ Related commands
 :doc:`angle_style cosine/shift <angle_cosine_shift>`,
 :doc:`dihedral_style cosine/shift/exp <dihedral_cosine_shift_exp>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -78,4 +62,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 """"""""""""
@@ -61,4 +62,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 """"""""""""
@@ -129,7 +113,10 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`, :doc:`angle_hybrid <angle_hybrid>`
 
-**Default:** none
+Default
+"""""""
+
+none
 
 ----------
 

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
 
 ----------
 
@@ -74,4 +58,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -73,4 +57,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -84,4 +69,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

doc/src/angle_hybrid.rst

@@ -95,4 +95,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 """"""""""""
@@ -55,4 +57,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

doc/src/angle_none.rst

@@ -37,4 +37,7 @@ Related commands
 
 :doc:`angle_style zero <angle_zero>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -80,4 +65,7 @@ Related commands
 
 :doc:`angle_coeff <angle_coeff>`
 
-**Default:** none
+Default
+"""""""
+
+none

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
 
 ----------
 
@@ -87,4 +73,7 @@ Related commands
 :doc:`angle_coeff <angle_coeff>`, :doc:`angle_style harmonic <angle_harmonic>`, :doc:`pair_style lj/sdk <pair_sdk>`,
 :doc:`pair_style lj/sdk/coul/long <pair_sdk>`
 
-**Default:** none
+Default
+"""""""
+
+none