Merge branch 'master' into charge_regulation2

.github/workflows/unittest-macos.yml

@@ -24,7 +24,9 @@ jobs:
       shell: bash
       working-directory: ${{github.workspace}}/build
       run: |
-        cmake -C $GITHUB_WORKSPACE/cmake/presets/most.cmake $GITHUB_WORKSPACE/cmake \
+        cmake -C $GITHUB_WORKSPACE/cmake/presets/clang.cmake \
+              -C $GITHUB_WORKSPACE/cmake/presets/most.cmake \
+                 $GITHUB_WORKSPACE/cmake \
               -DENABLE_TESTING=ON -DBUILD_SHARED_LIBS=ON -DLAMMPS_EXCEPTIONS=ON
         cmake --build . --parallel 2
 

LICENSE

@@ -301,9 +301,8 @@ one line to give the program's name and an idea of what it does.
 Copyright (C) yyyy  name of author
 
 This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
+it under the terms of the GNU General Public License version 2 as
-the Free Software Foundation; either version 2 of the License, or (at
+published by the Free Software Foundation.
-your option) any later version.
 
 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of

cmake/CMakeLists.txt

@@ -22,11 +22,23 @@ set(LAMMPS_TOOLS_DIR      ${LAMMPS_DIR}/tools)
 set(LAMMPS_PYTHON_DIR     ${LAMMPS_DIR}/python)
 set(LAMMPS_POTENTIALS_DIR ${LAMMPS_DIR}/potentials)
 
+set(LAMMPS_DOWNLOADS_URL "https://download.lammps.org" CACHE STRING "Base URL for LAMMPS downloads")
+set(LAMMPS_POTENTIALS_URL "${LAMMPS_DOWNLOADS_URL}/potentials")
+set(LAMMPS_THIRDPARTY_URL "${LAMMPS_DOWNLOADS_URL}/thirdparty")
+mark_as_advanced(LAMMPS_DOWNLOADS_URL)
+
 find_package(Git)
 
 # by default, install into $HOME/.local (not /usr/local), so that no root access (and sudo!!) is needed
 if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
-  set(CMAKE_INSTALL_PREFIX "$ENV{HOME}/.local" CACHE PATH "default install path" FORCE )
+  set(CMAKE_INSTALL_PREFIX "$ENV{HOME}/.local" CACHE PATH "Default install path" FORCE)
+endif()
+
+# If enabled, no need to use LD_LIBRARY_PATH / DYLD_LIBRARY_PATH when installed
+option(LAMMPS_INSTALL_RPATH "Set runtime path for shared libraries linked to LAMMPS binaries" OFF)
+if(LAMMPS_INSTALL_RPATH)
+  set(CMAKE_INSTALL_RPATH ${CMAKE_INSTALL_FULL_LIBDIR})
+  set(CMAKE_INSTALL_RPATH_USE_LINK_PATH ON)
 endif()
 
 # Cmake modules/macros are in a subdirectory to keep this file cleaner
@@ -106,7 +118,7 @@ option(CMAKE_VERBOSE_MAKEFILE "Generate verbose Makefiles" OFF)
 
 set(STANDARD_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS DIPOLE
   GRANULAR KSPACE LATTE MANYBODY MC MESSAGE MISC MLIAP MOLECULE PERI POEMS
-  QEQ REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
+  PLUGIN QEQ REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
   USER-ADIOS 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
@@ -156,8 +168,7 @@ if(BUILD_MPI)
     endif()
   endif()
 else()
-  enable_language(C)
+  file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
-  file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.c)
   add_library(mpi_stubs STATIC ${MPI_SOURCES})
   set_target_properties(mpi_stubs PROPERTIES OUTPUT_NAME lammps_mpi_stubs${LAMMPS_MACHINE})
   target_include_directories(mpi_stubs PUBLIC $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
@@ -527,6 +538,18 @@ foreach(PKG_WITH_INCL CORESHELL QEQ USER-OMP USER-SDPD KOKKOS OPT USER-INTEL GPU
   endif()
 endforeach()
 
+if(PKG_PLUGIN)
+  if(BUILD_SHARED_LIBS)
+    target_compile_definitions(lammps PRIVATE -DLMP_PLUGIN)
+  else()
+    message(WARNING "Plugin loading will not work unless BUILD_SHARED_LIBS is enabled")
+  endif()
+  # link with -ldl or equivalent for plugin loading; except on Windows
+  if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
+    target_link_libraries(lammps PRIVATE ${CMAKE_DL_LIBS})
+  endif()
+endif()
+
 ######################################################################
 # the windows version of LAMMPS requires a couple extra libraries
 # and the MPI library - if use - has to be linked right before those
@@ -778,9 +801,7 @@ if(PKG_GPU)
   message(STATUS "<<< GPU package settings >>>
 -- GPU API:          ${GPU_API}")
   if(GPU_API STREQUAL "CUDA")
-    message(STATUS "GPU architecture: ${GPU_ARCH}")
+    message(STATUS "GPU default architecture: ${GPU_ARCH}")
-  elseif(GPU_API STREQUAL "OPENCL")
-    message(STATUS "OpenCL tuning:    ${OCL_TUNE}")
   elseif(GPU_API STREQUAL "HIP")
     message(STATUS "HIP platform:     ${HIP_PLATFORM}")
     message(STATUS "HIP architecture: ${HIP_ARCH}")

cmake/Modules/Documentation.cmake

@@ -50,16 +50,20 @@ if(BUILD_DOC)
     OUTPUT ${DOC_BUILD_DIR}/requirements.txt
     DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE}
     COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt
-    COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade pip
+    COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade pip
-    COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
+    COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
-    COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
+    COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
   )
 
+  set(MATHJAX_URL "https://github.com/mathjax/MathJax/archive/3.1.2.tar.gz" CACHE STRING "URL for MathJax tarball")
+  set(MATHJAX_MD5 "a4a6a093a89bc2ccab1452d766b98e53" CACHE STRING "MD5 checksum of MathJax tarball")
+  mark_as_advanced(MATHJAX_URL)
+
   # download mathjax distribution and unpack to folder "mathjax"
   if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/mathjax/es5)
-    file(DOWNLOAD "https://github.com/mathjax/MathJax/archive/3.1.2.tar.gz"
+    file(DOWNLOAD ${MATHJAX_URL}
       "${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz"
-      EXPECTED_MD5 a4a6a093a89bc2ccab1452d766b98e53)
+      EXPECTED_MD5 ${MATHJAX_MD5})
     execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf mathjax.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
     file(GLOB MATHJAX_VERSION_DIR ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*)
     execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax)

cmake/Modules/GTest.cmake

@@ -8,10 +8,12 @@ endif()
 
 include(ExternalProject)
 set(GTEST_URL "https://github.com/google/googletest/archive/release-1.10.0.tar.gz" CACHE STRING "URL for GTest tarball")
+set(GTEST_MD5 "ecd1fa65e7de707cd5c00bdac56022cd" CACHE STRING "MD5 checksum of GTest tarball")
 mark_as_advanced(GTEST_URL)
+mark_as_advanced(GTEST_MD5)
 ExternalProject_Add(googletest
-                    URL ${GTEST_URL}
+                    URL             ${GTEST_URL}
-                    URL_MD5         ecd1fa65e7de707cd5c00bdac56022cd
+                    URL_MD5         ${GTEST_MD5}
                     SOURCE_DIR      "${CMAKE_BINARY_DIR}/gtest-src"
                     BINARY_DIR      "${CMAKE_BINARY_DIR}/gtest-build"
                     CMAKE_ARGS      ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_GTEST_OPTS}
@@ -20,10 +22,10 @@ ExternalProject_Add(googletest
                                     -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
                                     -DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
                                     -DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
-                    BUILD_BYPRODUCTS <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest${GTEST_LIB_POSTFIX}.a
+                    BUILD_BYPRODUCTS <BINARY_DIR>/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
-                                     <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock${GTEST_LIB_POSTFIX}.a
+                                     <BINARY_DIR>/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
-                                     <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest_main${GTEST_LIB_POSTFIX}.a
+                                     <BINARY_DIR>/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
-                                     <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock_main${GTEST_LIB_POSTFIX}.a
+                                     <BINARY_DIR>/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
                     LOG_DOWNLOAD ON
                     LOG_CONFIGURE ON
                     LOG_BUILD ON
@@ -39,10 +41,10 @@ file(MAKE_DIRECTORY ${GTEST_INCLUDE_DIR})
 file(MAKE_DIRECTORY ${GMOCK_INCLUDE_DIR})
 
 ExternalProject_Get_Property(googletest BINARY_DIR)
-set(GTEST_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest${GTEST_LIB_POSTFIX}.a)
+set(GTEST_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
-set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock${GTEST_LIB_POSTFIX}.a)
+set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
-set(GTEST_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest_main${GTEST_LIB_POSTFIX}.a)
+set(GTEST_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
-set(GMOCK_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock_main${GTEST_LIB_POSTFIX}.a)
+set(GMOCK_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
 
 # Prevent GoogleTest from overriding our compiler/linker options
 # when building with Visual Studio

cmake/Modules/LAMMPSUtils.cmake

@@ -86,7 +86,6 @@ endfunction(GenerateBinaryHeader)
 # fetch missing potential files
 function(FetchPotentials pkgfolder potfolder)
   if (EXISTS "${pkgfolder}/potentials.txt")
-    set(LAMMPS_POTENTIALS_URL "https://download.lammps.org/potentials")
     file(STRINGS "${pkgfolder}/potentials.txt" linelist REGEX "^[^#].")
     foreach(line ${linelist})
       string(FIND ${line} " " blank)

cmake/Modules/MPI4WIN.cmake

@@ -1,16 +1,25 @@
 # Download and configure custom MPICH files for Windows
 message(STATUS "Downloading and configuring MPICH-1.4.1 for Windows")
+set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win64-devel.tar.gz" CACHE STRING "URL for MPICH2 (win64) tarball")
+set(MPICH2_WIN32_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win32-devel.tar.gz" CACHE STRING "URL for MPICH2 (win32) tarball")
+set(MPICH2_WIN64_DEVEL_MD5 "4939fdb59d13182fd5dd65211e469f14" CACHE STRING "MD5 checksum of MPICH2 (win64) tarball")
+set(MPICH2_WIN32_DEVEL_MD5 "a61d153500dce44e21b755ee7257e031" CACHE STRING "MD5 checksum of MPICH2 (win32) tarball")
+mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
+mark_as_advanced(MPICH2_WIN32_DEVEL_URL)
+mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
+mark_as_advanced(MPICH2_WIN32_DEVEL_MD5)
+
 include(ExternalProject)
 if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
   ExternalProject_Add(mpi4win_build
-    URL https://download.lammps.org/thirdparty/mpich2-win64-devel.tar.gz
+    URL     ${MPICH2_WIN64_DEVEL_URL}
-    URL_MD5 4939fdb59d13182fd5dd65211e469f14
+    URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
     CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
     BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
 else()
   ExternalProject_Add(mpi4win_build
-    URL https://download.lammps.org/thirdparty/mpich2-win32-devel.tar.gz
+    URL     ${MPICH2_WIN32_DEVEL_URL}
-    URL_MD5 a61d153500dce44e21b755ee7257e031
+    URL_MD5 ${MPICH2_WIN32_DEVEL_MD5}
     CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
     BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
 endif()

cmake/Modules/OpenCLLoader.cmake

@@ -0,0 +1,50 @@
+message(STATUS "Downloading and building OpenCL loader library")
+set(OPENCL_LOADER_URL "${LAMMPS_THIRDPARTY_URL}/opencl-loader-2020.12.18.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
+set(OPENCL_LOADER_MD5 "011cdcbd41030be94f3fced6d763a52a" CACHE STRING "MD5 checksum of OpenCL loader tarball")
+mark_as_advanced(OPENCL_LOADER_URL)
+mark_as_advanced(OPENCL_LOADER_MD5)
+
+include(ExternalProject)
+ExternalProject_Add(opencl_loader
+                    URL             ${OPENCL_LOADER_URL}
+                    URL_MD5         ${OPENCL_LOADER_MD5}
+                    SOURCE_DIR      "${CMAKE_BINARY_DIR}/opencl_loader-src"
+                    BINARY_DIR      "${CMAKE_BINARY_DIR}/opencl_loader-build"
+                    CMAKE_ARGS      ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_OPENCL_LOADER_OPTS}
+                                    -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
+                                    -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
+                                    -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
+                                    -DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
+                                    -DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
+                    BUILD_BYPRODUCTS <BINARY_DIR>/libOpenCL${CMAKE_STATIC_LIBRARY_SUFFIX}
+                    LOG_DOWNLOAD ON
+                    LOG_CONFIGURE ON
+                    LOG_BUILD ON
+                    INSTALL_COMMAND ""
+                    TEST_COMMAND    "")
+
+ExternalProject_Get_Property(opencl_loader SOURCE_DIR)
+set(OPENCL_LOADER_INCLUDE_DIR ${SOURCE_DIR}/inc)
+
+# workaround for CMake 3.10 on ubuntu 18.04
+file(MAKE_DIRECTORY ${OPENCL_LOADER_INCLUDE_DIR})
+
+ExternalProject_Get_Property(opencl_loader BINARY_DIR)
+set(OPENCL_LOADER_LIBRARY_PATH "${BINARY_DIR}/libOpenCL${CMAKE_STATIC_LIBRARY_SUFFIX}")
+
+find_package(Threads QUIET)
+if(NOT WIN32)
+  set(OPENCL_LOADER_DEP_LIBS "Threads::Threads;${CMAKE_DL_LIBS}")
+else()
+  set(OPENCL_LOADER_DEP_LIBS "cfgmgr32;runtimeobject")
+endif()
+
+add_library(OpenCL::OpenCL UNKNOWN IMPORTED)
+add_dependencies(OpenCL::OpenCL opencl_loader)
+
+set_target_properties(OpenCL::OpenCL PROPERTIES
+  IMPORTED_LOCATION ${OPENCL_LOADER_LIBRARY_PATH}
+  INTERFACE_INCLUDE_DIRECTORIES ${OPENCL_LOADER_INCLUDE_DIR}
+  INTERFACE_LINK_LIBRARIES "${OPENCL_LOADER_DEP_LIBS}")
+
+

cmake/Modules/Packages/GPU.cmake

@@ -1,7 +1,9 @@
 set(GPU_SOURCES_DIR ${LAMMPS_SOURCE_DIR}/GPU)
 set(GPU_SOURCES ${GPU_SOURCES_DIR}/gpu_extra.h
                 ${GPU_SOURCES_DIR}/fix_gpu.h
-                ${GPU_SOURCES_DIR}/fix_gpu.cpp)
+                ${GPU_SOURCES_DIR}/fix_gpu.cpp
+                ${GPU_SOURCES_DIR}/fix_nh_gpu.h
+                ${GPU_SOURCES_DIR}/fix_nh_gpu.cpp)
 target_compile_definitions(lammps PRIVATE -DLMP_GPU)
 
 set(GPU_API "opencl" CACHE STRING "API used by GPU package")
@@ -33,7 +35,7 @@ if(GPU_API STREQUAL "CUDA")
   if(NOT BIN2C)
     message(FATAL_ERROR "Could not find bin2c, use -DBIN2C=/path/to/bin2c to help cmake finding it.")
   endif()
-  option(CUDPP_OPT "Enable CUDPP_OPT" ON)
+  option(CUDPP_OPT "Enable GPU binning via CUDAPP (should be off for modern GPUs)" OFF)
   option(CUDA_MPS_SUPPORT "Enable tweaks to support CUDA Multi-process service (MPS)" OFF)
   if(CUDA_MPS_SUPPORT)
     if(CUDPP_OPT)
@@ -97,9 +99,13 @@ if(GPU_API STREQUAL "CUDA")
   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 and 8.6) is supported by CUDA 11 and later
+  # 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] -gencode arch=compute_86,code=[sm_86,compute_86]")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
+  endif()
+  # Ampere (GPU Arch 8.6) is supported by CUDA 11.1 and later
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
   endif()
   if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
     message(WARNING "Unsupported CUDA version. Use at your own risk.")
@@ -125,7 +131,7 @@ if(GPU_API STREQUAL "CUDA")
   add_library(gpu STATIC ${GPU_LIB_SOURCES} ${GPU_LIB_CUDPP_SOURCES} ${GPU_OBJS})
   target_link_libraries(gpu PRIVATE ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
   target_include_directories(gpu PRIVATE ${LAMMPS_LIB_BINARY_DIR}/gpu ${CUDA_INCLUDE_DIRS})
-  target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -DMPI_GERYON -DUCL_NO_EXIT ${GPU_CUDA_MPS_FLAGS})
+  target_compile_definitions(gpu PRIVATE -DUSE_CUDA -D_${GPU_PREC_SETTING} -DMPI_GERYON -DUCL_NO_EXIT ${GPU_CUDA_MPS_FLAGS})
   if(CUDPP_OPT)
     target_include_directories(gpu PRIVATE ${LAMMPS_LIB_SOURCE_DIR}/gpu/cudpp_mini)
     target_compile_definitions(gpu PRIVATE -DUSE_CUDPP)
@@ -139,27 +145,13 @@ if(GPU_API STREQUAL "CUDA")
   target_include_directories(nvc_get_devices PRIVATE ${CUDA_INCLUDE_DIRS})
 
 elseif(GPU_API STREQUAL "OPENCL")
-  if(${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
+  option(USE_STATIC_OPENCL_LOADER "Download and include a static OpenCL ICD loader" ON)
-    # download and unpack support binaries for compilation of windows binaries.
+  mark_as_advanced(USE_STATIC_OPENCL_LOADER)
-    set(LAMMPS_THIRDPARTY_URL "https://download.lammps.org/thirdparty")
+  if (USE_STATIC_OPENCL_LOADER)
-    file(DOWNLOAD "${LAMMPS_THIRDPARTY_URL}/opencl-win-devel.tar.gz" "${CMAKE_CURRENT_BINARY_DIR}/opencl-win-devel.tar.gz"
+    include(OpenCLLoader)
-            EXPECTED_MD5 2c00364888d5671195598b44c2e0d44d)
-    execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf opencl-win-devel.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
-    add_library(OpenCL::OpenCL UNKNOWN IMPORTED)
-    if(${CMAKE_SYSTEM_PROCESSOR} STREQUAL "x86")
-      set_target_properties(OpenCL::OpenCL PROPERTIES IMPORTED_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/lib_win32/libOpenCL.dll")
-    elseif(${CMAKE_SYSTEM_PROCESSOR} STREQUAL "x86_64")
-      set_target_properties(OpenCL::OpenCL PROPERTIES IMPORTED_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/lib_win64/libOpenCL.dll")
-    endif()
-    set_target_properties(OpenCL::OpenCL PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/include")
   else()
     find_package(OpenCL REQUIRED)
   endif()
-  set(OCL_TUNE "generic" CACHE STRING "OpenCL Device Tuning")
-  set(OCL_TUNE_VALUES intel fermi kepler cypress generic)
-  set_property(CACHE OCL_TUNE PROPERTY STRINGS ${OCL_TUNE_VALUES})
-  validate_option(OCL_TUNE OCL_TUNE_VALUES)
-  string(TOUPPER ${OCL_TUNE} OCL_TUNE)
 
   include(OpenCLUtils)
   set(OCL_COMMON_HEADERS ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_preprocessor.h ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_aux_fun1.h)
@@ -203,7 +195,7 @@ elseif(GPU_API STREQUAL "OPENCL")
   add_library(gpu STATIC ${GPU_LIB_SOURCES})
   target_link_libraries(gpu PRIVATE OpenCL::OpenCL)
   target_include_directories(gpu PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/gpu)
-  target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -D${OCL_TUNE}_OCL -DMPI_GERYON -DUCL_NO_EXIT)
+  target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -DMPI_GERYON -DGERYON_NUMA_FISSION -DUCL_NO_EXIT)
   target_compile_definitions(gpu PRIVATE -DUSE_OPENCL)
 
   target_link_libraries(lammps PRIVATE gpu)
@@ -211,6 +203,7 @@ elseif(GPU_API STREQUAL "OPENCL")
   add_executable(ocl_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
   target_compile_definitions(ocl_get_devices PRIVATE -DUCL_OPENCL)
   target_link_libraries(ocl_get_devices PRIVATE OpenCL::OpenCL)
+  add_dependencies(ocl_get_devices OpenCL::OpenCL)
 elseif(GPU_API STREQUAL "HIP")
   if(NOT DEFINED HIP_PATH)
       if(NOT DEFINED ENV{HIP_PATH})
@@ -225,7 +218,7 @@ elseif(GPU_API STREQUAL "HIP")
 
   if(NOT DEFINED HIP_PLATFORM)
       if(NOT DEFINED ENV{HIP_PLATFORM})
-          set(HIP_PLATFORM "hcc" CACHE PATH "HIP Platform to be used during compilation")
+          set(HIP_PLATFORM "amd" CACHE PATH "HIP Platform to be used during compilation")
       else()
           set(HIP_PLATFORM $ENV{HIP_PLATFORM} CACHE PATH "HIP Platform used during compilation")
       endif()
@@ -233,7 +226,7 @@ elseif(GPU_API STREQUAL "HIP")
 
   set(ENV{HIP_PLATFORM} ${HIP_PLATFORM})
 
-  if(HIP_PLATFORM STREQUAL "hcc")
+  if(HIP_PLATFORM STREQUAL "hcc" OR HIP_PLATFORM STREQUAL "amd")
     set(HIP_ARCH "gfx906" CACHE STRING "HIP target architecture")
   elseif(HIP_PLATFORM STREQUAL "nvcc")
     find_package(CUDA REQUIRED)
@@ -291,7 +284,7 @@ elseif(GPU_API STREQUAL "HIP")
     set(CUBIN_FILE   "${LAMMPS_LIB_BINARY_DIR}/gpu/${CU_NAME}.cubin")
     set(CUBIN_H_FILE "${LAMMPS_LIB_BINARY_DIR}/gpu/${CU_NAME}_cubin.h")
 
-    if(HIP_PLATFORM STREQUAL "hcc")
+    if(HIP_PLATFORM STREQUAL "hcc" OR HIP_PLATFORM STREQUAL "amd")
         configure_file(${CU_FILE} ${CU_CPP_FILE} COPYONLY)
 
         if(HIP_COMPILER STREQUAL "clang")
@@ -345,11 +338,16 @@ elseif(GPU_API STREQUAL "HIP")
 
       if(DOWNLOAD_CUB)
         message(STATUS "CUB download requested")
+        set(CUB_URL "https://github.com/NVlabs/cub/archive/1.12.0.tar.gz" CACHE STRING "URL for CUB tarball")
+        set(CUB_MD5 "1cf595beacafff104700921bac8519f3" CACHE STRING "MD5 checksum of CUB tarball")
+        mark_as_advanced(CUB_URL)
+        mark_as_advanced(CUB_MD5)
+
         include(ExternalProject)
 
         ExternalProject_Add(CUB
-          GIT_REPOSITORY https://github.com/NVlabs/cub
+          URL     ${CUB_URL}
-          TIMEOUT 5
+          URL_MD5 ${CUB_MD5}
           PREFIX "${CMAKE_CURRENT_BINARY_DIR}"
           CONFIGURE_COMMAND ""
           BUILD_COMMAND ""
@@ -361,7 +359,7 @@ elseif(GPU_API STREQUAL "HIP")
       else()
         find_package(CUB)
         if(NOT CUB_FOUND)
-          message(FATAL_ERROR "CUB library not found. Help CMake to find it by setting CUB_INCLUDE_DIR, or set DOWNLOAD_VORO=ON to download it")
+          message(FATAL_ERROR "CUB library not found. Help CMake to find it by setting CUB_INCLUDE_DIR, or set DOWNLOAD_CUB=ON to download it")
         endif()
       endif()
 
@@ -388,18 +386,21 @@ elseif(GPU_API STREQUAL "HIP")
 
     target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_HCC__)
     target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/../include)
+  elseif(HIP_PLATFORM STREQUAL "amd")
+    target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_AMD__)
+    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
+
+    target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_AMD__)
+    target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/../include)
   endif()
 
   target_link_libraries(lammps PRIVATE gpu)
 endif()
 
-# GPU package
-FindStyleHeaders(${GPU_SOURCES_DIR} FIX_CLASS fix_ FIX)
-
 set_property(GLOBAL PROPERTY "GPU_SOURCES" "${GPU_SOURCES}")
-
+# detect styles which have a GPU version
-# detects styles which have GPU version
 RegisterStylesExt(${GPU_SOURCES_DIR} gpu GPU_SOURCES)
+RegisterFixStyle(${GPU_SOURCES_DIR}/fix_gpu.h)
 
 get_property(GPU_SOURCES GLOBAL PROPERTY GPU_SOURCES)
 

cmake/Modules/Packages/KIM.cmake

@@ -35,9 +35,13 @@ if(DOWNLOAD_KIM)
   include(ExternalProject)
   enable_language(C)
   enable_language(Fortran)
+  set(KIM_URL "https://s3.openkim.org/kim-api/kim-api-2.2.1.txz" CACHE STRING "URL for KIM tarball")
+  set(KIM_MD5 "ae1ddda2ef7017ea07934e519d023dca" CACHE STRING "MD5 checksum of KIM tarball")
+  mark_as_advanced(KIM_URL)
+  mark_as_advanced(KIM_MD5)
   ExternalProject_Add(kim_build
-    URL https://s3.openkim.org/kim-api/kim-api-2.2.1.txz
+    URL     ${KIM_URL}
-    URL_MD5 ae1ddda2ef7017ea07934e519d023dca
+    URL_MD5 ${KIM_MD5}
     BINARY_DIR build
     CMAKE_ARGS ${CMAKE_REQUEST_PIC}
                -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
@@ -69,14 +73,14 @@ if(DOWNLOAD_KIM)
     BUILD_RPATH "${_rpath_prefix}/kim_build-prefix/lib"
     )
 else()
-  if(KIM-API_FOUND AND KIM_API_VERSION VERSION_GREATER_EQUAL 2.2.0)
+  if(KIM-API_FOUND AND KIM-API_VERSION VERSION_GREATER_EQUAL 2.2.0)
     # For kim-api >= 2.2.0
-    find_package(KIM-API ${KIM-API_MIN_VERSION} CONFIG REQUIRED)
+    find_package(KIM-API 2.2.0 CONFIG REQUIRED)
     target_link_libraries(lammps PRIVATE KIM-API::kim-api)
   else()
     # For kim-api 2.1.3 (consistent with previous version of this file)
     find_package(PkgConfig REQUIRED)
-    pkg_check_modules(KIM-API REQUIRED IMPORTED_TARGET libkim-api>=KIM-API_MIN_VERSION)
+    pkg_check_modules(KIM-API REQUIRED IMPORTED_TARGET libkim-api>=${KIM-API_MIN_VERSION})
     target_link_libraries(lammps PRIVATE PkgConfig::KIM-API)
   endif()
 endif()

cmake/Modules/Packages/KOKKOS.cmake

@@ -37,9 +37,13 @@ if(DOWNLOAD_KOKKOS)
   list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}")
   list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}")
   include(ExternalProject)
+  set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/3.3.01.tar.gz" CACHE STRING "URL for KOKKOS tarball")
+  set(KOKKOS_MD5 "08201d1c7cf5bc458ce0f5b44a629d5a" CACHE STRING "MD5 checksum of KOKKOS tarball")
+  mark_as_advanced(KOKKOS_URL)
+  mark_as_advanced(KOKKOS_MD5)
   ExternalProject_Add(kokkos_build
-    URL https://github.com/kokkos/kokkos/archive/3.3.01.tar.gz
+    URL     ${KOKKOS_URL}
-    URL_MD5 08201d1c7cf5bc458ce0f5b44a629d5a
+    URL_MD5 ${KOKKOS_MD5}
     CMAKE_ARGS ${KOKKOS_LIB_BUILD_ARGS}
     BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a
   )
@@ -51,10 +55,12 @@ if(DOWNLOAD_KOKKOS)
     INTERFACE_INCLUDE_DIRECTORIES "${INSTALL_DIR}/include"
     INTERFACE_LINK_LIBRARIES ${CMAKE_DL_LIBS})
   target_link_libraries(lammps PRIVATE LAMMPS::KOKKOS)
+  target_link_libraries(lmp PRIVATE LAMMPS::KOKKOS)
   add_dependencies(LAMMPS::KOKKOS kokkos_build)
 elseif(EXTERNAL_KOKKOS)
   find_package(Kokkos 3.3.01 REQUIRED CONFIG)
   target_link_libraries(lammps PRIVATE Kokkos::kokkos)
+  target_link_libraries(lmp PRIVATE Kokkos::kokkos)
 else()
   set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)
   set(LAMMPS_LIB_KOKKOS_BIN_DIR ${LAMMPS_LIB_BINARY_DIR}/kokkos)
@@ -66,6 +72,7 @@ else()
                           ${LAMMPS_LIB_KOKKOS_BIN_DIR})
   target_include_directories(lammps PRIVATE ${Kokkos_INCLUDE_DIRS})
   target_link_libraries(lammps PRIVATE kokkos)
+  target_link_libraries(lmp PRIVATE kokkos)
 endif()
 target_compile_definitions(lammps PRIVATE -DLMP_KOKKOS)
 

cmake/Modules/Packages/LATTE.cmake

@@ -15,10 +15,14 @@ endif()
 option(DOWNLOAD_LATTE "Download the LATTE library instead of using an already installed one" ${DOWNLOAD_LATTE_DEFAULT})
 if(DOWNLOAD_LATTE)
   message(STATUS "LATTE download requested - we will build our own")
+  set(LATTE_URL "https://github.com/lanl/LATTE/archive/v1.2.2.tar.gz" CACHE STRING "URL for LATTE tarball")
+  set(LATTE_MD5 "820e73a457ced178c08c71389a385de7" CACHE STRING "MD5 checksum of LATTE tarball")
+  mark_as_advanced(LATTE_URL)
+  mark_as_advanced(LATTE_MD5)
   include(ExternalProject)
   ExternalProject_Add(latte_build
-    URL https://github.com/lanl/LATTE/archive/v1.2.2.tar.gz
+    URL     ${LATTE_URL}
-    URL_MD5 820e73a457ced178c08c71389a385de7
+    URL_MD5 ${LATTE_MD5}
     SOURCE_SUBDIR cmake
     CMAKE_ARGS -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR> ${CMAKE_REQUEST_PIC} -DCMAKE_INSTALL_LIBDIR=lib
     -DBLAS_LIBRARIES=${BLAS_LIBRARIES} -DLAPACK_LIBRARIES=${LAPACK_LIBRARIES}

cmake/Modules/Packages/MESSAGE.cmake

@@ -2,9 +2,8 @@ if(LAMMPS_SIZES STREQUAL BIGBIG)
   message(FATAL_ERROR "The MESSAGE Package is not compatible with -DLAMMPS_BIGBIG")
 endif()
 option(MESSAGE_ZMQ "Use ZeroMQ in MESSAGE package" OFF)
-file(GLOB_RECURSE cslib_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.F
+file(GLOB_RECURSE cslib_SOURCES
-    ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.c
+        ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.cpp)
-    ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.cpp)
 
 add_library(cslib STATIC ${cslib_SOURCES})
 target_compile_definitions(cslib PRIVATE -DLAMMPS_${LAMMPS_SIZES})

cmake/Modules/Packages/MSCG.cmake

@@ -7,10 +7,15 @@ else()
 endif()
 option(DOWNLOAD_MSCG "Download MSCG library instead of using an already installed one)" ${DOWNLOAD_MSCG_DEFAULT})
 if(DOWNLOAD_MSCG)
+  set(MSCG_URL "https://github.com/uchicago-voth/MSCG-release/archive/1.7.3.1.tar.gz" CACHE STRING "URL for MSCG tarball")
+  set(MSCG_MD5 "8c45e269ee13f60b303edd7823866a91" CACHE STRING "MD5 checksum of MSCG tarball")
+  mark_as_advanced(MSCG_URL)
+  mark_as_advanced(MSCG_MD5)
+
   include(ExternalProject)
   ExternalProject_Add(mscg_build
-    URL https://github.com/uchicago-voth/MSCG-release/archive/1.7.3.1.tar.gz
+    URL     ${MSCG_URL}
-    URL_MD5 8c45e269ee13f60b303edd7823866a91
+    URL_MD5 ${MSCG_MD5}
     SOURCE_SUBDIR src/CMake
     CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${EXTRA_MSCG_OPTS}
                -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}

cmake/Modules/Packages/USER-INTEL.cmake

@@ -30,7 +30,12 @@ if(INTEL_LRT_MODE STREQUAL "THREADS")
   endif()
 endif()
 if(INTEL_LRT_MODE STREQUAL "C++11")
-  target_compile_definitions(lammps PRIVATE -DLMP_INTEL_USELRT -DLMP_INTEL_LRT11)
+  if(Threads_FOUND)
+    target_compile_definitions(lammps PRIVATE -DLMP_INTEL_USELRT -DLMP_INTEL_LRT11)
+    target_link_libraries(lammps PRIVATE Threads::Threads)
+  else()
+    message(FATAL_ERROR "Must have working threads library for Long-range thread support")
+  endif()
 endif()
 
 if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")

cmake/Modules/Packages/USER-MOLFILE.cmake

@@ -2,8 +2,4 @@ set(MOLFILE_INCLUDE_DIR "${LAMMPS_LIB_SOURCE_DIR}/molfile" CACHE STRING "Path to
 set(MOLFILE_INCLUDE_DIRS "${MOLFILE_INCLUDE_DIR}")
 add_library(molfile INTERFACE)
 target_include_directories(molfile INTERFACE ${MOLFILE_INCLUDE_DIRS})
-# no need to link with -ldl on windows
-if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
-  target_link_libraries(molfile INTERFACE ${CMAKE_DL_LIBS})
-endif()
 target_link_libraries(lammps PRIVATE molfile)

cmake/Modules/Packages/USER-PLUMED.cmake

@@ -53,10 +53,16 @@ if(DOWNLOAD_PLUMED)
   elseif(PLUMED_MODE STREQUAL "RUNTIME")
     set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/libplumedWrapper.a")
   endif()
+
+  set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.7.0/plumed-src-2.7.0.tgz" CACHE STRING "URL for PLUMED tarball")
+  set(PLUMED_MD5 "95f29dd0c067577f11972ff90dfc7d12" CACHE STRING "MD5 checksum of PLUMED tarball")
+  mark_as_advanced(PLUMED_URL)
+  mark_as_advanced(PLUMED_MD5)
+
   include(ExternalProject)
   ExternalProject_Add(plumed_build
-    URL https://github.com/plumed/plumed2/releases/download/v2.7.0/plumed-src-2.7.0.tgz
+    URL     ${PLUMED_URL}
-    URL_MD5 95f29dd0c067577f11972ff90dfc7d12
+    URL_MD5 ${PLUMED_MD5}
     BUILD_IN_SOURCE 1
     CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR>
                                              ${CONFIGURE_REQUEST_PIC}

cmake/Modules/Packages/USER-SCAFACOS.cmake

@@ -14,15 +14,19 @@ 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")
+  set(SCAFACOS_URL "https://github.com/scafacos/scafacos/releases/download/v1.0.1/scafacos-1.0.1.tar.gz" CACHE STRING "URL for SCAFACOS tarball")
+  set(SCAFACOS_MD5 "bd46d74e3296bd8a444d731bb10c1738" CACHE STRING "MD5 checksum of SCAFACOS tarball")
+  mark_as_advanced(SCAFACOS_URL)
+  mark_as_advanced(SCAFACOS_MD5)
 
   # 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
+  file(DOWNLOAD ${LAMMPS_THIRDPARTY_URL}/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     ${SCAFACOS_URL}
-    URL_MD5 bd46d74e3296bd8a444d731bb10c1738
+    URL_MD5 ${SCAFACOS_MD5}
     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

cmake/Modules/Packages/USER-SMD.cmake

@@ -7,10 +7,14 @@ endif()
 option(DOWNLOAD_EIGEN3 "Download Eigen3 instead of using an already installed one)" ${DOWNLOAD_EIGEN3_DEFAULT})
 if(DOWNLOAD_EIGEN3)
   message(STATUS "Eigen3 download requested - we will build our own")
+  set(EIGEN3_URL "https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.tar.gz" CACHE STRING "URL for Eigen3 tarball")
+  set(EIGEN3_MD5 "9e30f67e8531477de4117506fe44669b" CACHE STRING "MD5 checksum of Eigen3 tarball")
+  mark_as_advanced(EIGEN3_URL)
+  mark_as_advanced(EIGEN3_MD5)
   include(ExternalProject)
   ExternalProject_Add(Eigen3_build
-    URL https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.tar.gz
+    URL     ${EIGEN3_URL}
-    URL_MD5 9e30f67e8531477de4117506fe44669b
+    URL_MD5 ${EIGEN3_MD5}
     CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
   )
   ExternalProject_get_property(Eigen3_build SOURCE_DIR)

cmake/Modules/Packages/VORONOI.cmake

@@ -7,6 +7,11 @@ endif()
 option(DOWNLOAD_VORO "Download and compile the Voro++ library instead of using an already installed one" ${DOWNLOAD_VORO_DEFAULT})
 if(DOWNLOAD_VORO)
   message(STATUS "Voro++ download requested - we will build our own")
+  set(VORO_URL "${LAMMPS_THIRDPARTY_URL}/voro++-0.4.6.tar.gz" CACHE STRING "URL for Voro++ tarball")
+  set(VORO_MD5 "2338b824c3b7b25590e18e8df5d68af9" CACHE STRING "MD5 checksum for Voro++ tarball")
+  mark_as_advanced(VORO_URL)
+  mark_as_advanced(VORO_MD5)
+
   include(ExternalProject)
 
   if(BUILD_SHARED_LIBS)
@@ -22,8 +27,8 @@ if(DOWNLOAD_VORO)
   endif()
 
   ExternalProject_Add(voro_build
-    URL https://download.lammps.org/thirdparty/voro++-0.4.6.tar.gz
+    URL     ${VORO_URL}
-    URL_MD5 2338b824c3b7b25590e18e8df5d68af9
+    URL_MD5 ${VORO_MD5}
     PATCH_COMMAND patch -b -p0 < ${LAMMPS_LIB_SOURCE_DIR}/voronoi/voro-make.patch
     CONFIGURE_COMMAND ""
     BUILD_COMMAND make ${VORO_BUILD_OPTIONS}

cmake/Modules/YAML.cmake

@@ -2,17 +2,20 @@ message(STATUS "Downloading and building YAML library")
 
 include(ExternalProject)
 set(YAML_URL "https://pyyaml.org/download/libyaml/yaml-0.2.5.tar.gz" CACHE STRING "URL for libyaml tarball")
+set(YAML_MD5 "bb15429d8fb787e7d3f1c83ae129a999" CACHE STRING "MD5 checksum of libyaml tarball")
 mark_as_advanced(YAML_URL)
+mark_as_advanced(YAML_MD5)
+
 ExternalProject_Add(libyaml
                     URL               ${YAML_URL}
-                    URL_MD5           bb15429d8fb787e7d3f1c83ae129a999
+                    URL_MD5           ${YAML_MD5}
                     SOURCE_DIR        "${CMAKE_BINARY_DIR}/yaml-src"
                     BINARY_DIR        "${CMAKE_BINARY_DIR}/yaml-build"
                     CONFIGURE_COMMAND <SOURCE_DIR>/configure ${CONFIGURE_REQUEST_PIC}
                                       CXX=${CMAKE_CXX_COMPILER}
                                       CC=${CMAKE_C_COMPILER}
                                       --prefix=<INSTALL_DIR> --disable-shared
-                    BUILD_BYPRODUCTS  <INSTALL_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}yaml.a
+                    BUILD_BYPRODUCTS  <INSTALL_DIR>/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX}
                     TEST_COMMAND      "")
 
 ExternalProject_Get_Property(libyaml INSTALL_DIR)
@@ -23,7 +26,7 @@ set(YAML_LIBRARY_DIR ${INSTALL_DIR}/lib)
 file(MAKE_DIRECTORY ${YAML_INCLUDE_DIR})
 file(MAKE_DIRECTORY ${YAML_LIBRARY_DIR})
 
-set(YAML_LIBRARY_PATH ${INSTALL_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}yaml.a)
+set(YAML_LIBRARY_PATH ${INSTALL_DIR}/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX})
 
 add_library(Yaml::Yaml UNKNOWN IMPORTED)
 set_target_properties(Yaml::Yaml PROPERTIES

cmake/presets/most.cmake

@@ -4,7 +4,7 @@
 
 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
+        PLUGIN 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
         USER-MISC USER-MOFFF USER-OMP USER-PHONON USER-REACTION

cmake/presets/oneapi.cmake

@@ -0,0 +1,18 @@
+# preset that will enable the LLVM based Intel compilers with support for MPI and OpenMP (on Linux boxes)
+
+set(CMAKE_CXX_COMPILER "icpx" CACHE STRING "" FORCE)
+set(CMAKE_C_COMPILER "icx" CACHE STRING "" FORCE)
+set(CMAKE_Fortran_COMPILER "ifx" CACHE STRING "" FORCE)
+set(MPI_CXX "icpx" CACHE STRING "" FORCE)
+set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
+unset(HAVE_OMP_H_INCLUDE CACHE)
+
+set(OpenMP_C "icx" CACHE STRING "" FORCE)
+set(OpenMP_C_FLAGS "-qopenmp" CACHE STRING "" FORCE)
+set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
+set(OpenMP_CXX "icpx" CACHE STRING "" FORCE)
+set(OpenMP_CXX_FLAGS "-qopenmp" CACHE STRING "" FORCE)
+set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
+set(OpenMP_Fortran_FLAGS "-qopenmp" CACHE STRING "" FORCE)
+set(OpenMP_omp_LIBRARY "libiomp5.so" CACHE PATH "" FORCE)
+

doc/Makefile

@@ -47,6 +47,8 @@ HAS_PDFLATEX = YES
 endif
 endif
 
+# override settings for PIP commands
+# PIP_OPTIONS = --cert /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt --proxy http://proxy.mydomain.org
 
 #SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E")
 
@@ -228,13 +230,13 @@ $(VENV):
 	@( \
 		$(VIRTUALENV) -p $(PYTHON) $(VENV); \
 		. $(VENV)/bin/activate; \
-		pip install --upgrade pip; \
+		pip $(PIP_OPTIONS) install --upgrade pip; \
-		pip install -r $(BUILDDIR)/utils/requirements.txt; \
+		pip $(PIP_OPTIONS) install -r $(BUILDDIR)/utils/requirements.txt; \
 		deactivate;\
 	)
 
 $(MATHJAX):
-	@git clone --depth 1 https://github.com/mathjax/MathJax.git $@
+	@git clone --depth 1 git://github.com/mathjax/MathJax.git $@
 
 $(TXT2RST) $(ANCHORCHECK): $(VENV)
 	@( \

doc/lammps.1

@@ -1,4 +1,4 @@
-.TH LAMMPS "10 February 2021" "2021-02-10"
+.TH LAMMPS "8 April 2021" "2021-04-08"
 .SH NAME
 .B LAMMPS
 \- Molecular Dynamics Simulator.

doc/src/Build_basics.rst

@@ -1,7 +1,7 @@
 Basic build options
 ===================
 
-The following topics are covered on this page, for building both with
+The following topics are covered on this page, for building with both
 CMake and make:
 
 * :ref:`Serial vs parallel build <serial>`
@@ -95,7 +95,7 @@ standard. A more detailed discussion of that is below.
 
       .. note::
 
-         The file ``src/STUBS/mpi.c`` provides a CPU timer function
+         The file ``src/STUBS/mpi.cpp`` provides a CPU timer function
          called ``MPI_Wtime()`` that calls ``gettimeofday()``.  If your
          operating system does not support ``gettimeofday()``, you will
          need to insert code to call another timer.  Note that the
@@ -234,6 +234,8 @@ LAMMPS.
          cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
          # Building with Intel Compilers:
          cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
+         # Building with Intel oneAPI Compilers:
+         cmake ../cmake -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx -DCMAKE_Fortran_COMPILER=ifx
          # Building with LLVM/Clang Compilers:
          cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
          # Building with PGI/Nvidia Compilers:
@@ -243,8 +245,10 @@ LAMMPS.
       provided that can be loaded with
       `-C ../cmake/presets/clang.cmake`.  Similarly,
       `-C ../cmake/presets/intel.cmake` should switch the compiler
-      toolchain to the Intel compilers and `-C ../cmake/presets/pgi.cmake`
+      toolchain to the legacy Intel compilers, `-C ../cmake/presets/oneapi.cmake`
-      should switch the compiler to the PGI compilers.
+      will switch to the LLVM based oneAPI Intel compilers,
+      and `-C ../cmake/presets/pgi.cmake`
+      will switch the compiler to the PGI compilers.
 
       In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
       compiler flags to tune for optimal performance on given hosts. By
@@ -526,6 +530,20 @@ you want to copy files to is protected.
          make                        # perform make after CMake command
          make install                # perform the installation into prefix
 
+      During the installation process CMake will by default remove any runtime
+      path settings for loading shared libraries.  Because of this you may
+      have to set or modify the ``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH``)
+      environment variable, if you are installing LAMMPS into a non-system
+      location and/or are linking to libraries in a non-system location that
+      depend on such runtime path settings.
+      As an alternative you may set the CMake variable ``LAMMPS_INSTALL_RPATH``
+      to ``on`` and then the runtime paths for any linked shared libraries
+      and the library installation folder for the LAMMPS library will be
+      embedded and thus the requirement to set environment variables is avoided.
+      The ``off`` setting is usually preferred for packaged binaries or when
+      setting up environment modules, the ``on`` setting is more convenient
+      for installing software into a non-system or personal folder.
+
    .. tab:: Traditional make
 
       There is no "install" option in the ``src/Makefile`` for LAMMPS.

doc/src/Build_extras.rst

@@ -120,21 +120,21 @@ CMake build
    -D GPU_API=value             # value = opencl (default) or cuda or hip
    -D GPU_PREC=value            # precision setting
                                 # value = double or mixed (default) or single
-   -D OCL_TUNE=value            # hardware choice for GPU_API=opencl
-                                # 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_50
    -D HIP_ARCH=value            # primary GPU hardware choice for GPU_API=hip
                                 # value depends on selected HIP_PLATFORM
-                                # default is 'gfx906' for HIP_PLATFORM=hcc and 'sm_50' for HIP_PLATFORM=nvcc
+                                # default is 'gfx906' for HIP_PLATFORM=amd and 'sm_50' for HIP_PLATFORM=nvcc
    -D HIP_USE_DEVICE_SORT=value # enables GPU sorting
                                 # value = yes (default) or no
-   -D CUDPP_OPT=value           # optimization setting for GPU_API=cuda
+   -D CUDPP_OPT=value           # use GPU binning on with CUDA (should be off for modern GPUs)
-                                # enables CUDA Performance Primitives Optimizations, must be "no" for CUDA_MPS_SUPPORT=yes
+                                # enables CUDA Performance Primitives, must be "no" for CUDA_MPS_SUPPORT=yes
-                                # value = yes (default) or no
+                                # value = yes or no (default)
    -D CUDA_MPS_SUPPORT=value    # enables some tweaks required to run with active nvidia-cuda-mps daemon
                                 # value = yes or no (default)
+   -D USE_STATIC_OPENCL_LOADER=value  # downloads/includes OpenCL ICD loader library, no local OpenCL headers/libs needed
+                                      # value = yes (default) or no
 
 :code:`GPU_ARCH` settings for different GPU hardware is as follows:
 
@@ -161,19 +161,32 @@ When building with CMake, you **must NOT** build the GPU library in ``lib/gpu``
 using the traditional build procedure. CMake will detect files generated by that
 process and will terminate with an error and a suggestion for how to remove them.
 
+If you are compiling for OpenCL, the default setting is to download, build, and
+link with a static OpenCL ICD loader library and standard OpenCL headers.  This
+way no local OpenCL development headers or library needs to be present and only
+OpenCL compatible drivers need to be installed to use OpenCL.  If this is not
+desired, you can set :code:`USE_STATIC_OPENCL_LOADER` to :code:`no`.
+
 If you are compiling with HIP, note that before running CMake you will have to
 set appropriate environment variables. Some variables such as
-:code:`HCC_AMDGPU_TARGET` or :code:`CUDA_PATH` are necessary for :code:`hipcc`
+:code:`HCC_AMDGPU_TARGET` (for ROCm <= 4.0) or :code:`CUDA_PATH` are necessary for :code:`hipcc`
 and the linker to work correctly.
 
 .. code:: bash
 
-   # AMDGPU target
+   # AMDGPU target (ROCm <= 4.0)
    export HIP_PLATFORM=hcc
    export HCC_AMDGPU_TARGET=gfx906
    cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
    make -j 4
 
+.. code:: bash
+
+   # AMDGPU target (ROCm >= 4.1)
+   export HIP_PLATFORM=amd
+   cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=gfx906 -D CMAKE_CXX_COMPILER=hipcc ..
+   make -j 4
+
 .. code:: bash
 
    # CUDA target (not recommended, use GPU_ARCH=cuda)
@@ -224,11 +237,12 @@ GPU architectures as supported by the CUDA toolkit in use. This is done
 through using the "--gencode " flag, which can be used multiple times and
 thus support all GPU architectures supported by your CUDA compiler.
 
-To include CUDA performance primitives set the Makefile variable
+To enable GPU binning via CUDA performance primitives set the Makefile variable
-``CUDPP_OPT = -DUSE_CUDPP -Icudpp_mini``.
+``CUDPP_OPT = -DUSE_CUDPP -Icudpp_mini``.  This should **not** be used with
+most modern GPUs.
 
 To support the CUDA multiprocessor server you can set the define
-``-DCUDA_PROXY``.  Please note that in this case you should **not** use
+``-DCUDA_PROXY``.  Please note that in this case you must **not** use
 the CUDA performance primitives and thus set the variable ``CUDPP_OPT``
 to empty.
 
@@ -258,18 +272,18 @@ To build with this package, the KIM library with API v2 must be downloaded
 and built on your system. It must include the KIM models that you want to
 use with LAMMPS.
 
-If you would like to use the :doc:`kim_query <kim_commands>`
+If you would like to use the :doc:`kim query <kim_commands>`
 command, you also need to have libcurl installed with the matching
 development headers and the curl-config tool.
 
-If you would like to use the :doc:`kim_property <kim_commands>`
+If you would like to use the :doc:`kim property <kim_commands>`
 command, you need to build LAMMPS with the PYTHON package installed
 and linked to Python 3.6 or later. See the :ref:`PYTHON package build info <python>`
 for more details on this. After successfully building LAMMPS with Python, you
-also need to install the kim-property Python package, which can be easily done using
+also need to install the ``kim-property`` Python package, which can be easily
-*pip* as ``pip install kim-property``, or from the *conda-forge* channel as
+done using *pip* as ``pip install kim-property``, or from the *conda-forge*
-``conda install kim-property`` if LAMMPS is built in Conda. More detailed
+channel as ``conda install kim-property`` if LAMMPS is built in Conda. More
-information is available at:
+detailed information is available at:
 `kim-property installation <https://github.com/openkim/kim-property#installing-kim-property>`_.
 
 In addition to installing the KIM API, it is also necessary to install the
@@ -309,7 +323,7 @@ minutes to hours) to build.  Of course you only need to do that once.)
 
       You can download and build the KIM library manually if you prefer;
       follow the instructions in ``lib/kim/README``.  You can also do
-      this in one step from the lammps/src dir, using a command like
+      this in one step from the lammps/src directory, using a command like
       these, which simply invoke the ``lib/kim/Install.py`` script with
       the specified args.
 
@@ -329,7 +343,7 @@ minutes to hours) to build.  Of course you only need to do that once.)
 
       .. code-block:: make
 
-         LMP_INC =       -DLMP_NO_SSL_CHECK
+         LMP_INC = -DLMP_NO_SSL_CHECK
 
 Debugging OpenKIM web queries in LAMMPS
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -377,10 +391,11 @@ Enabling the extra unit tests have some requirements,
   Conda. More detailed information is available at:
   `kim-property installation <https://github.com/openkim/kim-property#installing-kim-property>`_.
 * It is also necessary to install
-  ``EAM_Dynamo_Mendelev_2007_Zr__MO_848899341753_000``, and
+  ``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000``,
-  ``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005`` KIM models.
+  ``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005``, and
+  ``LennardJones612_UniversalShifted__MO_959249795837_003`` KIM models.
   See `Obtaining KIM Models <http://openkim.org/doc/usage/obtaining-models>`_
-  to learn how to install a pre-build binary of the OpenKIM Repository of
+  to learn how to install a pre-built binary of the OpenKIM Repository of
   Models or see
   `Installing KIM Models <https://openkim.org/doc/usage/obtaining-models/#installing_models>`_
   to learn how to install the specific KIM models.

doc/src/Build_link.rst

@@ -20,16 +20,8 @@ the suffix ``.so.0`` (or some other number).
 .. note::
 
    Care should be taken to use the same MPI library for the calling code
-   and the LAMMPS library.  The ``library.h`` file includes ``mpi.h``
+   and the LAMMPS library unless LAMMPS is to be compiled without (real)
-   and uses definitions from it so those need to be available and
+   MPI support using the include STUBS MPI library.
-   consistent.  When LAMMPS is compiled with the included STUBS MPI
-   library, then its ``mpi.h`` file needs to be included.  While it is
-   technically possible to use a full MPI library in the calling code
-   and link to a serial LAMMPS library compiled with MPI STUBS, it is
-   recommended to use the *same* MPI library for both, and then use
-   ``MPI_Comm_split()`` in the calling code to pass a suitable
-   communicator with a subset of MPI ranks to the function creating the
-   LAMMPS instance.
 
 Link with LAMMPS as a static library
 ------------------------------------
@@ -110,7 +102,7 @@ executable, that are also required to link the LAMMPS executable.
 
       .. code-block:: bash
 
-         gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
+         gcc -c -O -I${HOME}/lammps/src -caller.c
          g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
                       -L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src \
                       -llammps_serial -lpoems -lmpi_stubs
@@ -174,7 +166,7 @@ the POEMS package installed becomes:
 
       .. code-block:: bash
 
-         gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
+         gcc -c -O -I${HOME}/lammps/src -caller.c
          g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
 
 Locating liblammps.so at runtime

doc/src/Build_manual.rst

@@ -74,7 +74,11 @@ For the documentation build a python virtual environment is set up in
 the folder ``doc/docenv`` and various python packages are installed into
 that virtual environment via the ``pip`` tool.  For rendering embedded
 LaTeX code also the `MathJax <https://www.mathjax.org/>`_ JavaScript
-engine needs to be downloaded.
+engine needs to be downloaded.  If you need to pass additional options
+to the pip commands to work (e.g. to use a web proxy or to point to
+additional SSL certificates) you can set them via the ``PIP_OPTIONS``
+environment variable or uncomment and edit the ``PIP_OPTIONS`` setting
+at beginning of the makefile.
 
 The actual translation is then done via ``make`` commands in the doc
 folder.  The following ``make`` commands are available:
@@ -108,7 +112,10 @@ installation of the HTML manual pages into the "install" step when
 installing LAMMPS after the CMake build via ``cmake --build . --target
 install``.  The documentation build is included in the default build
 target, but can also be requested independently with
-``cmake --build . --target doc``.
+``cmake --build . --target doc``.  If you need to pass additional options
+to the pip commands to work (e.g. to use a web proxy or to point to
+additional SSL certificates) you can set them via the ``PIP_OPTIONS``
+environment variable.
 
 .. code-block:: bash
 

doc/src/Commands_all.rst

@@ -60,11 +60,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`include <include>`
    * :doc:`info <info>`
    * :doc:`jump <jump>`
-   * :doc:`kim_init <kim_commands>`
+   * :doc:`kim <kim_commands>`
-   * :doc:`kim_interactions <kim_commands>`
-   * :doc:`kim_param <kim_commands>`
-   * :doc:`kim_property <kim_commands>`
-   * :doc:`kim_query <kim_commands>`
    * :doc:`kspace_modify <kspace_modify>`
    * :doc:`kspace_style <kspace_style>`
    * :doc:`label <label>`
@@ -90,6 +86,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`pair_style <pair_style>`
    * :doc:`pair_write <pair_write>`
    * :doc:`partition <partition>`
+   * :doc:`plugin <plugin>`
    * :doc:`prd <prd>`
    * :doc:`print <print>`
    * :doc:`processors <processors>`

doc/src/Commands_bond.rst

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

doc/src/Commands_fix.rst

@@ -114,7 +114,7 @@ OPT.
    * :doc:`nph/eff <fix_nh_eff>`
    * :doc:`nph/sphere (o) <fix_nph_sphere>`
    * :doc:`nphug <fix_nphug>`
-   * :doc:`npt (iko) <fix_nh>`
+   * :doc:`npt (giko) <fix_nh>`
    * :doc:`npt/asphere (o) <fix_npt_asphere>`
    * :doc:`npt/body <fix_npt_body>`
    * :doc:`npt/cauchy <fix_npt_cauchy>`
@@ -122,8 +122,8 @@ OPT.
    * :doc:`npt/sphere (o) <fix_npt_sphere>`
    * :doc:`npt/uef <fix_nh_uef>`
    * :doc:`numdiff <fix_numdiff>`
-   * :doc:`nve (iko) <fix_nve>`
+   * :doc:`nve (giko) <fix_nve>`
-   * :doc:`nve/asphere (i) <fix_nve_asphere>`
+   * :doc:`nve/asphere (gi) <fix_nve_asphere>`
    * :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>`
    * :doc:`nve/awpmd <fix_nve_awpmd>`
    * :doc:`nve/body <fix_nve_body>`
@@ -138,7 +138,7 @@ OPT.
    * :doc:`nve/spin <fix_nve_spin>`
    * :doc:`nve/tri <fix_nve_tri>`
    * :doc:`nvk <fix_nvk>`
-   * :doc:`nvt (iko) <fix_nh>`
+   * :doc:`nvt (giko) <fix_nh>`
    * :doc:`nvt/asphere (o) <fix_nvt_asphere>`
    * :doc:`nvt/body <fix_nvt_body>`
    * :doc:`nvt/eff <fix_nh_eff>`

doc/src/Commands_pair.rst

@@ -122,7 +122,7 @@ OPT.
    * :doc:`lebedeva/z <pair_lebedeva_z>`
    * :doc:`lennard/mdf <pair_mdf>`
    * :doc:`line/lj <pair_line_lj>`
-   * :doc:`lj/charmm/coul/charmm (iko) <pair_charmm>`
+   * :doc:`lj/charmm/coul/charmm (giko) <pair_charmm>`
    * :doc:`lj/charmm/coul/charmm/implicit (ko) <pair_charmm>`
    * :doc:`lj/charmm/coul/long (gikot) <pair_charmm>`
    * :doc:`lj/charmm/coul/long/soft (o) <pair_fep_soft>`
@@ -163,6 +163,7 @@ OPT.
    * :doc:`lj/long/dipole/long <pair_dipole>`
    * :doc:`lj/long/tip4p/long (o) <pair_lj_long>`
    * :doc:`lj/mdf <pair_mdf>`
+   * :doc:`lj/relres (o) <pair_lj_relres>`
    * :doc:`lj/sdk (gko) <pair_sdk>`
    * :doc:`lj/sdk/coul/long (go) <pair_sdk>`
    * :doc:`lj/sdk/coul/msm (o) <pair_sdk>`
@@ -186,7 +187,7 @@ OPT.
    * :doc:`mgpt <pair_mgpt>`
    * :doc:`mie/cut (g) <pair_mie>`
    * :doc:`mliap <pair_mliap>`
-   * :doc:`mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>`
+   * :doc:`mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
    * :doc:`momb <pair_momb>`
    * :doc:`morse (gkot) <pair_morse>`
    * :doc:`morse/smooth/linear (o) <pair_morse>`

doc/src/Developer.rst

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

doc/src/Developer_plugins.rst

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

doc/src/Developer_unittest.rst

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

doc/src/Developer_utils.rst

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

doc/src/Howto_bioFF.rst

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

doc/src/Howto_cmake.rst

@@ -296,6 +296,8 @@ Some common CMake variables
      - Description
    * - ``CMAKE_INSTALL_PREFIX``
      - root directory of install location for ``make install``  (default: ``$HOME/.local``)
+   * - ``LAMMPS_INSTALL_RPATH``
+     - set or remove runtime path setting from binaries for ``make install`` (default: ``off``)
    * - ``CMAKE_BUILD_TYPE``
      - controls compilation options:
        one of ``RelWithDebInfo`` (default), ``Release``, ``Debug``, ``MinSizeRel``
@@ -409,10 +411,10 @@ interface (``ccmake`` or ``cmake-gui``).
 .. note::
 
    Using a preset to select a compiler package (``clang.cmake``,
-   ``gcc.cmake``, or ``intel.cmake``) are an exception to the option
+   ``gcc.cmake``, ``intel.cmake``, ``oneapi.cmake``, or ``pgi.cmake``)
-   of updating the configuration incrementally, as they will trigger
+   are an exception to the mechanism of updating the configuration incrementally,
-   a reset of cached internal CMake settings and thus reset them to
+   as they will trigger a reset of cached internal CMake settings and thus
-   their default values.
+   reset settings to their default values.
 
 Compilation and build targets
 -----------------------------

doc/src/Howto_granular.rst

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

doc/src/Install_git.rst

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

doc/src/Install_patch.rst

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

doc/src/Install_tarball.rst

@@ -33,22 +33,19 @@ in its name, e.g. lammps-23Jun18.
 
 ----------
 
-You can also download a zip file via the "Clone or download" button on
+You can also download a compressed tar or zip archives from the
-the `LAMMPS GitHub site <git_>`_.  The file name will be lammps-master.zip
+"Assets" sections of the `LAMMPS GitHub releases site <git_>`_.
-which can be unzipped with the following command, to create
+The file name will be lammps-<version>.zip which can be unzipped
-a lammps-master dir:
+with the following command, to create a lammps-<version> dir:
 
 .. code-block:: bash
 
    $ unzip lammps*.zip
 
-This version is the most up-to-date LAMMPS development version.  It
+This version corresponds to the selected LAMMPS patch or stable
-will have the date of the most recent patch release (see the file
+release.
-src/version.h).  But it will also include any new bug-fixes or
-features added since the last patch release.  They will be included in
-the next patch release tarball.
 
-.. _git: https://github.com/lammps/lammps
+.. _git: https://github.com/lammps/lammps/releases
 
 ----------
 

doc/src/Intro_features.rst

@@ -85,7 +85,7 @@ commands)
 * water potentials: TIP3P, TIP4P, SPC
 * implicit solvent potentials: hydrodynamic lubrication, Debye
 * force-field compatibility with common CHARMM, AMBER, DREIDING,     OPLS, GROMACS, COMPASS options
-* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via     :doc:`kim_init, kim_interactions, and kim_query <kim_commands>` commands
+* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via     :doc:`kim command <kim_commands>`
 * hybrid potentials: multiple pair, bond, angle, dihedral, improper     potentials can be used in one simulation
 * overlaid potentials: superposition of multiple pair potentials
 

doc/src/Library_scatter.rst

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

doc/src/Packages_details.rst

@@ -50,6 +50,7 @@ page gives those details.
    * :ref:`MSCG <PKG-MSCG>`
    * :ref:`OPT <PKG-OPT>`
    * :ref:`PERI <PKG-PERI>`
+   * :ref:`PLUGIN <PKG-PLUGIN>`
    * :ref:`POEMS <PKG-POEMS>`
    * :ref:`PYTHON <PKG-PYTHON>`
    * :ref:`QEQ <PKG-QEQ>`
@@ -367,17 +368,19 @@ KIM package
 
 **Contents:**
 
-This package contains a set of commands that serve as a wrapper on the
+This package contains a command with a set of sub-commands that serve as a
+wrapper on the
 `Open Knowledgebase of Interatomic Models (OpenKIM) <https://openkim.org>`_
 repository of interatomic models (IMs) enabling compatible ones to be used in
 LAMMPS simulations.
 
-This includes :doc:`kim_init <kim_commands>`, and
+
-:doc:`kim_interactions <kim_commands>` commands to select, initialize and
+This includes :doc:`kim init <kim_commands>`, and
-instantiate the IM, a :doc:`kim_query <kim_commands>` command to perform web
+:doc:`kim interactions <kim_commands>` commands to select, initialize and
+instantiate the IM, a :doc:`kim query <kim_commands>` command to perform web
 queries for material property predictions of OpenKIM IMs, a
-:doc:`kim_param <kim_commands>` command to access KIM Model Parameters from
+:doc:`kim param <kim_commands>` command to access KIM Model Parameters from
-LAMMPS, and a :doc:`kim_property <kim_commands>` command to write material
+LAMMPS, and a :doc:`kim property <kim_commands>` command to write material
 properties computed in LAMMPS to standard KIM property instance format.
 
 Support for KIM IMs that conform to the
@@ -386,8 +389,8 @@ is provided by the :doc:`pair_style kim <pair_kim>` command.
 
 .. note::
 
-   The command *pair_style kim* is called by *kim_interactions* and
+   The command *pair_style kim* is called by *kim interactions* and is not
-   is not recommended to be directly used in input scripts.
+   recommended to be directly used in input scripts.
 
 To use this package you must have the KIM API library available on your
 system. The KIM API is available for download on the
@@ -404,7 +407,7 @@ and is funded by the `National Science Foundation <https://www.nsf.gov/>`_.
 API and the *pair_style kim* command. Yaser Afshar (U Minnesota),
 Axel Kohlmeyer (Temple U), Ellad Tadmor (U Minnesota), and
 Daniel Karls (U Minnesota) contributed to the
-:doc:`kim_commands <kim_commands>` interface in close collaboration with
+:doc:`kim command <kim_commands>` interface in close collaboration with
 Ryan Elliott.
 
 **Install:**
@@ -414,7 +417,7 @@ This package has :ref:`specific installation instructions <kim>` on the
 
 **Supporting info:**
 
-* :doc:`kim_commands <kim_commands>`
+* :doc:`kim command <kim_commands>`
 * :doc:`pair_style kim <pair_kim>`
 * src/KIM: filenames -> commands
 * src/KIM/README
@@ -841,6 +844,28 @@ Foster (UTSA).
 
 ----------
 
+.. _PKG-PLUGIN:
+
+PLUGIN package
+--------------
+
+**Contents:**
+
+A :doc:`plugin <plugin>` command that can load and unload several
+kind of styles in LAMMPS from shared object files at runtime without
+having to recompile and relink LAMMPS.
+
+**Authors:** Axel Kohlmeyer (Temple U)
+
+**Supporting info:**
+
+* src/PLUGIN: filenames -> commands
+* :doc:`plugin command <plugin>`
+* :doc:`Information on writing plugins <Developer_plugins>`
+* examples/plugin
+
+----------
+
 .. _PKG-POEMS:
 
 POEMS package
@@ -1430,8 +1455,8 @@ oscillators as a model of polarization.  See the :doc:`Howto drude <Howto_drude>
 for an overview of how to use the package.  There are auxiliary tools
 for using this package in tools/drude.
 
-**Authors:** Alain Dequidt (U Blaise Pascal Clermont-Ferrand), Julien
+**Authors:** Alain Dequidt (U Clermont Auvergne), Julien
-Devemy (CNRS), and Agilio Padua (U Blaise Pascal).
+Devemy (CNRS), and Agilio Padua (ENS de Lyon).
 
 **Supporting info:**
 
@@ -1498,7 +1523,7 @@ methods for performing FEP simulations by using a :doc:`fix adapt/fep <fix_adapt
 which have a "soft" in their style name.  There are auxiliary tools
 for using this package in tools/fep; see its README file.
 
-**Author:** Agilio Padua (Universite Blaise Pascal Clermont-Ferrand)
+**Author:** Agilio Padua (ENS de Lyon)
 
 **Supporting info:**
 
@@ -2454,6 +2479,6 @@ which discuss the `QuickFF <quickff_>`_ methodology.
 * :doc:`bond_style mm3 <bond_mm3>`
 * :doc:`improper_style distharm <improper_distharm>`
 * :doc:`improper_style sqdistharm <improper_sqdistharm>`
-* :doc:`pair_style mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>`
+* :doc:`pair_style mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
 * :doc:`pair_style lj/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
 * examples/USER/yaff

doc/src/Packages_standard.rst

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

doc/src/Python_atoms.rst

@@ -50,7 +50,7 @@ against invalid accesses.
 
       **Numpy Methods**:
 
-      * :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
+      * :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
 
    .. tab:: PyLammps/IPyLammps API
 

doc/src/Python_formats.rst

@@ -0,0 +1,11 @@
+Output Readers
+==============
+
+.. py:module:: lammps.formats
+
+The Python package contains the :py:mod:`lammps.formats` module, which
+provides classes to post-process some of the output files generated by LAMMPS.
+
+.. automodule:: lammps.formats
+   :members:
+   :noindex:

doc/src/Python_head.rst

@@ -13,6 +13,7 @@ together.
    Python_module
    Python_ext
    Python_call
+   Python_formats
    Python_examples
    Python_error
    Python_trouble

doc/src/Python_module.rst

@@ -61,7 +61,7 @@ functions. Below is a detailed documentation of the API.
 .. autoclass:: lammps.lammps
    :members:
 
-.. autoclass:: lammps.numpy::numpy_wrapper
+.. autoclass:: lammps.numpy_wrapper::numpy_wrapper
    :members:
 
 ----------
@@ -134,23 +134,23 @@ Style Constants
    to request from computes or fixes. See :cpp:enum:`_LMP_STYLE_CONST`
    for the equivalent constants in the C library interface. Used in
    :py:func:`lammps.extract_compute`, :py:func:`lammps.extract_fix`, and their NumPy variants
-   :py:func:`lammps.numpy.extract_compute() <lammps.numpy.numpy_wrapper.extract_compute>` and
+   :py:func:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute>` and
-   :py:func:`lammps.numpy.extract_fix() <lammps.numpy.numpy_wrapper.extract_fix>`.
+   :py:func:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix>`.
 
 .. _py_type_constants:
 
 Type Constants
 --------------
 
-.. py:data:: LMP_TYPE_SCALAR, LMP_TYLE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
+.. py:data:: LMP_TYPE_SCALAR, LMP_TYPE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
    :type: int
 
    Constants in the :py:mod:`lammps` module to select what type of data
    to request  from computes  or fixes.  See :cpp:enum:`_LMP_TYPE_CONST`
    for the equivalent constants in the C library interface. Used in
    :py:func:`lammps.extract_compute`, :py:func:`lammps.extract_fix`, and their NumPy variants
-   :py:func:`lammps.numpy.extract_compute() <lammps.numpy.numpy_wrapper.extract_compute>` and
+   :py:func:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute>` and
-   :py:func:`lammps.numpy.extract_fix() <lammps.numpy.numpy_wrapper.extract_fix>`.
+   :py:func:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix>`.
 
 .. _py_vartype_constants:
 
@@ -170,6 +170,6 @@ Classes representing internal objects
    :members:
    :no-undoc-members:
 
-.. autoclass:: lammps.numpy::NumPyNeighList
+.. autoclass:: lammps.numpy_wrapper::NumPyNeighList
    :members:
    :no-undoc-members:

doc/src/Python_neighbor.rst

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

doc/src/Python_objects.rst

@@ -36,9 +36,9 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
       Python subscripting. The values will be zero for atoms not in the
       specified group.
 
-      :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`,
+      :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute()>`,
-      :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`, and
+      :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix()>`, and
-      :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>` are
+      :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.numpy_wrapper.extract_variable()>` are
       equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers.
 
       The :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>` method sets an
@@ -54,9 +54,9 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
 
       **NumPy Methods**:
 
-      * :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
+      * :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
-      * :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
+      * :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
-      * :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
+      * :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
 
 
    .. tab:: PyLammps/IPyLammps API

doc/src/Speed_gpu.rst

@@ -1,11 +1,14 @@
 GPU package
 ===========
 
-The GPU package was developed by Mike Brown while at SNL and ORNL
+The GPU package was developed by Mike Brown while at SNL and ORNL (now
-and his collaborators, particularly Trung Nguyen (now at Northwestern).
+at Intel Corp.) and his collaborators, particularly Trung Nguyen (now at
-It provides GPU versions of many pair styles and for parts of the
+Northwestern).  Support for AMD GPUs via HIP was added by Vsevolod Nikolskiy
-:doc:`kspace_style pppm <kspace_style>` for long-range Coulombics.
+and coworkers at HSE University.
-It has the following general features:
+
+The GPU package provides GPU versions of many pair styles and for
+parts of the :doc:`kspace_style pppm <kspace_style>` for long-range
+Coulombics.  It has the following general features:
 
 * It is designed to exploit common GPU hardware configurations where one
   or more GPUs are coupled to many cores of one or more multi-core CPUs,
@@ -24,8 +27,9 @@ It has the following general features:
   force vectors.
 * LAMMPS-specific code is in the GPU package.  It makes calls to a
   generic GPU library in the lib/gpu directory.  This library provides
-  NVIDIA support as well as more general OpenCL support, so that the
+  either Nvidia support, AMD support, or more general OpenCL support
-  same functionality is supported on a variety of hardware.
+  (for Nvidia GPUs, AMD GPUs, Intel GPUs, and multi-core CPUs).
+  so that the same functionality is supported on a variety of hardware.
 
 **Required hardware/software:**
 
@@ -45,12 +49,23 @@ to have the OpenCL headers and the (vendor neutral) OpenCL library installed.
 In OpenCL mode, the acceleration depends on having an `OpenCL Installable Client Driver (ICD) <https://www.khronos.org/news/permalink/opencl-installable-client-driver-icd-loader>`_
 installed. There can be multiple of them for the same or different hardware
 (GPUs, CPUs, Accelerators) installed at the same time. OpenCL refers to those
-as 'platforms'.  The GPU library will select the **first** suitable platform,
+as 'platforms'.  The GPU library will try to auto-select the best suitable platform,
-but this can be overridden using the device option of the :doc:`package <package>`
+but this can be overridden using the platform 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
+To compile and use this package for Intel GPUs, OpenCL or the Intel oneAPI
+HPC Toolkit can be installed using linux package managers. The latter also
+provides optimized C++, MPI, and many other libraries and tools. See:
+
+* https://software.intel.com/content/www/us/en/develop/tools/oneapi/hpc-toolkit/download.html
+
+If you do not have a discrete GPU card installed, this package can still provide
+significant speedups on some CPUs that include integrated GPUs. Additionally, for
+many macs, OpenCL is already included with the OS and Makefiles are available
+in the lib/gpu directory.
+
+To compile 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.
 
@@ -75,10 +90,20 @@ automatically if you create more MPI tasks/node than there are
 GPUs/mode.  E.g. with 8 MPI tasks/node and 2 GPUs, each GPU will be
 shared by 4 MPI tasks.
 
+The GPU package also has limited support for OpenMP for both
+multi-threading and vectorization of routines that are run on the CPUs.
+This requires that the GPU library and LAMMPS are built with flags to
+enable OpenMP support (e.g. -fopenmp). Some styles for time integration
+are also available in the GPU package. These run completely on the CPUs
+in full double precision, but exploit multi-threading and vectorization
+for faster performance.
+
 Use the "-sf gpu" :doc:`command-line switch <Run_options>`, which will
 automatically append "gpu" to styles that support it.  Use the "-pk
 gpu Ng" :doc:`command-line switch <Run_options>` to set Ng = # of
-GPUs/node to use.
+GPUs/node to use. If Ng is 0, the number is selected automatically as
+the number of matching GPUs that have the highest number of compute
+cores.
 
 .. code-block:: bash
 
@@ -87,8 +112,8 @@ GPUs/node to use.
    mpirun -np 48 -ppn 12 lmp_machine -sf gpu -pk gpu 2 -in in.script   # ditto on 4 16-core nodes
 
 Note that if the "-sf gpu" switch is used, it also issues a default
-:doc:`package gpu 1 <package>` command, which sets the number of
+:doc:`package gpu 0 <package>` command, which will result in
-GPUs/node to 1.
+automatic selection of the number of GPUs to use.
 
 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
@@ -138,6 +163,13 @@ Likewise, you should experiment with the precision setting for the GPU
 library to see if single or mixed precision will give accurate
 results, since they will typically be faster.
 
+MPI parallelism typically outperforms OpenMP parallelism, but in some
+cases using fewer MPI tasks and multiple OpenMP threads with the GPU
+package can give better performance. 3-body potentials can often perform
+better with multiple OMP threads because the inter-process communication
+is higher for these styles with the GPU package in order to allow
+deterministic results.
+
 **Guidelines for best performance:**
 
 * Using multiple MPI tasks per GPU will often give the best performance,
@@ -161,6 +193,12 @@ results, since they will typically be faster.
   :doc:`angle <angle_style>`, :doc:`dihedral <dihedral_style>`,
   :doc:`improper <improper_style>`, and :doc:`long-range <kspace_style>`
   calculations will not be included in the "Pair" time.
+* Since only part of the pppm kspace style is GPU accelerated, it
+  may be faster to only use GPU acceleration for Pair styles with
+  long-range electrostatics.  See the "pair/only" keyword of the
+  package command for a shortcut to do that.  The work between kspace
+  on the CPU and non-bonded interactions on the GPU can be balanced
+  through adjusting the coulomb cutoff without loss of accuracy.
 * When the *mode* setting for the package gpu command is force/neigh,
   the time for neighbor list calculations on the GPU will be added into
   the "Pair" time, not the "Neigh" time.  An additional breakdown of the

doc/src/Speed_packages.rst

@@ -16,7 +16,7 @@ These are the accelerator packages currently in LAMMPS, either as
 standard or user packages:
 
 +-----------------------------------------+-------------------------------------------------------+
-| :doc:`GPU Package <Speed_gpu>`          | for NVIDIA GPUs as well as OpenCL support             |
+| :doc:`GPU Package <Speed_gpu>`          | for GPUs via CUDA, OpenCL, or ROCm HIP                |
 +-----------------------------------------+-------------------------------------------------------+
 | :doc:`USER-INTEL Package <Speed_intel>` | for Intel CPUs and Intel Xeon Phi                     |
 +-----------------------------------------+-------------------------------------------------------+
@@ -43,7 +43,7 @@ three kinds of hardware, via the listed packages:
 +-----------------+-----------------------------------------------------------------------------------------------------------------------------+
 | Many-core CPUs  | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>`, :doc:`USER-OMP <Speed_omp>`, :doc:`OPT <Speed_opt>` packages |
 +-----------------+-----------------------------------------------------------------------------------------------------------------------------+
-| NVIDIA/AMD GPUs | :doc:`GPU <Speed_gpu>`, :doc:`KOKKOS <Speed_kokkos>` packages                                                               |
+| GPUs            | :doc:`GPU <Speed_gpu>`, :doc:`KOKKOS <Speed_kokkos>` packages                                                               |
 +-----------------+-----------------------------------------------------------------------------------------------------------------------------+
 | Intel Phi/AVX   | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>` packages                                                      |
 +-----------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -154,8 +154,8 @@ Here is a brief summary of what the various packages provide.  Details
 are in the individual accelerator sections.
 
 * Styles with a "gpu" suffix are part of the GPU package and can be run
-  on NVIDIA or AMD GPUs.  The speed-up on a GPU depends on a variety of
+  on Intel, NVIDIA, or AMD GPUs.  The speed-up on a GPU depends on a
-  factors, discussed in the accelerator sections.
+  variety of factors, discussed in the accelerator sections.
 * Styles with an "intel" suffix are part of the USER-INTEL
   package. These styles support vectorized single and mixed precision
   calculations, in addition to full double precision.  In extreme cases,

doc/src/Tools.rst

@@ -93,6 +93,7 @@ Miscellaneous tools
    * :ref:`i-pi <ipi>`
    * :ref:`kate <kate>`
    * :ref:`LAMMPS shell <lammps_shell>`
+   * :ref:`LAMMPS magic patterns for file(1) <magic>`
    * :ref:`singularity <singularity_tool>`
    * :ref:`SWIG interface <swig>`
    * :ref:`vim <vim>`
@@ -267,7 +268,7 @@ data file in the required format.
 See the header of the polarizer.py file for details.
 
 The tool is authored by Agilio Padua and Alain Dequidt: agilio.padua
-at univ-bpclermont.fr, alain.dequidt at univ-bpclermont.fr
+at ens-lyon.fr, alain.dequidt at uca.fr
 
 ----------
 
@@ -341,8 +342,7 @@ The tools/fep directory contains Python scripts useful for
 post-processing results from performing free-energy perturbation
 simulations using the USER-FEP package.
 
-The scripts were contributed by Agilio Padua (Universite Blaise
+The scripts were contributed by Agilio Padua (ENS de Lyon), agilio.padua at ens-lyon.fr.
-Pascal Clermont-Ferrand), agilio.padua at univ-bpclermont.fr.
 
 See README file in the tools/fep directory.
 
@@ -642,6 +642,39 @@ This tool was written by Ara Kooser at Sandia (askoose at sandia.gov).
 
 ----------
 
+.. _magic:
+
+Magic patterns for the "file" command
+-------------------------------------
+
+.. versionadded:: 10Mar2021
+
+The file ``magic`` contains patterns that are used by the
+`file program <https://en.wikipedia.org/wiki/File_(command)>`_
+available on most Unix-like operating systems which enables it
+to detect various LAMMPS files and print some useful information
+about them.  To enable these patterns, append or copy the contents
+of the file to either the file ``.magic`` in your home directory
+or (as administrator) to ``/etc/magic`` (for a system-wide
+installation).  Afterwards the ``file`` command should be able to
+detect most LAMMPS restarts, dump, data and log files. Examples:
+
+.. code-block:: bash
+
+   $ file *.*
+   dihedral-quadratic.restart:   LAMMPS binary restart file (rev 2), Version 10 Mar 2021, Little Endian
+   mol-pair-wf_cut.restart:      LAMMPS binary restart file (rev 2), Version 24 Dec 2020, Little Endian
+   atom.bin:                     LAMMPS atom style binary dump (rev 2), Little Endian, First time step: 445570
+   custom.bin:                   LAMMPS custom style binary dump (rev 2), Little Endian, First time step: 100
+   bn1.lammpstrj:                LAMMPS text mode dump, First time step: 5000
+   data.fourmol:                 LAMMPS data file written by LAMMPS
+   pnc.data:                     LAMMPS data file written by msi2lmp
+   data.spce:                    LAMMPS data file written by TopoTools
+   B.data:                       LAMMPS data file written by OVITO
+   log.lammps:                   LAMMPS log file written by version 10 Feb 2021
+
+----------
+
 .. _matlab:
 
 matlab tool

doc/src/angle_cosine_periodic.rst

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

doc/src/angle_cosine_squared.rst

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

doc/src/commands_list.rst

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

doc/src/compute_fep.rst

@@ -163,7 +163,7 @@ the meaning of these parameters:
 +------------------------------------------------------------------------------+-------------------------+------------+
 | :doc:`born <pair_born>`                                                      | a,b,c                   | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+
-| :doc:`buck <pair_buck>`                                                      | a,c                     | type pairs |
+| :doc:`buck, buck/coul/cut, buck/coul/long, buck/coul/msm  <pair_buck>`       | a,c                     | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+
 | :doc:`buck/mdf <pair_mdf>`                                                   | a,c                     | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+

doc/src/compute_pressure.rst

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

doc/src/compute_temp_chunk.rst

@@ -153,7 +153,7 @@ temp/chunk calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>
 
    compute cc1 all chunk/atom molecule
    compute myChunk all temp/chunk cc1 temp
-   fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector
+   fix 1 all ave/time 100 1 100 c_myChunk[1] file tmp.out mode vector
 
 ----------
 

doc/src/create_box.rst

@@ -13,7 +13,7 @@ Syntax
 * N = # of atom types to use in this simulation
 * region-ID = ID of region to use as simulation domain
 * zero or more keyword/value pairs may be appended
-* keyword = *bond/types* or *angle/types* or *dihedral/types* or *improper/types* or *extra/bond/per/atom* or *extra/angle/per/atom* or *extra/dihedral/per/atom* or *extra/improper/per/atom*
+* keyword = *bond/types* or *angle/types* or *dihedral/types* or *improper/types* or *extra/bond/per/atom* or *extra/angle/per/atom* or *extra/dihedral/per/atom* or *extra/improper/per/atom* or *extra/special/per/atom*
 
   .. parsed-literal::
 

doc/src/dihedral_style.rst

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

doc/src/dihedral_table.rst

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

doc/src/dihedral_table_cut.rst

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

doc/src/dump.rst

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

doc/src/fix_adapt.rst

@@ -128,9 +128,9 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`born/coul/long, born/coul/msm <pair_born>`                             | coulombic_cutoff                                 | type global |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
-| :doc:`buck <pair_buck>`                                                      | a,c                                              | type pairs  |
+| :doc:`buck, buck/coul/cut  <pair_buck>`                                      | a,c                                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
-| :doc:`buck/coul/long, buck/coul/msm <pair_buck>`                             | coulombic_cutoff                                 | type global |
+| :doc:`buck/coul/long, buck/coul/msm <pair_buck>`                             | a,c,coulombic_cutoff                             | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`buck/mdf <pair_mdf>`                                                   | a,c                                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+

doc/src/fix_adapt_fep.rst

@@ -120,7 +120,7 @@ styles and their energy formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+-------------------------+------------+
 | :doc:`born <pair_born>`                                                      | a,b,c                   | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+
-| :doc:`buck <pair_buck>`                                                      | a,c                     | type pairs |
+| :doc:`buck, buck/coul/cut, buck/coul/long, buck/coul/msm  <pair_buck>`       | a,c                     | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+
 | :doc:`buck/mdf <pair_mdf>`                                                   | a,c                     | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+

doc/src/fix_ave_chunk.rst

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

doc/src/fix_ave_histo.rst

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

doc/src/fix_cmap.rst

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

doc/src/fix_halt.rst

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

doc/src/fix_nh.rst

@@ -1,8 +1,10 @@
 .. index:: fix nvt
+.. index:: fix nvt/gpu
 .. index:: fix nvt/intel
 .. index:: fix nvt/kk
 .. index:: fix nvt/omp
 .. index:: fix npt
+.. index:: fix npt/gpu
 .. index:: fix npt/intel
 .. index:: fix npt/kk
 .. index:: fix npt/omp
@@ -13,12 +15,12 @@
 fix nvt command
 ===============
 
-Accelerator Variants: *nvt/intel*, *nvt/kk*, *nvt/omp*
+Accelerator Variants: *nvt/gpu*, *nvt/intel*, *nvt/kk*, *nvt/omp*
 
 fix npt command
 ===============
 
-Accelerator Variants: *npt/intel*, *npt/kk*, *npt/omp*
+Accelerator Variants: *npt/gpu*, *npt/intel*, *npt/kk*, *npt/omp*
 
 fix nph command
 ===============

doc/src/fix_nve.rst

@@ -1,4 +1,5 @@
 .. index:: fix nve
+.. index:: fix nve/gpu
 .. index:: fix nve/intel
 .. index:: fix nve/kk
 .. index:: fix nve/omp
@@ -6,7 +7,7 @@
 fix nve command
 ===============
 
-Accelerator Variants: *nve/intel*, *nve/kk*, *nve/omp*
+Accelerator Variants: *nve/gpu*, *nve/intel*, *nve/kk*, *nve/omp*
 
 Syntax
 """"""

doc/src/fix_nve_asphere.rst

@@ -1,10 +1,11 @@
 .. index:: fix nve/asphere
+.. index:: fix nve/asphere/gpu
 .. index:: fix nve/asphere/intel
 
 fix nve/asphere command
 =======================
 
-Accelerator Variants: *nve/asphere/intel*
+Accelerator Variants: *nve/asphere/gpu*, *nve/asphere/intel*
 
 Syntax
 """"""

doc/src/fix_rigid_meso.rst

@@ -48,8 +48,8 @@ Examples
    fix 1 ellipsoid rigid/meso single
    fix 1 rods      rigid/meso molecule
    fix 1 spheres   rigid/meso single force 1 off off on
-   fix 1 particles rigid/meso molecule force 1\*5 off off off force 6\*10 off off on
+   fix 1 particles rigid/meso molecule force 1*5 off off off force 6*10 off off on
-   fix 2 spheres   rigid/meso group 3 sphere1 sphere2 sphere3 torque \* off off off
+   fix 2 spheres   rigid/meso group 3 sphere1 sphere2 sphere3 torque * off off off
 
 Description
 """""""""""

doc/src/fix_wall_body_polygon.rst

@@ -15,7 +15,7 @@ Syntax
 * k_n = normal repulsion strength (force/distance or pressure units)
 * c_n = normal damping coefficient (force/distance or pressure units)
 * c_t = tangential damping coefficient (force/distance or pressure units)
-* wallstyle = *xplane* or *yplane* or *zplane* or *zcylinder*
+* wallstyle = *xplane* or *yplane* or *zcylinder*
 * args = list of arguments for a particular style
 
   .. parsed-literal::

doc/src/fix_wall_gran.rst

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

doc/src/fix_wall_gran_region.rst

@@ -181,7 +181,8 @@ radius - r = overlap of particle with wall, m_eff = mass of particle,
 and the effective radius of contact is just the radius of the
 particle.
 
-The parameters *Kn*\ , *Kt*\ , *gamma_n*, *gamma_t*, *xmu* and *dampflag*
+The parameters *Kn*\ , *Kt*\ , *gamma_n*, *gamma_t*, *xmu*, *dampflag*,
+and the optional keyword *limit_damping*
 have the same meaning and units as those specified with the
 :doc:`pair_style gran/\* <pair_gran>` commands.  This means a NULL can be
 used for either *Kt* or *gamma_t* as described on that page.  If a
@@ -240,11 +241,11 @@ the following table:
 |     1 | 1.0 if particle is in contact with wall,           |                |
 |       | 0.0 otherwise                                      |                |
 +-------+----------------------------------------------------+----------------+
-|     2 | Force :math:`f_x` exerted on the wall              | force units    |
+|     2 | Force :math:`f_x` exerted by the wall              | force units    |
 +-------+----------------------------------------------------+----------------+
-|     3 | Force :math:`f_y` exerted on the wall              | force units    |
+|     3 | Force :math:`f_y` exerted by the wall              | force units    |
 +-------+----------------------------------------------------+----------------+
-|     4 | Force :math:`f_z` exerted on the wall              | force units    |
+|     4 | Force :math:`f_z` exerted by the wall              | force units    |
 +-------+----------------------------------------------------+----------------+
 |     5 | :math:`x`-coordinate of contact point on wall      | distance units |
 +-------+----------------------------------------------------+----------------+

doc/src/group.rst

@@ -120,12 +120,12 @@ specified atom types, atom IDs, or molecule IDs into the group.  These
 The first format is a list of values (types or IDs).  For example, the
 second command in the examples above puts all atoms of type 3 or 4 into
 the group named *water*\ .  Each entry in the list can be a
-colon-separated sequence A:B or A:B:C, as in two of the examples
+colon-separated sequence ``A:B`` or ``A:B:C``, as in two of the examples
 above.  A "sequence" generates a sequence of values (types or IDs),
-with an optional increment.  The first example with 500:1000 has the
+with an optional increment.  The first example with ``500:1000`` has the
 default increment of 1 and would add all atom IDs from 500 to 1000
 (inclusive) to the group sub, along with 10,25,50 since they also
-appear in the list of values.  The second example with 100:10000:10
+appear in the list of values.  The second example with ``100:10000:10``
 uses an increment of 10 and would thus would add atoms IDs
 100,110,120, ... 9990,10000 to the group sub.
 
@@ -269,7 +269,7 @@ group and running further.
 .. code-block:: LAMMPS
 
    variable        nsteps equal 5000
-   variable        rad equal 18-(step/v_nsteps)\*(18-5)
+   variable        rad equal 18-(step/v_nsteps)*(18-5)
    region          ss sphere 20 20 0 v_rad
    group           mobile dynamic all region ss
    fix             1 mobile nve

doc/src/package.rst

@@ -18,7 +18,7 @@ Syntax
        *gpu* args = Ngpu keyword value ...
          Ngpu = # of GPUs per node
          zero or more keyword/value pairs may be appended
-         keywords = *neigh* or *newton* or *pair/only* or *binsize* or *split* or *gpuID* or *tpa* or *device* or *blocksize*
+         keywords = *neigh* or *newton* or *pair/only* or *binsize* or *split* or *gpuID* or *tpa* or *blocksize* or *platform* or *device_type* or *ocl_args*
            *neigh* value = *yes* or *no*
              yes = neighbor list build on GPU (default)
              no = neighbor list build on CPU
@@ -32,17 +32,20 @@ Syntax
              size = bin size for neighbor list construction (distance units)
            *split* = fraction
              fraction = fraction of atoms assigned to GPU (default = 1.0)
-           *gpuID* values = first last
+           *tpa* value = Nlanes
-             first = ID of first GPU to be used on each node
+             Nlanes = # of GPU vector lanes (CUDA threads) used per atom
-             last = ID of last GPU to be used on each node
-           *tpa* value = Nthreads
-             Nthreads = # of GPU threads used per atom
-           *device* value = device_type or platform_id:device_type or platform_id:custom,val1,val2,val3,..,val13
-             platform_id = numerical OpenCL platform id (default: -1)
-             device_type = *kepler* or *fermi* or *cypress* or *intel* or *phi* or *generic* or *custom*
-             val1,val2,... = custom OpenCL tune parameters (see below for details)
            *blocksize* value = size
              size = thread block size for pair force computation
+           *omp* value = Nthreads
+             Nthreads = number of OpenMP threads to use on CPU (default = 0)
+           *platform* value = id
+             id = For OpenCL, platform ID for the GPU or accelerator
+           *gpuID* values = id
+             id = ID of first GPU to be used on each node
+           *device_type* value = *intelgpu* or *nvidiagpu* or *amdgpu* or *applegpu* or *generic* or *custom,val1,val2,...*
+             val1,val2,... = custom OpenCL accelerator configuration parameters (see below for details)
+           *ocl_args* value = args
+             args = List of additional OpenCL compiler arguments delimited by colons
        *intel* args = NPhi keyword value ...
          Nphi = # of co-processors per node
          zero or more keyword/value pairs may be appended
@@ -100,7 +103,7 @@ Syntax
              off = use device acceleration (e.g. GPU) for all available styles in the KOKKOS package (default)
              on  = use device acceleration only for pair styles (and host acceleration for others)
        *omp* args = Nthreads keyword value ...
-         Nthread = # of OpenMP threads to associate with each MPI process
+         Nthreads = # of OpenMP threads to associate with each MPI process
          zero or more keyword/value pairs may be appended
          keywords = *neigh*
            *neigh* value = *yes* or *no*
@@ -112,12 +115,10 @@ Examples
 
 .. code-block:: LAMMPS
 
-   package gpu 1
+   package gpu 0
    package gpu 1 split 0.75
    package gpu 2 split -1.0
-   package gpu 1 device kepler
+   package gpu 0 omp 2 device_type intelgpu
-   package gpu 1 device 2:generic
-   package gpu 1 device custom,32,4,8,256,11,128,256,128,32,64,8,128,128
    package kokkos neigh half comm device
    package omp 0 neigh no
    package omp 4
@@ -174,10 +175,18 @@ simulations.
 The *gpu* style invokes settings associated with the use of the GPU
 package.
 
-The *Ngpu* argument sets the number of GPUs per node.  There must be
+The *Ngpu* argument sets the number of GPUs per node. If *Ngpu* is 0
-at least as many MPI tasks per node as GPUs, as set by the mpirun or
+and no other keywords are specified, GPU or accelerator devices are
-mpiexec command.  If there are more MPI tasks (per node)
+auto-selected. In this process, all platforms are searched for
-than GPUs, multiple MPI tasks will share each GPU.
+accelerator devices and GPUs are chosen if available. The device with
+the highest number of compute cores is selected. The number of devices
+is increased to be the number of matching accelerators with the same
+number of compute cores. If there are more devices than MPI tasks,
+the additional devices will be unused. The auto-selection of GPUs/
+accelerator devices and platforms can be restricted by specifying
+a non-zero value for *Ngpu* and / or using the *gpuID*, *platform*,
+and *device_type* keywords as described below. If there are more MPI
+tasks (per node) than GPUs, multiple MPI tasks will share each GPU.
 
 Optional keyword/value pairs can also be specified.  Each has a
 default value as listed below.
@@ -212,18 +221,8 @@ overlapped with all other computations on the CPU.
 
 The *binsize* keyword sets the size of bins used to bin atoms in
 neighbor list builds performed on the GPU, if *neigh* = *yes* is set.
-If *binsize* is set to 0.0 (the default), then bins = the size of the
+If *binsize* is set to 0.0 (the default), then the binsize is set
-pairwise cutoff + neighbor skin distance.  This is 2x larger than the
+automatically using heuristics in the GPU package.
-LAMMPS default used for neighbor list building on the CPU.  This will
-be close to optimal for the GPU, so you do not normally need to use
-this keyword.  Note that if you use a longer-than-usual pairwise
-cutoff, e.g. to allow for a smaller fraction of KSpace work with a
-:doc:`long-range Coulombic solver <kspace_style>` because the GPU is
-faster at performing pairwise interactions, then it may be optimal to
-make the *binsize* smaller than the default.  For example, with a
-cutoff of 20\*sigma in LJ :doc:`units <units>` and a neighbor skin
-distance of sigma, a *binsize* = 5.25\*sigma can be more efficient than
-the default.
 
 The *split* keyword can be used for load balancing force calculations
 between CPU and GPU cores in GPU-enabled pair styles. If 0 < *split* <
@@ -257,63 +256,79 @@ cores would perform force calculations for some fraction of the
 particles at the same time the GPUs performed force calculation for
 the other particles.
 
-The *gpuID* keyword allows selection of which GPUs on each node will
+The *gpuID* keyword is used to specify the first ID for the GPU or
-be used for a simulation.  The *first* and *last* values specify the
+other accelerator that LAMMPS will use. For example, if the ID is
-GPU IDs to use (from 0 to Ngpu-1).  By default, first = 0 and last =
+1 and *Ngpu* is 3, GPUs 1-3 will be used. Device IDs should be
-Ngpu-1, so that all GPUs are used, assuming Ngpu is set to the number
+determined from the output of nvc_get_devices, ocl_get_devices,
-of physical GPUs.  If you only wish to use a subset, set Ngpu to a
+or hip_get_devices
-smaller number and first/last to a sub-range of the available GPUs.
+as provided in the lib/gpu directory. When using OpenCL with
+accelerators that have main memory NUMA, the accelerators can be
+split into smaller virtual accelerators for more efficient use
+with MPI.
 
-The *tpa* keyword sets the number of GPU thread per atom used to
+The *tpa* keyword sets the number of GPU vector lanes per atom used to
 perform force calculations.  With a default value of 1, the number of
-threads will be chosen based on the pair style, however, the value can
+lanes will be chosen based on the pair style, however, the value can
 be set explicitly with this keyword to fine-tune performance.  For
 large cutoffs or with a small number of particles per GPU, increasing
-the value can improve performance. The number of threads per atom must
+the value can improve performance. The number of lanes per atom must
-be a power of 2 and currently cannot be greater than 32.
+be a power of 2 and currently cannot be greater than the SIMD width
-
+for the GPU / accelerator. In the case it exceeds the SIMD width, it
-The *device* keyword can be used to tune parameters optimized for a
+will automatically be decreased to meet the restriction.
-specific accelerator and platform when using OpenCL. OpenCL supports
-the concept of a **platform**\ , which represents one or more devices that
-share the same driver (e.g. there would be a different platform for
-GPUs from different vendors or for CPU based accelerator support).
-In LAMMPS only one platform can be active at a time and by default
-the first platform with an accelerator is selected. This is equivalent
-to using a platform ID of -1. The platform ID is a number corresponding
-to the output of the ocl_get_devices tool. The platform ID is passed
-to the GPU library, by prefixing the *device* keyword with that number
-separated by a colon. For CUDA, the *device* keyword is ignored.
-Currently, the device tuning support is limited to NVIDIA Kepler, NVIDIA
-Fermi, AMD Cypress, Intel x86_64 CPU, Intel Xeon Phi, or a generic device.
-More devices may be added later.  The default device type can be
-specified when building LAMMPS with the GPU library, via setting a
-variable in the lib/gpu/Makefile that is used.
-
-In addition, a device type *custom* is available, which is followed by
-13 comma separated numbers, which allows to set those tweakable parameters
-from the package command. It can be combined with the (colon separated)
-platform id. The individual settings are:
-
-* MEM_THREADS
-* THREADS_PER_ATOM
-* THREADS_PER_CHARGE
-* BLOCK_PAIR
-* MAX_SHARED_TYPES
-* BLOCK_NBOR_BUILD
-* BLOCK_BIO_PAIR
-* BLOCK_ELLIPSE
-* WARP_SIZE
-* PPPM_BLOCK_1D
-* BLOCK_CELL_2D
-* BLOCK_CELL_ID
-* MAX_BIO_SHARED_TYPES
 
 The *blocksize* keyword allows you to tweak the number of threads used
 per thread block. This number should be a multiple of 32 (for GPUs)
 and its maximum depends on the specific GPU hardware. Typical choices
 are 64, 128, or 256. A larger block size increases occupancy of
 individual GPU cores, but reduces the total number of thread blocks,
-thus may lead to load imbalance.
+thus may lead to load imbalance. On modern hardware, the sensitivity
+to the blocksize is typically low.
+
+The *Nthreads* value for the *omp* keyword sets the number of OpenMP
+threads allocated for each MPI task. This setting controls OpenMP
+parallelism only for routines run on the CPUs. For more details on
+setting the number of OpenMP threads, see the discussion of the
+*Nthreads* setting on this doc page for the "package omp" command.
+The meaning of *Nthreads* is exactly the same for the GPU, USER-INTEL,
+and GPU packages.
+
+The *platform* keyword is only used with OpenCL to specify the ID for
+an OpenCL platform. See the output from ocl_get_devices in the lib/gpu
+directory. In LAMMPS only one platform can be active at a time and by
+default (id=-1) the platform is auto-selected to find the GPU with the
+most compute cores. When *Ngpu* or other keywords are specified, the
+auto-selection is appropriately restricted. For example, if *Ngpu* is
+3, only platforms with at least 3 accelerators are considered. Similar
+restrictions can be enforced by the *gpuID* and *device_type* keywords.
+
+The *device_type* keyword can be used for OpenCL to specify the type of
+GPU to use or specify a custom configuration for an accelerator. In most
+cases this selection will be automatic and there is no need to use the
+keyword. The *applegpu* type is not specific to a particular GPU vendor,
+but is separate due to the more restrictive Apple OpenCL implementation.
+For expert users, to specify a custom configuration, the *custom* keyword
+followed by the next parameters can be specified:
+
+CONFIG_ID, SIMD_SIZE, MEM_THREADS, SHUFFLE_AVAIL, FAST_MATH,
+THREADS_PER_ATOM, THREADS_PER_CHARGE, THREADS_PER_THREE, BLOCK_PAIR,
+BLOCK_BIO_PAIR, BLOCK_ELLIPSE, PPPM_BLOCK_1D, BLOCK_NBOR_BUILD,
+BLOCK_CELL_2D, BLOCK_CELL_ID, MAX_SHARED_TYPES, MAX_BIO_SHARED_TYPES,
+PPPM_MAX_SPLINE.
+
+CONFIG_ID can be 0. SHUFFLE_AVAIL in {0,1} indicates that inline-PTX
+(NVIDIA) or OpenCL extensions (Intel) should be used for horizontal
+vector operations. FAST_MATH in {0,1} indicates that OpenCL fast math
+optimizations are used during the build and hardware-accelerated
+transcendental functions are used when available. THREADS_PER_* give the
+default *tpa* values for ellipsoidal models, styles using charge, and
+any other styles. The BLOCK_* parameters specify the block sizes for
+various kernel calls and the MAX_*SHARED*_ parameters are used to
+determine the amount of local shared memory to use for storing model
+parameters.
+
+For OpenCL, the routines are compiled at runtime for the specified GPU
+or accelerator architecture. The *ocl_args* keyword can be used to
+specify additional flags for the runtime build.
 
 ----------
 
@@ -331,44 +346,13 @@ built with co-processor support.
 Optional keyword/value pairs can also be specified.  Each has a
 default value as listed below.
 
-The *omp* keyword determines the number of OpenMP threads allocated
+The *Nthreads* value for the *omp* keyword sets the number of OpenMP
-for each MPI task when any portion of the interactions computed by a
+threads allocated for each MPI task. This setting controls OpenMP
-USER-INTEL pair style are run on the CPU.  This can be the case even
+parallelism only for routines run on the CPUs. For more details on
-if LAMMPS was built with co-processor support; see the *balance*
+setting the number of OpenMP threads, see the discussion of the
-keyword discussion below.  If you are running with less MPI tasks/node
+*Nthreads* setting on this doc page for the "package omp" command.
-than there are CPUs, it can be advantageous to use OpenMP threading on
+The meaning of *Nthreads* is exactly the same for the GPU, USER-INTEL,
-the CPUs.
+and GPU packages.
-
-.. note::
-
-   The *omp* keyword has nothing to do with co-processor threads on
-   the Xeon Phi; see the *tpc* and *tptask* keywords below for a
-   discussion of co-processor threads.
-
-The *Nthread* value for the *omp* keyword sets the number of OpenMP
-threads allocated for each MPI task.  Setting *Nthread* = 0 (the
-default) instructs LAMMPS to use whatever value is the default for the
-given OpenMP environment. This is usually determined via the
-*OMP_NUM_THREADS* environment variable or the compiler runtime, which
-is usually a value of 1.
-
-For more details, including examples of how to set the OMP_NUM_THREADS
-environment variable, see the discussion of the *Nthreads* setting on
-this doc page for the "package omp" command.  Nthreads is a required
-argument for the USER-OMP package.  Its meaning is exactly the same
-for the USER-INTEL package.
-
-.. note::
-
-   If you build LAMMPS with both the USER-INTEL and USER-OMP
-   packages, be aware that both packages allow setting of the *Nthreads*
-   value via their package commands, but there is only a single global
-   *Nthreads* value used by OpenMP.  Thus if both package commands are
-   invoked, you should insure the two values are consistent.  If they are
-   not, the last one invoked will take precedence, for both packages.
-   Also note that if the :doc:`-sf hybrid intel omp command-line switch <Run_options>` is used, it invokes a "package intel"
-   command, followed by a "package omp" command, both with a setting of
-   *Nthreads* = 0.
 
 The *mode* keyword determines the precision mode to use for
 computing pair style forces, either on the CPU or on the co-processor,
@@ -574,7 +558,7 @@ result in better performance for certain configurations and system sizes.
 The *omp* style invokes settings associated with the use of the
 USER-OMP package.
 
-The *Nthread* argument sets the number of OpenMP threads allocated for
+The *Nthreads* argument sets the number of OpenMP threads allocated for
 each MPI task.  For example, if your system has nodes with dual
 quad-core processors, it has a total of 8 cores per node.  You could
 use two MPI tasks per node (e.g. using the -ppn option of the mpirun
@@ -583,7 +567,7 @@ This would use all 8 cores on each node.  Note that the product of MPI
 tasks \* threads/task should not exceed the physical number of cores
 (on a node), otherwise performance will suffer.
 
-Setting *Nthread* = 0 instructs LAMMPS to use whatever value is the
+Setting *Nthreads* = 0 instructs LAMMPS to use whatever value is the
 default for the given OpenMP environment. This is usually determined
 via the *OMP_NUM_THREADS* environment variable or the compiler
 runtime.  Note that in most cases the default for OpenMP capable
@@ -614,6 +598,24 @@ input.  Not all features of LAMMPS support OpenMP threading via the
 USER-OMP package and the parallel efficiency can be very different,
 too.
 
+.. note::
+
+   If you build LAMMPS with the GPU, USER-INTEL, and / or USER-OMP
+   packages, be aware these packages all allow setting of the *Nthreads*
+   value via their package commands, but there is only a single global
+   *Nthreads* value used by OpenMP.  Thus if multiple package commands are
+   invoked, you should insure the values are consistent.  If they are
+   not, the last one invoked will take precedence, for all packages.
+   Also note that if the :doc:`-sf hybrid intel omp command-line switch <Run_options>` is used, it invokes a "package intel" command, followed by a
+   "package omp" command, both with a setting of *Nthreads* = 0. Likewise
+   for a hybrid suffix for gpu and omp. Note that KOKKOS also supports
+   setting the number of OpenMP threads from the command line using the
+   "-k on" :doc:`command-line switch <Run_options>`. The default for
+   KOKKOS is 1 thread per MPI task, so any other number of threads should
+   be explicitly set using the "-k on" command-line switch (and this
+   setting should be consistent with settings from any other packages
+   used).
+
 Optional keyword/value pairs can also be specified.  Each has a
 default value as listed below.
 
@@ -658,9 +660,9 @@ Related commands
 Default
 """""""
 
-For the GPU package, the default is Ngpu = 1 and the option defaults
+For the GPU package, the default is Ngpu = 0 and the option defaults
 are neigh = yes, newton = off, binsize = 0.0, split = 1.0, gpuID = 0
-to Ngpu-1, tpa = 1, and device = not used.  These settings are made
+to Ngpu-1, tpa = 1, omp = 0, and platform=-1.  These settings are made
 automatically if the "-sf gpu" :doc:`command-line switch <Run_options>`
 is used.  If it is not used, you must invoke the package gpu command
 in your input script or via the "-pk gpu" :doc:`command-line switch <Run_options>`.

doc/src/pair_adp.rst

@@ -59,7 +59,7 @@ command to specify them.
 * The OpenKIM Project at
   `https://openkim.org/browse/models/by-type <https://openkim.org/browse/models/by-type>`_
   provides ADP potentials that can be used directly in LAMMPS with the
-  :doc:`kim_commands <kim_commands>` interface.
+  :doc:`kim command <kim_commands>` interface.
 
 ----------
 

doc/src/pair_charmm.rst

@@ -1,4 +1,5 @@
 .. index:: pair_style lj/charmm/coul/charmm
+.. index:: pair_style lj/charmm/coul/charmm/gpu
 .. index:: pair_style lj/charmm/coul/charmm/intel
 .. index:: pair_style lj/charmm/coul/charmm/kk
 .. index:: pair_style lj/charmm/coul/charmm/omp
@@ -19,7 +20,7 @@
 pair_style lj/charmm/coul/charmm command
 ========================================
 
-Accelerator Variants: *lj/charmm/coul/charmm/intel*, *lj/charmm/coul/charmm/kk*, *lj/charmm/coul/charmm/omp*
+Accelerator Variants: *lj/charmm/coul/charmm/gpu*, *lj/charmm/coul/charmm/intel*, *lj/charmm/coul/charmm/kk*, *lj/charmm/coul/charmm/omp*
 
 pair_style lj/charmm/coul/charmm/implicit command
 =================================================

doc/src/pair_dpd.rst

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

doc/src/pair_eam.rst

@@ -141,7 +141,7 @@ interatomic potentials and file formats.
 The OpenKIM Project at
 `https://openkim.org/browse/models/by-type <https://openkim.org/browse/models/by-type>`_
 provides EAM potentials that can be used directly in LAMMPS with the
-:doc:`kim_commands <kim_commands>` interface.
+:doc:`kim command <kim_commands>` interface.
 
 ----------
 

doc/src/pair_fep_soft.rst

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

doc/src/pair_gayberne.rst

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

doc/src/pair_gran.rst

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

doc/src/pair_granular.rst

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

doc/src/pair_kim.rst

@@ -23,29 +23,30 @@ Examples
 Description
 """""""""""
 
-This pair style is a wrapper on the `Open Knowledgebase of Interatomic Models (OpenKIM) <https://openkim.org>`_ repository of interatomic
+This pair style is a wrapper on the
-potentials to enable their use in LAMMPS scripts.
+`Open Knowledgebase of Interatomic Models (OpenKIM) <https://openkim.org>`_
+repository of interatomic potentials to enable their use in LAMMPS scripts.
 
 The preferred interface for using interatomic models archived in
-OpenKIM is the :doc:`kim_commands interface <kim_commands>`. That
+OpenKIM is the :doc:`kim command <kim_commands>` interface. That
 interface supports both "KIM Portable Models" (PMs) that conform to the
 KIM API Portable Model Interface (PMI) and can be used by any
 simulation code that conforms to the KIM API/PMI, and
-"KIM Simulator Models" that are natively implemented within a single
+"KIM Simulator Models" (SMs) that are natively implemented within a single
 simulation code (like LAMMPS) and can only be used with it.
 The *pair_style kim* command is limited to KIM PMs. It is
-used by the :doc:`kim_commands interface <kim_commands>` as needed.
+used by the :doc:`kim command <kim_commands>` interface as needed.
 
 .. note::
 
-   Since *pair_style kim* is called by *kim_interactions* as needed,
+   Since *pair_style kim* is called by *kim interactions* as needed,
-   is not recommended to be directly used in input scripts.
+   it is not recommended to be directly used in input scripts.
 
 ----------
 
 The argument *model* is the name of the KIM PM.
 For potentials archived in OpenKIM
-this is the extended KIM ID (see :doc:`kim_commands <kim_commands>`
+this is the extended KIM ID (see :doc:`kim command <kim_commands>`
 for details). LAMMPS can invoke any KIM PM, however there can
 be incompatibilities (for example due to unit matching issues).
 In the event of an incompatibility, the code will terminate with
@@ -106,7 +107,7 @@ Restrictions
 """"""""""""
 
 This pair style is part of the KIM package. See details on
-restrictions in :doc:`kim_commands <kim_commands>`.
+restrictions in :doc:`kim command <kim_commands>`.
 
 This current version of pair_style kim is compatible with the
 kim-api package version 2.0.0 and higher.
@@ -114,7 +115,7 @@ kim-api package version 2.0.0 and higher.
 Related commands
 """"""""""""""""
 
-:doc:`pair_coeff <pair_coeff>`, :doc:`kim_commands <kim_commands>`
+:doc:`pair_coeff <pair_coeff>`, :doc:`kim command <kim_commands>`
 
 Default
 """""""

doc/src/pair_lj_relres.rst

@@ -0,0 +1,291 @@
+.. index:: pair_style lj/relres
+.. index:: pair_style lj/relres/omp
+
+pair_style lj/relres command
+============================
+
+Accelerator Variants: *lj/relres/omp*
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   pair_style lj/relres Rsi Rso Rci Rco
+
+* Rsi = inner switching cutoff between the fine-grained and coarse-grained potentials (distance units)
+* Rso = outer switching cutoff between the fine-grained and coarse-grained potentials (distance units)
+* Rci = inner cutoff beyond which the force smoothing for all interactions is applied (distance units)
+* Rco = outer cutoff for all interactions (distance units)
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   pair_style lj/relres 4.0 5.0 8.0 10.0
+   pair_coeff 1 1 0.5 1.0 1.5 1.1
+   pair_coeff 2 2 0.5 1.0 0.0 0.0 3.0 3.5 6.0 7.0
+
+Description
+"""""""""""
+
+Pair style *lj/relres* computes a LJ interaction using the Relative
+Resolution (RelRes) framework which applies a fine-grained (FG)
+potential between near neighbors and a coarse-grained (CG) potential
+between far neighbors :ref:`(Chaimovich1) <Chaimovich1>`. This approach
+can improve the computational efficiency by almost an order of
+magnitude, while maintaining the correct static and dynamic behavior of
+a reference system :ref:`(Chaimovich2) <Chaimovich2>`.
+
+.. math::
+
+   E = \left\{\begin{array}{lr}
+        4 \epsilon^{\scriptscriptstyle FG} \left[ \left(\frac{\sigma^{FG}}{r}\right)^{12} - \left(\frac{\sigma^{FG}}{r}\right)^6 \right]-\Gamma_{si}, & \quad\mathrm{if}\quad  r< r_{si}, \\
+        \sum_{m=0}^{4} \gamma_{sm}\left(r-r_{si}\right)^m-\Gamma_{so} ,   & \quad\mathrm{if}\quad  r_{si}\leq r< r_{so}, \\
+        4 \epsilon^{\scriptscriptstyle CG} \left[ \left(\frac{\sigma^{CG}}{r}\right)^{12} -     \left(\frac{\sigma^{CG}}{r}\right)^6 \right]-\Gamma_c, &  \quad\mathrm{if}\quad  r_{so}\leq r<r_{ci}, \\
+        \sum_{m=0}^{4} \gamma_{cm}\left(r-r_{ci}\right)^m -\Gamma_c, & \quad\mathrm{if}\quad  r_{ci}\leq r< r_{co}, \\
+        0, & \quad\mathrm{if}\quad  r\geq r_{co}.\end{array}\right.
+
+The FG parameters of the LJ potential (:math:`\epsilon^{FG}` and
+:math:`\sigma^{FG}`) are applied up to the inner switching cutoff,
+:math:`r_{si}`, while the CG parameters of the LJ potential
+(:math:`\epsilon^{CG}` and :math:`\sigma^{CG}`) are applied beyond the
+outer switching cutoff, :math:`r_{so}`. Between :math:`r_{si}` and
+:math:`r_{so}` a polynomial smoothing function is applied so that the
+force and its derivative are continuous between the FG and CG
+potentials.  An analogous smoothing function is applied between the
+inner and outer cutoffs (:math:`r_{ci}` and :math:`r_{co}`).
+The offsets :math:`\Gamma_{si}`, :math:`\Gamma_{so}` and
+:math:`\Gamma_{c}` ensure the continuity of the energy over the entire
+domain.  The corresponding polynomial coefficients :math:`\gamma_{sm}`
+and :math:`\gamma_{cm}`, as well as the offsets are automatically
+computed by LAMMPS.
+
+.. note::
+
+   Energy and force resulting from this methodology can be plotted via the
+   :doc:`pair_write <pair_write>` command.
+
+The following coefficients must be defined for each pair of atom types
+via the :doc:`pair_coeff <pair_coeff>` command as in the examples above,
+or in the data file or restart files read by the :doc:`read_data
+<read_data>` or :doc:`read_restart <read_restart>` commands, or by
+mixing as will be described below:
+
+* :math:`\epsilon^{FG}` (energy units)
+* :math:`\sigma^{FG}` (distance units)
+* :math:`\epsilon^{CG}` (energy units)
+* :math:`\sigma^{CG}` (distance units)
+
+Additional parameters can be defined to specify different
+:math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`, :math:`r_{co}` for
+a particular set of atom types:
+
+* :math:`r_{si}` (distance units)
+* :math:`r_{so}` (distance units)
+* :math:`r_{ci}` (distance units)
+* :math:`r_{co}` (distance units)
+
+These parameters are optional, and they are used to override the global
+cutoffs as defined in the pair_style command.  If not specified, the
+global values for :math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`, and
+:math:`r_{co}` are used.  If this override option is employed, all four
+arguments must be specified.
+
+----------
+
+Here are some guidelines for using the pair_style *lj/relres* command.
+
+In general, RelRes focuses on the speedup of pairwise interactions between
+all LJ sites. Importantly, it works with any settings and flags (e.g.,
+:doc:`special_bonds <special_bonds>` settings and :doc:`newton <newton>`
+flags) that can be used in a molecular simulation with the
+conventional LJ potential. In particular, all intramolecular topology
+with its energetics (i.e., bonds, angles, etc.) remains unaltered.
+
+At the most basic level in the RelRes framework, all sites are mapped into
+clusters. Each cluster is just a collection of sites bonded together (the
+bonds themselves are not part of the cluster). In general, a molecule may
+be comprised of several clusters, and preferably, no two sites in a cluster
+are separated by more than two bonds. There are two categories of sites in
+RelRes: "hybrid" sites embody both FG and CG models, while "ordinary" sites
+embody just FG characteristics with no CG features. A given cluster has
+a single hybrid site (typically its central site) and several ordinary sites
+(typically its peripheral sites). Notice that while clusters are necessary
+for the RelRes parameterization (discussed below), they are not actually
+defined in LAMMPS. Besides, the total number of sites in the cluster are
+called the "mapping ratio", and this substantially impacts the computational
+efficiency of RelRes: For a mapping ratio of 3, the efficiency factor is
+around 4, and for a mapping ratio of 5, the efficiency factor is around 5
+:ref:`(Chaimovich2) <Chaimovich2>`.
+
+The flexibility of LAMMPS allows placing any values for the LJ
+parameters in the input script. However, here are the optimal
+recommendations for the RelRes parameters, which yield the correct
+structural and thermal behavior in a system of interest
+:ref:`(Chaimovich1) <Chaimovich1>`.  One must first assign a complete set of
+parameters for the FG interactions that are applicable to all atom types.
+Regarding the parameters for the CG interactions, the rules rely on the
+site category (if it is a hybrid or an ordinary site). For atom types of
+ordinary sites, :math:`\epsilon^{CG}` must be set to 0 (zero) while the
+specific value of :math:`\sigma^{CG}` is irrelevant. For atom types of
+hybrid sites, the CG parameters should be generally calculated using the
+following equations:
+
+.. math::
+
+   \sigma_I^{CG}=\frac{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^{12}}\right)^{1/2}}{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^6}\right)^{1/3}}
+   \quad\mathrm{and}\quad
+   \epsilon_I^{CG}=\frac{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^6}\right)^4}{\left((\sum_{\alpha\in A}\sqrt{\epsilon_\alpha^{FG}\left(\sigma_\alpha^{FG}\right)^{12}}\right)^2}
+
+where :math:`I` is an atom type of a hybrid site of a particular cluster
+:math:`A`, and corresponding with this cluster, the summation proceeds over
+all of its sites :math:`\alpha`.  These equations are derived from the
+monopole term in the underlying Taylor series, and they are indeed relevant
+only if geometric mixing is applicable for the FG model; if this is not the
+case, Ref. :ref:`(Chaimovich2) <Chaimovich2>` discusses the alternative
+formula, and in such a situation, the pair_coeff command should be explicitly
+used for all combinations of atom types :math:`I\;!=J`.
+
+The switching distance (the midpoint between inner and outer switching
+cutoffs) is another crucial factor in RelRes: decreasing it improves the
+computational efficiency, yet if it is too small, the molecular simulations
+may not capture the system behavior correctly.  As a rule of thumb,
+the switching distance should be approximately :math:`\,\sim\! 1.5\sigma`
+:ref:`(Chaimovich1) <Chaimovich1>`; recommendations can be found in
+Ref. :ref:`(Chaimovich2) <Chaimovich2>`.
+Regarding the switching smoothing zone, :math:`\,\sim\!0.1\sigma` is
+recommended; if desired, smoothing can be eliminated by setting
+the inner switching cutoff, :math:`r_{si}`, equal to the outer
+switching cutoff, :math:`r_{so}` (the same is true for the other cutoffs
+:math:`r_{ci}` and :math:`r_{co}`).
+
+----------
+
+As an example, imagine that in your system, a molecule is comprised just
+of one cluster such that one atom type (#1) is associated with
+its hybrid site, and another atom type (#2) is associated with its ordinary
+sites (in total, there are 2 atom types). If geometric mixing is applicable,
+the following commands should be used:
+
+.. code-block:: LAMMPS
+
+   pair_style lj/relres Rsi Rso Rci Rco
+   pair_coeff 1 1 epsilon_FG1 sigma_FG1 epsilon_CG1 sigma_CG1
+   pair_coeff 2 2 epsilon_FG2 sigma_FG2 0.0         0.0
+   pair_modify shift yes
+
+In a more complex situation, there may be two distinct clusters in a system
+(these two clusters may be on same molecule or on different molecules),
+each with its own switching cutoffs.  If there are still two atom types
+in each cluster as in the earlier example, the commands should be:
+
+.. code-block:: LAMMPS
+
+   pair_style lj/relres Rsi Rso Rci Rco
+   pair_coeff 1 1 epsilon_FG1 sigma_FG1 epsilon_CG1 sigma_CG1 Rsi1 Rso1 Rci Rco
+   pair_coeff 2 2 epsilon_FG2 sigma_FG2 0.0         0.0       Rsi1 Rso1 Rci Rco
+   pair_coeff 3 3 epsilon_FG3 sigma_FG3 epsilon_CG3 sigma_CG3
+   pair_coeff 4 4 epsilon_FG4 sigma_FG4 0.0         0.0
+   pair_modify shift yes
+
+In this example, the switching cutoffs for the first cluster (atom types 1
+and 2) is defined explicitly in the pair_coeff command which overrides the
+global values, while the second cluster (atom types 3 and 4) uses the global
+definition from the pair_style command. The emphasis here is that the atom
+types that belong to a specific cluster should have the same switching/cutoff
+arguments.
+
+In the case that geometric mixing is not applicable, for simulating the
+system from the previous example, we recommend using the following commands:
+
+.. code-block:: LAMMPS
+
+   pair_style lj/relres Rsi Rso Rci Rco
+   pair_coeff 1 1 epsilon_FG1  sigma_FG1  epsilon_CG1  sigma_CG1  Rsi1  Rso1  Rci Rco
+   pair_coeff 1 2 epsilon_FG12 sigma_FG12 0.0          0.0        Rsi1  Rso1  Rci Rco
+   pair_coeff 1 3 epsilon_FG13 sigma_FG13 epsilon_CG13 sigma_CG13 Rsi13 Rso13 Rci Rco
+   pair_coeff 1 4 epsilon_FG14 sigma_FG14 0.0          0.0        Rsi13 Rso13 Rci Rco
+   pair_coeff 2 2 epsilon_FG2  sigma_FG2  0.0          0.0        Rsi1  Rso1  Rci Rco
+   pair_coeff 2 3 epsilon_FG23 sigma_FG23 0.0          0.0        Rsi13 Rso13 Rci Rco
+   pair_coeff 2 4 epsilon_FG24 sigma_FG24 0.0          0.0        Rsi13 Rso13 Rci Rco
+   pair_coeff 3 3 epsilon_FG3  sigma_FG3  epsilon_CG3  sigma_CG3
+   pair_coeff 3 4 epsilon_FG34 sigma_FG34 0.0          0.0
+   pair_coeff 4 4 epsilon_FG4  sigma_FG4  0.0          0.0
+   pair_modify shift yes
+
+Notice that the CG parameters are mixed only for interactions between atom
+types associated with hybrid sites, and that the cutoffs are
+mixed on the cluster basis.
+
+More examples can be found in the *examples/relres* folder.
+
+----------
+
+.. include:: accel_styles.rst
+
+----------
+
+Mixing, shift, table, tail correction, restart, rRESPA info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+For atom type pairs :math:`I,\:J` with :math:`I\;!=J`, the
+:math:`\epsilon^{FG}`, :math:`\sigma^{FG}`, :math:`\epsilon^{CG}`,
+:math:`\sigma^{CG}`, :math:`r_{si}`, :math:`r_{so}`, :math:`r_{ci}`,
+and :math:`r_{co}` parameters for this pair style can be mixed, if
+not defined explicitly. All parameters are mixed according to the
+pair_modify mix option.  The default mix value is *geometric*\ ,
+and it is recommended to use with this *lj/relres* style.  See the
+"pair_modify" command for details.
+
+This pair style supports the :doc:`pair_modify <pair_modify>` shift
+option for the energy of the pair interaction. It is recommended to set
+this option to *yes*\ .  Otherwise, the offset :math:`\Gamma_{c}`
+is set to zero. Constants :math:`\Gamma_{si}` and :math:`\Gamma_{so}` are
+not impacted by this option.
+
+The :doc:`pair_modify <pair_modify>` table option is not relevant
+for this pair style.
+
+This pair style does not support the :doc:`pair_modify <pair_modify>`
+tail option for adding long-range tail corrections to energy and
+pressure, since the energy of the pair interaction is smoothed to 0.0
+at the cutoff.
+
+This pair style writes its information to :doc:`binary restart files
+<restart>`, so pair_style and pair_coeff commands do not need to be
+specified in an input script that reads a restart file.
+
+This pair style can only be used via the *pair* keyword of the
+:doc:`run_style respa <run_style>` command.  It does not support the
+*inner*\ , *middle*\ , *outer* keywords.
+
+----------
+
+Restrictions
+""""""""""""
+none
+
+Related commands
+""""""""""""""""
+
+:doc:`pair_coeff <pair_coeff>`
+
+Default
+"""""""
+
+none
+
+----------
+
+.. _Chaimovich1:
+
+**(Chaimovich1)** A. Chaimovich, C. Peter and K. Kremer, J. Chem. Phys. 143,
+243107 (2015).
+
+.. _Chaimovich2:
+
+**(Chaimovich2)** M. Chaimovich and A. Chaimovich, J. Chem. Theory Comput. 17,
+1045-1059 (2021).
+

doc/src/pair_lj_switch3_coulgauss_long.rst

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

doc/src/pair_mliap.rst

@@ -16,7 +16,7 @@ Syntax
   .. parsed-literal::
 
        *model* values = style filename
-         style = *linear* or *quadratic* or *mliappy*
+         style = *linear* or *quadratic* or *nn* or *mliappy*
          filename = name of file containing model definitions
        *descriptor* values = style filename
          style = *sna*
@@ -45,7 +45,7 @@ pair style currently supports just one descriptor style, but it is
 is straightforward to add new descriptor styles.
 The SNAP descriptor style *sna* is the same as that used by :doc:`pair_style snap <pair_snap>`,
 including the linear, quadratic, and chem variants.
-The available models are *linear*, *quadratic*, and *mliappy*.
+The available models are *linear*, *quadratic*, *nn*, and *mliappy*.
 The *mliappy* style can be used to couple python models,
 e.g. PyTorch neural network energy models, and requires building
 LAMMPS with the PYTHON package (see below).
@@ -77,13 +77,32 @@ line must contain two integers:
 * nelems  = Number of elements
 * nparams = Number of parameters
 
-This is followed by one block for each of the *nelem* elements.
+When the *model* keyword is *linear* or *quadratic*,
+this is followed by one block for each of the *nelem* elements.
 Each block consists of *nparams* parameters, one per line.
 Note that this format is similar, but not identical to that used
 for the :doc:`pair_style snap <pair_snap>` coefficient file.
 Specifically, the line containing the element weight and radius is omitted,
 since these are handled by the *descriptor*.
 
+When the *model* keyword is *nn* (neural networks), the model file can contain
+blank and comment lines (start with #) anywhere. The second non-blank non-comment
+line must contain the string NET, followed by two integers:
+
+* ndescriptors = Number of descriptors
+* nlayers      = Number of layers (including the hidden layers and the output layer)
+
+and followed by a sequence of a string and an integer for each layer:
+
+* Activation function (linear, sigmoid, tanh or relu)
+* nnodes = Number of nodes
+
+This is followed by one block for each of the *nelem* elements. Each block consists
+of *scale0* minimum value, *scale1* (maximum - minimum) value,
+in order to normalize the descriptors, followed by *nparams* parameters,
+including *bias* and *weights* of the model, starting with the first node of the first layer
+and so on, with a maximum of 30 values per line.
+
 Notes on mliappy models:
 When the *model* keyword is *mliappy*, the filename should end in '.pt',
 '.pth' for pytorch models, or be a pickle file. To load a model from

doc/src/pair_mm3_switch3_coulgauss_long.rst

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

doc/src/pair_polymorphic.rst

@@ -319,7 +319,7 @@ This pair style is part of the MANYBODY package. It is only enabled if
 LAMMPS was built with that package. See the :doc:`Build package
 <Build_package>` doc page for more info.
 
-This pair potential requires the :doc:`newtion <newton>` setting to be
+This pair potential requires the :doc:`newton <newton>` setting to be
 "on" for pair interactions.
 
 The potential files provided with LAMMPS (see the potentials directory)

doc/src/pair_snap.rst

@@ -88,9 +88,12 @@ that will be used with other potentials.
 
 The name of the SNAP coefficient file usually ends in the
 ".snapcoeff" extension. It may contain coefficients
-for many SNAP elements. The only requirement is that it
+for many SNAP elements. The only requirement is that
-contain at least those element names appearing in the
+each of the unique element names appearing in the
-LAMMPS mapping list.
+LAMMPS pair_coeff command appear exactly once in
+the SNAP coefficient file. It is okay if the SNAP coefficient file
+contains additional elements not in the pair_coeff command,
+except when using *chemflag* (see below).
 The name of the SNAP parameter file usually ends in the ".snapparam"
 extension. It contains a small number
 of parameters that define the overall form of the SNAP potential.
@@ -129,7 +132,7 @@ line must contain two integers:
 This is followed by one block for each of the *nelem* elements.
 The first line of each block contains three entries:
 
-* Element symbol (text string)
+* Element name (text string)
 * R = Element radius (distance units)
 * w = Element weight (dimensionless)
 
@@ -166,8 +169,8 @@ where :math:`\mathbf{B}_i` is the *K*-vector of bispectrum components,
 :math:`\boldsymbol{\beta}^{\mu_i}` is the *K*-vector of linear coefficients
 for element :math:`\mu_i`, and :math:`\boldsymbol{\alpha}^{\mu_i}`
 is the symmetric *K* by *K* matrix of quadratic coefficients.
-The SNAP element file should contain *K*\ (\ *K*\ +1)/2 additional coefficients
+The SNAP coefficient file should contain *K*\ (\ *K*\ +1)/2 additional coefficients
-for each element, the upper-triangular elements of :math:`\boldsymbol{\alpha}^{\mu_i}`.
+in each element block, the upper-triangular elements of :math:`\boldsymbol{\alpha}^{\mu_i}`.
 
 If *chemflag* is set to 1, then the energy expression is written in terms of explicit multi-element bispectrum
 components indexed on ordered triplets of elements, which has been shown to increase the ability of the SNAP
@@ -181,8 +184,12 @@ at the expense of a significant increase in computational cost :ref:`(Cusentino)
 where :math:`\mathbf{B}^{\kappa\lambda\mu}_i` is the *K*-vector of bispectrum components
 for neighbors of elements :math:`\kappa`, :math:`\lambda`, and :math:`\mu` and
 :math:`\boldsymbol{\beta}^{\kappa\lambda\mu}_{\mu_i}` is the corresponding *K*-vector
-of linear coefficients for element :math:`\mu_i`. The SNAP element file should contain
+of linear coefficients for element :math:`\mu_i`. The SNAP coefficient file should contain
-a total of :math:`K N_{elem}^3` coefficients for each of the :math:`N_{elem}` elements.
+a total of :math:`K N_{elem}^3` coefficients in each element block,
+where :math:`N_{elem}` is the number of elements in the SNAP coefficient file,
+which must equal the number of unique elements appearing in the
+LAMMPS pair_coeff command, to avoid ambiguity in the
+number of coefficients.
 
 The keyword *chunksize* is only applicable when using the
 pair style *snap* with the KOKKOS package and is ignored otherwise.

doc/src/pair_style.rst

@@ -227,6 +227,7 @@ accelerated styles exist.
 * :doc:`lj/long/dipole/long <pair_dipole>` - long-range LJ and long-range point dipoles
 * :doc:`lj/long/tip4p/long <pair_lj_long>` - long-range LJ and long-range Coulomb for TIP4P water
 * :doc:`lj/mdf <pair_mdf>` - LJ potential with a taper function
+* :doc:`lj/relres <pair_lj_relres>` - LJ using multiscale Relative Resolution (RelRes) methodology :ref:`(Chaimovich) <Chaimovich2>`.
 * :doc:`lj/sdk <pair_sdk>` - LJ for SDK coarse-graining
 * :doc:`lj/sdk/coul/long <pair_sdk>` - LJ for SDK coarse-graining with long-range Coulomb
 * :doc:`lj/sdk/coul/msm <pair_sdk>` - LJ for SDK coarse-graining with long-range Coulomb via MSM
@@ -249,7 +250,7 @@ accelerated styles exist.
 * :doc:`mgpt <pair_mgpt>` - simplified model generalized pseudopotential theory (MGPT) potential
 * :doc:`mesont/tpm <pair_mesont_tpm>` - nanotubes mesoscopic force field
 * :doc:`mie/cut <pair_mie>` - Mie potential
-* :doc:`mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>` - smoothed MM3 vdW potential with Gaussian electrostatics
+* :doc:`mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>` - smoothed MM3 vdW potential with Gaussian electrostatics
 * :doc:`momb <pair_momb>` - Many-Body Metal-Organic (MOMB) force field
 * :doc:`morse <pair_morse>` - Morse potential
 * :doc:`morse/smooth/linear <pair_morse>` - linear smoothed Morse potential

doc/src/pair_vashishta.rst

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