Merge pull request #3135 from akohlmey/next_patch_release

Step version strings for the next patch release

.github/workflows/compile-msvc.yml

@@ -1,5 +1,5 @@
 # GitHub action to build LAMMPS on Windows with Visual C++
-name: "Native Windows Compilation"
+name: "Native Windows Compilation and Unit Tests"
 
 on:
   push:
@@ -17,13 +17,21 @@ jobs:
       with:
         fetch-depth: 2
 
+    - name: Select Python version
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.10'
+
     - name: Building LAMMPS via CMake
       shell: bash
       run: |
+        python3 -m pip install numpy
         cmake -C cmake/presets/windows.cmake \
+              -D PKG_PYTHON=on \
               -S cmake -B build \
               -D BUILD_SHARED_LIBS=on \
-              -D LAMMPS_EXCEPTIONS=on
+              -D LAMMPS_EXCEPTIONS=on \
+              -D ENABLE_TESTING=on
         cmake --build build --config Release
 
     - name: Run LAMMPS executable
@@ -31,3 +39,8 @@ jobs:
       run: |
         ./build/Release/lmp.exe -h
         ./build/Release/lmp.exe -in bench/in.lj
+
+    - name: Run Unit Tests
+      working-directory: build
+      shell: bash
+      run: ctest -V -C Release

SECURITY.md

@@ -23,6 +23,10 @@ either a user mistake or a bug in the code.  Bugs can be reported in
 the LAMMPS project
 [issue tracker on GitHub](https://github.com/lammps/lammps/issues).
 
+To mitigate issues with using homoglyphs or bidirectional reordering in
+unicode, which have been demonstrated as a vector to obfuscate and hide
+malicious changes to the source code, all LAMMPS submissions are checked
+for unicode characters and only all-ASCII source code is accepted.
 
 # Version Updates
 

cmake/CMakeLists.txt

@@ -19,6 +19,9 @@ set(SOVERSION 0)
 
 get_filename_component(LAMMPS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/.. ABSOLUTE)
 get_filename_component(LAMMPS_LIB_BINARY_DIR ${CMAKE_BINARY_DIR}/lib ABSOLUTE)
+# collect all executables and shared libs in the top level build folder
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
 
 set(LAMMPS_SOURCE_DIR     ${LAMMPS_DIR}/src)
 set(LAMMPS_LIB_SOURCE_DIR ${LAMMPS_DIR}/lib)
@@ -133,10 +136,7 @@ endif()
 set(LAMMPS_BINARY lmp${LAMMPS_MACHINE})
 
 option(BUILD_SHARED_LIBS "Build shared library" OFF)
-if(BUILD_SHARED_LIBS) # for all pkg libs, mpi_stubs and linalg
-  set(CMAKE_POSITION_INDEPENDENT_CODE ON)
-endif()
-
+option(CMAKE_POSITION_INDEPENDENT_CODE "Create object compatible with shared libraries" ON)
 option(BUILD_TOOLS "Build and install LAMMPS tools (msi2lmp, binary2txt, chain)" OFF)
 option(BUILD_LAMMPS_SHELL "Build and install the LAMMPS shell" OFF)
 
@@ -283,33 +283,19 @@ if(BUILD_MPI)
   # We use a non-standard procedure to cross-compile with MPI on Windows
   if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND CMAKE_CROSSCOMPILING)
     include(MPI4WIN)
-    target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
   else()
     find_package(MPI REQUIRED)
-    target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
     option(LAMMPS_LONGLONG_TO_LONG "Workaround if your system or MPI version does not recognize 'long long' data types" OFF)
     if(LAMMPS_LONGLONG_TO_LONG)
       target_compile_definitions(lammps PRIVATE -DLAMMPS_LONGLONG_TO_LONG)
     endif()
   endif()
+  target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
 else()
-  file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
-  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>)
-  if(BUILD_SHARED_LIBS)
-    target_link_libraries(lammps PRIVATE mpi_stubs)
-    if(MSVC)
-      target_link_libraries(lmp PRIVATE mpi_stubs)
-      target_include_directories(lmp INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
-      target_compile_definitions(lmp INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
-    endif(MSVC)
-    target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
-    target_compile_definitions(lammps INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
-  else()
-    target_link_libraries(lammps PUBLIC mpi_stubs)
-  endif()
-  add_library(MPI::MPI_CXX ALIAS mpi_stubs)
+  target_sources(lammps PRIVATE ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
+  add_library(mpi_stubs INTERFACE)
+  target_include_directories(mpi_stubs INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
+  target_link_libraries(lammps PUBLIC mpi_stubs)
 endif()
 
 set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallsmall: all 32-bit, smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)")
@@ -340,7 +326,6 @@ pkg_depends(ML-IAP ML-SNAP)
 pkg_depends(MPIIO MPI)
 pkg_depends(ATC MANYBODY)
 pkg_depends(LATBOLTZ MPI)
-pkg_depends(PHONON KSPACE)
 pkg_depends(SCAFACOS MPI)
 pkg_depends(DIELECTRIC KSPACE)
 pkg_depends(DIELECTRIC EXTRA-PAIR)
@@ -374,11 +359,13 @@ if(BUILD_OMP)
       ((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 19.0)))
     # GCC 9.x and later plus Clang 10.x and later implement strict OpenMP 4.0 semantics for consts.
     # Intel 18.0 was tested to support both, so we switch to OpenMP 4+ from 19.x onward to be safe.
-    target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=4)
+    set(LAMMPS_OMP_COMPAT_LEVEL 4)
   else()
-    target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=3)
+    set(LAMMPS_OMP_COMPAT_LEVEL 3)
   endif()
+  target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=${LAMMPS_OMP_COMPAT_LEVEL})
   target_link_libraries(lammps PRIVATE OpenMP::OpenMP_CXX)
+  target_link_libraries(lmp PRIVATE OpenMP::OpenMP_CXX)
 endif()
 
 if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_LATTE)
@@ -592,11 +579,10 @@ if(PKG_ATC)
   if(LAMMPS_SIZES STREQUAL "BIGBIG")
     message(FATAL_ERROR "The ATC Package is not compatible with -DLAMMPS_BIGBIG")
   endif()
-  target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES})
   if(BUILD_MPI)
-    target_link_libraries(atc PRIVATE MPI::MPI_CXX)
+    target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES} MPI::MPI_CXX)
   else()
-    target_link_libraries(atc PRIVATE mpi_stubs)
+    target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES} mpi_stubs)
   endif()
   target_include_directories(atc PRIVATE ${LAMMPS_SOURCE_DIR})
   target_compile_definitions(atc PRIVATE -DLAMMPS_${LAMMPS_SIZES})
@@ -610,7 +596,7 @@ endif()
 # packages which selectively include variants based on enabled styles
 # e.g. accelerator packages
 ######################################################################
-foreach(PKG_WITH_INCL CORESHELL QEQ OPENMP DPD-SMOOTH KOKKOS OPT INTEL GPU)
+foreach(PKG_WITH_INCL CORESHELL DPD-SMOOTH PHONON QEQ OPENMP KOKKOS OPT INTEL GPU)
   if(PKG_${PKG_WITH_INCL})
     include(Packages/${PKG_WITH_INCL})
   endif()
@@ -692,6 +678,7 @@ endif()
 
 set_target_properties(lammps PROPERTIES OUTPUT_NAME lammps${LAMMPS_MACHINE})
 set_target_properties(lammps PROPERTIES SOVERSION ${SOVERSION})
+set_target_properties(lammps PROPERTIES PREFIX "lib")
 target_include_directories(lammps PUBLIC $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/lammps>)
 file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps)
 foreach(_HEADER ${LAMMPS_CXX_HEADERS})
@@ -711,6 +698,9 @@ foreach(_DEF ${LAMMPS_DEFINES})
 endforeach()
 if(BUILD_SHARED_LIBS)
   install(TARGETS lammps EXPORT LAMMPS_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+  if(NOT BUILD_MPI)
+    install(TARGETS mpi_stubs EXPORT LAMMPS_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+  endif()
   configure_file(pkgconfig/liblammps.pc.in ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc @ONLY)
   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)
   install(EXPORT LAMMPS_Targets FILE LAMMPS_Targets.cmake NAMESPACE LAMMPS:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/LAMMPS)
@@ -750,7 +740,7 @@ install(
 if(BUILD_SHARED_LIBS)
   if(CMAKE_VERSION VERSION_LESS 3.12)
     # adjust so we find Python 3 versions before Python 2 on old systems with old CMake
-    set(Python_ADDITIONAL_VERSIONS 3.9 3.8 3.7 3.6 3.5)
+    set(Python_ADDITIONAL_VERSIONS 3.12 3.11 3.10 3.9 3.8 3.7 3.6)
     find_package(PythonInterp) # Deprecated since version 3.12
     if(PYTHONINTERP_FOUND)
         set(Python_EXECUTABLE ${PYTHON_EXECUTABLE})
@@ -809,11 +799,17 @@ if(ClangFormat_FOUND)
 endif()
 
 get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
+get_property(BUILD_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
+if(BUILD_IS_MULTI_CONFIG)
+  set(LAMMPS_BUILD_TYPE "Multi-Config")
+else()
+  set(LAMMPS_BUILD_TYPE ${CMAKE_BUILD_TYPE})
+endif()
 include(FeatureSummary)
 feature_summary(DESCRIPTION "The following tools and libraries have been found and configured:" WHAT PACKAGES_FOUND)
 message(STATUS "<<< Build configuration >>>
    Operating System: ${CMAKE_SYSTEM_NAME} ${CMAKE_LINUX_DISTRO} ${CMAKE_DISTRO_VERSION}
-   Build type:       ${CMAKE_BUILD_TYPE}
+   Build type:       ${LAMMPS_BUILD_TYPE}
    Install path:     ${CMAKE_INSTALL_PREFIX}
    Generator:        ${CMAKE_GENERATOR} using ${CMAKE_MAKE_PROGRAM}")
 ###############################################################################

cmake/CMakeSettings.json

@@ -1,55 +1,204 @@
 {
-    "configurations": [
+  "configurations": [
+    {
+      "name": "x64-Debug-MSVC",
+      "generator": "Ninja",
+      "configurationType": "Debug",
+      "buildRoot": "${workspaceRoot}\\build\\${name}",
+      "installRoot": "${workspaceRoot}\\install\\${name}",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
+      "buildCommandArgs": "",
+      "ctestCommandArgs": "",
+      "inheritEnvironments": [ "msvc_x64_x64" ],
+      "variables": [
         {
-            "name": "x64-Debug-MSVC",
-            "generator": "Ninja",
-            "configurationType": "Debug",
-            "buildRoot": "${workspaceRoot}\\build\\${name}",
-            "installRoot": "${workspaceRoot}\\install\\${name}",
-            "cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
-            "buildCommandArgs": "",
-            "ctestCommandArgs": "",
-            "inheritEnvironments": [ "msvc_x64_x64" ],
-            "variables": [
-                {
-                    "name": "BUILD_SHARED_LIBS",
-                    "value": "True",
-                    "type": "BOOL"
-                },
-                {
-                    "name": "BUILD_TOOLS",
-                    "value": "True",
-                    "type": "BOOL"
-                },
-                {
-                    "name": "LAMMPS_EXCEPTIONS",
-                    "value": "True",
-                    "type": "BOOL"
-                }
-            ]
+          "name": "BUILD_SHARED_LIBS",
+          "value": "True",
+          "type": "BOOL"
         },
         {
-            "name": "x64-Debug-Clang",
-            "generator": "Ninja",
-            "configurationType": "Debug",
-            "buildRoot": "${workspaceRoot}\\build\\${name}",
-            "installRoot": "${workspaceRoot}\\install\\${name}",
-            "cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
-            "buildCommandArgs": "",
-            "ctestCommandArgs": "",
-            "inheritEnvironments": [ "clang_cl_x64" ],
-            "variables": [
-                {
-                    "name": "BUILD_TOOLS",
-                    "value": "True",
-                    "type": "BOOL"
-                },
-                {
-                    "name": "LAMMPS_EXCEPTIONS",
-                    "value": "True",
-                    "type": "BOOL"
-                }
-            ]
+          "name": "BUILD_TOOLS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "LAMMPS_EXCEPTIONS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "PKG_PYTHON",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "ENABLE_TESTING",
+          "value": "True",
+          "type": "BOOL"
         }
-    ]
-}
+      ]
+    },
+    {
+      "name": "x64-Release-MSVC",
+      "generator": "Ninja",
+      "configurationType": "Release",
+      "buildRoot": "${workspaceRoot}\\build\\${name}",
+      "installRoot": "${workspaceRoot}\\install\\${name}",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
+      "buildCommandArgs": "",
+      "ctestCommandArgs": "",
+      "inheritEnvironments": [ "msvc_x64_x64" ],
+      "variables": [
+        {
+          "name": "BUILD_SHARED_LIBS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "BUILD_TOOLS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "LAMMPS_EXCEPTIONS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "PKG_PYTHON",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "ENABLE_TESTING",
+          "value": "True",
+          "type": "BOOL"
+        }
+      ]
+    },
+    {
+      "name": "x64-Debug-Clang",
+      "generator": "Ninja",
+      "configurationType": "Debug",
+      "buildRoot": "${workspaceRoot}\\build\\${name}",
+      "installRoot": "${workspaceRoot}\\install\\${name}",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
+      "buildCommandArgs": "",
+      "ctestCommandArgs": "",
+      "inheritEnvironments": [ "clang_cl_x64" ],
+      "variables": [
+        {
+          "name": "BUILD_SHARED_LIBS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "BUILD_TOOLS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "LAMMPS_EXCEPTIONS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "PKG_PYTHON",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "ENABLE_TESTING",
+          "value": "True",
+          "type": "BOOL"
+        }
+      ]
+    },
+    {
+      "name": "x64-Debug-OneAPI",
+      "generator": "Ninja",
+      "configurationType": "Debug",
+      "buildRoot": "${workspaceRoot}\\build\\${name}",
+      "installRoot": "${workspaceRoot}\\install\\${name}",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_CXX_COMPILER=icx -DCMAKE_C_COMPILER=icx",
+      "buildCommandArgs": "",
+      "ctestCommandArgs": "",
+      "inheritEnvironments": [ "msvc_x64_x64" ],
+      "variables": [
+        {
+          "name": "BUILD_SHARED_LIBS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "BUILD_TOOLS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "LAMMPS_EXCEPTIONS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "PKG_PYTHON",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "ENABLE_TESTING",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "BUILD_MPI",
+          "value": "False",
+          "type": "BOOL"
+        }
+      ]
+    },
+    {
+      "name": "x64-Debug-Intel",
+      "generator": "Ninja",
+      "configurationType": "Debug",
+      "buildRoot": "${workspaceRoot}\\build\\${name}",
+      "installRoot": "${workspaceRoot}\\install\\${name}",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_CXX_COMPILER=icl -DCMAKE_C_COMPILER=icl -DCMAKE_Fortran_COMPILER=ifort",
+      "buildCommandArgs": "",
+      "ctestCommandArgs": "",
+      "inheritEnvironments": [ "msvc_x64_x64" ],
+      "variables": [
+        {
+          "name": "BUILD_SHARED_LIBS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "BUILD_TOOLS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "LAMMPS_EXCEPTIONS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "PKG_PYTHON",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "ENABLE_TESTING",
+          "value": "False",
+          "type": "BOOL"
+        },
+        {
+          "name": "BUILD_MPI",
+          "value": "False",
+          "type": "BOOL"
+        }
+      ]
+    }
+  ]
+}

cmake/Modules/ExternalCMakeProject.cmake

@@ -0,0 +1,33 @@
+# Build a CMake based external library as subdirectory.
+# The sources will be unpacked to ${CMAKE_BINARY_DIR}/_deps/${target}-src
+# The binaries will be built in ${CMAKE_BINARY_DIR}/_deps/${target}-build
+#
+function(ExternalCMakeProject target url hash basedir cmakedir cmakefile)
+  # change settings locally
+  set(BUILD_SHARED_LIBS OFF)
+  set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+  get_filename_component(archive ${url} NAME)
+  file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/_deps/src)
+  message(STATUS "Downloading ${url}")
+  file(DOWNLOAD ${url} ${CMAKE_BINARY_DIR}/_deps/${archive} EXPECTED_HASH MD5=${hash} SHOW_PROGRESS)
+  message(STATUS "Unpacking and configuring ${archive}")
+  execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf ${CMAKE_BINARY_DIR}/_deps/${archive}
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/_deps/src)
+  file(GLOB TARGET_SOURCE "${CMAKE_BINARY_DIR}/_deps/src/${basedir}*")
+  list(LENGTH TARGET_SOURCE _num)
+  if(_num GREATER 1)
+    message(FATAL_ERROR "Inconsistent ${target} library sources. "
+      "Please delete ${CMAKE_BINARY_DIR}/_deps/src and re-run cmake")
+  endif()
+  file(REMOVE_RECURSE ${CMAKE_BINARY_DIR}/_deps/${target}-src)
+  file(RENAME ${TARGET_SOURCE} ${CMAKE_BINARY_DIR}/_deps/${target}-src)
+  if(NOT (cmakefile STREQUAL ""))
+    file(COPY ${cmakefile} DESTINATION ${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/)
+    get_filename_component(_cmakefile ${cmakefile} NAME)
+    file(RENAME "${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/${_cmakefile}"
+      "${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}/CMakeLists.txt")
+  endif()
+  add_subdirectory("${CMAKE_BINARY_DIR}/_deps/${target}-src/${cmakedir}"
+    "${CMAKE_BINARY_DIR}/_deps/${target}-build")
+endfunction(ExternalCMakeProject)

cmake/Modules/FindCythonize.cmake

@@ -8,18 +8,19 @@
 #=============================================================================
 
 if(CMAKE_VERSION VERSION_LESS 3.12)
+    set(Python_ADDITIONAL_VERSIONS 3.12 3.11 3.10 3.9 3.8 3.7 3.6)
     find_package(PythonInterp 3.6 QUIET) # Deprecated since version 3.12
     if(PYTHONINTERP_FOUND)
-        set(Python3_EXECUTABLE ${PYTHON_EXECUTABLE})
+        set(Python_EXECUTABLE ${PYTHON_EXECUTABLE})
     endif()
 else()
-    find_package(Python3 3.6 COMPONENTS Interpreter QUIET)
+    find_package(Python 3.6 COMPONENTS Interpreter QUIET)
 endif()
 
 # Use the Cython executable that lives next to the Python executable
 # if it is a local installation.
-if(Python3_EXECUTABLE)
-  get_filename_component(_python_path ${Python3_EXECUTABLE} PATH)
+if(Python_EXECUTABLE)
+  get_filename_component(_python_path ${Python_EXECUTABLE} PATH)
   find_program(Cythonize_EXECUTABLE
     NAMES cythonize3 cythonize cythonize.bat
     HINTS ${_python_path})

cmake/Modules/GTest.cmake

@@ -1,81 +0,0 @@
-message(STATUS "Downloading and building Google Test library")
-
-if(CMAKE_BUILD_TYPE STREQUAL "Debug")
-  set(GTEST_LIB_POSTFIX d)
-else()
-  set(GTEST_LIB_POSTFIX)
-endif()
-
-include(ExternalProject)
-set(GTEST_URL "https://github.com/google/googletest/archive/release-1.11.0.tar.gz" CACHE STRING "URL of googletest source")
-set(GTEST_MD5 "e8a8df240b6938bb6384155d4c37d937" CACHE STRING "MD5 sum for googletest source")
-mark_as_advanced(GTEST_URL)
-mark_as_advanced(GTEST_MD5)
-ExternalProject_Add(googletest
-                    URL             ${GTEST_URL}
-                    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}
-                                    -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>/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
-                                     <BINARY_DIR>/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
-                                     <BINARY_DIR>/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
-                                     <BINARY_DIR>/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
-                    LOG_DOWNLOAD ON
-                    LOG_CONFIGURE ON
-                    LOG_BUILD ON
-                    INSTALL_COMMAND ""
-                    TEST_COMMAND    "")
-
-ExternalProject_Get_Property(googletest SOURCE_DIR)
-set(GTEST_INCLUDE_DIR ${SOURCE_DIR}/googletest/include)
-set(GMOCK_INCLUDE_DIR ${SOURCE_DIR}/googlemock/include)
-
-# workaround for CMake 3.10 on ubuntu 18.04
-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/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
-set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
-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/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
-
-# Prevent GoogleTest from overriding our compiler/linker options
-# when building with Visual Studio
-set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
-
-find_package(Threads QUIET)
-
-add_library(GTest::GTest UNKNOWN IMPORTED)
-set_target_properties(GTest::GTest PROPERTIES
-        IMPORTED_LOCATION ${GTEST_LIBRARY_PATH}
-        INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
-        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
-add_dependencies(GTest::GTest googletest)
-
-add_library(GTest::GMock UNKNOWN IMPORTED)
-set_target_properties(GTest::GMock PROPERTIES
-        IMPORTED_LOCATION ${GMOCK_LIBRARY_PATH}
-        INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
-        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
-add_dependencies(GTest::GMock googletest)
-
-add_library(GTest::GTestMain UNKNOWN IMPORTED)
-set_target_properties(GTest::GTestMain PROPERTIES
-        IMPORTED_LOCATION ${GTEST_MAIN_LIBRARY_PATH}
-        INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
-        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
-add_dependencies(GTest::GTestMain googletest)
-
-add_library(GTest::GMockMain UNKNOWN IMPORTED)
-set_target_properties(GTest::GMockMain PROPERTIES
-        IMPORTED_LOCATION ${GMOCK_MAIN_LIBRARY_PATH}
-        INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
-        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
-add_dependencies(GTest::GMockMain googletest)

cmake/Modules/LAMMPSUtils.cmake

@@ -25,7 +25,7 @@ function(validate_option name values)
 endfunction(validate_option)
 
 function(get_lammps_version version_header variable)
-    file(READ ${version_header} line)
+    file(STRINGS ${version_header} line REGEX LAMMPS_VERSION)
     set(MONTHS x Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec)
     string(REGEX REPLACE "#define LAMMPS_VERSION \"([0-9]+) ([A-Za-z]+) ([0-9]+)\"" "\\1" day "${line}")
     string(REGEX REPLACE "#define LAMMPS_VERSION \"([0-9]+) ([A-Za-z]+) ([0-9]+)\"" "\\2" month "${line}")

cmake/Modules/OpenCLLoader.cmake

@@ -1,50 +1,11 @@
 message(STATUS "Downloading and building OpenCL loader library")
-set(OPENCL_LOADER_URL "${LAMMPS_THIRDPARTY_URL}/opencl-loader-2021.09.18.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
-set(OPENCL_LOADER_MD5 "3b3882627964bd02e5c3b02065daac3c" CACHE STRING "MD5 checksum of OpenCL loader tarball")
+set(OPENCL_LOADER_URL "${LAMMPS_THIRDPARTY_URL}/opencl-loader-2022.01.04.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
+set(OPENCL_LOADER_MD5 "8d3a801e87a2c6653bf0e27707063914" 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}")
-
+set(INSTALL_LIBOPENCL OFF CACHE BOOL "" FORCE)
+include(ExternalCMakeProject)
+ExternalCMakeProject(opencl_loader ${OPENCL_LOADER_URL} ${OPENCL_LOADER_MD5} opencl-loader . "")
 
+add_library(OpenCL::OpenCL ALIAS OpenCL)

cmake/Modules/Packages/COMPRESS.cmake

@@ -1,10 +1,11 @@
 find_package(ZLIB REQUIRED)
 target_link_libraries(lammps PRIVATE ZLIB::ZLIB)
 
-find_package(PkgConfig REQUIRED)
-pkg_check_modules(Zstd IMPORTED_TARGET libzstd>=1.4)
-
-if(Zstd_FOUND)
+find_package(PkgConfig QUIET)
+if(PkgConfig_FOUND)
+  pkg_check_modules(Zstd IMPORTED_TARGET libzstd>=1.4)
+  if(Zstd_FOUND)
     target_compile_definitions(lammps PRIVATE -DLAMMPS_ZSTD)
     target_link_libraries(lammps PRIVATE PkgConfig::Zstd)
+  endif()
 endif()

cmake/Modules/Packages/GPU.cmake

@@ -306,12 +306,12 @@ elseif(GPU_API STREQUAL "HIP")
 
         if(HIP_COMPILER STREQUAL "clang")
           add_custom_command(OUTPUT ${CUBIN_FILE}
-            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
+            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
             DEPENDS ${CU_CPP_FILE}
             COMMENT "Generating ${CU_NAME}.cubin")
         else()
           add_custom_command(OUTPUT ${CUBIN_FILE}
-            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
+            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
             DEPENDS ${CU_CPP_FILE}
             COMMENT "Generating ${CU_NAME}.cubin")
         endif()
@@ -422,13 +422,12 @@ RegisterStylesExt(${GPU_SOURCES_DIR} gpu GPU_SOURCES)
 RegisterFixStyle(${GPU_SOURCES_DIR}/fix_gpu.h)
 
 get_property(GPU_SOURCES GLOBAL PROPERTY GPU_SOURCES)
-
-if(NOT BUILD_MPI)
-  # mpistubs is aliased to MPI::MPI_CXX, but older versions of cmake won't work forward the include path
-  target_link_libraries(gpu PRIVATE mpi_stubs)
-else()
+if(BUILD_MPI)
   target_link_libraries(gpu PRIVATE MPI::MPI_CXX)
+else()
+  target_link_libraries(gpu PRIVATE mpi_stubs)
 endif()
+
 target_compile_definitions(gpu PRIVATE -DLAMMPS_${LAMMPS_SIZES})
 set_target_properties(gpu PROPERTIES OUTPUT_NAME lammps_gpu${LAMMPS_MACHINE})
 target_sources(lammps PRIVATE ${GPU_SOURCES})

cmake/Modules/Packages/KOKKOS.cmake

@@ -11,8 +11,14 @@ if(Kokkos_ENABLE_CUDA)
 endif()
 # Adding OpenMP compiler flags without the checks done for
 # BUILD_OMP can result in compile failures. Enforce consistency.
-if(Kokkos_ENABLE_OPENMP AND NOT BUILD_OMP)
-  message(FATAL_ERROR "Must enable BUILD_OMP with Kokkos_ENABLE_OPENMP")
+if(Kokkos_ENABLE_OPENMP)
+  if(NOT BUILD_OMP)
+    message(FATAL_ERROR "Must enable BUILD_OMP with Kokkos_ENABLE_OPENMP")
+  else()
+    if(LAMMPS_OMP_COMPAT_LEVEL LESS 4)
+      message(FATAL_ERROR "Compiler must support OpenMP 4.0 or later with Kokkos_ENABLE_OPENMP")
+    endif()
+  endif()
 endif()
 ########################################################################
 
@@ -27,6 +33,8 @@ if(DOWNLOAD_KOKKOS)
   endforeach()
   message(STATUS "KOKKOS download requested - we will build our own")
   list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>")
+  # build KOKKOS downloaded libraries as static libraries but with PIC, if needed
+  list(APPEND KOKKOS_LIB_BUILD_ARGS "-DBUILD_SHARED_LIBS=OFF")
   if(CMAKE_REQUEST_PIC)
     list(APPEND KOKKOS_LIB_BUILD_ARGS ${CMAKE_REQUEST_PIC})
   endif()
@@ -39,35 +47,48 @@ 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.4.01.tar.gz" CACHE STRING "URL for KOKKOS tarball")
-  set(KOKKOS_MD5 "4c84698917c93a18985b311bb6caf84f" CACHE STRING "MD5 checksum of KOKKOS tarball")
+  set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/3.5.00.tar.gz" CACHE STRING "URL for KOKKOS tarball")
+  set(KOKKOS_MD5 "079323d973ae0e1c38c0a54a150c674e" CACHE STRING "MD5 checksum of KOKKOS tarball")
   mark_as_advanced(KOKKOS_URL)
   mark_as_advanced(KOKKOS_MD5)
   ExternalProject_Add(kokkos_build
     URL     ${KOKKOS_URL}
     URL_MD5 ${KOKKOS_MD5}
     CMAKE_ARGS ${KOKKOS_LIB_BUILD_ARGS}
-    BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a
+    BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a <INSTALL_DIR>/lib/libkokkoscontainers.a
   )
   ExternalProject_get_property(kokkos_build INSTALL_DIR)
   file(MAKE_DIRECTORY ${INSTALL_DIR}/include)
-  add_library(LAMMPS::KOKKOS UNKNOWN IMPORTED)
-  set_target_properties(LAMMPS::KOKKOS PROPERTIES
+  add_library(LAMMPS::KOKKOSCORE UNKNOWN IMPORTED)
+  add_library(LAMMPS::KOKKOSCONTAINERS UNKNOWN IMPORTED)
+  set_target_properties(LAMMPS::KOKKOSCORE PROPERTIES
     IMPORTED_LOCATION "${INSTALL_DIR}/lib/libkokkoscore.a"
     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)
+  set_target_properties(LAMMPS::KOKKOSCONTAINERS PROPERTIES
+    IMPORTED_LOCATION "${INSTALL_DIR}/lib/libkokkoscontainers.a")
+  target_link_libraries(lammps PRIVATE LAMMPS::KOKKOSCORE LAMMPS::KOKKOSCONTAINERS)
+  target_link_libraries(lmp PRIVATE LAMMPS::KOKKOSCORE LAMMPS::KOKKOSCONTAINERS)
+  add_dependencies(LAMMPS::KOKKOSCORE kokkos_build)
+  add_dependencies(LAMMPS::KOKKOSCONTAINERS kokkos_build)
 elseif(EXTERNAL_KOKKOS)
-  find_package(Kokkos 3.4.01 REQUIRED CONFIG)
+  find_package(Kokkos 3.5.00 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)
+  # build KOKKOS internal libraries as static libraries but with PIC, if needed
+  if(BUILD_SHARED_LIBS)
+    set(BUILD_SHARED_LIBS_WAS_ON YES)
+    set(BUILD_SHARED_LIBS OFF)
+  endif()
+  if(CMAKE_REQUEST_PIC)
+    set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+  endif()
   add_subdirectory(${LAMMPS_LIB_KOKKOS_SRC_DIR} ${LAMMPS_LIB_KOKKOS_BIN_DIR})
 
+
   set(Kokkos_INCLUDE_DIRS ${LAMMPS_LIB_KOKKOS_SRC_DIR}/core/src
                           ${LAMMPS_LIB_KOKKOS_SRC_DIR}/containers/src
                           ${LAMMPS_LIB_KOKKOS_SRC_DIR}/algorithms/src
@@ -75,6 +96,9 @@ else()
   target_include_directories(lammps PRIVATE ${Kokkos_INCLUDE_DIRS})
   target_link_libraries(lammps PRIVATE kokkos)
   target_link_libraries(lmp PRIVATE kokkos)
+  if(BUILD_SHARED_LIBS_WAS_ON)
+    set(BUILD_SHARED_LIBS ON)
+  endif()
 endif()
 target_compile_definitions(lammps PUBLIC $<BUILD_INTERFACE:LMP_KOKKOS>)
 
@@ -109,6 +133,12 @@ if(PKG_KSPACE)
   endif()
 endif()
 
+
+if(PKG_PHONON)
+  list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/dynamical_matrix_kokkos.cpp)
+  list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/third_order_kokkos.cpp)
+endif()
+
 set_property(GLOBAL PROPERTY "KOKKOS_PKG_SOURCES" "${KOKKOS_PKG_SOURCES}")
 
 # detects styles which have KOKKOS version

cmake/Modules/Packages/ML-HDNNP.cmake

@@ -46,12 +46,10 @@ if(DOWNLOAD_N2P2)
     if((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING)
       get_target_property(N2P2_MPI_INCLUDE MPI::MPI_CXX INTERFACE_INCLUDE_DIRECTORIES)
       set(N2P2_PROJECT_OPTIONS "-I${N2P2_MPI_INCLUDE}")
-      set(MPI_CXX_COMPILER ${CMAKE_CXX_COMPILER})
     endif()
     if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
       get_target_property(N2P2_MPI_INCLUDE MPI::MPI_CXX INTERFACE_INCLUDE_DIRECTORIES)
       set(N2P2_PROJECT_OPTIONS "-I${N2P2_MPI_INCLUDE}")
-      set(MPI_CXX_COMPILER ${CMAKE_CXX_COMPILER})
     endif()
   endif()
 
@@ -64,8 +62,8 @@ if(DOWNLOAD_N2P2)
   string(TOUPPER "${CMAKE_BUILD_TYPE}" BTYPE)
   set(N2P2_BUILD_FLAGS "${CMAKE_SHARED_LIBRARY_CXX_FLAGS} ${CMAKE_CXX_FLAGS} ${CMAKE_CXX_FLAGS_${BTYPE}} ${N2P2_CXX_STD}")
   set(N2P2_BUILD_OPTIONS INTERFACES=LAMMPS COMP=${N2P2_COMP} "PROJECT_OPTIONS=${N2P2_PROJECT_OPTIONS}" "PROJECT_DEBUG="
-    "PROJECT_CC=${CMAKE_CXX_COMPILER}" "PROJECT_MPICC=${MPI_CXX_COMPILER}" "PROJECT_CFLAGS=${N2P2_BUILD_FLAGS}"
-    "PROJECT_AR=${N2P2_AR}")
+    "PROJECT_CC=${CMAKE_CXX_COMPILER}" "PROJECT_MPICC=${CMAKE_CXX_COMPILER}" "PROJECT_CFLAGS=${N2P2_BUILD_FLAGS}"
+    "PROJECT_AR=${N2P2_AR}" "APP_CORE=nnp-convert" "APP_TRAIN=nnp-train" "APP=nnp-convert")
   # echo final flag for debugging
   message(STATUS "N2P2 BUILD OPTIONS: ${N2P2_BUILD_OPTIONS}")
 

cmake/Modules/Packages/ML-QUIP.cmake

@@ -32,7 +32,8 @@ if(DOWNLOAD_QUIP)
   foreach(flag ${LAPACK_LIBRARIES})
     set(temp "${temp} ${flag}")
   endforeach()
-  set(temp "${temp}\n")
+  # Fix cmake crashing when MATH_LINKOPTS not set, required for e.g. recent Cray Programming Environment
+  set(temp "${temp} -L/_DUMMY_PATH_\n")
   set(temp "${temp}PYTHON=python\nPIP=pip\nEXTRA_LINKOPTS=\n")
   set(temp "${temp}HAVE_CP2K=0\nHAVE_VASP=0\nHAVE_TB=0\nHAVE_PRECON=1\nHAVE_LOTF=0\nHAVE_ONIOM=0\n")
   set(temp "${temp}HAVE_LOCAL_E_MIX=0\nHAVE_QC=0\nHAVE_GAP=1\nHAVE_DESCRIPTORS_NONCOMMERCIAL=1\n")

cmake/Modules/Packages/MSCG.cmake

@@ -12,41 +12,12 @@ if(DOWNLOAD_MSCG)
   mark_as_advanced(MSCG_URL)
   mark_as_advanced(MSCG_MD5)
 
-  # CMake cannot pass BLAS or LAPACK library variable to external project if they are a list
-  list(LENGTH BLAS_LIBRARIES} NUM_BLAS)
-  list(LENGTH LAPACK_LIBRARIES NUM_LAPACK)
-  if((NUM_BLAS GREATER 1) OR (NUM_LAPACK GREATER 1))
-    message(FATAL_ERROR "Cannot compile downloaded MSCG library due to a technical limitation")
-  endif()
+  include(ExternalCMakeProject)
+  ExternalCMakeProject(mscg ${MSCG_URL} ${MSCG_MD5} MSCG-release src/CMake "")
 
-  include(ExternalProject)
-  ExternalProject_Add(mscg_build
-    URL     ${MSCG_URL}
-    URL_MD5 ${MSCG_MD5}
-    SOURCE_SUBDIR src/CMake
-    CMAKE_ARGS ${CMAKE_REQUEST_PIC} ${EXTRA_MSCG_OPTS}
-               -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
-               -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
-               -DCMAKE_Fortran_COMPILER=${CMAKE_Fortran_COMPILER}
-               -DBLAS_LIBRARIES=${BLAS_LIBRARIES} -DLAPACK_LIBRARIES=${LAPACK_LIBRARIES}
-               -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
-               -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
-               -DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
-               -DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
-    BUILD_COMMAND ${CMAKE_COMMAND} --build . --target mscg
-    INSTALL_COMMAND ""
-    BUILD_BYPRODUCTS <BINARY_DIR>/libmscg.a
-    )
-  ExternalProject_get_property(mscg_build BINARY_DIR)
-  ExternalProject_get_property(mscg_build SOURCE_DIR)
-  file(MAKE_DIRECTORY ${SOURCE_DIR}/src)
-  add_library(LAMMPS::MSCG UNKNOWN IMPORTED)
-  set_target_properties(LAMMPS::MSCG PROPERTIES
-    IMPORTED_LOCATION "${BINARY_DIR}/libmscg.a"
-    INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/src"
-    INTERFACE_LINK_LIBRARIES "${LAPACK_LIBRARIES}")
-  target_link_libraries(lammps PRIVATE LAMMPS::MSCG)
-  add_dependencies(LAMMPS::MSCG mscg_build)
+  # set include and link library
+  target_include_directories(lammps PRIVATE "${CMAKE_BINARY_DIR}/_deps/mscg-src/src")
+  target_link_libraries(lammps PRIVATE mscg)
 else()
   find_package(MSCG)
   if(NOT MSCG_FOUND)

cmake/Modules/Packages/PHONON.cmake

@@ -0,0 +1,9 @@
+# fix phonon may only be installed if also the FFT wrappers from KSPACE are installed
+if(NOT PKG_KSPACE)
+  get_property(LAMMPS_FIX_HEADERS GLOBAL PROPERTY FIX)
+  list(REMOVE_ITEM LAMMPS_FIX_HEADERS ${LAMMPS_SOURCE_DIR}/PHONON/fix_phonon.h)
+  set_property(GLOBAL PROPERTY FIX "${LAMMPS_FIX_HEADERS}")
+  get_target_property(LAMMPS_SOURCES lammps SOURCES)
+  list(REMOVE_ITEM LAMMPS_SOURCES ${LAMMPS_SOURCE_DIR}/PHONON/fix_phonon.cpp)
+  set_property(TARGET lammps PROPERTY SOURCES "${LAMMPS_SOURCES}")
+endif()

cmake/Modules/Packages/PLUMED.cmake

@@ -54,8 +54,8 @@ if(DOWNLOAD_PLUMED)
     set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/libplumedWrapper.a")
   endif()
 
-  set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.7.2/plumed-src-2.7.2.tgz" CACHE STRING "URL for PLUMED tarball")
-  set(PLUMED_MD5 "cfa0b4dd90a81c25d3302e8d97bfeaea" CACHE STRING "MD5 checksum of PLUMED tarball")
+  set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.7.3/plumed-src-2.7.3.tgz" CACHE STRING "URL for PLUMED tarball")
+  set(PLUMED_MD5 "f00cc82edfefe6bb3df934911dbe32fb" CACHE STRING "MD5 checksum of PLUMED tarball")
 
   mark_as_advanced(PLUMED_URL)
   mark_as_advanced(PLUMED_MD5)

cmake/Modules/Packages/PYTHON.cmake

@@ -3,7 +3,7 @@ if(CMAKE_VERSION VERSION_LESS 3.12)
   target_include_directories(lammps PRIVATE ${PYTHON_INCLUDE_DIRS})
   target_link_libraries(lammps PRIVATE ${PYTHON_LIBRARIES})
 else()
-  find_package(Python REQUIRED COMPONENTS Development)
+  find_package(Python REQUIRED COMPONENTS Interpreter Development)
   target_link_libraries(lammps PRIVATE Python::Python)
 endif()
 target_compile_definitions(lammps PRIVATE -DLMP_PYTHON)

cmake/Modules/YAML.cmake

@@ -1,47 +0,0 @@
-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)
-
-# support cross-compilation to windows
-if(CMAKE_CROSSCOMPILING AND (CMAKE_SYSTEM_NAME STREQUAL "Windows"))
-  if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86")
-    set(YAML_CROSS_HOST --host=i686-mingw64)
-  elseif(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
-    set(YAML_CROSS_HOST --host=x86_64-mingw64)
-  else()
-    message(FATAL_ERROR "Unsupported cross-compilation "
-      " for ${CMAKE_SYSTEM_NAME}/${CMAKE_SYSTEM_PROCESSOR}"
-      " on ${CMAKE_HOST_SYSTEM}/${CMAKE_HOST_SYSTEM_PROCESSOR}")
-  endif()
-endif()
-
-ExternalProject_Add(libyaml
-                    URL               ${YAML_URL}
-                    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 ${YAML_CROSS_HOST}
-                    BUILD_BYPRODUCTS  <INSTALL_DIR>/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX}
-                    TEST_COMMAND      "")
-
-ExternalProject_Get_Property(libyaml INSTALL_DIR)
-set(YAML_INCLUDE_DIR ${INSTALL_DIR}/include)
-set(YAML_LIBRARY_DIR ${INSTALL_DIR}/lib)
-
-# workaround for CMake 3.10 on ubuntu 18.04
-file(MAKE_DIRECTORY ${YAML_INCLUDE_DIR})
-file(MAKE_DIRECTORY ${YAML_LIBRARY_DIR})
-
-set(YAML_LIBRARY_PATH ${INSTALL_DIR}/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX})
-
-add_library(Yaml::Yaml UNKNOWN IMPORTED)
-set_target_properties(Yaml::Yaml PROPERTIES
-        IMPORTED_LOCATION ${YAML_LIBRARY_PATH}
-        INTERFACE_INCLUDE_DIRECTORIES ${YAML_INCLUDE_DIR})
-add_dependencies(Yaml::Yaml libyaml)

cmake/Modules/generate_lmpgitversion.cmake

@@ -24,10 +24,10 @@ if(GIT_FOUND AND EXISTS ${LAMMPS_DIR}/.git)
     OUTPUT_STRIP_TRAILING_WHITESPACE)
 endif()
 
-set(temp "${temp}const bool LAMMPS_NS::LAMMPS::has_git_info = ${temp_git_info};\n")
-set(temp "${temp}const char LAMMPS_NS::LAMMPS::git_commit[] = \"${temp_git_commit}\";\n")
-set(temp "${temp}const char LAMMPS_NS::LAMMPS::git_branch[] = \"${temp_git_branch}\";\n")
-set(temp "${temp}const char LAMMPS_NS::LAMMPS::git_descriptor[] = \"${temp_git_describe}\";\n")
+set(temp "${temp}bool LAMMPS_NS::LAMMPS::has_git_info() { return ${temp_git_info}; }\n")
+set(temp "${temp}const char *LAMMPS_NS::LAMMPS::git_commit() { return \"${temp_git_commit}\"; }\n")
+set(temp "${temp}const char *LAMMPS_NS::LAMMPS::git_branch() { return \"${temp_git_branch}\"; }\n")
+set(temp "${temp}const char *LAMMPS_NS::LAMMPS::git_descriptor() { return \"${temp_git_describe}\"; }\n")
 set(temp "${temp}#endif\n\n")
 
 message(STATUS "Generating lmpgitversion.h...")

cmake/iwyu/iwyu-extra-map.imp

@@ -20,9 +20,14 @@
   { include: [ "@\"kspace_.*.h\"", public, "\"style_kspace.h\"", public ] },
   { include: [ "@\"nbin_.*.h\"", public, "\"style_nbin.h\"", public ] },
   { include: [ "@\"npair_.*.h\"", public, "\"style_npair.h\"", public ] },
-  { include: [ "@\"nstenci_.*.h\"", public, "\"style_nstencil.h\"", public ] },
+  { include: [ "@\"nstencil_.*.h\"", public, "\"style_nstencil.h\"", public ] },
   { include: [ "@\"ntopo_.*.h\"", public, "\"style_ntopo.h\"", public ] },
+  { include: [ "\"fmt/core.h\"", private, "\"fmt/format.h\"", public ] },
   { include: [ "<float.h>",   public, "<cfloat>", public ] },
+  { include: [ "\"float.h\"",   public, "<cfloat>", public ] },
   { include: [ "<limits.h>",  public, "<climits>", public ] },
+  { include: [ "\"limits.h\"",  public, "<climits>", public ] },
+  { include: [ "<stdio.h>",  public, "<cstdio>", public ] },
+  { include: [ "<bits/types/struct_rusage.h>", private, "<sys/types.h>", public ] },
   { include: [ "<bits/types/struct_tm.h>", private, "<ctime>", public ] },
 ]

cmake/presets/gcc.cmake

@@ -3,19 +3,19 @@
 set(CMAKE_CXX_COMPILER "g++" CACHE STRING "" FORCE)
 set(CMAKE_C_COMPILER "gcc" CACHE STRING "" FORCE)
 set(CMAKE_Fortran_COMPILER "gfortran" CACHE STRING "" FORCE)
-set(CMAKE_CXX_FLAGS_DEBUG "-Wall -g" CACHE STRING "" FORCE)
+set(CMAKE_CXX_FLAGS_DEBUG "-Wall -Og -g" CACHE STRING "" FORCE)
 set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-g -O2 -DNDEBUG" CACHE STRING "" FORCE)
 set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
 set(MPI_CXX "g++" CACHE STRING "" FORCE)
 set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
 set(MPI_C "gcc" CACHE STRING "" FORCE)
 set(MPI_C_COMPILER "mpicc" CACHE STRING "" FORCE)
-set(CMAKE_C_FLAGS_DEBUG "-Wall -g" CACHE STRING "" FORCE)
+set(CMAKE_C_FLAGS_DEBUG "-Wall -Og -g" CACHE STRING "" FORCE)
 set(CMAKE_C_FLAGS_RELWITHDEBINFO "-g -O2 -DNDEBUG" CACHE STRING "" FORCE)
 set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
 set(MPI_Fortran "gfortran" CACHE STRING "" FORCE)
 set(MPI_Fortran_COMPILER "mpifort" CACHE STRING "" FORCE)
-set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -g -std=f2003" CACHE STRING "" FORCE)
+set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -Og -g -std=f2003" CACHE STRING "" FORCE)
 set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-g -O2 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
 set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
 unset(HAVE_OMP_H_INCLUDE CACHE)

cmake/presets/most.cmake

@@ -48,7 +48,6 @@ set(ALL_PACKAGES
   PHONON
   PLUGIN
   POEMS
-  PYTHON
   QEQ
   REACTION
   REAXFF

doc/Makefile

@@ -230,7 +230,7 @@ $(VENV):
 	)
 
 $(MATHJAX):
-	@git clone -b 3.2.0 -c advice.detachedHead=0 --depth 1 git://github.com/mathjax/MathJax.git $@
+	@git clone -b 3.2.0 -c advice.detachedHead=0 --depth 1 https://github.com/mathjax/MathJax.git $@
 
 $(ANCHORCHECK): $(VENV)
 	@( \

doc/lammps.1

@@ -1,4 +1,4 @@
-.TH LAMMPS "1" "27 October 2021" "2021-10-27"
+.TH LAMMPS "1" "17 February 2022" "2022-2-17"
 .SH NAME
 .B LAMMPS
 \- Molecular Dynamics Simulator.

doc/src/Bibliography.rst

@@ -1123,9 +1123,12 @@ Bibliography
 **(Sun)**
    Sun, J. Phys. Chem. B, 102, 7338-7364 (1998).
 
-**(Surblys)**
+**(Surblys2019)**
    Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
 
+**(Surblys2021)**
+   Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021).
+
 **(Sutmann)**
    Sutmann, Arnold, Fahrenberger, et. al., Physical review / E 88(6), 063308 (2013)
 

doc/src/Build_cmake.rst

@@ -150,6 +150,42 @@ for IDEs like Eclipse, CodeBlocks, or Kate can be selected using the *-G*
 command line flag.  A list of available generator settings for your
 specific CMake version is given when running ``cmake --help``.
 
+.. _cmake_multiconfig:
+
+Multi-configuration build systems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Throughout this manual it is mostly assumed that LAMMPS is being built
+on a Unix-like operating system with "make" as the underlying "builder",
+since this is the most common case.  In this case the build "configuration"
+is chose using ``-D CMAKE_BUILD_TYPE=<configuration>`` with ``<configuration>``
+being one of "Release", "Debug", "RelWithDebInfo", or "MinSizeRel".
+Some build tools, however, can also use or even require to have a so-called
+multi-configuration build system setup.  For those the built type (or
+configuration) is chosen at compile time using the same build files. E.g.
+with:
+
+.. code-block:: bash
+
+   cmake --build build-multi --config Release
+
+In that case the resulting binaries are not in the build folder directly
+but in sub-directories corresponding to the build type (i.e. Release in
+the example from above).  Similarly, for running unit tests the
+configuration is selected with the *-C* flag:
+
+.. code-block:: bash
+
+   ctest -C Debug
+
+The CMake scripts in LAMMPS have basic support for being compiled using a
+multi-config build system, but not all of it has been ported.  This is in
+particular applicable to compiling packages that require additional libraries
+that would be downloaded and compiled by CMake.  The "windows" preset file
+tries to keep track of which packages can be compiled natively with the
+MSVC compilers out-of-the box.  Not all of those external libraries are
+portable to Windows either.
+
 
 Installing CMake
 ^^^^^^^^^^^^^^^^

doc/src/Build_development.rst

@@ -185,6 +185,10 @@ The ``ctest`` command has many options, the most important ones are:
      - run subset of tests matching the regular expression <regex>
    * - -E <regex>
      - exclude subset of tests matching the regular expression <regex>
+   * - -L <regex>
+     - run subset of tests with a label matching the regular expression <regex>
+   * - -LE <regex>
+     - exclude subset of tests with a label matching the regular expression <regex>
    * - -N
      - dry-run: display list of tests without running them
    * - -T memcheck
@@ -299,6 +303,12 @@ will destroy the original file, if the generation run does not complete,
 so using *-g* is recommended unless the YAML file is fully tested
 and working.
 
+Some of the force style tests are rather slow to run and some are very
+sensitive to small differences like CPU architecture, compiler
+toolchain, compiler optimization. Those tests are flagged with a "slow"
+and/or "unstable" label, and thus those tests can be selectively
+excluded with the ``-LE`` flag or selected with the ``-L`` flag.
+
 .. admonition:: Recommendations and notes for YAML files
    :class: note
 

doc/src/Build_extras.rst

@@ -341,6 +341,18 @@ minutes to hours) to build.  Of course you only need to do that once.)
          $ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location
          $ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
 
+      When using the "-b " option, the KIM library is built using its native
+      cmake build system.  The ``lib/kim/Install.py`` script supports a
+      ``CMAKE`` environment variable if the cmake executable is named other
+      than ``cmake`` on your system.  Additional environment variables may be
+      provided on the command line for use by cmake.  For example, to use the
+      ``cmake3`` executable and tell it to use the gnu version 11 compilers
+      to build KIM, one could use the following command line.
+
+      .. code-block:: bash
+
+         $ CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b "  # (re-)install KIM API lib using cmake3 and gnu v11 compilers with only example models
+
       Settings for debugging OpenKIM web queries discussed below need to
       be applied by adding them to the ``LMP_INC`` variable through
       editing the ``Makefile.machine`` you are using.  For example:
@@ -560,11 +572,26 @@ They must be specified in uppercase.
    *  - VEGA908
       - GPU
       - AMD GPU MI100 GFX908
-   *  - INTEL_GEN
+   *  - VEGA90A
       - GPU
-      - Intel GPUs Gen9+
+      - AMD GPU
+   *  - INTEL_DG1
+      - GPU
+      - Intel Iris XeMAX GPU
+   *  - INTEL_GEN9
+      - GPU
+      - Intel GPU Gen9
+   *  - INTEL_GEN11
+      - GPU
+      - Intel GPU Gen11
+   *  - INTEL_GEN12LP
+      - GPU
+      - Intel GPU Gen12LP
+   *  - INTEL_XEHP
+      - GPU
+      - Intel GPUs Xe-HP
 
-This list was last updated for version 3.4.1 of the Kokkos library.
+This list was last updated for version 3.5.0 of the Kokkos library.
 
 .. tabs::
 

doc/src/Build_windows.rst

@@ -89,6 +89,11 @@ miss the correct master ``CMakeLists.txt``.  Try to open the
 starting point.  It is also possible to configure and compile LAMMPS
 from the command line with a CMake binary from `cmake.org <https://cmake.org>`_.
 
+Please note, that for either approach CMake will create a so-called
+:ref:`"multi-configuration" build environment <cmake_multiconfig>`, and
+the command lines for building and testing LAMMPS must be adjusted
+accordingly.
+
 To support running in parallel you can compile with OpenMP enabled using
 the OPENMP package or install Microsoft MPI (including the SDK) and compile
 LAMMPS with MPI enabled.

doc/src/Commands_all.rst

@@ -47,7 +47,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`displace_atoms <displace_atoms>`
    * :doc:`dump <dump>`
    * :doc:`dump_modify <dump_modify>`
-   * :doc:`dynamical_matrix <dynamical_matrix>`
+   * :doc:`dynamical_matrix (k) <dynamical_matrix>`
    * :doc:`echo <echo>`
    * :doc:`fix <fix>`
    * :doc:`fix_modify <fix_modify>`
@@ -117,7 +117,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`thermo <thermo>`
    * :doc:`thermo_modify <thermo_modify>`
    * :doc:`thermo_style <thermo_style>`
-   * :doc:`third_order <third_order>`
+   * :doc:`third_order (k) <third_order>`
    * :doc:`timer <timer>`
    * :doc:`timestep <timestep>`
    * :doc:`uncompute <uncompute>`

doc/src/Commands_bond.rst

@@ -35,6 +35,7 @@ OPT.
    * :doc:`class2 (ko) <bond_class2>`
    * :doc:`fene (iko) <bond_fene>`
    * :doc:`fene/expand (o) <bond_fene_expand>`
+   * :doc:`fene/nm <bond_fene>`
    * :doc:`gaussian <bond_gaussian>`
    * :doc:`gromos (o) <bond_gromos>`
    * :doc:`harmonic (iko) <bond_harmonic>`

doc/src/Commands_compute.rst

@@ -28,6 +28,7 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`angle <compute_angle>`
    * :doc:`angle/local <compute_angle_local>`
    * :doc:`angmom/chunk <compute_angmom_chunk>`
+   * :doc:`ave/sphere/atom (k) <compute_ave_sphere_atom>`
    * :doc:`basal/atom <compute_basal_atom>`
    * :doc:`body/local <compute_body_local>`
    * :doc:`bond <compute_bond>`

doc/src/Commands_fix.rst

@@ -129,6 +129,7 @@ OPT.
    * :doc:`npt/sphere (o) <fix_npt_sphere>`
    * :doc:`npt/uef <fix_nh_uef>`
    * :doc:`numdiff <fix_numdiff>`
+   * :doc:`numdiff/virial <fix_numdiff_virial>`
    * :doc:`nve (giko) <fix_nve>`
    * :doc:`nve/asphere (gi) <fix_nve_asphere>`
    * :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>`

doc/src/Commands_pair.rst

@@ -119,10 +119,12 @@ OPT.
    * :doc:`granular <pair_granular>`
    * :doc:`gw <pair_gw>`
    * :doc:`gw/zbl <pair_gw>`
+   * :doc:`harmonic/cut (o) <pair_harmonic_cut>`
    * :doc:`hbond/dreiding/lj (o) <pair_hbond_dreiding>`
    * :doc:`hbond/dreiding/morse (o) <pair_hbond_dreiding>`
    * :doc:`hdnnp <pair_hdnnp>`
    * :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>`
+   * :doc:`ilp/tmd <pair_ilp_tmd>`
    * :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>`
    * :doc:`kolmogorov/crespi/z <pair_kolmogorov_crespi_z>`
    * :doc:`lcbop <pair_lcbop>`
@@ -210,6 +212,7 @@ OPT.
    * :doc:`nm/cut (o) <pair_nm>`
    * :doc:`nm/cut/coul/cut (o) <pair_nm>`
    * :doc:`nm/cut/coul/long (o) <pair_nm>`
+   * :doc:`nm/cut/split <pair_nm>`
    * :doc:`oxdna/coaxstk <pair_oxdna>`
    * :doc:`oxdna/excv <pair_oxdna>`
    * :doc:`oxdna/hbond <pair_oxdna>`
@@ -239,6 +242,7 @@ OPT.
    * :doc:`reaxff (ko) <pair_reaxff>`
    * :doc:`rebo (io) <pair_airebo>`
    * :doc:`resquared (go) <pair_resquared>`
+   * :doc:`saip/metal <pair_saip_metal>`
    * :doc:`sdpd/taitwater/isothermal <pair_sdpd_taitwater_isothermal>`
    * :doc:`smd/hertz <pair_smd_hertz>`
    * :doc:`smd/tlsph <pair_smd_tlsph>`
@@ -262,6 +266,7 @@ OPT.
    * :doc:`spin/neel <pair_spin_neel>`
    * :doc:`srp <pair_srp>`
    * :doc:`sw (giko) <pair_sw>`
+   * :doc:`sw/mod (o) <pair_sw>`
    * :doc:`table (gko) <pair_table>`
    * :doc:`table/rx (k) <pair_table_rx>`
    * :doc:`tdpd <pair_mesodpd>`

doc/src/Developer.rst

@@ -11,6 +11,7 @@ of time and requests from the LAMMPS user community.
    :maxdepth: 1
 
    Developer_org
+   Developer_cxx_vs_c_style
    Developer_parallel
    Developer_flow
    Developer_write

doc/src/Developer_cxx_vs_c_style.rst

@@ -0,0 +1,384 @@
+Code design
+-----------
+
+This section discusses some of the code design choices in LAMMPS and
+overall strategy in order to assist developers to write new code that
+will fit well with the remaining code.  Please see the section on
+:doc:`Requirements for contributed code <Modify_style>` for more
+specific recommendations and guidelines.  While that section is
+organized more in the form of a checklist for code contributors, the
+focus here is on overall code design strategy, choices made between
+possible alternatives, and to discuss of some relevant C++ programming
+language constructs.
+
+Historically, the basic design philosophy of the LAMMPS C++ code was
+that of a "C with classes" style.  The was motivated by the desire to
+make it easier to modify LAMMPS for people without significant training
+in C++ programming and by trying to use data structures and code constructs
+that somewhat resemble the previous implementation(s) in Fortran.
+A contributing factor for this choice also was that at the time the
+implementation of C++ compilers was not always very mature and some of
+the advanced features contained bugs or were not functioning exactly
+as the standard required; plus there was some disagreement between
+compiler vendors about how to interpret the C++ standard documents.
+
+However, C++ compilers have advanced a lot since then and with the
+transition to requiring the C++11 standard in 2020 as the minimum C++ language
+standard for LAMMPS, the decision was made to also replace some of the
+C-style constructs with equivalent C++ functionality, either from the
+C++ standard library or as custom classes or function, in order to
+improve readability of the code and to increase code reuse through
+abstraction of commonly used functionality.
+
+.. note::
+
+   Please note that as of spring 2022 there is still a sizable chunk of
+   legacy code in LAMMPS that has not yet been refactored to reflect these
+   style conventions in full.  LAMMPS has a large code base and many
+   different contributors and there also is a hierarchy of precedence
+   in which the code is adapted.  Highest priority has the code in the
+   ``src`` folder, followed by code in packages in order of their popularity
+   and complexity (simpler code is adapted sooner), followed by code
+   in the ``lib`` folder.  Source code that is downloaded during compilation
+   is not subject to the conventions discussed here.
+
+Object oriented code
+^^^^^^^^^^^^^^^^^^^^
+
+LAMMPS is designed to be an object oriented code, that is each
+simulation is represented by an instance of the LAMMPS class.  When
+running in parallel, of course, each MPI process will create such an
+instance.  This can be seen in the ``main.cpp`` file where the core
+steps of running a LAMMPS simulation are the following 3 lines of code:
+
+.. code-block:: C++
+
+    LAMMPS *lammps = new LAMMPS(argc, argv, lammps_comm);
+    lammps->input->file();
+    delete lammps;
+
+The first line creates a LAMMPS class instance and passes the command
+line arguments and the global communicator to its constructor.  The
+second line tells the LAMMPS instance to process the input (either from
+standard input or the provided input file) until the end.  And the third
+line deletes that instance again.  The remainder of the main.cpp file
+are for error handling, MPI configuration and other special features.
+
+In the constructor of the LAMMPS class instance the basic LAMMPS class hierarchy
+is created as shown in :ref:`class-topology`.  While processing the input further
+class instances are created, or deleted, or replaced and specific member functions
+of specific classes are called to trigger actions like creating atoms, computing
+forces, computing properties, propagating the system, or writing output.
+
+Compositing and Inheritance
+===========================
+
+LAMMPS makes extensive use of the object oriented programming (OOP)
+principles of *compositing* and *inheritance*. Classes like the
+``LAMMPS`` class are a **composite** containing pointers to instances of
+other classes like ``Atom``, ``Comm``, ``Force``, ``Neighbor``,
+``Modify``, and so on.  Each of these classes implement certain
+functionality by storing and manipulating data related to the simulation
+and providing member functions that trigger certain actions.  Some of
+those classes like ``Force`` are a composite again containing instances
+of classes describing the force interactions or ``Modify`` containing
+and calling fixes and computes.  In most cases (e.g. ``AtomVec``, ``Comm``,
+``Pair``, or ``Bond``) there is only one instance of those member classes
+allowed, but in a few cases (e.g. ``Region``, ``Fix``, ``Compute``, or
+``Dump``) there can be multiple instances and the parent class is
+maintaining a list of the pointers of instantiated classes instead
+of a single pointer.
+
+Changing behavior or adjusting how LAMMPS handles a simulation is
+implemented via **inheritance** where different variants of the
+functionality are realized by creating *derived* classes that can share
+common functionality in their base class and provide a consistent
+interface where the derived classes replace (dummy or pure) functions in
+the base class.  The higher level classes can then call those methods of
+the instantiated classes without having to know which specific derived
+class variant was instantiated.  In the LAMMPS documentation those
+derived classes are usually referred to a "styles", e.g.  pair styles,
+fix styles, atom styles and so on.
+
+This is the origin of the flexibility of LAMMPS and facilitates for
+example to compute forces for very different non-bonded potential
+functions by having different pair styles (implemented as different
+classes derived from the ``Pair`` class) where the evaluation of the
+potential function is confined to the implementation of the individual
+classes.  Whenever a new :doc:`pair_style` or :doc:`bond_style` or
+:doc:`comm_style` or similar command is processed in the LAMMPS input
+any existing class instance is deleted and a new instance created in
+it place.
+
+Classes derived from ``Fix`` or ``Compute`` represent a different facet
+of LAMMPS' flexibility as there can be multiple instances of them an
+their member functions will be called at different phases of the time
+integration process (as explained in `Developer_flow`).  This way
+multiple manipulations of the entire or parts of the system can be
+programmed (with fix styles) or different computations can be performed
+and accessed and further processed or output through a common interface
+(with compute styles).
+
+Further code sharing is possible by creating derived classes from the
+derived classes (for instance to implement an accelerated version of a
+pair style) where then only a subset of the methods are replaced with
+the accelerated versions.
+
+Polymorphism
+============
+
+Polymorphism and dynamic dispatch are another OOP feature that play an
+important part of how LAMMPS selects which code to execute.  In a nutshell,
+this is a mechanism where the decision of which member function to call
+from a class is determined at runtime and not when the code is compiled.
+To enable it, the function has to be declared as ``virtual`` and all
+corresponding functions in derived classes should be using the ``override``
+property. Below is a brief example.
+
+.. code-block:: c++
+
+   class Base {
+   public:
+    virtual ~Base() = default;
+    void call();
+    void normal();
+    virtual void poly();
+   };
+
+   void Base::call() {
+    normal();
+    poly();
+   }
+
+   class Derived : public Base {
+   public:
+    ~Derived() override = default;
+    void normal();
+    void poly() override;
+   };
+
+   // [....]
+
+   Base *base1 = new Base();
+   Base *base2 = new Derived();
+
+   base1->call();
+   base2->call();
+
+The difference in behavior of the ``normal()`` and the ``poly()`` member
+functions is in which of the two member functions is called when
+executing `base1->call()` and `base2->call()`.  Without polymorphism, a
+function within the base class will call only member functions within
+the same scope, that is ``Base::call()`` will always call
+``Base::normal()``.  But for the `base2->call()` the call for the
+virtual member function will be dispatched to ``Derived::poly()``
+instead.  This mechanism allows to always call functions within the
+scope of the class type that was used to create the class instance, even
+if they are assigned to a pointer using the type of a base class. This
+is the desired behavior, and thanks to dynamic dispatch, LAMMPS can even
+use styles that are loaded at runtime from a shared object file with the
+:doc:`plugin command <plugin>`.
+
+A special case of virtual functions are so-called pure functions. These
+are virtual functions that are initialized to 0 in the class declaration
+(see example below).
+
+.. code-block:: c++
+
+   class Base {
+   public:
+    virtual void pure() = 0;
+   };
+
+This has the effect that it will no longer be possible to create an
+instance of the base class and that derived classes **must** implement
+these functions.  Many of the functions listed with the various class
+styles in the section :doc:`Modify` are such pure functions.  The
+motivation for this is to define the interface or API of the functions
+but defer the implementation to the derived classes.
+
+However, there are downsides to this. For example, calls to virtual
+functions from within a constructor, will not be in the scope of the
+derived class and thus it is good practice to either avoid calling them
+or to provide an explicit scope like in ``Base::poly()``.  Furthermore,
+any destructors in classes containing virtual functions should be
+declared virtual, too, so they are processed in the expected order
+before types are removed from dynamic dispatch.
+
+.. admonition:: Important Notes
+
+   In order to be able to detect incompatibilities and to avoid unexpected
+   behavior already at compile time, it is crucial that all member functions
+   that are intended to replace a virtual or pure function use the ``override``
+   property keyword.  For the same reason it should be avoided to use overloads
+   or default arguments for virtual functions as they lead to confusion over
+   which function is supposed to override which and which arguments need to be
+   declared.
+
+Style Factories
+===============
+
+In order to create class instances of the different styles, LAMMPS often
+uses a programming pattern called `Factory`.  Those are functions that create
+an instance of a specific derived class, say ``PairLJCut`` and return a pointer
+to the type of the common base class of that style, ``Pair`` in this case.
+To associate the factory function with the style keyword, an ``std::map``
+class is used in which function pointers are indexed by their keyword
+(for example "lj/cut" for ``PairLJCut`` and "morse" ``PairMorse``).
+A couple of typedefs help to keep the code readable and a template function
+is used to implement the actual factory functions for the individual classes.
+
+I/O and output formatting
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+C-style stdio versus C++ style iostreams
+========================================
+
+LAMMPS chooses to use the "stdio" library of the standard C library for
+reading from and writing to files and console instead of C++
+"iostreams".  This is mainly motivated by the better performance, better
+control over formatting, and less effort to achieve specific formatting.
+
+Since mixing "stdio" and "iostreams" can lead to unexpected behavior using
+the latter is strongly discouraged.  Also output to the screen should not
+use the predefined ``stdout`` FILE pointer, but rather the ``screen`` and
+``logfile`` FILE pointers managed by the LAMMPS class.  Furthermore, output
+should only be done by MPI rank 0 (``comm->me == 0``) and output that is
+send to both ``screen`` and ``logfile`` should use the
+:cpp:func:`utils::logmesg() convenience function <LAMMPS_NS::utils::logmesg>`.
+
+We also discourage the use for stringstreams as the bundled {fmt} library
+and the customized tokenizer classes can provide the same functionality
+in a cleaner way with better performance. This will also help to retain
+a consistent programming style despite the many different contributors.
+
+Formatting with the {fmt} library
+===================================
+
+The LAMMPS source code includes a copy of the `{fmt} library
+<https://fmt.dev>`_ which is preferred over formatting with the
+"printf()" family of functions.  The primary reason is that it allows a
+typesafe default format for any type of supported data.  This is
+particularly useful for formatting integers of a given size (32-bit or
+64-bit) which may require different format strings depending on compile
+time settings or compilers/operating systems.  Furthermore, {fmt} gives
+better performance, has more functionality, a familiar formatting syntax
+that has similarities to ``format()`` in Python, and provides a facility
+that can be used to integrate format strings and a variable number of
+arguments into custom functions in a much simpler way that the varargs
+mechanism of the C library.  Finally, {fmt} has been included into the
+C++20 language standard, so changes to adopt it are future proof.
+
+Formatted strings are frequently created by calling the
+``fmt::format()`` function which will return a string as ``std::string``
+class instance.  In contrast to the ``%`` placeholder in ``printf()``,
+the {fmt} library uses ``{}`` to embed format descriptors.  In the
+simplest case, no additional characters are needed as {fmt} will choose
+the default format based on the data type of the argument. Alternatively
+The ``fmt::print()`` function may be used instead of ``printf()`` or
+``fprintf()``.  In addition, several LAMMPS output functions, that
+originally accepted a single string as arguments have been overloaded to
+accept a format string with optional arguments as well (e.g.
+``Error::all()``, ``Error::one()``, ``utils::logmesg()``).
+
+Summary of the {fmt} format syntax
+==================================
+
+The syntax of the format string is "{[<argument id>][:<format spec>]}",
+where either the argument id or the format spec (separated by a colon
+':') is optional.  The argument id is usually a number starting from 0
+that is the index to the arguments following the format string.  By
+default these are assigned in order (i.e. 0, 1, 2, 3, 4 etc.).  The most
+common case for using argument id would be to use the same argument in
+multiple places in the format string without having to provide it as an
+argument multiple times. In LAMMPS the argument id is rarely used.
+
+More common is the use of the format specifier, which starts with a
+colon.  This may optionally be followed by a fill character (default is
+' '). If provided, the fill character **must** be followed by an
+alignment character ('<', '^', '>' for left, centered, or right
+alignment (default)). The alignment character may be used without a fill
+character. The next important format parameter would be the minimum
+width, which may be followed by a dot '.'  and a precision for floating
+point numbers. The final character in the format string would be an
+indicator for the "presentation", i.e. 'd' for decimal presentation of
+integers, 'x' for hexadecimal, 'o' for octal, 'c' for character
+etc. This mostly follows the "printf()" scheme but without requiring an
+additional length parameter to distinguish between different integer
+widths. The {fmt} library will detect those and adapt the formatting
+accordingly.  For floating point numbers there are correspondingly, 'g'
+for generic presentation, 'e' for exponential presentation, and 'f' for
+fixed point presentation.
+
+Thus "{:8}" would represent *any* type argument using at least 8
+characters; "{:<8}" would do this as left aligned, "{:^8}" as centered,
+"{:>8}" as right aligned.  If a specific presentation is selected, the
+argument type must be compatible or else the {fmt} formatting code will
+throw an exception. Some format string examples are given below:
+
+.. code-block:: C
+
+   auto mesg = fmt::format("  CPU time: {:4d}:{:02d}:{:02d}\n", cpuh, cpum, cpus);
+   mesg = fmt::format("{:<8s}| {:<10.5g} | {:<10.5g} | {:<10.5g} |{:6.1f} |{:6.2f}\n",
+                      label, time_min, time, time_max, time_sq, tmp);
+   utils::logmesg(lmp,"{:>6} = max # of 1-2 neighbors\n",maxall);
+   utils::logmesg(lmp,"Lattice spacing in x,y,z = {:.8} {:.8} {:.8}\n",
+                  xlattice,ylattice,zlattice);
+
+which will create the following output lines:
+
+.. parsed-literal::
+
+     CPU time:    0:02:16
+     Pair    | 2.0133     | 2.0133     | 2.0133     |   0.0 | 84.21
+          4 = max # of 1-2 neighbors
+     Lattice spacing in x,y,z = 1.6795962 1.6795962 1.6795962
+
+A special feature of the {fmt} library is that format parameters like
+the width or the precision may be also provided as arguments. In that
+case a nested format is used where a pair of curly braces (with an
+optional argument id) "{}" are used instead of the value, for example
+"{:{}d}" will consume two integer arguments, the first will be the value
+shown and the second the minimum width.
+
+For more details and examples, please consult the `{fmt} syntax
+documentation <https://fmt.dev/latest/syntax.html>`_ website.
+
+
+Memory management
+^^^^^^^^^^^^^^^^^
+
+Dynamical allocation of data and objects should be done with either the
+C++ commands "new" and "delete/delete[]" or using member functions of
+the ``Memory`` class, most commonly, ``Memory::create()``,
+``Memory::grow()``, and ``Memory::destroy()``.  The use of ``malloc()``,
+``calloc()``, ``realloc()`` and ``free()`` directly is strongly
+discouraged.  To simplify adapting legacy code into the LAMMPS code base
+the member functions ``Memory::smalloc()``, ``Memory::srealloc()``, and
+``Memory::sfree()`` are available.
+
+Using those custom memory allocation functions is motivated by the
+following considerations:
+
+- memory allocation failures on *any* MPI rank during a parallel run
+  will trigger an immediate abort of the entire parallel calculation
+  instead of stalling it
+- a failing "new" will trigger an exception which is also captured by
+  LAMMPS and triggers a global abort
+- allocation of multi-dimensional arrays will be done in a C compatible
+  fashion but so that the storage of the actual data is stored in one
+  large consecutive block and thus when MPI communication is needed,
+  only this storage needs to be communicated (similar to Fortran arrays)
+- the "destroy()" and "sfree()" functions may safely be called on NULL
+  pointers
+- the "destroy()" functions will nullify the pointer variables making
+  "use after free" errors easy to detect
+- it is possible to use a larger than default memory alignment (not on
+  all operating systems, since the allocated storage pointers must be
+  compatible with ``free()`` for technical reasons)
+
+In the practical implementation of code this means that any pointer variables
+that are class members should be initialized to a ``nullptr`` value in their
+respective constructors.  That way it would be safe to call ``Memory::destroy()``
+or ``delete[]`` on them before *any* allocation outside the constructor.
+This helps to prevent memory leaks.

doc/src/Developer_notes.rst

@@ -7,6 +7,61 @@ typically document what a variable stores, what a small section of
 code does, or what a function does and its input/outputs.  The topics
 on this page are intended to document code functionality at a higher level.
 
+Reading and parsing of text and text files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is frequently required for a class in LAMMPS to read in additional
+data from a file, most commonly potential parameters from a potential
+file for manybody potentials.  LAMMPS provides several custom classes
+and convenience functions to simplify the process.  This offers the
+following benefits:
+
+- better code reuse and fewer lines of code needed to implement reading
+  and parsing data from a file
+- better detection of format errors, incompatible data, and better error messages
+- exit with an error message instead of silently converting only part of the
+  text to a number or returning a 0 on unrecognized text and thus reading incorrect values
+- re-entrant code through avoiding global static variables (as used by ``strtok()``)
+- transparent support for translating unsupported UTF-8 characters to their ASCII equivalents
+  (the text to value conversion functions **only** accept ASCII characters)
+
+In most cases (e.g. potential files) the same data is needed on all MPI
+ranks.  Then it is best to do the reading and parsing only on MPI rank
+0, and communicate the data later with one or more ``MPI_Bcast()``
+calls.  For reading generic text and potential parameter files the
+custom classes :cpp:class:`TextFileReader <LAMMPS_NS::TextFileReader>`
+and :cpp:class:`PotentialFileReader <LAMMPS_NS::PotentialFileReader>`
+are available. Those classes allow to read the file as individual lines
+for which they can return a tokenizer class (see below) for parsing the
+line, or they can return blocks of numbers as a vector directly.  The
+documentation on `File reader classes <file-reader-classes>`_ contains
+an example for a typical case.
+
+When reading per-atom data, the data in the file usually needs include
+an atom ID so it can be associated with a particular atom.  In that case
+the data can be read in multi-line chunks and broadcast to all MPI ranks
+with :cpp:func:`utils::read_lines_from_file()
+<LAMMPS_NS::utils::read_lines_from_file>`.  Those chunks are then
+split into lines, parsed, and applied only to atoms the MPI rank
+"owns".
+
+For splitting a string (incrementally) into words and optionally
+converting those to numbers, the :cpp:class:`Tokenizer
+<LAMMPS_NS::Tokenizer>` and :cpp:class:`ValueTokenizer
+<LAMMPS_NS::ValueTokenizer>` can be used.  Those provide a superset of
+the functionality of ``strtok()`` from the C-library and the latter also
+includes conversion to different types.  Any errors while processing the
+string in those classes will result in an exception, which can be caught
+and the error processed as needed.  Unlike the C-library functions
+``atoi()``, ``atof()``, ``strtol()``, or ``strtod()`` the conversion
+will check if the converted text is a valid integer of floating point
+number and will not silently return an unexpected or incorrect value.
+For example, ``atoi()`` will return 12 when converting "12.5" while the
+ValueTokenizer class will throw an :cpp:class:`InvalidIntegerException
+<LAMMPS_NS::InvalidIntegerException>` if
+:cpp:func:`ValueTokenizer::next_int()
+<LAMMPS_NS::ValueTokenizer::next_int>` is called on the same string.
+
 Fix contributions to instantaneous energy, virial, and cumulative energy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/src/Developer_org.rst

@@ -225,7 +225,7 @@ follows:
   commands in an input script.
 
 - The Force class computes various forces between atoms.  The Pair
-  parent class is for non-bonded or pair-wise forces, which in LAMMPS
+  parent class is for non-bonded or pairwise forces, which in LAMMPS
   also includes many-body forces such as the Tersoff 3-body potential if
   those are computed by walking pairwise neighbor lists.  The Bond,
   Angle, Dihedral, Improper parent classes are styles for bonded

doc/src/Developer_platform.rst

@@ -118,6 +118,9 @@ Environment variable functions
 .. doxygenfunction:: putenv
    :project: progguide
 
+.. doxygenfunction:: unsetenv
+   :project: progguide
+
 .. doxygenfunction:: list_pathenv
    :project: progguide
 

doc/src/Developer_utils.rst

@@ -21,18 +21,21 @@ In that case, the functions will stop with an error message, indicating
 the name of the problematic file, if possible unless the *error* argument
 is a NULL pointer.
 
-The :cpp:func:`fgets_trunc` function will work similar for ``fgets()``
-but it will read in a whole line (i.e. until the end of line or end
-of file), but store only as many characters as will fit into the buffer
-including a final newline character and the terminating NULL byte.
-If the line in the file is longer it will thus be truncated in the buffer.
-This function is used by :cpp:func:`read_lines_from_file` to read individual
-lines but make certain they follow the size constraints.
+The :cpp:func:`utils::fgets_trunc() <LAMMPS_NS::utils::fgets_trunc>`
+function will work similar for ``fgets()`` but it will read in a whole
+line (i.e. until the end of line or end of file), but store only as many
+characters as will fit into the buffer including a final newline
+character and the terminating NULL byte.  If the line in the file is
+longer it will thus be truncated in the buffer.  This function is used
+by :cpp:func:`utils::read_lines_from_file()
+<LAMMPS_NS::utils::read_lines_from_file>` to read individual lines but
+make certain they follow the size constraints.
 
-The :cpp:func:`read_lines_from_file` function will read the requested
-number of lines of a maximum length into a buffer and will return 0
-if successful or 1 if not. It also guarantees that all lines are
-terminated with a newline character and the entire buffer with a
+The :cpp:func:`utils::read_lines_from_file()
+<LAMMPS_NS::utils::read_lines_from_file>` function will read the
+requested number of lines of a maximum length into a buffer and will
+return 0 if successful or 1 if not. It also guarantees that all lines
+are terminated with a newline character and the entire buffer with a
 NULL character.
 
 ----------
@@ -56,13 +59,13 @@ String to number conversions with validity check
 
 These functions should be used to convert strings to numbers. They are
 are strongly preferred over C library calls like ``atoi()`` or
-``atof()`` since they check if the **entire** provided string is a valid
+``atof()`` since they check if the **entire** string is a valid
 (floating-point or integer) number, and will error out instead of
 silently returning the result of a partial conversion or zero in cases
-where the string is not a valid number.  This behavior allows to more
-easily detect typos or issues when processing input files.
+where the string is not a valid number.  This behavior improves
+detecting typos or issues when processing input files.
 
-Similarly the :cpp:func:`logical() <LAMMPS_NS::utils::logical>` function
+Similarly the :cpp:func:`utils::logical() <LAMMPS_NS::utils::logical>` function
 will convert a string into a boolean and will only accept certain words.
 
 The *do_abort* flag should be set to ``true`` in case  this function
@@ -70,25 +73,40 @@ is called only on a single MPI rank, as that will then trigger the
 a call to ``Error::one()`` for errors instead of ``Error::all()``
 and avoids a "hanging" calculation when run in parallel.
 
-Please also see :cpp:func:`is_integer() <LAMMPS_NS::utils::is_integer>`
-and :cpp:func:`is_double() <LAMMPS_NS::utils::is_double>` for testing
+Please also see :cpp:func:`utils::is_integer() <LAMMPS_NS::utils::is_integer>`
+and :cpp:func:`utils::is_double() <LAMMPS_NS::utils::is_double>` for testing
 strings for compliance without conversion.
 
 ----------
 
-.. doxygenfunction:: numeric
+.. doxygenfunction:: numeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
    :project: progguide
 
-.. doxygenfunction:: inumeric
+.. doxygenfunction:: numeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
    :project: progguide
 
-.. doxygenfunction:: bnumeric
+.. doxygenfunction:: inumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
    :project: progguide
 
-.. doxygenfunction:: tnumeric
+.. doxygenfunction:: inumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
    :project: progguide
 
-.. doxygenfunction:: logical
+.. doxygenfunction:: bnumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
+   :project: progguide
+
+.. doxygenfunction:: bnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
+   :project: progguide
+
+.. doxygenfunction:: tnumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
+   :project: progguide
+
+.. doxygenfunction:: tnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
+   :project: progguide
+
+.. doxygenfunction:: logical(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
+   :project: progguide
+
+.. doxygenfunction:: logical(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
    :project: progguide
 
 
@@ -190,6 +208,9 @@ Convenience functions
 .. doxygenfunction:: logmesg(LAMMPS *lmp, const std::string &mesg)
    :project: progguide
 
+.. doxygenfunction:: flush_buffers(LAMMPS *lmp)
+   :project: progguide
+
 .. doxygenfunction:: getsyserror
    :project: progguide
 
@@ -322,11 +343,11 @@ This code example should produce the following output:
 
 .. doxygenclass:: LAMMPS_NS::InvalidIntegerException
    :project: progguide
-   :members: what
+   :members:
 
 .. doxygenclass:: LAMMPS_NS::InvalidFloatException
    :project: progguide
-   :members: what
+   :members:
 
 ----------
 
@@ -375,21 +396,26 @@ A typical code segment would look like this:
 
 ----------
 
+.. file-reader-classes:
+
 File reader classes
 -------------------
 
 The purpose of the file reader classes is to simplify the recurring task
 of reading and parsing files. They can use the
-:cpp:class:`LAMMPS_NS::ValueTokenizer` class to process the read in
-text.  The :cpp:class:`LAMMPS_NS::TextFileReader` is a more general
-version while :cpp:class:`LAMMPS_NS::PotentialFileReader` is specialized
-to implement the behavior expected for looking up and reading/parsing
-files with potential parameters in LAMMPS.  The potential file reader
-class requires a LAMMPS instance, requires to be run on MPI rank 0 only,
-will use the :cpp:func:`LAMMPS_NS::utils::get_potential_file_path`
-function to look up and open the file, and will call the
-:cpp:class:`LAMMPS_NS::Error` class in case of failures to read or to
-convert numbers, so that LAMMPS will be aborted.
+:cpp:class:`ValueTokenizer <LAMMPS_NS::ValueTokenizer>` class to process
+the read in text.  The :cpp:class:`TextFileReader
+<LAMMPS_NS::TextFileReader>` is a more general version while
+:cpp:class:`PotentialFileReader <LAMMPS_NS::PotentialFileReader>` is
+specialized to implement the behavior expected for looking up and
+reading/parsing files with potential parameters in LAMMPS.  The
+potential file reader class requires a LAMMPS instance, requires to be
+run on MPI rank 0 only, will use the
+:cpp:func:`utils::get_potential_file_path
+<LAMMPS_NS::utils::get_potential_file_path>` function to look up and
+open the file, and will call the :cpp:class:`LAMMPS_NS::Error` class in
+case of failures to read or to convert numbers, so that LAMMPS will be
+aborted.
 
 .. code-block:: C++
    :caption: Use of PotentialFileReader class in pair style coul/streitz
@@ -464,10 +490,10 @@ provided, as that is used to determine whether a new page of memory
 must be used.
 
 The :cpp:class:`MyPage <LAMMPS_NS::MyPage>` class offers two ways to
-reserve a chunk: 1) with :cpp:func:`get() <LAMMPS_NS::MyPage::get>` the
-chunk size needs to be known in advance, 2) with :cpp:func:`vget()
+reserve a chunk: 1) with :cpp:func:`MyPage::get() <LAMMPS_NS::MyPage::get>` the
+chunk size needs to be known in advance, 2) with :cpp:func:`MyPage::vget()
 <LAMMPS_NS::MyPage::vget>` a pointer to the next chunk is returned, but
-its size is registered later with :cpp:func:`vgot()
+its size is registered later with :cpp:func:`MyPage::vgot()
 <LAMMPS_NS::MyPage::vgot>`.
 
 .. code-block:: C++
@@ -570,4 +596,3 @@ the communication buffers.
 
 .. doxygenunion:: LAMMPS_NS::ubuf
    :project: progguide
-

doc/src/Developer_write.rst

@@ -55,7 +55,7 @@ of each timestep. First of all, implement a constructor:
      if (narg < 4)
        error->all(FLERR,"Illegal fix print/vel command");
 
-     nevery = force->inumeric(FLERR,arg[3]);
+     nevery = utils::inumeric(FLERR,arg[3],false,lmp);
      if (nevery <= 0)
        error->all(FLERR,"Illegal fix print/vel command");
    }

doc/src/Errors_messages.rst

@@ -1941,6 +1941,9 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Compute ID for fix numdiff does not exist*
    Self-explanatory.
 
+*Compute ID for fix numdiff/virial does not exist*
+   Self-explanatory.
+
 *Compute ID for fix store/state does not exist*
    Self-explanatory.
 
@@ -3796,6 +3799,10 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    Self-explanatory. Efficient loop over all atoms for numerical
    difference requires consecutive atom IDs.
 
+*Fix numdiff/virial must use group all*
+   Virial contributions computed by this fix are
+   computed on all atoms.
+
 *Fix nve/asphere requires extended particles*
    This fix can only be used for particles with a shape setting.
 
@@ -7772,9 +7779,6 @@ keyword to allow for additional bonds to be formed
    The system size must fit in a 32-bit integer to use this dump
    style.
 
-*Too many atoms to dump sort*
-   Cannot sort when running with more than 2\^31 atoms.
-
 *Too many elements extracted from MEAM library.*
    Increase 'maxelt' in meam.h and recompile.
 

doc/src/Errors_warnings.rst

@@ -416,7 +416,7 @@ This will most likely cause errors in kinetic fluctuations.
    not defined for the specified atom style.
 
 *Molecule has bond topology but no special bond settings*
-   This means the bonded atoms will not be excluded in pair-wise
+   This means the bonded atoms will not be excluded in pairwise
    interactions.
 
 *Molecule template for create_atoms has multiple molecules*

doc/src/Howto_drude2.rst

@@ -491,11 +491,6 @@ NPT ensemble using Nose-Hoover thermostat:
 **(Schroeder)**  Schroeder and Steinhauser, J Chem Phys, 133,
 154511 (2010).
 
-.. _Jiang2:
-
-**(Jiang)** Jiang, Hardy, Phillips, MacKerell, Schulten, and Roux,
- J Phys Chem Lett, 2, 87-92 (2011).
-
 .. _Thole2:
 
 **(Thole)** Chem Phys, 59, 341 (1981).

doc/src/Howto_github.rst

@@ -141,7 +141,8 @@ unrelated feature, you should switch branches!
    Committing changes to the *develop*, *release*, or *stable* branches
    is strongly discouraged.  While it may be convenient initially, it
    will create more work in the long run.  Various texts and tutorials
-   on using git effectively discuss the motivation for this.
+   on using git effectively discuss the motivation for using feature
+   branches instead.
 
 **After changes are made**
 

doc/src/Howto_pylammps.rst

@@ -545,6 +545,6 @@ Feedback and Contributing
 -------------------------
 
 If you find this Python interface useful, please feel free to provide feedback
-and ideas on how to improve it to Richard Berger (richard.berger@temple.edu). We also
+and ideas on how to improve it to Richard Berger (richard.berger@outlook.com). We also
 want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage
 and maybe their latest research results.

doc/src/Install_git.rst

@@ -28,8 +28,9 @@ provides `limited support for subversion clients <svn_>`_.
 
 You can follow the LAMMPS development on 3 different git branches:
 
-* **stable**   :  this branch is updated with every stable release;
-  updates are always "fast forward" merges from *develop*
+* **stable**   :  this branch is updated from the *release* branch with
+  every stable release version and also has selected bug fixes and updates
+  back-ported from the *develop* branch
 * **release**  :  this branch is updated with every patch release;
   updates are always "fast forward" merges from *develop*
 * **develop**  :  this branch follows the ongoing development and
@@ -47,20 +48,22 @@ your machine and "release" is one of the 3 branches listed above.
 (Note that you actually download all 3 branches; you can switch
 between them at any time using "git checkout <branch name>".)
 
-.. note::
+.. admonition:: Saving time and disk space when using ``git clone``
 
    The complete git history of the LAMMPS project is quite large because
    it contains the entire commit history of the project since fall 2006,
-   which includes the time when LAMMPS was managed with subversion. This
-   also includes commits that have added and removed some large files
-   (mostly by accident).  If you do not need access to the entire commit
-   history, you can speed up the "cloning" process and reduce local disk
-   space requirements by using the *--depth* git command line flag thus
-   create a "shallow clone" of the repository that contains only a
-   subset of the git history. Using a depth of 1000 is usually sufficient
-   to include the head commits of the *develop* and the *release* branches.
-   To include the head commit of the *stable* branch you may need a depth
-   of up to 10000.
+   which includes the time when LAMMPS was managed with subversion.
+   This includes a few commits that have added and removed some large
+   files (mostly by accident).  If you do not need access to the entire
+   commit history (most people don't), you can speed up the "cloning"
+   process and reduce local disk space requirements by using the
+   *--depth* git command line flag.  That will create a "shallow clone"
+   of the repository containing only a subset of the git history.  Using
+   a depth of 1000 is usually sufficient to include the head commits of
+   the *develop* and the *release* branches.  To include the head commit
+   of the *stable* branch you may need a depth of up to 10000.  If you
+   later need more of the git history, you can always convert the
+   shallow clone into a "full clone".
 
 Once the command completes, your directory will contain the same files
 as if you unpacked a current LAMMPS tarball, with the exception, that
@@ -156,9 +159,9 @@ changed.  How to do this depends on the build system you are using.
 .. 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
+   The servers at github.com support the "https://" access protocol 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

doc/src/Intro_authors.rst

@@ -8,7 +8,7 @@ University:
 * Aidan Thompson, athomps at sandia.gov
 * Stan Moore, stamoor at sandia.gov
 * Axel Kohlmeyer, akohlmey at gmail.com
-* Richard Berger, richard.berger at temple.edu
+* Richard Berger, richard.berger at outlook.com
 
 .. _sjp: http://www.cs.sandia.gov/~sjplimp
 .. _lws: https://www.lammps.org

doc/src/Intro_citing.rst

@@ -16,7 +16,7 @@ source code design, the program structure, the spatial decomposition
 approach, the neighbor finding, basic communications algorithms, and how
 users and developers have contributed to LAMMPS is:
 
-  `LAMMPS - A flexible simulation tool for particle-based materials modeling at the atomic, meso, and continuum scales, Comp. Phys. Comm. (accepted 09/2021), DOI:10.1016/j.cpc.2021.108171 <https://doi.org/10.1016/j.cpc.2021.108171>`_
+  `LAMMPS - A flexible simulation tool for particle-based materials modeling at the atomic, meso, and continuum scales, Comp. Phys. Comm. 271, 108171 (2022) <https://doi.org/10.1016/j.cpc.2021.108171>`_
 
 So a project using LAMMPS or a derivative application that uses LAMMPS
 as a simulation engine should cite this paper.  The paper is expected to

doc/src/Library_utility.rst

@@ -13,6 +13,7 @@ functions.  They do not directly call the LAMMPS library.
 - :cpp:func:`lammps_fix_external_set_virial_peratom`
 - :cpp:func:`lammps_fix_external_set_vector_length`
 - :cpp:func:`lammps_fix_external_set_vector`
+- :cpp:func:`lammps_flush_buffers`
 - :cpp:func:`lammps_free`
 - :cpp:func:`lammps_is_running`
 - :cpp:func:`lammps_force_timeout`
@@ -72,6 +73,11 @@ where such memory buffers were allocated that require the use of
 
 -----------------------
 
+.. doxygenfunction:: lammps_flush_buffers
+   :project: progguide
+
+-----------------------
+
 .. doxygenfunction:: lammps_free
    :project: progguide
 

doc/src/Manual_version.rst

@@ -10,23 +10,31 @@ Whenever we fix a bug or update or add a feature, it will be merged into
 the *develop* branch of the git repository.  When a sufficient number of
 changes have accumulated *and* the software passes a set of automated
 tests, we release it in the next *patch* release, which are made every
-few weeks.  Info on patch releases are on `this website page
+few weeks.  The *release* branch of the git repository is updated with
+every such release.  Info on patch releases are on `this website page
 <https://www.lammps.org/bug.html>`_.
 
-Once or twice a year, only bug fixes and small, non-intrusive changes are
-included for a period of time, and the code is subjected to more detailed
+Once or twice a year, we apply only bug fixes and small, non-intrusive
+changes to the *develop* branch and the code is subjected to more detailed
 and thorough testing than the default automated testing.  The latest
-patch release after such a period is then labeled as a *stable* version.
+patch release after such a period is then also labeled as a *stable* version
+and the *stable* branch is updated with it.  Between stable releases
+we occasionally release some updates to the stable release containing
+only bug fixes and updates back-ported from *develop* but no new features
+and update the *stable* branch accordingly.
 
-Each version of LAMMPS contains all the features and bug-fixes up to
-and including its version date.
+Each version of LAMMPS contains all the documented features up to and
+including its version date.
 
 The version date is printed to the screen and logfile every time you
 run LAMMPS. It is also in the file src/version.h and in the LAMMPS
 directory name created when you unpack a tarball.  And it is on the
 first page of the :doc:`manual <Manual>`.
 
-* If you browse the HTML pages on the LAMMPS WWW site, they always
-  describe the most current patch release of LAMMPS.
+* If you browse the HTML pages on the LAMMPS WWW site, they will by
+  default describe the most current patch release version of LAMMPS.
+  In the navigation bar on the bottom left, there is the option to
+  view instead the documentation for the most recent *stable* version
+  or the latest version from the current development branch.
 * If you browse the HTML pages included in your tarball, they
   describe the version you have, which may be older.

doc/src/Modify_pair.rst

@@ -12,24 +12,24 @@ includes some optional methods to enable its use with rRESPA.
 
 Here is a brief description of the class methods in pair.h:
 
-+---------------------------------+-------------------------------------------------------------------+
-| compute                         | workhorse routine that computes pairwise interactions             |
-+---------------------------------+-------------------------------------------------------------------+
-| settings                        | reads the input script line with arguments you define             |
-+---------------------------------+-------------------------------------------------------------------+
-| coeff                           | set coefficients for one i,j type pair                            |
-+---------------------------------+-------------------------------------------------------------------+
-| init_one                        | perform initialization for one i,j type pair                      |
-+---------------------------------+-------------------------------------------------------------------+
-| init_style                      | initialization specific to this pair style                        |
-+---------------------------------+-------------------------------------------------------------------+
-| write & read_restart            | write/read i,j pair coeffs to restart files                       |
-+---------------------------------+-------------------------------------------------------------------+
-| write & read_restart_settings   | write/read global settings to restart files                       |
-+---------------------------------+-------------------------------------------------------------------+
-| single                          | force and energy of a single pairwise interaction between 2 atoms |
-+---------------------------------+-------------------------------------------------------------------+
-| compute_inner/middle/outer      | versions of compute used by rRESPA                                |
-+---------------------------------+-------------------------------------------------------------------+
++---------------------------------+---------------------------------------------------------------------+
+| compute                         | workhorse routine that computes pairwise interactions               |
++---------------------------------+---------------------------------------------------------------------+
+| settings                        | reads the input script line with arguments you define               |
++---------------------------------+---------------------------------------------------------------------+
+| coeff                           | set coefficients for one i,j type pair                              |
++---------------------------------+---------------------------------------------------------------------+
+| init_one                        | perform initialization for one i,j type pair                        |
++---------------------------------+---------------------------------------------------------------------+
+| init_style                      | initialization specific to this pair style                          |
++---------------------------------+---------------------------------------------------------------------+
+| write & read_restart            | write/read i,j pair coeffs to restart files                         |
++---------------------------------+---------------------------------------------------------------------+
+| write & read_restart_settings   | write/read global settings to restart files                         |
++---------------------------------+---------------------------------------------------------------------+
+| single                          | force/r and energy of a single pairwise interaction between 2 atoms |
++---------------------------------+---------------------------------------------------------------------+
+| compute_inner/middle/outer      | versions of compute used by rRESPA                                  |
++---------------------------------+---------------------------------------------------------------------+
 
 The inner/middle/outer routines are optional.

doc/src/Modify_style.rst

@@ -305,6 +305,40 @@ you are uncertain, please ask.
   FILE pointers and only be done on MPI rank 0.  Use the :cpp:func:`utils::logmesg`
   convenience function where possible.
 
+- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the
+  `C++ Core Guideline C.128 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
+  That means, you should only use `virtual` to declare a new virtual
+  function, `override` to indicate you are overriding an existing virtual
+  function, and `final` to prevent any further overriding.
+
+- Trivial destructors: Prefer not writing destructors when they are empty and `default`.
+
+  .. code-block:: c++
+
+     // don't write destructors for A or B like this
+     class A : protected Pointers {
+      public:
+        A();
+        ~A() override {}
+     };
+
+     class B : protected Pointers {
+      public:
+        B();
+        ~B() override = default;
+     };
+
+     // instead, let the compiler create the implicit default destructor by not writing it
+     class A : protected Pointers {
+      public:
+        A();
+     };
+
+     class B : protected Pointers {
+      public:
+        B();
+     };
+
 - Header files, especially those defining a "style", should only use
   the absolute minimum number of include files and **must not** contain
   any ``using`` statements. Typically that would be only the header for

doc/src/Packages_details.rst

@@ -1880,6 +1880,12 @@ MPIIO library.  It adds :doc:`dump styles <dump>` with a "mpiio" in
 their style name.  Restart files with an ".mpiio" suffix are also
 written and read in parallel.
 
+.. warning::
+
+   The MPIIO package is currently unmaintained and has become
+   unreliable. Use with caution.
+
+
 **Install:**
 
 The MPIIO package requires that LAMMPS is build in :ref:`MPI parallel mode <serial>`.

doc/src/Run_output.rst

@@ -106,7 +106,7 @@ individual ranks. Here is an example output for this section:
 ----------
 
 The third section above lists the number of owned atoms (Nlocal),
-ghost atoms (Nghost), and pair-wise neighbors stored per processor.
+ghost atoms (Nghost), and pairwise neighbors stored per processor.
 The max and min values give the spread of these values across
 processors with a 10-bin histogram showing the distribution. The total
 number of histogram counts is equal to the number of processors.
@@ -114,7 +114,7 @@ number of histogram counts is equal to the number of processors.
 ----------
 
 The last section gives aggregate statistics (across all processors)
-for pair-wise neighbors and special neighbors that LAMMPS keeps track
+for pairwise neighbors and special neighbors that LAMMPS keeps track
 of (see the :doc:`special_bonds <special_bonds>` command).  The number
 of times neighbor lists were rebuilt is tallied, as is the number of
 potentially *dangerous* rebuilds.  If atom movement triggered neighbor

doc/src/Speed_kokkos.rst

@@ -214,7 +214,7 @@ threads/task as Nt. The product of these two values should be N, i.e.
    The default for the :doc:`package kokkos <package>` command when
    running on KNL is to use "half" neighbor lists and set the Newton flag
    to "on" for both pairwise and bonded interactions. This will typically
-   be best for many-body potentials. For simpler pair-wise potentials, it
+   be best for many-body potentials. For simpler pairwise potentials, it
    may be faster to use a "full" neighbor list with Newton flag to "off".
    Use the "-pk kokkos" :doc:`command-line switch <Run_options>` to change
    the default :doc:`package kokkos <package>` options. See its page for

doc/src/Tools.rst

@@ -277,17 +277,34 @@ at ens-lyon.fr, alain.dequidt at uca.fr
 eam database tool
 -----------------------------
 
-The tools/eam_database directory contains a Fortran program that will
-generate EAM alloy setfl potential files for any combination of 16
-elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg, Co, Ti,
-Zr.  The files can then be used with the :doc:`pair_style eam/alloy <pair_eam>` command.
+The tools/eam_database directory contains a Fortran and a Python program
+that will generate EAM alloy setfl potential files for any combination
+of the 17 elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg,
+Co, Ti, Zr, Cr.  The files can then be used with the :doc:`pair_style
+eam/alloy <pair_eam>` command.
 
-The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov,
-and is based on his paper:
+The Fortran version of the tool was authored by Xiaowang Zhou (Sandia),
+xzhou at sandia.gov, with updates from Lucas Hale (NIST) lucas.hale at
+nist.gov and is based on his paper:
 
 X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69,
 144113 (2004).
 
+The parameters for Cr were taken from:
+
+Lin Z B, Johnson R A and Zhigilei L V, Phys. Rev. B 77 214108 (2008).
+
+The Python version of the tool was authored  by Germain Clavier
+(TU Eindhoven) g.m.g.c.clavier at tue.nl or germain.clavier at gmail.com
+
+.. note::
+
+   The parameters in the database are only optimized for individual
+   elements. The mixed parameters for interactions between different
+   elements generated by this tool are derived from simple mixing rules
+   and are thus inferior to parameterizations that are specifically
+   optimized for specific mixtures and combinations of elements.
+
 ----------
 
 .. _eamgn:

doc/src/angle_class2.rst

@@ -64,34 +64,44 @@ These are the 4 coefficients for the :math:`E_a` formula:
 radians internally; hence the various :math:`K` are effectively energy
 per radian\^2 or radian\^3 or radian\^4.
 
-For the :math:`E_{bb}` formula, each line in a :doc:`angle_coeff <angle_coeff>`
-command in the input script lists 4 coefficients, the first of which
-is "bb" to indicate they are BondBond coefficients.  In a data file,
-these coefficients should be listed under a "BondBond Coeffs" heading
-and you must leave out the "bb", i.e. only list 3 coefficients after
-the angle type.
+For the :math:`E_{bb}` formula, each line in a :doc:`angle_coeff
+<angle_coeff>` command in the input script lists 4 coefficients, the
+first of which is "bb" to indicate they are BondBond coefficients.  In
+a data file, these coefficients should be listed under a "BondBond
+Coeffs" heading and you must leave out the "bb", i.e. only list 3
+coefficients after the angle type.
 
 * bb
 * :math:`M` (energy/distance\^2)
 * :math:`r_1` (distance)
 * :math:`r_2` (distance)
 
-For the :math:`E_{ba}` formula, each line in a :doc:`angle_coeff <angle_coeff>`
-command in the input script lists 5 coefficients, the first of which
-is "ba" to indicate they are BondAngle coefficients.  In a data file,
-these coefficients should be listed under a "BondAngle Coeffs" heading
-and you must leave out the "ba", i.e. only list 4 coefficients after
-the angle type.
+For the :math:`E_{ba}` formula, each line in a :doc:`angle_coeff
+<angle_coeff>` command in the input script lists 5 coefficients, the
+first of which is "ba" to indicate they are BondAngle coefficients.
+In a data file, these coefficients should be listed under a "BondAngle
+Coeffs" heading and you must leave out the "ba", i.e. only list 4
+coefficients after the angle type.
 
 * ba
-* :math:`N_1` (energy/distance\^2)
-* :math:`N_2` (energy/distance\^2)
+* :math:`N_1` (energy/distance)
+* :math:`N_2` (energy/distance)
 * :math:`r_1` (distance)
 * :math:`r_2` (distance)
 
 The :math:`\theta_0` value in the :math:`E_{ba}` formula is not specified,
 since it is the same value from the :math:`E_a` formula.
 
+.. note::
+
+   It is important that the order of the I,J,K atoms in each angle
+   listed in the Angles section of the data file read by the
+   :doc:`read_data <read_data>` command be consistent with the order
+   of the :math:`r_1` and :math:`r_2` BondBond and BondAngle
+   coefficients.  This is because the terms in the formulas for
+   :math:`E_{bb}` and :math:`E_{ba}` will use the I,J atoms to compute
+   :math:`r_{ij}` and the J,K atoms to compute :math:`r_{jk}`.
+
 ----------
 
 .. include:: accel_styles.rst

doc/src/balance.rst

@@ -383,7 +383,7 @@ multiple groups, its weight is the product of the weight factors.
 
 This weight style is useful in combination with pair style
 :doc:`hybrid <pair_hybrid>`, e.g. when combining a more costly many-body
-potential with a fast pair-wise potential.  It is also useful when
+potential with a fast pairwise potential.  It is also useful when
 using :doc:`run_style respa <run_style>` where some portions of the
 system have many bonded interactions and others none.  It assumes that
 the computational cost for each group remains constant over time.

doc/src/bond_fene.rst

@@ -1,4 +1,5 @@
 .. index:: bond_style fene
+.. index:: bond_style fene/nm
 .. index:: bond_style fene/intel
 .. index:: bond_style fene/kk
 .. index:: bond_style fene/omp
@@ -8,12 +9,16 @@ bond_style fene command
 
 Accelerator Variants: *fene/intel*, *fene/kk*, *fene/omp*
 
+bond_style fene/nm command
+==========================
+
 Syntax
 """"""
 
 .. code-block:: LAMMPS
 
    bond_style fene
+   bond_style fene/nm
 
 Examples
 """"""""
@@ -23,6 +28,9 @@ Examples
    bond_style fene
    bond_coeff 1 30.0 1.5 1.0 1.0
 
+   bond_style fene/nm
+   bond_coeff 1 2.25344 1.5 1.0 1.12246 2 6
+
 Description
 """""""""""
 
@@ -38,16 +46,36 @@ term is attractive, the second Lennard-Jones term is repulsive.  The
 first term extends to :math:`R_0`, the maximum extent of the bond.  The second
 term is cutoff at :math:`2^\frac{1}{6} \sigma`, the minimum of the LJ potential.
 
-The following coefficients must be defined for each bond type via the
-:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
-the data file or restart files read by the :doc:`read_data <read_data>`
-or :doc:`read_restart <read_restart>` commands:
+The *fene/nm* bond style substitutes the standard LJ potential with the generalized LJ potential
+in the same form as in pair style :doc:`nm/cut <pair_nm>`. The bond energy is then given by
+
+.. math::
+
+  E = -0.5 K r_0^2  \ln \left[ 1 - \left(\frac{r}{R_0}\right)^2\right] + \frac{E_0}{(n-m)} \left[ m \left(\frac{r_0}{r}\right)^n - n \left(\frac{r_0}{r}\right)^m \right]
+
+Similar to the *fene* style, the generalized Lennard-Jones is cut off at
+the potential minimum, :math:`r_0`, to be repulsive only.  The following
+coefficients must be defined for each bond type via the :doc:`bond_coeff
+<bond_coeff>` command as in the example above, or in the data file or
+restart files read by the :doc:`read_data <read_data>` or
+:doc:`read_restart <read_restart>` commands:
 
 * :math:`K` (energy/distance\^2)
 * :math:`R_0` (distance)
 * :math:`\epsilon` (energy)
 * :math:`\sigma` (distance)
 
+For the *fene/nm* style, the following coefficients are used.  Please
+note, that the standard LJ potential and thus the regular FENE potential
+is recovered for (n=12 m=6) and :math:`r_0 = 2^\frac{1}{6} \sigma`.
+
+* :math:`K` (energy/distance\^2)
+* :math:`R_0` (distance)
+* :math:`E_0` (energy)
+* :math:`r_0` (distance)
+* :math:`n` (unitless)
+* :math:`m` (unitless)
+
 ----------
 
 .. include:: accel_styles.rst
@@ -57,9 +85,10 @@ or :doc:`read_restart <read_restart>` commands:
 Restrictions
 """"""""""""
 
-This bond style can only be used if LAMMPS was built with the MOLECULE
-package.  See the :doc:`Build package <Build_package>` page for more
-info.
+The *fene* bond style can only be used if LAMMPS was built with the MOLECULE
+package; the *fene/nm* bond style can only be used if LAMMPS was built
+with the EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>`
+page for more info.
 
 You typically should specify :doc:`special_bonds fene <special_bonds>`
 or :doc:`special_bonds lj/coul 0 1 1 <special_bonds>` to use this bond
@@ -68,7 +97,8 @@ style.  LAMMPS will issue a warning it that's not the case.
 Related commands
 """"""""""""""""
 
-:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
+:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
+:doc:`pair style lj/cut <pair_lj>`, :doc:`pair style nm/cut <pair_nm>`.
 
 Default
 """""""

doc/src/bond_style.rst

@@ -87,6 +87,7 @@ accelerated styles exist.
 * :doc:`class2 <bond_class2>` - COMPASS (class 2) bond
 * :doc:`fene <bond_fene>` - FENE (finite-extensible non-linear elastic) bond
 * :doc:`fene/expand <bond_fene_expand>` - FENE bonds with variable size particles
+* :doc:`fene/nm <bond_fene>` - FENE bonds with a generalized Lennard-Jones potential
 * :doc:`gaussian <bond_gaussian>` - multicentered Gaussian-based bond potential
 * :doc:`gromos <bond_gromos>` - GROMOS force field bond
 * :doc:`harmonic <bond_harmonic>` - harmonic bond

doc/src/compute.rst

@@ -174,6 +174,7 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
 * :doc:`angle <compute_angle>` - energy of each angle sub-style
 * :doc:`angle/local <compute_angle_local>` - theta and energy of each angle
 * :doc:`angmom/chunk <compute_angmom_chunk>` - angular momentum for each chunk
+* :doc:`ave/sphere/atom <compute_ave_sphere_atom>` - compute local density and temperature around each atom
 * :doc:`basal/atom <compute_basal_atom>` - calculates the hexagonal close-packed "c" lattice vector of each atom
 * :doc:`body/local <compute_body_local>` - attributes of body sub-particles
 * :doc:`bond <compute_bond>` - energy of each bond sub-style

doc/src/compute_ave_sphere_atom.rst

@@ -0,0 +1,101 @@
+.. index:: compute ave/sphere/atom
+.. index:: compute ave/sphere/atom/kk
+
+compute ave/sphere/atom command
+================================
+
+Accelerator Variants: *ave/sphere/atom/kk*
+
+Syntax
+""""""
+
+.. parsed-literal::
+
+   compute ID group-ID ave/sphere/atom keyword values ...
+
+* ID, group-ID are documented in :doc:`compute <compute>` command
+* ave/sphere/atom = style name of this compute command
+* one or more keyword/value pairs may be appended
+
+  .. parsed-literal::
+
+     keyword = *cutoff*
+       *cutoff* value = distance cutoff
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   compute 1 all ave/sphere/atom
+
+   compute 1 all ave/sphere/atom cutoff 5.0
+   comm_modify cutoff 5.0
+
+Description
+"""""""""""
+
+Define a computation that calculates the local density and temperature
+for each atom and neighbors inside a spherical cutoff.
+
+The optional keyword *cutoff* defines the distance cutoff
+used when searching for neighbors. The default value is the cutoff
+specified by the pair style. If no pair style is defined, then a cutoff
+must be defined using this keyword. If the specified cutoff is larger than
+that of the pair_style plus neighbor skin (or no pair style is defined),
+the *comm_modify cutoff* option must also be set to match that of the
+*cutoff* keyword.
+
+The neighbor list needed to compute this quantity is constructed each
+time the calculation is performed (i.e. each time a snapshot of atoms
+is dumped).  Thus it can be inefficient to compute/dump this quantity
+too frequently.
+
+.. note::
+
+   If you have a bonded system, then the settings of
+   :doc:`special_bonds <special_bonds>` command can remove pairwise
+   interactions between atoms in the same bond, angle, or dihedral.  This
+   is the default setting for the :doc:`special_bonds <special_bonds>`
+   command, and means those pairwise interactions do not appear in the
+   neighbor list.  Because this fix uses the neighbor list, it also means
+   those pairs will not be included in the order parameter.  This
+   difficulty can be circumvented by writing a dump file, and using the
+   :doc:`rerun <rerun>` command to compute the order parameter for
+   snapshots in the dump file.  The rerun script can use a
+   :doc:`special_bonds <special_bonds>` command that includes all pairs in
+   the neighbor list.
+
+----------
+
+
+.. include:: accel_styles.rst
+
+
+----------
+
+Output info
+"""""""""""
+
+This compute calculates a per-atom array with two columns: density and temperature.
+
+These values can be accessed by any command that uses per-atom values
+from a compute as input.  See the :doc:`Howto output <Howto_output>` doc
+page for an overview of LAMMPS output options.
+
+Restrictions
+""""""""""""
+
+This compute is part of the EXTRA-COMPUTE package.  It is only enabled if
+LAMMPS was built with that package.  See the :doc:`Build package <Build_package>` page for more info.
+
+Related commands
+""""""""""""""""
+
+:doc:`comm_modify <comm_modify>`
+
+Default
+"""""""
+
+The option defaults are *cutoff* = pair style cutoff
+

doc/src/compute_bond_local.rst

@@ -13,7 +13,7 @@ Syntax
 * ID, group-ID are documented in :doc:`compute <compute>` command
 * bond/local = style name of this compute command
 * one or more values may be appended
-* value = *dist* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v_name*
+* value = *dist* or *dx* or *dy* or *dz* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v_name*
 
 .. parsed-literal::
 
@@ -21,6 +21,7 @@ Syntax
      *engpot* = bond potential energy
      *force* = bond force
 
+     *dx*,\ *dy*,\ *dz* = components of pairwise distance
      *fx*,\ *fy*,\ *fz* = components of bond force
      *engvib* = bond kinetic energy of vibration
      *engrot* = bond kinetic energy of rotation
@@ -63,6 +64,9 @@ whether the 2 atoms represent a simple diatomic molecule, or are part
 of some larger molecule.
 
 The value *dist* is the current length of the bond.
+The values *dx*, *dy*, and *dz* are the xyz components of the
+*distance* between the pair of atoms. This value is always the
+distance from the atom of lower to the one with the higher id.
 
 The value *engpot* is the potential energy for the bond,
 based on the current separation of the pair of atoms in the bond.

doc/src/compute_heat_flux.rst

@@ -89,13 +89,20 @@ included in the calculation.
 .. warning::
 
    The compute *heat/flux* has been reported to produce unphysical
-   values for angle, dihedral and improper contributions
+   values for angle, dihedral, improper and constraint force contributions
    when used with :doc:`compute stress/atom <compute_stress_atom>`,
-   as discussed in :ref:`(Surblys) <Surblys2>` and :ref:`(Boone) <Boone>`.
-   You are strongly advised to
+   as discussed in :ref:`(Surblys2019) <Surblys3>`, :ref:`(Boone) <Boone>`
+   and :ref:`(Surblys2021) <Surblys4>`. You are strongly advised to
    use :doc:`compute centroid/stress/atom <compute_stress_atom>`,
    which has been implemented specifically for such cases.
 
+.. warning::
+
+   Due to an implementation detail, the :math:`y` and :math:`z`
+   components of heat flux from :doc:`fix rigid <fix_rigid>`
+   contribution when computed via :doc:`compute stress/atom <compute_stress_atom>`
+   are highly unphysical and should not be used.
+
 The Green-Kubo formulas relate the ensemble average of the
 auto-correlation of the heat flux :math:`\mathbf{J}`
 to the thermal conductivity :math:`\kappa`:
@@ -232,10 +239,14 @@ none
 
 ----------
 
-.. _Surblys2:
+.. _Surblys3:
 
-**(Surblys)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
+**(Surblys2019)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
 
 .. _Boone:
 
 **(Boone)** Boone, Babaei, Wilmer, J Chem Theory Comput, 15, 5579--5587 (2019).
+
+.. _Surblys4:
+
+**(Surblys2021)** Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021).

doc/src/compute_pair_local.rst

@@ -13,11 +13,12 @@ Syntax
 * ID, group-ID are documented in :doc:`compute <compute>` command
 * pair/local = style name of this compute command
 * one or more values may be appended
-* value = *dist* or *eng* or *force* or *fx* or *fy* or *fz* or *pN*
+* value = *dist* or *dx* or *dy* or *dz* or *eng* or *force* or *fx* or *fy* or *fz* or *pN*
 
   .. parsed-literal::
 
        *dist* = pairwise distance
+       *dx*,\ *dy*,\ *dz* = components of pairwise distance
        *eng* = pairwise energy
        *force* = pairwise force
        *fx*,\ *fy*,\ *fz* = components of pairwise force
@@ -56,6 +57,9 @@ force cutoff distance for that interaction, as defined by the
 commands.
 
 The value *dist* is the distance between the pair of atoms.
+The values *dx*, *dy*, and *dz* are the xyz components of the
+*distance* between the pair of atoms. This value is always the
+distance from the atom of lower to the one with the higher id.
 
 The value *eng* is the interaction energy for the pair of atoms.
 
@@ -89,10 +93,10 @@ from the second of the two sub-styles.  If the referenced *pN*
 is not computed for the specific pairwise interaction (based on
 atom types), then the output will be 0.0.
 
-The value *dist* will be in distance :doc:`units <units>`.  The value
-*eng* will be in energy :doc:`units <units>`.  The values *force*, *fx*,
-*fy*, and *fz* will be in force :doc:`units <units>`.  The values *pN*
-will be in whatever units the pair style defines.
+The value *dist*, *dx*, *dy* and *dz* will be in distance :doc:`units <units>`.
+The value *eng* will be in energy :doc:`units <units>`.
+The values *force*, *fx*, *fy*, and *fz* will be in force :doc:`units <units>`.
+The values *pN* will be in whatever units the pair style defines.
 
 The optional *cutoff* keyword determines how the force cutoff distance
 for an interaction is determined.  For the default setting of *type*,

doc/src/compute_pressure.rst

@@ -141,7 +141,7 @@ Related commands
 """"""""""""""""
 
 :doc:`compute temp <compute_temp>`, :doc:`compute stress/atom <compute_stress_atom>`,
-:doc:`thermo_style <thermo_style>`,
+:doc:`thermo_style <thermo_style>`, :doc:`fix numdiff/virial <fix_numdiff_virial>`,
 
 Default
 """""""

doc/src/compute_pressure_cylinder.rst

@@ -61,7 +61,7 @@ Restrictions
 This compute currently calculates the pressure tensor contributions
 for pair styles only (i.e. no bond, angle, dihedral, etc. contributions
 and in the presence of bonded interactions, the result will be incorrect
-due to exclusions for special bonds)  and requires pair-wise force
+due to exclusions for special bonds)  and requires pairwise force
 calculations not available for most many-body pair styles. K-space
 calculations are also excluded. Note that this pressure compute outputs
 the configurational terms only; the kinetic contribution is not included

doc/src/compute_stress_atom.rst

@@ -87,6 +87,10 @@ Tersoff 3-body interaction) is assigned in equal portions to each atom
 in the set.  E.g. 1/4 of the dihedral virial to each of the 4 atoms,
 or 1/3 of the fix virial due to SHAKE constraints applied to atoms in
 a water molecule via the :doc:`fix shake <fix_shake>` command.
+As an exception, the virial contribution from
+constraint forces in :doc:`fix rigid <fix_rigid>` on each atom
+is computed from the constraint force acting on the corresponding atom
+and its position, i.e. the total virial is not equally distributed.
 
 In case of compute *centroid/stress/atom*, the virial contribution is:
 
@@ -103,13 +107,25 @@ atom :math:`I` due to the interaction and the relative position
 :math:`\mathbf{r}_{I0}` of the atom :math:`I` to the geometric center
 of the interacting atoms, i.e. centroid, is used.  As the geometric
 center is different for each interaction, the :math:`\mathbf{r}_{I0}`
-also differs.  The sixth and seventh terms, Kspace and :doc:`fix
-<fix>` contribution respectively, are computed identical to compute
-*stress/atom*.  Although the total system virial is the same as
+also differs. The sixth term, Kspace contribution,
+is computed identically to compute *stress/atom*.
+The seventh term is handed differently depending on
+if the constraint forces are due to :doc:`fix shake <fix_shake>`
+or :doc:`fix rigid <fix_rigid>`.
+In case of SHAKE constraints, each distance constraint is
+handed as a pairwise interaction.
+E.g. in case of a water molecule, two OH and one HH distance
+constraints are treated as three pairwise interactions.
+In case of :doc:`fix rigid <fix_rigid>`,
+all constraint forces in the molecule are treated
+as a single many-body interaction with a single centroid position.
+In case of water molecule, the formula expression would become
+identical to that of the three-body angle interaction.
+Although the total system virial is the same as
 compute *stress/atom*, compute *centroid/stress/atom* is know to
-result in more consistent heat flux values for angle, dihedrals and
-improper contributions when computed via :doc:`compute heat/flux
-<compute_heat_flux>`.
+result in more consistent heat flux values for angle, dihedrals,
+improper and constraint force contributions
+when computed via :doc:`compute heat/flux <compute_heat_flux>`.
 
 If no extra keywords are listed, the kinetic contribution all of the
 virial contribution terms are included in the per-atom stress tensor.
@@ -134,7 +150,8 @@ contribution for the cluster interaction is divided evenly among those
 atoms.
 
 Details of how compute *centroid/stress/atom* obtains the virial for
-individual atoms is given in :ref:`(Surblys) <Surblys1>`, where the
+individual atoms are given in :ref:`(Surblys2019) <Surblys1>` and
+:ref:`(Surblys2021) <Surblys2>`, where the
 idea is that the virial of the atom :math:`I` is the result of only
 the force :math:`\mathbf{F}_I` on the atom due to the interaction and
 its positional vector :math:`\mathbf{r}_{I0}`, relative to the
@@ -235,10 +252,10 @@ between the pair of particles.  All bond styles are supported.  All
 angle, dihedral, improper styles are supported with the exception of
 INTEL and KOKKOS variants of specific styles.  It also does not
 support models with long-range Coulombic or dispersion forces,
-i.e. the kspace_style command in LAMMPS.  It also does not support the
-following fixes which add rigid-body constraints: :doc:`fix shake
-<fix_shake>`, :doc:`fix rattle <fix_shake>`, :doc:`fix rigid
-<fix_rigid>`, :doc:`fix rigid/small <fix_rigid>`.
+i.e. the kspace_style command in LAMMPS.  It also does not implement the
+following fixes which add rigid-body constraints:
+:doc:`fix rigid/* <fix_rigid>` and the OpenMP accelerated version of :doc:`fix rigid/small <fix_rigid>`,
+while all other :doc:`fix rigid/*/small <fix_rigid>` are implemented.
 
 LAMMPS will generate an error if one of these options is included in
 your model.  Extension of centroid stress calculations to these force
@@ -270,4 +287,8 @@ none
 
 .. _Surblys1:
 
-**(Surblys)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
+**(Surblys2019)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
+
+.. _Surblys2:
+
+**(Surblys2021)** Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021).

doc/src/delete_atoms.rst

@@ -20,8 +20,10 @@ Syntax
          cutoff = delete one atom from pairs of atoms within the cutoff (distance units)
          group1-ID = one atom in pair must be in this group
          group2-ID = other atom in pair must be in this group
-       *porosity* args = region-ID fraction seed
+       *porosity* args = group-ID region-ID fraction seed
+         group-ID = group within which to perform deletions
          region-ID = region within which to perform deletions
+                     or NULL to only impose the group criterion
          fraction = delete this fraction of atoms
          seed = random number seed (positive integer)
 
@@ -43,7 +45,8 @@ Examples
    delete_atoms region sphere compress no
    delete_atoms overlap 0.3 all all
    delete_atoms overlap 0.5 solvent colloid
-   delete_atoms porosity cube 0.1 482793 bond yes
+   delete_atoms porosity all cube 0.1 482793 bond yes
+   delete_atoms porosity polymer cube 0.1 482793 bond yes
 
 Description
 """""""""""
@@ -76,12 +79,17 @@ have occurred that no atom pairs within the cutoff will remain
 minimum number of atoms will be deleted, or that the same atoms will
 be deleted when running on different numbers of processors.
 
-For style *porosity* a specified *fraction* of atoms are deleted
-within the specified region.  For example, if fraction is 0.1, then
-10% of the atoms will be deleted.  The atoms to delete are chosen
-randomly.  There is no guarantee that the exact fraction of atoms will
-be deleted, or that the same atoms will be deleted when running on
-different numbers of processors.
+For style *porosity* a specified *fraction* of atoms are deleted which
+are both in the specified group and within the specified region.  The
+region-ID can be specified as NULL to only impose the group criterion.
+Likewise, specifying the group-ID as *all* will only impose the region
+criterion.
+
+For example, if fraction is 0.1, then 10% of the eligible atoms will
+be deleted.  The atoms to delete are chosen randomly.  There is no
+guarantee that the exact fraction of atoms will be deleted, or that
+the same atoms will be deleted when running on different numbers of
+processors.
 
 If the *compress* keyword is set to *yes*, then after atoms are
 deleted, then atom IDs are re-assigned so that they run from 1 to the
@@ -89,8 +97,8 @@ number of atoms in the system.  Note that this is not done for
 molecular systems (see the :doc:`atom_style <atom_style>` command),
 regardless of the *compress* setting, since it would foul up the bond
 connectivity that has already been assigned.  However, the
-:doc:`reset_atom_ids <reset_atom_ids>` command can be used after this command to
-accomplish the same thing.
+:doc:`reset_atom_ids <reset_atom_ids>` command can be used after this
+command to accomplish the same thing.
 
 Note that the re-assignment of IDs is not really a compression, where
 gaps in atom IDs are removed by decrementing atom IDs that are larger.
@@ -100,15 +108,15 @@ the :doc:`create_atoms <create_atoms>` command explains.
 
 A molecular system with fixed bonds, angles, dihedrals, or improper
 interactions, is one where the topology of the interactions is
-typically defined in the data file read by the
-:doc:`read_data <read_data>` command, and where the interactions
-themselves are defined with the :doc:`bond_style <bond_style>`,
-:doc:`angle_style <angle_style>`, etc commands.  If you delete atoms
-from such a system, you must be careful not to end up with bonded
-interactions that are stored by remaining atoms but which include
-deleted atoms.  This will cause LAMMPS to generate a "missing atoms"
-error when the bonded interaction is computed.  The *bond* and *mol*
-keywords offer two ways to do that.
+typically defined in the data file read by the :doc:`read_data
+<read_data>` command, and where the interactions themselves are
+defined with the :doc:`bond_style <bond_style>`, :doc:`angle_style
+<angle_style>`, etc commands.  If you delete atoms from such a system,
+you must be careful not to end up with bonded interactions that are
+stored by remaining atoms but which include deleted atoms.  This will
+cause LAMMPS to generate a "missing atoms" error when the bonded
+interaction is computed.  The *bond* and *mol* keywords offer two ways
+to do that.
 
 It the *bond* keyword is set to *yes* then any bond or angle or
 dihedral or improper interaction that includes a deleted atom is also

doc/src/dump.rst

@@ -137,7 +137,7 @@ Examples
    dump myDump all atom/gz 100 dump.atom.gz
    dump myDump all atom/zstd 100 dump.atom.zst
    dump 2 subgroup atom 50 dump.run.bin
-   dump 2 subgroup atom 50 dump.run.mpiio.bin
+   dump 2 subgroup atom/mpiio 50 dump.run.mpiio.bin
    dump 4a all custom 100 dump.myforce.* id type x y vx fx
    dump 4b flow custom 100 dump.%.myforce id type c_myF[3] v_ke
    dump 4b flow custom 100 dump.%.myforce id type c_myF[*] v_ke
@@ -169,11 +169,12 @@ or multiple smaller files).
 
 .. note::
 
-   Because periodic boundary conditions are enforced only on
-   timesteps when neighbor lists are rebuilt, the coordinates of an atom
-   written to a dump file may be slightly outside the simulation box.
-   Re-neighbor timesteps will not typically coincide with the timesteps
-   dump snapshots are written.  See the :doc:`dump_modify pbc <dump_modify>` command if you with to force coordinates to be
+   Because periodic boundary conditions are enforced only on timesteps
+   when neighbor lists are rebuilt, the coordinates of an atom written
+   to a dump file may be slightly outside the simulation box.
+   Re-neighbor timesteps will not typically coincide with the
+   timesteps dump snapshots are written.  See the :doc:`dump_modify
+   pbc <dump_modify>` command if you with to force coordinates to be
    strictly inside the simulation box.
 
 .. note::
@@ -189,20 +190,21 @@ or multiple smaller files).
    multiple processors, each of which owns a subset of the atoms.
 
 For the *atom*, *custom*, *cfg*, and *local* styles, sorting is off by
-default.  For the *dcd*, *xtc*, *xyz*, and *molfile* styles, sorting by
-atom ID is on by default. See the :doc:`dump_modify <dump_modify>` doc
-page for details.
+default.  For the *dcd*, *xtc*, *xyz*, and *molfile* styles, sorting
+by atom ID is on by default. See the :doc:`dump_modify <dump_modify>`
+doc page for details.
 
-The *atom/gz*, *cfg/gz*, *custom/gz*, *local/gz*, and *xyz/gz* styles are identical
-in command syntax to the corresponding styles without "gz", however,
-they generate compressed files using the zlib library. Thus the filename
-suffix ".gz" is mandatory. This is an alternative approach to writing
-compressed files via a pipe, as done by the regular dump styles, which
-may be required on clusters where the interface to the high-speed network
-disallows using the fork() library call (which is needed for a pipe).
-For the remainder of this doc page, you should thus consider the *atom*
-and *atom/gz* styles (etc) to be inter-changeable, with the exception
-of the required filename suffix.
+The *atom/gz*, *cfg/gz*, *custom/gz*, *local/gz*, and *xyz/gz* styles
+are identical in command syntax to the corresponding styles without
+"gz", however, they generate compressed files using the zlib
+library. Thus the filename suffix ".gz" is mandatory. This is an
+alternative approach to writing compressed files via a pipe, as done
+by the regular dump styles, which may be required on clusters where
+the interface to the high-speed network disallows using the fork()
+library call (which is needed for a pipe).  For the remainder of this
+doc page, you should thus consider the *atom* and *atom/gz* styles
+(etc) to be inter-changeable, with the exception of the required
+filename suffix.
 
 Similarly, the *atom/zstd*, *cfg/zstd*, *custom/zstd*, *local/zstd*,
 and *xyz/zstd* styles are identical to the gz styles, but use the Zstd
@@ -219,6 +221,11 @@ you should thus consider the *atom* and *atom/mpiio* styles (etc) to
 be inter-changeable.  The one exception is how the filename is
 specified for the MPI-IO styles, as explained below.
 
+.. warning::
+
+   The MPIIO package is currently unmaintained and has become
+   unreliable. Use with caution.
+
 The precision of values output to text-based dump files can be
 controlled by the :doc:`dump_modify format <dump_modify>` command and
 its options.
@@ -275,10 +282,11 @@ This bounding box is convenient for many visualization programs.  The
 meaning of the 6 character flags for "xx yy zz" is the same as above.
 
 Note that the first two numbers on each line are now xlo_bound instead
-of xlo, etc, since they represent a bounding box.  See the :doc:`Howto triclinic <Howto_triclinic>` page for a geometric description
-of triclinic boxes, as defined by LAMMPS, simple formulas for how the
-6 bounding box extents (xlo_bound,xhi_bound,etc) are calculated from
-the triclinic parameters, and how to transform those parameters to and
+of xlo, etc, since they represent a bounding box.  See the :doc:`Howto
+triclinic <Howto_triclinic>` page for a geometric description of
+triclinic boxes, as defined by LAMMPS, simple formulas for how the 6
+bounding box extents (xlo_bound,xhi_bound,etc) are calculated from the
+triclinic parameters, and how to transform those parameters to and
 from other commonly used triclinic representations.
 
 The "ITEM: ATOMS" line in each snapshot lists column descriptors for
@@ -310,23 +318,24 @@ written to the dump file.  This local data is typically calculated by
 each processor based on the atoms it owns, but there may be zero or
 more entities per atom, e.g. a list of bond distances.  An explanation
 of the possible dump local attributes is given below.  Note that by
-using input from the :doc:`compute property/local <compute_property_local>` command with dump local,
-it is possible to generate information on bonds, angles, etc that can
-be cut and pasted directly into a data file read by the
-:doc:`read_data <read_data>` command.
+using input from the :doc:`compute property/local
+<compute_property_local>` command with dump local, it is possible to
+generate information on bonds, angles, etc that can be cut and pasted
+directly into a data file read by the :doc:`read_data <read_data>`
+command.
 
 Style *cfg* has the same command syntax as style *custom* and writes
-extended CFG format files, as used by the
-`AtomEye <http://li.mit.edu/Archive/Graphics/A/>`_ visualization
-package.  Since the extended CFG format uses a single snapshot of the
-system per file, a wildcard "\*" must be included in the filename, as
-discussed below.  The list of atom attributes for style *cfg* must
-begin with either "mass type xs ys zs" or "mass type xsu ysu zsu"
-since these quantities are needed to write the CFG files in the
-appropriate format (though the "mass" and "type" fields do not appear
-explicitly in the file).  Any remaining attributes will be stored as
-"auxiliary properties" in the CFG files.  Note that you will typically
-want to use the :doc:`dump_modify element <dump_modify>` command with
+extended CFG format files, as used by the `AtomEye
+<http://li.mit.edu/Archive/Graphics/A/>`_ visualization package.
+Since the extended CFG format uses a single snapshot of the system per
+file, a wildcard "\*" must be included in the filename, as discussed
+below.  The list of atom attributes for style *cfg* must begin with
+either "mass type xs ys zs" or "mass type xsu ysu zsu" since these
+quantities are needed to write the CFG files in the appropriate format
+(though the "mass" and "type" fields do not appear explicitly in the
+file).  Any remaining attributes will be stored as "auxiliary
+properties" in the CFG files.  Note that you will typically want to
+use the :doc:`dump_modify element <dump_modify>` command with
 CFG-formatted files, to associate element names with atom types, so
 that AtomEye can render atoms appropriately. When unwrapped
 coordinates *xsu*, *ysu*, and *zsu* are requested, the nominal AtomEye
@@ -452,6 +461,11 @@ use the :doc:`read_dump <read_dump>` command or perform other
 post-processing, just as if the dump file was not written using
 MPI-IO.
 
+.. warning::
+
+   The MPIIO package is currently unmaintained and has become
+   unreliable. Use with caution.
+
 Note that MPI-IO dump files are one large file which all processors
 write to.  You thus cannot use the "%" wildcard character described
 above in the filename since that specifies generation of multiple
@@ -708,8 +722,9 @@ are part of the MPIIO package.  They are only enabled if LAMMPS was
 built with that package.  See the :doc:`Build package <Build_package>`
 doc page for more info.
 
-The *xtc* style is part of the MISC package.  It is only enabled if
-LAMMPS was built with that package.  See the :doc:`Build package <Build_package>` page for more info.
+The *xtc* and *dcd* styles are part of the EXTRA-DUMP package.  They
+are only enabled if LAMMPS was built with that package.  See the
+:doc:`Build package <Build_package>` page for more info.
 
 Related commands
 """"""""""""""""

doc/src/dump_image.rst

@@ -6,6 +6,8 @@ dump image command
 dump movie command
 ==================
 
+(see below for :ref:`dump_modify options <dump_modify_image>` specific to dump image/movie)
+
 Syntax
 """"""
 
@@ -15,7 +17,7 @@ Syntax
 
 * ID = user-assigned name for the dump
 * group-ID = ID of the group of atoms to be imaged
-* style = *image* or *movie* = style of dump command (other styles *atom* or *cfg* or *dcd* or *xtc* or *xyz* or *local* or *custom* are discussed on the :doc:`dump <dump>` doc page)
+* style = *image* or *movie* = style of dump command (other styles such as *atom* or *cfg* or *dcd* or *xtc* or *xyz* or *local* or *custom* are discussed on the :doc:`dump <dump>` doc page)
 * N = dump every this many timesteps
 * file = name of file to write image to
 * color = atom attribute that determines color of each atom
@@ -79,6 +81,69 @@ Syntax
          seed = random # seed (positive integer)
          dfactor = strength of shading from 0.0 to 1.0
 
+
+.. _dump_modify_image:
+
+dump_modify options for dump image/movie
+========================================
+
+Syntax
+""""""
+
+.. parsed-literal::
+
+   dump_modify dump-ID keyword values ...
+
+* these keywords apply only to the *image* and *movie* styles and are documented on this page
+* keyword = *acolor* or *adiam* or *amap* or *backcolor* or *bcolor* or *bdiam* or *boxcolor* or *color* or *bitrate* or *framerate*
+* see the :doc:`dump modify <dump_modify>` doc page for more general keywords
+
+  .. parsed-literal::
+
+       *acolor* args = type color
+         type = atom type or range of types (see below)
+         color = name of color or color1/color2/...
+       *adiam* args = type diam
+         type = atom type or range of types (see below)
+         diam = diameter of atoms of that type (distance units)
+       *amap* args = lo hi style delta N entry1 entry2 ... entryN
+         lo = number or *min* = lower bound of range of color map
+         hi = number or *max* = upper bound of range of color map
+         style = 2 letters = "c" or "d" or "s" plus "a" or "f"
+           "c" for continuous
+           "d" for discrete
+           "s" for sequential
+           "a" for absolute
+           "f" for fractional
+         delta = binsize (only used for style "s", otherwise ignored)
+           binsize = range is divided into bins of this width
+         N = # of subsequent entries
+         entry = value color (for continuous style)
+           value = number or *min* or *max* = single value within range
+           color = name of color used for that value
+         entry = lo hi color (for discrete style)
+           lo/hi = number or *min* or *max* = lower/upper bound of subset of range
+           color = name of color used for that subset of values
+         entry = color (for sequential style)
+           color = name of color used for a bin of values
+       *backcolor* arg = color
+         color = name of color for background
+       *bcolor* args = type color
+         type = bond type or range of types (see below)
+         color = name of color or color1/color2/...
+       *bdiam* args = type diam
+         type = bond type or range of types (see below)
+         diam = diameter of bonds of that type (distance units)
+       *boxcolor* arg = color
+         color = name of color for simulation box lines and processor sub-domain lines
+       *color* args = name R G B
+         name = name of color
+         R,G,B = red/green/blue numeric values from 0.0 to 1.0
+       *bitrate* arg = rate
+         rate = target bitrate for movie in kbps
+       *framerate* arg = fps
+         fps = frames per second for movie
+
 Examples
 """"""""
 
@@ -91,6 +156,8 @@ Examples
    dump m1 all movie 1000 movie.avi type type size 640 480
    dump m2 all movie 100 movie.m4v type type zoom 1.8 adiam v_value size 1280 720
 
+   dump_modify 1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red
+
 Description
 """""""""""
 
@@ -145,10 +212,10 @@ is used.
 Similarly, the format of the resulting movie is chosen with the
 *movie* dump style. This is handled by the underlying FFmpeg converter
 and thus details have to be looked up in the `FFmpeg documentation
-<http://ffmpeg.org/ffmpeg.html>`_.
-Typical examples are: .avi, .mpg, .m4v, .mp4, .mkv, .flv, .mov, .gif
-Additional settings of the movie compression like bitrate and
-framerate can be set using the :doc:`dump_modify <dump_modify>` command.
+<http://ffmpeg.org/ffmpeg.html>`_.  Typical examples are: .avi, .mpg,
+.m4v, .mp4, .mkv, .flv, .mov, .gif Additional settings of the movie
+compression like bitrate and framerate can be set using the
+dump_modify command as described below.
 
 To write out JPEG and PNG format files, you must build LAMMPS with
 support for the corresponding JPEG or PNG library. To convert images
@@ -210,19 +277,20 @@ to colors is as follows:
 * type 6 = cyan
 
 and repeats itself for types > 6.  This mapping can be changed by the
-:doc:`dump_modify acolor <dump_modify>` command.
+"dump_modify acolor" command, as described below.
 
 If *type* is specified for the *diameter* setting then the diameter of
 each atom is determined by its atom type.  By default all types have
-diameter 1.0.  This mapping can be changed by the :doc:`dump_modify adiam <dump_modify>` command.
+diameter 1.0.  This mapping can be changed by the "dump_modify adiam"
+command, as described below.
 
 If *element* is specified for the *color* and/or *diameter* setting,
 then the color and/or diameter of each atom is determined by which
 element it is, which in turn is specified by the element-to-type
-mapping specified by the "dump_modify element" command.  By default
-every atom type is C (carbon).  Every element has a color and diameter
-associated with it, which is the same as the colors and sizes used by
-the `AtomEye <atomeye_>`_ visualization package.
+mapping specified by the "dump_modify element" command, as described
+below.  By default every atom type is C (carbon).  Every element has a
+color and diameter associated with it, which is the same as the colors
+and sizes used by the `AtomEye <atomeye_>`_ visualization package.
 
 .. _atomeye: http://li.mit.edu/Archive/Graphics/A/
 
@@ -232,13 +300,13 @@ settings, they are interpreted in the following way.
 If "vx", for example, is used as the *color* setting, then the color
 of the atom will depend on the x-component of its velocity.  The
 association of a per-atom value with a specific color is determined by
-a "color map", which can be specified via the
-:doc:`dump_modify <dump_modify>` command.  The basic idea is that the
-atom-attribute will be within a range of values, and every value
-within the range is mapped to a specific color.  Depending on how the
-color map is defined, that mapping can take place via interpolation so
-that a value of -3.2 is halfway between "red" and "blue", or
-discretely so that the value of -3.2 is "orange".
+a "color map", which can be specified via the dump_modify command, as
+described below.  The basic idea is that the atom-attribute will be
+within a range of values, and every value within the range is mapped
+to a specific color.  Depending on how the color map is defined, that
+mapping can take place via interpolation so that a value of -3.2 is
+halfway between "red" and "blue", or discretely so that the value of
+-3.2 is "orange".
 
 If "vx", for example, is used as the *diameter* setting, then the atom
 will be rendered using the x-component of its velocity as the
@@ -251,9 +319,10 @@ diameter, which can be used as the *diameter* setting.
 
 The various keywords listed above control how the image is rendered.
 As listed below, all of the keywords have defaults, most of which you
-will likely not need to change.  The :doc:`dump modify <dump_modify>`
-also has options specific to the dump image style, particularly for
-assigning colors to atoms, bonds, and other image features.
+will likely not need to change.  As described below, the dump modify
+command also has options specific to the dump image style,
+particularly for assigning colors to atoms, bonds, and other image
+features.
 
 ----------
 
@@ -295,7 +364,7 @@ types to colors is as follows:
 * type 6 = cyan
 
 and repeats itself for bond types > 6.  This mapping can be changed by
-the :doc:`dump_modify bcolor <dump_modify>` command.
+the "dump_modify bcolor" command, as described below.
 
 The bond *width* value can be a numeric value or *atom* or *type* (or
 *none* as indicated above).
@@ -310,7 +379,8 @@ of the 2 atoms in the bond.
 
 If *type* is specified for the *width* value then the diameter of each
 bond is determined by its bond type.  By default all types have
-diameter 0.5.  This mapping can be changed by the :doc:`dump_modify bdiam <dump_modify>` command.
+diameter 0.5.  This mapping can be changed by the "dump_modify bdiam" command,
+as described below.
 
 ----------
 
@@ -330,7 +400,7 @@ mapping of types to colors is as follows:
 * type 6 = cyan
 
 and repeats itself for types > 6.  There is not yet an option to
-change this via the :doc:`dump_modify <dump_modify>` command.
+change this via the dump_modify command.
 
 The line *width* can only be a numeric value, which specifies that all
 lines will be drawn as cylinders with that diameter, e.g. 1.0, which
@@ -357,7 +427,7 @@ default the mapping of types to colors is as follows:
 * type 6 = cyan
 
 and repeats itself for types > 6.  There is not yet an option to
-change this via the :doc:`dump_modify <dump_modify>` command.
+change this via the dump_modify command.
 
 ----------
 
@@ -390,7 +460,7 @@ particle.  By default the mapping of types to colors is as follows:
 * type 6 = cyan
 
 and repeats itself for types > 6.  There is not yet an option to
-change this via the :doc:`dump_modify <dump_modify>` command.
+change this via the dump_modify command.
 
 ----------
 
@@ -414,7 +484,7 @@ the mapping of types to colors is as follows:
 * type 6 = cyan
 
 and repeats itself for types > 6.  There is not yet an option to
-change this via the :doc:`dump_modify <dump_modify>` command.
+change this via the dump_modify command.
 
 ----------
 
@@ -488,7 +558,8 @@ are rendered as thin cylinders in the image.  If *no* is set, then the
 box boundaries are not drawn and the *diam* setting is ignored.  If
 *yes* is set, the 12 edges of the box are drawn, with a diameter that
 is a fraction of the shortest box length in x,y,z (for 3d) or x,y (for
-2d).  The color of the box boundaries can be set with the :doc:`dump_modify boxcolor <dump_modify>` command.
+2d).  The color of the box boundaries can be set with the "dump_modify
+boxcolor" command.
 
 The *axes* keyword determines if and how the coordinate axes are
 rendered as thin cylinders in the image.  If *no* is set, then the
@@ -507,7 +578,8 @@ set (default), then the sub-domain boundaries are not drawn and the
 *diam* setting is ignored.  If *yes* is set, the 12 edges of each
 processor sub-domain are drawn, with a diameter that is a fraction of
 the shortest box length in x,y,z (for 3d) or x,y (for 2d).  The color
-of the sub-domain boundaries can be set with the :doc:`dump_modify boxcolor <dump_modify>` command.
+of the sub-domain boundaries can be set with the "dump_modify
+boxcolor" command.
 
 ----------
 
@@ -607,9 +679,272 @@ Play the movie:
 
 ----------
 
-See the :doc:`Modify <Modify>` page for information on how to add
-new compute and fix styles to LAMMPS to calculate per-atom quantities
-which could then be output into dump files.
+Dump_modify keywords for dump image and dump movie
+""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The following dump_modify keywords apply only to the dump image and
+dump movie styles.  Any keyword that works with dump image also works
+with dump movie, since the movie is simply a collection of images.
+Some of the keywords only affect the dump movie style.  The
+descriptions give details.
+
+----------
+
+The *acolor* keyword can be used with the dump image command, when its
+atom color setting is *type*, to set the color that atoms of each type
+will be drawn in the image.
+
+The specified *type* should be an integer from 1 to Ntypes = the
+number of atom types.  A wildcard asterisk can be used in place of or
+in conjunction with the *type* argument to specify a range of atom
+types.  This takes the form "\*" or "\*n" or "n\*" or "m\*n".  If N =
+the number of atom types, then an asterisk with no numeric values
+means all types from 1 to N.  A leading asterisk means all types from
+1 to n (inclusive).  A trailing asterisk means all types from n to N
+(inclusive).  A middle asterisk means all types from m to n
+(inclusive).
+
+The specified *color* can be a single color which is any of the 140
+pre-defined colors (see below) or a color name defined by the
+"dump_modify color" command, as described below.  Or it can be two or
+more colors separated by a "/" character, e.g. red/green/blue.  In the
+former case, that color is assigned to all the specified atom types.
+In the latter case, the list of colors are assigned in a round-robin
+fashion to each of the specified atom types.
+
+----------
+
+The *adiam* keyword can be used with the dump image command, when its
+atom diameter setting is *type*, to set the size that atoms of each
+type will be drawn in the image.  The specified *type* should be an
+integer from 1 to Ntypes.  As with the *acolor* keyword, a wildcard
+asterisk can be used as part of the *type* argument to specify a range
+of atom types.  The specified *diam* is the size in whatever distance
+:doc:`units <units>` the input script is using, e.g. Angstroms.
+
+----------
+
+The *amap* keyword can be used with the dump image command, with its
+*atom* keyword, when its atom setting is an atom-attribute, to setup a
+color map.  The color map is used to assign a specific RGB
+(red/green/blue) color value to an individual atom when it is drawn,
+based on the atom's attribute, which is a numeric value, e.g. its
+x-component of velocity if the atom-attribute "vx" was specified.
+
+The basic idea of a color map is that the atom-attribute will be
+within a range of values, and that range is associated with a series
+of colors (e.g. red, blue, green).  An atom's specific value (vx =
+-3.2) can then mapped to the series of colors (e.g. halfway between
+red and blue), and a specific color is determined via an interpolation
+procedure.
+
+There are many possible options for the color map, enabled by the
+*amap* keyword.  Here are the details.
+
+The *lo* and *hi* settings determine the range of values allowed for
+the atom attribute.  If numeric values are used for *lo* and/or *hi*,
+then values that are lower/higher than that value are set to the
+value.  I.e. the range is static.  If *lo* is specified as *min* or
+*hi* as *max* then the range is dynamic, and the lower and/or
+upper bound will be calculated each time an image is drawn, based
+on the set of atoms being visualized.
+
+The *style* setting is two letters, such as "ca".  The first letter is
+either "c" for continuous, "d" for discrete, or "s" for sequential.
+The second letter is either "a" for absolute, or "f" for fractional.
+
+A continuous color map is one in which the color changes continuously
+from value to value within the range.  A discrete color map is one in
+which discrete colors are assigned to sub-ranges of values within the
+range.  A sequential color map is one in which discrete colors are
+assigned to a sequence of sub-ranges of values covering the entire
+range.
+
+An absolute color map is one in which the values to which colors are
+assigned are specified explicitly as values within the range.  A
+fractional color map is one in which the values to which colors are
+assigned are specified as a fractional portion of the range.  For
+example if the range is from -10.0 to 10.0, and the color red is to be
+assigned to atoms with a value of 5.0, then for an absolute color map
+the number 5.0 would be used.  But for a fractional map, the number
+0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.
+
+The *delta* setting must be specified for all styles, but is only used
+for the sequential style; otherwise the value is ignored.  It
+specifies the bin size to use within the range for assigning
+consecutive colors to.  For example, if the range is from -10.0 to
+10.0 and a *delta* of 1.0 is used, then 20 colors will be assigned to
+the range.  The first will be from -10.0 <= color1 < -9.0, then second
+from -9.0 <= color2 < -8.0, etc.
+
+The *N* setting is how many entries follow.  The format of the entries
+depends on whether the color map style is continuous, discrete or
+sequential.  In all cases the *color* setting can be any of the 140
+pre-defined colors (see below) or a color name defined by the
+dump_modify color option.
+
+For continuous color maps, each entry has a *value* and a *color*\ .
+The *value* is either a number within the range of values or *min* or
+*max*\ .  The *value* of the first entry must be *min* and the *value*
+of the last entry must be *max*\ .  Any entries in between must have
+increasing values.  Note that numeric values can be specified either
+as absolute numbers or as fractions (0.0 to 1.0) of the range,
+depending on the "a" or "f" in the style setting for the color map.
+
+Here is how the entries are used to determine the color of an
+individual atom, given the value X of its atom attribute.  X will fall
+between 2 of the entry values.  The color of the atom is linearly
+interpolated (in each of the RGB values) between the 2 colors
+associated with those entries.  For example, if X = -5.0 and the 2
+surrounding entries are "red" at -10.0 and "blue" at 0.0, then the
+atom's color will be halfway between "red" and "blue", which happens
+to be "purple".
+
+For discrete color maps, each entry has a *lo* and *hi* value and a
+*color*\ .  The *lo* and *hi* settings are either numbers within the
+range of values or *lo* can be *min* or *hi* can be *max*\ .  The *lo*
+and *hi* settings of the last entry must be *min* and *max*\ .  Other
+entries can have any *lo* and *hi* values and the sub-ranges of
+different values can overlap.  Note that numeric *lo* and *hi* values
+can be specified either as absolute numbers or as fractions (0.0 to
+1.0) of the range, depending on the "a" or "f" in the style setting
+for the color map.
+
+Here is how the entries are used to determine the color of an
+individual atom, given the value X of its atom attribute.  The entries
+are scanned from first to last.  The first time that *lo* <= X <=
+*hi*, X is assigned the color associated with that entry.  You can
+think of the last entry as assigning a default color (since it will
+always be matched by X), and the earlier entries as colors that
+override the default.  Also note that no interpolation of a color RGB
+is done.  All atoms will be drawn with one of the colors in the list
+of entries.
+
+For sequential color maps, each entry has only a *color*\ .  Here is how
+the entries are used to determine the color of an individual atom,
+given the value X of its atom attribute.  The range is partitioned
+into N bins of width *binsize*\ .  Thus X will fall in a specific bin
+from 1 to N, say the Mth bin.  If it falls on a boundary between 2
+bins, it is considered to be in the higher of the 2 bins.  Each bin is
+assigned a color from the E entries.  If E < N, then the colors are
+repeated.  For example if 2 entries with colors red and green are
+specified, then the odd numbered bins will be red and the even bins
+green.  The color of the atom is the color of its bin.  Note that the
+sequential color map is really a shorthand way of defining a discrete
+color map without having to specify where all the bin boundaries are.
+
+Here is an example of using a sequential color map to color all the
+atoms in individual molecules with a different color.  See the
+examples/pour/in.pour.2d.molecule input script for an example of how
+this is used.
+
+.. code-block:: LAMMPS
+
+   variable        colors string &
+                   "red green blue yellow white &
+                   purple pink orange lime gray"
+   variable        mol atom mol%10
+   dump            1 all image 250 image.*.jpg v_mol type &
+                   zoom 1.6 adiam 1.5
+   dump_modify     1 pad 5 amap 0 10 sa 1 10 ${colors}
+
+In this case, 10 colors are defined, and molecule IDs are
+mapped to one of the colors, even if there are 1000s of molecules.
+
+----------
+
+The *backcolor* sets the background color of the images.  The color
+name can be any of the 140 pre-defined colors (see below) or a color
+name defined by the dump_modify color option.
+
+----------
+
+The *bcolor* keyword can be used with the dump image command, with its
+*bond* keyword, when its color setting is *type*, to set the color
+that bonds of each type will be drawn in the image.
+
+The specified *type* should be an integer from 1 to Nbondtypes = the
+number of bond types.  A wildcard asterisk can be used in place of or
+in conjunction with the *type* argument to specify a range of bond
+types.  This takes the form "\*" or "\*n" or "n\*" or "m\*n".  If N =
+the number of bond types, then an asterisk with no numeric values
+means all types from 1 to N.  A leading asterisk means all types from
+1 to n (inclusive).  A trailing asterisk means all types from n to N
+(inclusive).  A middle asterisk means all types from m to n
+(inclusive).
+
+The specified *color* can be a single color which is any of the 140
+pre-defined colors (see below) or a color name defined by the
+dump_modify color option.  Or it can be two or more colors separated
+by a "/" character, e.g. red/green/blue.  In the former case, that
+color is assigned to all the specified bond types.  In the latter
+case, the list of colors are assigned in a round-robin fashion to each
+of the specified bond types.
+
+----------
+
+The *bdiam* keyword can be used with the dump image command, with its
+*bond* keyword, when its diam setting is *type*, to set the diameter
+that bonds of each type will be drawn in the image.  The specified
+*type* should be an integer from 1 to Nbondtypes.  As with the
+*bcolor* keyword, a wildcard asterisk can be used as part of the
+*type* argument to specify a range of bond types.  The specified
+*diam* is the size in whatever distance :doc:`units <units>` you are
+using, e.g. Angstroms.
+
+----------
+
+The *bitrate* keyword can be used with the :doc:`dump movie
+<dump_image>` command to define the size of the resulting movie file
+and its quality via setting how many kbits per second are to be used
+for the movie file. Higher bitrates require less compression and will
+result in higher quality movies.  The quality is also determined by
+the compression format and encoder.  The default setting is 2000
+kbit/s, which will result in average quality with older compression
+formats.
+
+.. note::
+
+   Not all movie file formats supported by dump movie allow the
+   bitrate to be set.  If not, the setting is silently ignored.
+
+----------
+
+The *boxcolor* keyword sets the color of the simulation box drawn
+around the atoms in each image as well as the color of processor
+sub-domain boundaries.  See the "dump image box" command for how to
+specify that a box be drawn via the *box* keyword, and the sub-domain
+boundaries via the *subbox* keyword.  The color name can be any of the
+140 pre-defined colors (see below) or a color name defined by the
+dump_modify color option.
+
+----------
+
+The *color* keyword allows definition of a new color name, in addition
+to the 140-predefined colors (see below), and associates 3
+red/green/blue RGB values with that color name.  The color name can
+then be used with any other dump_modify keyword that takes a color
+name as a value.  The RGB values should each be floating point values
+between 0.0 and 1.0 inclusive.
+
+When a color name is converted to RGB values, the user-defined color
+names are searched first, then the 140 pre-defined color names.  This
+means you can also use the *color* keyword to overwrite one of the
+pre-defined color names with new RBG values.
+
+----------
+
+The *framerate* keyword can be used with the :doc:`dump movie
+<dump_image>` command to define the duration of the resulting movie
+file.  Movie files written by the dump *movie* command have a default
+frame rate of 24 frames per second and the images generated will be
+converted at that rate.  Thus a sequence of 1000 dump images will
+result in a movie of about 42 seconds.  To make a movie run longer you
+can either generate images more frequently or lower the frame rate.
+To speed a movie up, you can do the inverse.  Using a frame rate
+higher than 24 is not recommended, as it will result in simply
+dropping the rendered images. It is more efficient to dump images less
+frequently.
 
 ----------
 
@@ -664,7 +999,7 @@ Related commands
 Default
 """""""
 
-The defaults for the keywords are as follows:
+The defaults for the dump image and dump movie keywords are as follows:
 
 * adiam = not specified (use diameter setting)
 * atom = yes
@@ -682,3 +1017,101 @@ The defaults for the keywords are as follows:
 * subbox no 0.0
 * shiny = 1.0
 * ssao = no
+
+----------
+
+The defaults for the dump_modify keywords specific to dump image and dump movie are as follows:
+
+* acolor = \* red/green/blue/yellow/aqua/cyan
+* adiam = \* 1.0
+* amap = min max cf 0.0 2 min blue max red
+* backcolor = black
+* bcolor = \* red/green/blue/yellow/aqua/cyan
+* bdiam = \* 0.5
+* bitrate = 2000
+* boxcolor = yellow
+* color = 140 color names are pre-defined as listed below
+* framerate = 24
+
+----------
+
+These are the standard 109 element names that LAMMPS pre-defines for
+use with the dump image and dump_modify commands.
+
+* 1-10 = "H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne"
+* 11-20 = "Na", "Mg", "Al", "Si", "P", "S", "Cl", "Ar", "K", "Ca"
+* 21-30 = "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co", "Ni", "Cu", "Zn"
+* 31-40 = "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y", "Zr"
+* 41-50 = "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn"
+* 51-60 = "Sb", "Te", "I", "Xe", "Cs", "Ba", "La", "Ce", "Pr", "Nd"
+* 61-70 = "Pm", "Sm", "Eu", "Gd", "Tb", "Dy", "Ho", "Er", "Tm", "Yb"
+* 71-80 = "Lu", "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt", "Au", "Hg"
+* 81-90 = "Tl", "Pb", "Bi", "Po", "At", "Rn", "Fr", "Ra", "Ac", "Th"
+* 91-100 = "Pa", "U", "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm"
+* 101-109 = "Md", "No", "Lr", "Rf", "Db", "Sg", "Bh", "Hs", "Mt"
+
+----------
+
+These are the 140 colors that LAMMPS pre-defines for use with the dump
+image and dump_modify commands.  Additional colors can be defined with
+the dump_modify color command.  The 3 numbers listed for each name are
+the RGB (red/green/blue) values.  Divide each value by 255 to get the
+equivalent 0.0 to 1.0 value.
+
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| aliceblue = 240, 248, 255     | antiquewhite = 250, 235, 215         | aqua = 0, 255, 255              | aquamarine = 127, 255, 212     | azure = 240, 255, 255          |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| beige = 245, 245, 220         | bisque = 255, 228, 196               | black = 0, 0, 0                 | blanchedalmond = 255, 255, 205 | blue = 0, 0, 255               |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| blueviolet = 138, 43, 226     | brown = 165, 42, 42                  | burlywood = 222, 184, 135       | cadetblue = 95, 158, 160       | chartreuse = 127, 255, 0       |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| chocolate = 210, 105, 30      | coral = 255, 127, 80                 | cornflowerblue = 100, 149, 237  | cornsilk = 255, 248, 220       | crimson = 220, 20, 60          |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| cyan = 0, 255, 255            | darkblue = 0, 0, 139                 | darkcyan = 0, 139, 139          | darkgoldenrod = 184, 134, 11   | darkgray = 169, 169, 169       |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| darkgreen = 0, 100, 0         | darkkhaki = 189, 183, 107            | darkmagenta = 139, 0, 139       | darkolivegreen = 85, 107, 47   | darkorange = 255, 140, 0       |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| darkorchid = 153, 50, 204     | darkred = 139, 0, 0                  | darksalmon = 233, 150, 122      | darkseagreen = 143, 188, 143   | darkslateblue = 72, 61, 139    |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| darkslategray = 47, 79, 79    | darkturquoise = 0, 206, 209          | darkviolet = 148, 0, 211        | deeppink = 255, 20, 147        | deepskyblue = 0, 191, 255      |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| dimgray = 105, 105, 105       | dodgerblue = 30, 144, 255            | firebrick = 178, 34, 34         | floralwhite = 255, 250, 240    | forestgreen = 34, 139, 34      |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| fuchsia = 255, 0, 255         | gainsboro = 220, 220, 220            | ghostwhite = 248, 248, 255      | gold = 255, 215, 0             | goldenrod = 218, 165, 32       |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| gray = 128, 128, 128          | green = 0, 128, 0                    | greenyellow = 173, 255, 47      | honeydew = 240, 255, 240       | hotpink = 255, 105, 180        |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| indianred = 205, 92, 92       | indigo = 75, 0, 130                  | ivory = 255, 240, 240           | khaki = 240, 230, 140          | lavender = 230, 230, 250       |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| lavenderblush = 255, 240, 245 | lawngreen = 124, 252, 0              | lemonchiffon = 255, 250, 205    | lightblue = 173, 216, 230      | lightcoral = 240, 128, 128     |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| lightcyan = 224, 255, 255     | lightgoldenrodyellow = 250, 250, 210 | lightgreen = 144, 238, 144      | lightgrey = 211, 211, 211      | lightpink = 255, 182, 193      |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| lightsalmon = 255, 160, 122   | lightseagreen = 32, 178, 170         | lightskyblue = 135, 206, 250    | lightslategray = 119, 136, 153 | lightsteelblue = 176, 196, 222 |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| lightyellow = 255, 255, 224   | lime = 0, 255, 0                     | limegreen = 50, 205, 50         | linen = 250, 240, 230          | magenta = 255, 0, 255          |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| maroon = 128, 0, 0            | mediumaquamarine = 102, 205, 170     | mediumblue = 0, 0, 205          | mediumorchid = 186, 85, 211    | mediumpurple = 147, 112, 219   |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| mediumseagreen = 60, 179, 113 | mediumslateblue = 123, 104, 238      | mediumspringgreen = 0, 250, 154 | mediumturquoise = 72, 209, 204 | mediumvioletred = 199, 21, 133 |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| midnightblue = 25, 25, 112    | mintcream = 245, 255, 250            | mistyrose = 255, 228, 225       | moccasin = 255, 228, 181       | navajowhite = 255, 222, 173    |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| navy = 0, 0, 128              | oldlace = 253, 245, 230              | olive = 128, 128, 0             | olivedrab = 107, 142, 35       | orange = 255, 165, 0           |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| orangered = 255, 69, 0        | orchid = 218, 112, 214               | palegoldenrod = 238, 232, 170   | palegreen = 152, 251, 152      | paleturquoise = 175, 238, 238  |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| palevioletred = 219, 112, 147 | papayawhip = 255, 239, 213           | peachpuff = 255, 239, 213       | peru = 205, 133, 63            | pink = 255, 192, 203           |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| plum = 221, 160, 221          | powderblue = 176, 224, 230           | purple = 128, 0, 128            | red = 255, 0, 0                | rosybrown = 188, 143, 143      |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| royalblue = 65, 105, 225      | saddlebrown = 139, 69, 19            | salmon = 250, 128, 114          | sandybrown = 244, 164, 96      | seagreen = 46, 139, 87         |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| seashell = 255, 245, 238      | sienna = 160, 82, 45                 | silver = 192, 192, 192          | skyblue = 135, 206, 235        | slateblue = 106, 90, 205       |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| slategray = 112, 128, 144     | snow = 255, 250, 250                 | springgreen = 0, 255, 127       | steelblue = 70, 130, 180       | tan = 210, 180, 140            |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| teal = 0, 128, 128            | thistle = 216, 191, 216              | tomato = 253, 99, 71            | turquoise = 64, 224, 208       | violet = 238, 130, 238         |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
+| wheat = 245, 222, 179         | white = 255, 255, 255                | whitesmoke = 245, 245, 245      | yellow = 255, 255, 0           | yellowgreen = 154, 205, 50     |
++-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+

doc/src/dump_modify.rst

@@ -3,6 +3,9 @@
 dump_modify command
 ===================
 
+:doc:`dump_modify <dump_image>` command for image/movie options
+===============================================================
+
 Syntax
 """"""
 
@@ -12,14 +15,16 @@ Syntax
 
 * dump-ID = ID of dump to modify
 * one or more keyword/value pairs may be appended
+
 * these keywords apply to various dump styles
-* keyword = *append* or *at* or *buffer* or *delay* or *element* or *every* or *fileper* or *first* or *flush* or *format* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
+* keyword = *append* or *at* or *balance* or *buffer* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
 
   .. parsed-literal::
 
        *append* arg = *yes* or *no*
        *at* arg = N
          N = index of frame written upon first dump
+       *balance* arg = *yes* or *no*
        *buffer* arg = *yes* or *no*
        *delay* arg = Dstep
          Dstep = delay output until this timestep
@@ -28,6 +33,9 @@ Syntax
        *every* arg = N
          N = dump every this many timesteps
          N can be a variable (see below)
+       *every/time* arg = Delta
+         Delta = dump every this interval in simulation time (time units)
+         Delta can be a variable (see below)
        *fileper* arg = Np
          Np = write one file for every this many processors
        *first* arg = *yes* or *no*
@@ -35,6 +43,9 @@ Syntax
        *format* args = *line* string, *int* string, *float* string, M string, or *none*
          string = C-style format string
          M = integer from 1 to N, where N = # of per-atom quantities being output
+       *header* arg = *yes* or *no*
+         *yes* to write the header
+         *no* to not write the header
        *image* arg = *yes* or *no*
        *label* arg = string
          string = character string (e.g. BONDS) to use in header of dump local file
@@ -66,56 +77,11 @@ Syntax
        *unwrap* arg = *yes* or *no*
 
 * these keywords apply only to the *image* and *movie* :doc:`styles <dump_image>`
-* keyword = *acolor* or *adiam* or *amap* or *backcolor* or *bcolor* or *bdiam* or *boxcolor* or *color* or *bitrate* or *framerate* or *header*
+* keyword = *acolor* or *adiam* or *amap* or *backcolor* or *bcolor* or *bdiam* or *boxcolor* or *color* or *bitrate* or *framerate*
 
   .. parsed-literal::
 
-       *acolor* args = type color
-         type = atom type or range of types (see below)
-         color = name of color or color1/color2/...
-       *adiam* args = type diam
-         type = atom type or range of types (see below)
-         diam = diameter of atoms of that type (distance units)
-       *amap* args = lo hi style delta N entry1 entry2 ... entryN
-         lo = number or *min* = lower bound of range of color map
-         hi = number or *max* = upper bound of range of color map
-         style = 2 letters = "c" or "d" or "s" plus "a" or "f"
-           "c" for continuous
-           "d" for discrete
-           "s" for sequential
-           "a" for absolute
-           "f" for fractional
-         delta = binsize (only used for style "s", otherwise ignored)
-           binsize = range is divided into bins of this width
-         N = # of subsequent entries
-         entry = value color (for continuous style)
-           value = number or *min* or *max* = single value within range
-           color = name of color used for that value
-         entry = lo hi color (for discrete style)
-           lo/hi = number or *min* or *max* = lower/upper bound of subset of range
-           color = name of color used for that subset of values
-         entry = color (for sequential style)
-           color = name of color used for a bin of values
-       *backcolor* arg = color
-         color = name of color for background
-       *bcolor* args = type color
-         type = bond type or range of types (see below)
-         color = name of color or color1/color2/...
-       *bdiam* args = type diam
-         type = bond type or range of types (see below)
-         diam = diameter of bonds of that type (distance units)
-       *boxcolor* arg = color
-         color = name of color for simulation box lines and processor sub-domain lines
-       *color* args = name R G B
-         name = name of color
-         R,G,B = red/green/blue numeric values from 0.0 to 1.0
-       *bitrate* arg = rate
-         rate = target bitrate for movie in kbps
-       *framerate* arg = fps
-         fps = frames per second for movie
-       *header* arg = *yes* or *no*
-         *yes* to write the header
-         *no* to not write the header
+       see the :doc:`dump image <dump_image>` doc page for details
 
 * these keywords apply only to the */gz* and */zstd* dump styles
 * keyword = *compression_level*
@@ -126,7 +92,7 @@ Syntax
          level = integer specifying the compression level that should be used (see below for supported levels)
 
 * these keywords apply only to the */zstd* dump styles
-* keyword = *compression_level*
+* keyword = *checksum*
 
   .. parsed-literal::
 
@@ -144,7 +110,6 @@ Examples
    dump_modify xtcdump precision 10000 sfactor 0.1
    dump_modify 1 every 1000 nfile 20
    dump_modify 1 every v_myVar
-   dump_modify 1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red
 
 Description
 """""""""""
@@ -163,8 +128,9 @@ which allow for use of MPI-IO.
 
 ----------
 
-These keywords apply to various dump styles, including the :doc:`dump image <dump_image>` and :doc:`dump movie <dump_image>` styles.  The
-description gives details.
+Unless otherwise noted, the following keywords apply to all the
+various dump styles, including the :doc:`dump image <dump_image>` and
+:doc:`dump movie <dump_image>` styles.
 
 ----------
 
@@ -235,11 +201,19 @@ will be accepted.
 
 ----------
 
-The *every* keyword changes the dump frequency originally specified by
-the :doc:`dump <dump>` command to a new value.  The every keyword can be
-specified in one of two ways.  It can be a numeric value in which case
-it must be > 0.  Or it can be an :doc:`equal-style variable <variable>`,
-which should be specified as v_name, where name is the variable name.
+The *every* keyword can be used with any dump style except the *dcd*
+and *xtc* styles.  It does two things.  It specifies that the interval
+between dump snapshots will be set in timesteps, which is the default
+if the *every* or *every/time* keywords are not used.  See the
+*every/time* keyword for how to specify the interval in simulation
+time, i.e. in time units of the :doc:`units <units>` command.  The
+*every* keyword also sets the interval value, which overrides the dump
+frequency originally specified by the :doc:`dump <dump>` command.
+
+The *every* keyword can be specified in one of two ways.  It can be a
+numeric value in which case it must be > 0.  Or it can be an
+:doc:`equal-style variable <variable>`, which should be specified as
+v_name, where name is the variable name.
 
 In this case, the variable is evaluated at the beginning of a run to
 determine the next timestep at which a dump snapshot will be written
@@ -248,11 +222,12 @@ determine the next timestep, etc.  Thus the variable should return
 timestep values.  See the stagger() and logfreq() and stride() math
 functions for :doc:`equal-style variables <variable>`, as examples of
 useful functions to use in this context.  Other similar math functions
-could easily be added as options for :doc:`equal-style variables <variable>`.  Also see the next() function, which allows
-use of a file-style variable which reads successive values from a
-file, each time the variable is evaluated.  Used with the *every*
-keyword, if the file contains a list of ascending timesteps, you can
-output snapshots whenever you wish.
+could easily be added as options for :doc:`equal-style variables
+<variable>`.  Also see the next() function, which allows use of a
+file-style variable which reads successive values from a file, each
+time the variable is evaluated.  Used with the *every* keyword, if the
+file contains a list of ascending timesteps, you can output snapshots
+whenever you wish.
 
 Note that when using the variable option with the *every* keyword, you
 need to use the *first* option if you want an initial snapshot written
@@ -293,14 +268,103 @@ in file tmp.times:
 
 ----------
 
+The *every/time* keyword can be used with any dump style except the
+*dcd* and *xtc* styles.  It does two things.  It specifies that the
+interval between dump snapshots will be set in simulation time,
+i.e. in time units of the :doc:`units <units>` command.  This can be
+useful when the timestep size varies during a simulation run, e.g. by
+use of the :doc:`fix dt/reset <fix_dt_reset>` command.  The default is
+to specify the interval in timesteps; see the *every* keyword.  The
+*every/time* command also sets the interval value.
+
+.. note::
+
+   If you wish dump styles *atom*, *custom*, *local*, or *xyz* to
+   include the simulation time as a field in the header portion of
+   each snapshot, you also need to use the dump_modify *time* keyword
+   with a setting of *yes*.  See its documentation below.
+
+Note that since snapshots are output on simulation steps, each
+snapshot will be written on the first timestep whose associated
+simulation time is >= the exact snapshot time value.
+
+As with the *every* option, the *Delta* value can be specified in one
+of two ways.  It can be a numeric value in which case it must be >
+0.0.  Or it can be an :doc:`equal-style variable <variable>`, which
+should be specified as v_name, where name is the variable name.
+
+In this case, the variable is evaluated at the beginning of a run to
+determine the next simulation time at which a dump snapshot will be
+written out.  On that timestep the variable will be evaluated again to
+determine the next simulation time, etc.  Thus the variable should
+return values in time units.  Note the current timestep or simulation
+time can be used in an :doc:`equal-style variables <variable>` since
+they are both thermodynamic keywords.  Also see the next() function,
+which allows use of a file-style variable which reads successive
+values from a file, each time the variable is evaluated.  Used with
+the *every/time* keyword, if the file contains a list of ascending
+simulation times, you can output snapshots whenever you wish.
+
+Note that when using the variable option with the *every/time*
+keyword, you need to use the *first* option if you want an initial
+snapshot written to the dump file.  The *every/time* keyword cannot be
+used with the dump *dcd* style.
+
+For example, the following commands will write snapshots at successive
+simulation times which grow by a factor of 1.5 with each interval.
+The dt value used in the variable is to avoid a zero result when the
+initial simulation time is 0.0.
+
+.. code-block:: LAMMPS
+
+   variable        increase equal 1.5*(time+dt)
+   dump            1 all atom 100 tmp.dump
+   dump_modify     1 every/time v_increase first yes
+
+The following commands would write snapshots at the times listed in
+file tmp.times:
+
+.. code-block:: LAMMPS
+
+   variable        f file tmp.times
+   variable        s equal next(f)
+   dump            1 all atom 100 tmp.dump
+   dump_modify     1 every/time v_s
+
+.. note::
+
+   When using a file-style variable with the *every/time* keyword, the
+   file of timesteps must list a first time that is beyond the time
+   associated with the current timestep (e.g. it cannot be 0.0).  And
+   it must list one or more times beyond the length of the run you
+   perform.  This is because the dump command will generate an error
+   if the next time it reads from the file is not a value greater than
+   the current time.  Thus if you wanted output at times 0,15,100 of a
+   run of length 100 in simulation time, the file should contain the
+   values 15,100,101 and you should also use the dump_modify first
+   command.  Any final value > 100 could be used in place of 101.
+
+----------
+
 The *first* keyword determines whether a dump snapshot is written on
 the very first timestep after the dump command is invoked.  This will
-always occur if the current timestep is a multiple of N, the frequency
-specified in the :doc:`dump <dump>` command, including timestep 0.  But
-if this is not the case, a dump snapshot will only be written if the
-setting of this keyword is *yes*\ .  If it is *no*, which is the
+always occur if the current timestep is a multiple of $N$, the
+frequency specified in the :doc:`dump <dump>` command or
+:doc:`dump_modify every <dump_modify>` command, including timestep 0.
+It will also always occur if the current simulation time is a multiple
+of *Delta*, the time interval specified in the doc:`dump_modify
+every/time <dump_modify>` command.
+
+But if this is not the case, a dump snapshot will only be written if
+the setting of this keyword is *yes*\ .  If it is *no*, which is the
 default, then it will not be written.
 
+Note that if the argument to the :doc:`dump_modify every
+<dump_modify>` doc:`dump_modify every/time <dump_modify>` commands is
+a variable and not a numeric value, then specifying *first yes* is the
+only way to write a dump snapshot on the first timestep after the dump
+command is invoked.
+
 ----------
 
 The *flush* keyword determines whether a flush operation is invoked
@@ -380,6 +444,13 @@ The *fileper* keyword is documented below with the *nfile* keyword.
 
 ----------
 
+The *header* keyword toggles whether the dump file will include a
+header.  Excluding a header will reduce the size of the dump file for
+fixes such as :doc:`fix pair/tracker <fix_pair_tracker>` which do not
+require the information typically written to the header.
+
+----------
+
 The *image* keyword applies only to the dump *atom* style.  If the
 image value is *yes*, 3 flags are appended to each atom's coords which
 are the absolute box image of the atom in each dimension.  For
@@ -592,9 +663,19 @@ The dump *local* style cannot be sorted by atom ID, since there are
 typically multiple lines of output per atom.  Some dump styles, such
 as *dcd* and *xtc*, require sorting by atom ID to format the output
 file correctly.  If multiple processors are writing the dump file, via
-the "%" wildcard in the dump filename, then sorting cannot be
+the "%" wildcard in the dump filename and the *nfile* or *fileper*
+keywords are set to non-default values (i.e. the number of dump file
+pieces is not equal to the number of procs), then sorting cannot be
 performed.
 
+In a parallel run, the per-processor dump file pieces can have
+significant imbalance in number of lines of per-atom info. The *balance*
+keyword determines whether the number of lines in each processor
+snapshot are balanced to be nearly the same. A balance value of *no*
+means no balancing will be done, while *yes* means balancing will be
+performed. This balancing preserves dump sorting order. For a serial
+run, this option is ignored since the output is already balanced.
+
 .. note::
 
    Unless it is required by the dump style, sorting dump file
@@ -670,16 +751,20 @@ threshold criterion is met.  Otherwise it is not met.
 
 ----------
 
-The *time* keyword only applies to the dump *atom*, *custom*, and
-*local* styles (and their COMPRESS package versions *atom/gz*,
-*custom/gz* and *local/gz*\ ). If set to *yes*, each frame will will
-contain two extra lines before the "ITEM: TIMESTEP" entry:
+The *time* keyword only applies to the dump *atom*, *custom*, *local*,
+and *xyz* styles (and their COMPRESS package versions *atom/gz*,
+*custom/gz* and *local/gz*\ ).  For the first 3 styles, if set to
+*yes*, each frame will will contain two extra lines before the "ITEM:
+TIMESTEP" entry:
 
 .. parsed-literal::
 
    ITEM: TIME
    \<elapsed time\>
 
+For the *xyz* style, the simulation time is included on the same line
+as the timestep value.
+
 This will output the current elapsed simulation time in current
 time units equivalent to the :doc:`thermo keyword <thermo_style>` *time*\ .
 This is to simplify post-processing of trajectories using a variable time
@@ -715,303 +800,35 @@ box size stored with the snapshot.
 
 ----------
 
-These keywords apply only to the :doc:`dump image <dump_image>` and
-:doc:`dump movie <dump_image>` styles.  Any keyword that affects an
-image, also affects a movie, since the movie is simply a collection of
-images.  Some of the keywords only affect the :doc:`dump movie <dump_image>` style.  The descriptions give details.
+The COMPRESS package offers both GZ and Zstd compression variants of
+styles atom, custom, local, cfg, and xyz. When using these styles the
+compression level can be controlled by the :code:`compression_level`
+keyword. File names with these styles have to end in either
+:code:`.gz` or :code:`.zst`.
 
-----------
-
-The *acolor* keyword can be used with the :doc:`dump image <dump_image>`
-command, when its atom color setting is *type*, to set the color that
-atoms of each type will be drawn in the image.
-
-The specified *type* should be an integer from 1 to Ntypes = the
-number of atom types.  A wildcard asterisk can be used in place of or
-in conjunction with the *type* argument to specify a range of atom
-types.  This takes the form "\*" or "\*n" or "n\*" or "m\*n".  If N = the
-number of atom types, then an asterisk with no numeric values means
-all types from 1 to N.  A leading asterisk means all types from 1 to n
-(inclusive).  A trailing asterisk means all types from n to N
-(inclusive).  A middle asterisk means all types from m to n
-(inclusive).
-
-The specified *color* can be a single color which is any of the 140
-pre-defined colors (see below) or a color name defined by the
-dump_modify color option.  Or it can be two or more colors separated
-by a "/" character, e.g. red/green/blue.  In the former case, that
-color is assigned to all the specified atom types.  In the latter
-case, the list of colors are assigned in a round-robin fashion to each
-of the specified atom types.
-
-----------
-
-The *adiam* keyword can be used with the :doc:`dump image <dump_image>`
-command, when its atom diameter setting is *type*, to set the size
-that atoms of each type will be drawn in the image.  The specified
-*type* should be an integer from 1 to Ntypes.  As with the *acolor*
-keyword, a wildcard asterisk can be used as part of the *type*
-argument to specify a range of atom types.  The specified *diam* is
-the size in whatever distance :doc:`units <units>` the input script is
-using, e.g. Angstroms.
-
-----------
-
-The *amap* keyword can be used with the :doc:`dump image <dump_image>`
-command, with its *atom* keyword, when its atom setting is an
-atom-attribute, to setup a color map.  The color map is used to assign
-a specific RGB (red/green/blue) color value to an individual atom when
-it is drawn, based on the atom's attribute, which is a numeric value,
-e.g. its x-component of velocity if the atom-attribute "vx" was
-specified.
-
-The basic idea of a color map is that the atom-attribute will be
-within a range of values, and that range is associated with a series
-of colors (e.g. red, blue, green).  An atom's specific value (vx =
--3.2) can then mapped to the series of colors (e.g. halfway between
-red and blue), and a specific color is determined via an interpolation
-procedure.
-
-There are many possible options for the color map, enabled by the
-*amap* keyword.  Here are the details.
-
-The *lo* and *hi* settings determine the range of values allowed for
-the atom attribute.  If numeric values are used for *lo* and/or *hi*,
-then values that are lower/higher than that value are set to the
-value.  I.e. the range is static.  If *lo* is specified as *min* or
-*hi* as *max* then the range is dynamic, and the lower and/or
-upper bound will be calculated each time an image is drawn, based
-on the set of atoms being visualized.
-
-The *style* setting is two letters, such as "ca".  The first letter is
-either "c" for continuous, "d" for discrete, or "s" for sequential.
-The second letter is either "a" for absolute, or "f" for fractional.
-
-A continuous color map is one in which the color changes continuously
-from value to value within the range.  A discrete color map is one in
-which discrete colors are assigned to sub-ranges of values within the
-range.  A sequential color map is one in which discrete colors are
-assigned to a sequence of sub-ranges of values covering the entire
-range.
-
-An absolute color map is one in which the values to which colors are
-assigned are specified explicitly as values within the range.  A
-fractional color map is one in which the values to which colors are
-assigned are specified as a fractional portion of the range.  For
-example if the range is from -10.0 to 10.0, and the color red is to be
-assigned to atoms with a value of 5.0, then for an absolute color map
-the number 5.0 would be used.  But for a fractional map, the number
-0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.
-
-The *delta* setting must be specified for all styles, but is only used
-for the sequential style; otherwise the value is ignored.  It
-specifies the bin size to use within the range for assigning
-consecutive colors to.  For example, if the range is from -10.0 to
-10.0 and a *delta* of 1.0 is used, then 20 colors will be assigned to
-the range.  The first will be from -10.0 <= color1 < -9.0, then second
-from -9.0 <= color2 < -8.0, etc.
-
-The *N* setting is how many entries follow.  The format of the entries
-depends on whether the color map style is continuous, discrete or
-sequential.  In all cases the *color* setting can be any of the 140
-pre-defined colors (see below) or a color name defined by the
-dump_modify color option.
-
-For continuous color maps, each entry has a *value* and a *color*\ .
-The *value* is either a number within the range of values or *min* or
-*max*\ .  The *value* of the first entry must be *min* and the *value*
-of the last entry must be *max*\ .  Any entries in between must have
-increasing values.  Note that numeric values can be specified either
-as absolute numbers or as fractions (0.0 to 1.0) of the range,
-depending on the "a" or "f" in the style setting for the color map.
-
-Here is how the entries are used to determine the color of an
-individual atom, given the value X of its atom attribute.  X will fall
-between 2 of the entry values.  The color of the atom is linearly
-interpolated (in each of the RGB values) between the 2 colors
-associated with those entries.  For example, if X = -5.0 and the 2
-surrounding entries are "red" at -10.0 and "blue" at 0.0, then the
-atom's color will be halfway between "red" and "blue", which happens
-to be "purple".
-
-For discrete color maps, each entry has a *lo* and *hi* value and a
-*color*\ .  The *lo* and *hi* settings are either numbers within the
-range of values or *lo* can be *min* or *hi* can be *max*\ .  The *lo*
-and *hi* settings of the last entry must be *min* and *max*\ .  Other
-entries can have any *lo* and *hi* values and the sub-ranges of
-different values can overlap.  Note that numeric *lo* and *hi* values
-can be specified either as absolute numbers or as fractions (0.0 to
-1.0) of the range, depending on the "a" or "f" in the style setting
-for the color map.
-
-Here is how the entries are used to determine the color of an
-individual atom, given the value X of its atom attribute.  The entries
-are scanned from first to last.  The first time that *lo* <= X <=
-*hi*, X is assigned the color associated with that entry.  You can
-think of the last entry as assigning a default color (since it will
-always be matched by X), and the earlier entries as colors that
-override the default.  Also note that no interpolation of a color RGB
-is done.  All atoms will be drawn with one of the colors in the list
-of entries.
-
-For sequential color maps, each entry has only a *color*\ .  Here is how
-the entries are used to determine the color of an individual atom,
-given the value X of its atom attribute.  The range is partitioned
-into N bins of width *binsize*\ .  Thus X will fall in a specific bin
-from 1 to N, say the Mth bin.  If it falls on a boundary between 2
-bins, it is considered to be in the higher of the 2 bins.  Each bin is
-assigned a color from the E entries.  If E < N, then the colors are
-repeated.  For example if 2 entries with colors red and green are
-specified, then the odd numbered bins will be red and the even bins
-green.  The color of the atom is the color of its bin.  Note that the
-sequential color map is really a shorthand way of defining a discrete
-color map without having to specify where all the bin boundaries are.
-
-Here is an example of using a sequential color map to color all the
-atoms in individual molecules with a different color.  See the
-examples/pour/in.pour.2d.molecule input script for an example of how
-this is used.
-
-.. code-block:: LAMMPS
-
-   variable        colors string &
-                   "red green blue yellow white &
-                   purple pink orange lime gray"
-   variable        mol atom mol%10
-   dump            1 all image 250 image.*.jpg v_mol type &
-                   zoom 1.6 adiam 1.5
-   dump_modify     1 pad 5 amap 0 10 sa 1 10 ${colors}
-
-In this case, 10 colors are defined, and molecule IDs are
-mapped to one of the colors, even if there are 1000s of molecules.
-
-----------
-
-The *backcolor* sets the background color of the images.  The color
-name can be any of the 140 pre-defined colors (see below) or a color
-name defined by the dump_modify color option.
-
-----------
-
-The *bcolor* keyword can be used with the :doc:`dump image <dump_image>`
-command, with its *bond* keyword, when its color setting is *type*, to
-set the color that bonds of each type will be drawn in the image.
-
-The specified *type* should be an integer from 1 to Nbondtypes = the
-number of bond types.  A wildcard asterisk can be used in place of or
-in conjunction with the *type* argument to specify a range of bond
-types.  This takes the form "\*" or "\*n" or "n\*" or "m\*n".  If N = the
-number of bond types, then an asterisk with no numeric values means
-all types from 1 to N.  A leading asterisk means all types from 1 to n
-(inclusive).  A trailing asterisk means all types from n to N
-(inclusive).  A middle asterisk means all types from m to n
-(inclusive).
-
-The specified *color* can be a single color which is any of the 140
-pre-defined colors (see below) or a color name defined by the
-dump_modify color option.  Or it can be two or more colors separated
-by a "/" character, e.g. red/green/blue.  In the former case, that
-color is assigned to all the specified bond types.  In the latter
-case, the list of colors are assigned in a round-robin fashion to each
-of the specified bond types.
-
-----------
-
-The *bdiam* keyword can be used with the :doc:`dump image <dump_image>`
-command, with its *bond* keyword, when its diam setting is *type*, to
-set the diameter that bonds of each type will be drawn in the image.
-The specified *type* should be an integer from 1 to Nbondtypes.  As
-with the *bcolor* keyword, a wildcard asterisk can be used as part of
-the *type* argument to specify a range of bond types.  The specified
-*diam* is the size in whatever distance :doc:`units <units>` you are
-using, e.g. Angstroms.
-
-----------
-
-The *bitrate* keyword can be used with the :doc:`dump movie <dump_image>` command to define the size of the resulting
-movie file and its quality via setting how many kbits per second are
-to be used for the movie file. Higher bitrates require less
-compression and will result in higher quality movies.  The quality is
-also determined by the compression format and encoder.  The default
-setting is 2000 kbit/s, which will result in average quality with
-older compression formats.
-
-.. note::
-
-   Not all movie file formats supported by dump movie allow the
-   bitrate to be set.  If not, the setting is silently ignored.
-
-----------
-
-The *boxcolor* keyword sets the color of the simulation box drawn
-around the atoms in each image as well as the color of processor
-sub-domain boundaries.  See the "dump image box" command for how to
-specify that a box be drawn via the *box* keyword, and the sub-domain
-boundaries via the *subbox* keyword.  The color name can be any of the
-140 pre-defined colors (see below) or a color name defined by the
-dump_modify color option.
-
-----------
-
-The *color* keyword allows definition of a new color name, in addition
-to the 140-predefined colors (see below), and associates 3
-red/green/blue RGB values with that color name.  The color name can
-then be used with any other dump_modify keyword that takes a color
-name as a value.  The RGB values should each be floating point values
-between 0.0 and 1.0 inclusive.
-
-When a color name is converted to RGB values, the user-defined color
-names are searched first, then the 140 pre-defined color names.  This
-means you can also use the *color* keyword to overwrite one of the
-pre-defined color names with new RBG values.
-
-----------
-
-The *framerate* keyword can be used with the :doc:`dump movie <dump_image>` command to define the duration of the resulting
-movie file.  Movie files written by the dump *movie* command have a
-default frame rate of 24 frames per second and the images generated
-will be converted at that rate.  Thus a sequence of 1000 dump images
-will result in a movie of about 42 seconds.  To make a movie run
-longer you can either generate images more frequently or lower the
-frame rate.  To speed a movie up, you can do the inverse.  Using a
-frame rate higher than 24 is not recommended, as it will result in
-simply dropping the rendered images. It is more efficient to dump
-images less frequently.
-
-----------
-
-The *header* keyword toggles whether the dump file will include a header.
-Excluding a header will reduce the size of the dump file for fixes such as
-:doc:`fix pair/tracker <fix_pair_tracker>` which do not require the information
-typically written to the header.
-
-----------
-
-The COMPRESS package offers both GZ and Zstd compression variants of styles
-atom, custom, local, cfg, and xyz. When using these styles the compression
-level can be controlled by the :code:`compression_level` parameter. File names
-with these styles have to end in either :code:`.gz` or :code:`.zst`.
-
-GZ supports compression levels from -1 (default), 0 (no compression), and 1 to
-9. 9 being the best compression. The COMPRESS :code:`/gz` styles use 9 as
-default compression level.
+GZ supports compression levels from -1 (default), 0 (no compression),
+and 1 to
+9. 9 being the best compression. The COMPRESS :code:`/gz` styles use 9
+as default compression level.
 
 Zstd offers a wider range of compression levels, including negative
-levels that sacrifice compression for performance. 0 is the
-default, positive levels are 1 to 22, with 22 being the most expensive
+levels that sacrifice compression for performance. 0 is the default,
+positive levels are 1 to 22, with 22 being the most expensive
 compression. Zstd promises higher compression/decompression speeds for
 similar compression ratios. For more details see
 `http://facebook.github.io/zstd/`.
 
-In addition, Zstd compressed files can have a checksum of the entire
-contents. The Zstd enabled dump styles enable this feature by default and it
-can be disabled with the :code:`checksum` parameter.
+In addition, Zstd compressed files can include a checksum of the
+entire contents. The Zstd enabled dump styles enable this feature by
+default and it can be disabled with the :code:`checksum` keyword.
 
 ----------
 
 Restrictions
 """"""""""""
- none
+
+Not all *dump_modify* options can be applied to all dump styles.
+Details are in the discussions of the individual options.
 
 Related commands
 """"""""""""""""
@@ -1024,6 +841,7 @@ Default
 The option defaults are
 
 * append = no
+* balance = no
 * buffer = yes for dump styles *atom*, *custom*, *loca*, and *xyz*
 * element = "C" for every atom type
 * every = whatever it was set to via the :doc:`dump <dump>` command
@@ -1046,100 +864,7 @@ The option defaults are
 * units = no
 * unwrap = no
 
-* acolor = \* red/green/blue/yellow/aqua/cyan
-* adiam = \* 1.0
-* amap = min max cf 0.0 2 min blue max red
-* backcolor = black
-* bcolor = \* red/green/blue/yellow/aqua/cyan
-* bdiam = \* 0.5
-* bitrate = 2000
-* boxcolor = yellow
-* color = 140 color names are pre-defined as listed below
-* framerate = 24
-
 * compression_level = 9 (gz variants)
 * compression_level = 0 (zstd variants)
 * checksum = yes (zstd variants)
 
-----------
-
-These are the standard 109 element names that LAMMPS pre-defines for
-use with the :doc:`dump image <dump_image>` and dump_modify commands.
-
-* 1-10 = "H", "He", "Li", "Be", "B", "C", "N", "O", "F", "Ne"
-* 11-20 = "Na", "Mg", "Al", "Si", "P", "S", "Cl", "Ar", "K", "Ca"
-* 21-30 = "Sc", "Ti", "V", "Cr", "Mn", "Fe", "Co", "Ni", "Cu", "Zn"
-* 31-40 = "Ga", "Ge", "As", "Se", "Br", "Kr", "Rb", "Sr", "Y", "Zr"
-* 41-50 = "Nb", "Mo", "Tc", "Ru", "Rh", "Pd", "Ag", "Cd", "In", "Sn"
-* 51-60 = "Sb", "Te", "I", "Xe", "Cs", "Ba", "La", "Ce", "Pr", "Nd"
-* 61-70 = "Pm", "Sm", "Eu", "Gd", "Tb", "Dy", "Ho", "Er", "Tm", "Yb"
-* 71-80 = "Lu", "Hf", "Ta", "W", "Re", "Os", "Ir", "Pt", "Au", "Hg"
-* 81-90 = "Tl", "Pb", "Bi", "Po", "At", "Rn", "Fr", "Ra", "Ac", "Th"
-* 91-100 = "Pa", "U", "Np", "Pu", "Am", "Cm", "Bk", "Cf", "Es", "Fm"
-* 101-109 = "Md", "No", "Lr", "Rf", "Db", "Sg", "Bh", "Hs", "Mt"
-
-----------
-
-These are the 140 colors that LAMMPS pre-defines for use with the
-:doc:`dump image <dump_image>` and dump_modify commands.  Additional
-colors can be defined with the dump_modify color command.  The 3
-numbers listed for each name are the RGB (red/green/blue) values.
-Divide each value by 255 to get the equivalent 0.0 to 1.0 value.
-
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| aliceblue = 240, 248, 255     | antiquewhite = 250, 235, 215         | aqua = 0, 255, 255              | aquamarine = 127, 255, 212     | azure = 240, 255, 255          |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| beige = 245, 245, 220         | bisque = 255, 228, 196               | black = 0, 0, 0                 | blanchedalmond = 255, 255, 205 | blue = 0, 0, 255               |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| blueviolet = 138, 43, 226     | brown = 165, 42, 42                  | burlywood = 222, 184, 135       | cadetblue = 95, 158, 160       | chartreuse = 127, 255, 0       |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| chocolate = 210, 105, 30      | coral = 255, 127, 80                 | cornflowerblue = 100, 149, 237  | cornsilk = 255, 248, 220       | crimson = 220, 20, 60          |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| cyan = 0, 255, 255            | darkblue = 0, 0, 139                 | darkcyan = 0, 139, 139          | darkgoldenrod = 184, 134, 11   | darkgray = 169, 169, 169       |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| darkgreen = 0, 100, 0         | darkkhaki = 189, 183, 107            | darkmagenta = 139, 0, 139       | darkolivegreen = 85, 107, 47   | darkorange = 255, 140, 0       |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| darkorchid = 153, 50, 204     | darkred = 139, 0, 0                  | darksalmon = 233, 150, 122      | darkseagreen = 143, 188, 143   | darkslateblue = 72, 61, 139    |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| darkslategray = 47, 79, 79    | darkturquoise = 0, 206, 209          | darkviolet = 148, 0, 211        | deeppink = 255, 20, 147        | deepskyblue = 0, 191, 255      |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| dimgray = 105, 105, 105       | dodgerblue = 30, 144, 255            | firebrick = 178, 34, 34         | floralwhite = 255, 250, 240    | forestgreen = 34, 139, 34      |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| fuchsia = 255, 0, 255         | gainsboro = 220, 220, 220            | ghostwhite = 248, 248, 255      | gold = 255, 215, 0             | goldenrod = 218, 165, 32       |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| gray = 128, 128, 128          | green = 0, 128, 0                    | greenyellow = 173, 255, 47      | honeydew = 240, 255, 240       | hotpink = 255, 105, 180        |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| indianred = 205, 92, 92       | indigo = 75, 0, 130                  | ivory = 255, 240, 240           | khaki = 240, 230, 140          | lavender = 230, 230, 250       |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| lavenderblush = 255, 240, 245 | lawngreen = 124, 252, 0              | lemonchiffon = 255, 250, 205    | lightblue = 173, 216, 230      | lightcoral = 240, 128, 128     |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| lightcyan = 224, 255, 255     | lightgoldenrodyellow = 250, 250, 210 | lightgreen = 144, 238, 144      | lightgrey = 211, 211, 211      | lightpink = 255, 182, 193      |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| lightsalmon = 255, 160, 122   | lightseagreen = 32, 178, 170         | lightskyblue = 135, 206, 250    | lightslategray = 119, 136, 153 | lightsteelblue = 176, 196, 222 |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| lightyellow = 255, 255, 224   | lime = 0, 255, 0                     | limegreen = 50, 205, 50         | linen = 250, 240, 230          | magenta = 255, 0, 255          |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| maroon = 128, 0, 0            | mediumaquamarine = 102, 205, 170     | mediumblue = 0, 0, 205          | mediumorchid = 186, 85, 211    | mediumpurple = 147, 112, 219   |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| mediumseagreen = 60, 179, 113 | mediumslateblue = 123, 104, 238      | mediumspringgreen = 0, 250, 154 | mediumturquoise = 72, 209, 204 | mediumvioletred = 199, 21, 133 |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| midnightblue = 25, 25, 112    | mintcream = 245, 255, 250            | mistyrose = 255, 228, 225       | moccasin = 255, 228, 181       | navajowhite = 255, 222, 173    |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| navy = 0, 0, 128              | oldlace = 253, 245, 230              | olive = 128, 128, 0             | olivedrab = 107, 142, 35       | orange = 255, 165, 0           |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| orangered = 255, 69, 0        | orchid = 218, 112, 214               | palegoldenrod = 238, 232, 170   | palegreen = 152, 251, 152      | paleturquoise = 175, 238, 238  |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| palevioletred = 219, 112, 147 | papayawhip = 255, 239, 213           | peachpuff = 255, 239, 213       | peru = 205, 133, 63            | pink = 255, 192, 203           |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| plum = 221, 160, 221          | powderblue = 176, 224, 230           | purple = 128, 0, 128            | red = 255, 0, 0                | rosybrown = 188, 143, 143      |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| royalblue = 65, 105, 225      | saddlebrown = 139, 69, 19            | salmon = 250, 128, 114          | sandybrown = 244, 164, 96      | seagreen = 46, 139, 87         |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| seashell = 255, 245, 238      | sienna = 160, 82, 45                 | silver = 192, 192, 192          | skyblue = 135, 206, 235        | slateblue = 106, 90, 205       |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| slategray = 112, 128, 144     | snow = 255, 250, 250                 | springgreen = 0, 255, 127       | steelblue = 70, 130, 180       | tan = 210, 180, 140            |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| teal = 0, 128, 128            | thistle = 216, 191, 216              | tomato = 253, 99, 71            | turquoise = 64, 224, 208       | violet = 238, 130, 238         |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+
-| wheat = 245, 222, 179         | white = 255, 255, 255                | whitesmoke = 245, 245, 245      | yellow = 255, 255, 0           | yellowgreen = 154, 205, 50     |
-+-------------------------------+--------------------------------------+---------------------------------+--------------------------------+--------------------------------+

doc/src/dynamical_matrix.rst

@@ -1,8 +1,11 @@
 .. index:: dynamical_matrix
+.. index:: dynamical_matrix/kk
 
 dynamical_matrix command
 ========================
 
+Accelerator Variants: dynamical_matrix/kk
+
 Syntax
 """"""
 
@@ -56,6 +59,12 @@ If the style eskm is selected, the dynamical matrix will be in units of
 inverse squared femtoseconds. These units will then conveniently leave
 frequencies in THz.
 
+----------
+
+.. include:: accel_styles.rst
+
+----------
+
 Restrictions
 """"""""""""
 

doc/src/fix.rst

@@ -271,7 +271,8 @@ accelerated styles exist.
 * :doc:`npt/eff <fix_nh_eff>` - NPT for  nuclei and electrons in the electron force field model
 * :doc:`npt/sphere <fix_npt_sphere>` - NPT for spherical particles
 * :doc:`npt/uef <fix_nh_uef>` - NPT style time integration with diagonal flow
-* :doc:`numdiff <fix_numdiff>` - compute derivatives of per-atom data from finite differences
+* :doc:`numdiff <fix_numdiff>` - numerically approximate atomic forces using finite energy differences
+* :doc:`numdiff/virial <fix_numdiff_virial>` - numerically approximate virial stress tensor using finite energy differences
 * :doc:`nve <fix_nve>` - constant NVE time integration
 * :doc:`nve/asphere <fix_nve_asphere>` - NVE for aspherical particles
 * :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>` - NVE for aspherical particles without forces

doc/src/fix_addtorque.rst

@@ -99,7 +99,7 @@ invoked by the :doc:`minimize <minimize>` command.
 Restrictions
 """"""""""""
 
-This fix is part of the MISC package.  It is only enabled if
+This fix is part of the EXTRA-FIX package.  It is only enabled if
 LAMMPS was built with that package.  See the :doc:`Build package
 <Build_package>` page for more info.
 

doc/src/fix_charge_regulation.rst

@@ -20,13 +20,13 @@ Syntax
 
   .. parsed-literal::
 
-     keyword = *pH*, *pKa*, *pKb*, *pIp*, *pIm*, *pKs*, *acid_type*, *base_type*, *lunit_nm*, *temp*, *tempfixid*, *nevery*, *nmc*, *xrd*, *seed*, *tag*, *group*, *onlysalt*, *pmcmoves*
+     keyword = *pH*, *pKa*, *pKb*, *pIp*, *pIm*, *pKs*, *acid_type*, *base_type*, *lunit_nm*, *temp*, *tempfixid*, *nevery*, *nmc*, *rxd*, *seed*, *tag*, *group*, *onlysalt*, *pmcmoves*
      *pH* value = pH of the solution (can be specified as an equal-style variable)
-     *pKa* value = acid dissociation constant
-     *pKb* value = base dissociation constant
-     *pIp* value = chemical potential of free cations
-     *pIm* value = chemical potential of free anions
-     *pKs* value = solution self-dissociation constant
+     *pKa* value = acid dissociation constant (in the -log10 representation)
+     *pKb* value = base dissociation constant (in the -log10 representation)
+     *pIp* value = activity (effective concentration) of free cations (in the -log10 representation)
+     *pIm* value = activity (effective concentration) of free anions (in the -log10 representation)
+     *pKs* value = solvent self-dissociation constant (in the -log10 representation)
      *acid_type* = atom type of acid groups
      *base_type*  = atom type of base groups
      *lunit_nm* value = unit length used by LAMMPS (# in the units of nanometers)
@@ -34,7 +34,7 @@ Syntax
      *tempfixid* value = fix ID of temperature thermostat
      *nevery* value = invoke this fix every nevery steps
      *nmc* value = number of charge regulation MC moves to attempt every nevery steps
-     *xrd* value = cutoff distance for acid/base reaction
+     *rxd* value = cutoff distance for acid/base reaction
      *seed* value = random # seed (positive integer)
      *tag* value = yes or no (yes: The code assign unique tags to inserted ions; no: The tag of all inserted ions is "0")
      *group* value = group-ID, inserted ions are assigned to group group-ID. Can be used multiple times to assign inserted ions to multiple groups.
@@ -47,7 +47,7 @@ Examples
 """"""""
 .. code-block:: LAMMPS
 
-    fix chareg all charge/regulation 1 2 acid_type 3 base_type 4 pKa 5 pKb 7 lb 1.0 nevery 200 nexchange 200 seed 123 tempfixid fT
+    fix chareg all charge/regulation 1 2 acid_type 3 base_type 4 pKa 5.0 pKb 6.0 pH 7.0 pIp 3.0 pIm 3.0 nevery 200 nmc 200 seed 123 tempfixid fT
 
     fix chareg all charge/regulation 1 2 pIp 3 pIm 3 onlysalt yes 2 -1 seed 123 tag yes temp 1.0
 
@@ -92,7 +92,11 @@ where the fix attempts to charge :math:`\mathrm{A}` (discharge
 :math:`\mathrm{A}^-`) to :math:`\mathrm{A}^-` (:math:`\mathrm{A}`) and
 insert (delete) a proton (atom type 2). Besides, the fix implements
 self-ionization reaction of water :math:`\emptyset \rightleftharpoons
-\mathrm{H}^++\mathrm{OH}^-`.  However, this approach is highly
+\mathrm{H}^++\mathrm{OH}^-`.
+
+
+
+However, this approach is highly
 inefficient at :math:`\mathrm{pH} \approx 7` when the concentration of
 both protons and hydroxyl ions is low, resulting in a relatively low
 acceptance rate of MC moves.
@@ -102,24 +106,31 @@ reactions, which can be easily achieved via
 
 .. code-block:: LAMMPS
 
-    fix acid_reaction all charge/regulation 4 5 acid_type 1 pH 7.0 pKa 5.0 pIp 2.0 pIm 2.0
+    fix acid_reaction2 all charge/regulation 4 5 acid_type 1 pH 7.0 pKa 5.0 pIp 2.0 pIm 2.0
 
-where particles of atom type 4 and 5 are the salt cations and anions,
-both at chemical potential pI=2.0, see :ref:`(Curk1) <Curk1>` and
+where particles of atom type 4 and 5 are the salt cations and anions, both at activity (effective concentration) of :math:`10^{-2}` mol/l, see :ref:`(Curk1) <Curk1>` and
 :ref:`(Landsgesell) <Landsgesell>` for more details.
 
-
- Similarly, we could have simultaneously added a base ionization reaction
- (:math:`\mathrm{B} \rightleftharpoons \mathrm{B}^++\mathrm{OH}^-`)
+We could have simultaneously added a base ionization reaction (:math:`\mathrm{B} \rightleftharpoons \mathrm{B}^++\mathrm{OH}^-`)
 
 .. code-block:: LAMMPS
 
-    fix base_reaction all charge/regulation 2 3 base_type 6 pH 7.0 pKb 6.0 pIp 7.0 pIm 7.0
+    fix acid_base_reaction all charge/regulation 2 3 acid_type 1 base_type 6 pH 7.0 pKa 5.0 pKb 6.0 pIp 7.0 pIm 7.0
 
 where the fix will attempt to charge :math:`\mathrm{B}` (discharge
 :math:`\mathrm{B}^+`) to :math:`\mathrm{B}^+` (:math:`\mathrm{B}`) and
-insert (delete) a hydroxyl ion :math:`\mathrm{OH}^-` of atom type 3.  If
-neither the acid or the base type is specified, for example,
+insert (delete) a hydroxyl ion :math:`\mathrm{OH}^-` of atom type 3.
+
+
+Dissociated ions and salt ions can be combined into a single particle type, which reduces the number of necessary MC moves and increases sampling performance, see :ref:`(Curk1) <Curk1>`. The :math:`\mathrm{H}^+` and monovalent salt cation (:math:`\mathrm{S}^+`) are combined into a single particle type, :math:`\mathrm{X}^+ = \{\mathrm{H}^+, \mathrm{S}^+\}`. In this case "pIp" refers to the effective concentration of the combined cation type :math:`\mathrm{X}^+` and its value is determined by :math:`10^{-\mathrm{pIp}} = 10^{-\mathrm{pH}} + 10^{-\mathrm{pSp}}`, where :math:`10^{-\mathrm{pSp}}` is the effective concentration of salt cations. For example, at pH=7 and pSp=6 we would find pIp~5.958 and the command that performs reactions with combined ions could read,
+
+.. code-block:: LAMMPS
+
+    fix acid_reaction_combined all charge/regulation 2 3 acid_type 1 pH 7.0 pKa 5.0 pIp 5.958 pIm 5.958
+
+
+
+If neither the acid or the base type is specified, for example,
 
 .. code-block:: LAMMPS
 
@@ -127,11 +138,11 @@ neither the acid or the base type is specified, for example,
 
 the fix simply inserts or deletes an ion pair of a free cation (atom
 type 4) and a free anion (atom type 5) as done in a conventional
-grand-canonical MC simulation.
+grand-canonical MC simulation. Multivalent ions can be inserted (deleted) by using the *onlysalt* keyword.
 
 
 The fix is compatible with LAMMPS sub-packages such as *molecule* or
-*rigid*. That said, the acid and base particles can be part of larger
+*rigid*. The acid and base particles can be part of larger
 molecules or rigid bodies. Free ions that are inserted to or deleted
 from the system must be defined as single particles (no bonded
 interactions allowed) and cannot be part of larger molecules or rigid
@@ -153,14 +164,14 @@ Langevin thermostat:
     fix fT all langevin 1.0 1.0 1.0 123
     fix_modify fT temp dtemp
 
-The chemical potential units (e.g. pH) are in the standard log10
+The units of  pH, pKa, pKb, pIp, pIm are considered to be in the standard -log10
 representation assuming reference concentration :math:`\rho_0 =
-\mathrm{mol}/\mathrm{l}`.  Therefore, to perform the internal unit
-conversion, the length (in nanometers) of the LAMMPS unit length must be
-specified via *lunit_nm* (default is set to the Bjerrum length in water
-at room temperature *lunit_nm* = 0.71nm). For example, in the dilute
-ideal solution limit, the concentration of free ions will be
-:math:`c_\mathrm{I} = 10^{-\mathrm{pIp}}\mathrm{mol}/\mathrm{l}`.
+\mathrm{mol}/\mathrm{l}`.  For example, in the dilute
+ideal solution limit, the concentration of free cations will be
+:math:`c_\mathrm{I} = 10^{-\mathrm{pIp}}\mathrm{mol}/\mathrm{l}`. To perform the internal unit
+conversion, the the value of the LAMMPS unit length must be
+specified in nanometers via *lunit_nm*. The default value is set to the Bjerrum length in water
+at room temperature (0.71 nm), *lunit_nm* = 0.71.
 
 The temperature used in MC acceptance probability is set by *temp*. This
 temperature should be the same as the temperature set by the molecular
@@ -171,10 +182,10 @@ thermostat fix-ID is *fT*. The inserted particles attain a random
 velocity corresponding to the specified temperature. Using *tempfixid*
 overrides any fixed temperature set by *temp*.
 
-The *xrd* keyword can be used to restrict the inserted/deleted
+The *rxd* keyword can be used to restrict the inserted/deleted
 counterions to a specific radial distance from an acid or base particle
 that is currently participating in a reaction. This can be used to
-simulate more realist reaction dynamics. If *xrd* = 0 or *xrd* > *L* /
+simulate more realist reaction dynamics. If *rxd* = 0 or *rxd* > *L* /
 2, where *L* is the smallest box dimension, the radial restriction is
 automatically turned off and free ion can be inserted or deleted
 anywhere in the simulation box.
@@ -258,18 +269,18 @@ Default
 
 pH = 7.0; pKa = 100.0; pKb = 100.0; pIp = 5.0; pIm = 5.0; pKs = 14.0;
 acid_type = -1; base_type = -1; lunit_nm = 0.71; temp = 1.0; nevery =
-100; nmc = 100; xrd = 0; seed = 0; tag = no; onlysalt = no, pmcmoves =
+100; nmc = 100; rxd = 0; seed = 0; tag = no; onlysalt = no, pmcmoves =
 [1/3, 1/3, 1/3], group-ID = all
 
 ----------
 
 .. _Curk1:
 
-**(Curk1)** T. Curk, J. Yuan, and E. Luijten, "Coarse-grained simulation of charge regulation using LAMMPS", preprint (2021).
+**(Curk1)** T. Curk, J. Yuan, and E. Luijten, "Accelerated simulation method for charge regulation effects", JCP 156 (2022).
 
 .. _Curk2:
 
-**(Curk2)** T. Curk and E. Luijten, "Charge-regulation effects in nanoparticle self-assembly", PRL (2021)
+**(Curk2)** T. Curk and E. Luijten, "Charge-regulation effects in nanoparticle self-assembly", PRL 126 (2021)
 
 .. _Landsgesell:
 

doc/src/fix_dt_reset.rst

@@ -78,13 +78,20 @@ outer loop (largest) timestep, which is the same timestep that the
 
 Note that the cumulative simulation time (in time units), which
 accounts for changes in the timestep size as a simulation proceeds,
-can be accessed by the :doc:`thermo_style time <thermo_style>` keyword.
+can be accessed by the :doc:`thermo_style time <thermo_style>`
+keyword.
+
+Also note that the :doc:`dump_modify every/time <dump_modify>` option
+allows dump files to be written at intervals specified by simulation
+time, rather than by timesteps.  Simulation time is in time units;
+see the :doc:`units <units>` doc page for details.
 
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-No information about this fix is written to :doc:`binary restart files <restart>`.  None of the :doc:`fix_modify <fix_modify>` options
-are relevant to this fix.
+No information about this fix is written to :doc:`binary restart files
+<restart>`.  None of the :doc:`fix_modify <fix_modify>` options are
+relevant to this fix.
 
 This fix computes a global scalar which can be accessed by various
 :doc:`output commands <Howto_output>`.  The scalar stores the last
@@ -93,7 +100,8 @@ timestep on which the timestep was reset to a new value.
 The scalar value calculated by this fix is "intensive".
 
 No parameter of this fix can be used with the *start/stop* keywords of
-the :doc:`run <run>` command.  This fix is not invoked during :doc:`energy minimization <minimize>`.
+the :doc:`run <run>` command.  This fix is not invoked during
+:doc:`energy minimization <minimize>`.
 
 Restrictions
 """"""""""""
@@ -102,7 +110,7 @@ Restrictions
 Related commands
 """"""""""""""""
 
-:doc:`timestep <timestep>`
+:doc:`timestep <timestep>`, :doc:`dump_modify every/time <dump_modify>`
 
 Default
 """""""

doc/src/fix_langevin_drude.rst

@@ -40,7 +40,7 @@ Example input scripts available: examples/PACKAGES/drude
 Description
 """""""""""
 
-Apply two Langevin thermostats as described in :ref:`(Jiang) <Jiang1>` for
+Apply two Langevin thermostats as described in :ref:`(Jiang1) <Jiang1>` for
 thermalizing the reduced degrees of freedom of Drude oscillators.
 This link describes how to use the :doc:`thermalized Drude oscillator model <Howto_drude>` in LAMMPS and polarizable models in LAMMPS
 are discussed on the :doc:`Howto polarizable <Howto_polarizable>` doc
@@ -300,5 +300,5 @@ The option defaults are zero = no.
 
 .. _Jiang1:
 
-**(Jiang)** Jiang, Hardy, Phillips, MacKerell, Schulten, and Roux, J
+**(Jiang1)** Jiang, Hardy, Phillips, MacKerell, Schulten, and Roux, J
 Phys Chem Lett, 2, 87-92 (2011).

doc/src/fix_numdiff.rst

@@ -13,16 +13,15 @@ Syntax
 * ID, group-ID are documented in :doc:`fix <fix>` command
 * numdiff = style name of this fix command
 * Nevery = calculate force by finite difference every this many timesteps
-* delta = finite difference displacement length (distance units)
+* delta = size of atom displacements (distance units)
 
 Examples
 """"""""
 
 .. code-block:: LAMMPS
 
-   fix 1 all numdiff 1 0.0001
    fix 1 all numdiff 10 1e-6
-   fix 1 all numdiff 100 0.01
+   fix 1 movegroup numdiff 100 0.01
 
 Description
 """""""""""
@@ -67,16 +66,17 @@ by two times *delta*.
 
    The cost of each energy evaluation is essentially the cost of an MD
    timestep.  Thus invoking this fix once for a 3d system has a cost
-   of 6N timesteps, where N is the total number of atoms in the system
-   (assuming all atoms are included in the group).  So this fix can be
-   very expensive to use for large systems.
+   of 6N timesteps, where N is the total number of atoms in the system.
+   So this fix can be very expensive to use for large systems.
+   One expedient alternative is to define the fix for a group containing
+   only a few atoms.
 
 ----------
 
 The *Nevery* argument specifies on what timesteps the force will
 be used calculated by finite difference.
 
-The *delta* argument specifies the positional displacement each
+The *delta* argument specifies the size of the displacement each
 atom will undergo.
 
 ----------
@@ -93,7 +93,12 @@ This fix produces a per-atom array which can be accessed by various
 the force on each atom as calculated by finite difference.  The
 per-atom values can only be accessed on timesteps that are multiples
 of *Nevery* since that is when the finite difference forces are
-calculated.
+calculated. See the examples in *examples/numdiff* directory
+to see how this fix can be used to directly compare with
+the analytic forces computed by LAMMPS.
+
+The array values calculated by this compute
+will be in force :doc:`units <units>`.
 
 No parameter of this fix can be used with the *start/stop* keywords of
 the :doc:`run <run>` command.  This fix is invoked during :doc:`energy
@@ -108,7 +113,7 @@ was built with that package.  See the :doc:`Build package <Build_package>` page
 Related commands
 """"""""""""""""
 
-:doc:`dynamical_matrix <dynamical_matrix>`,
+:doc:`dynamical_matrix <dynamical_matrix>`, :doc:`fix numdiff/virial <fix_numdiff_virial>`,
 
 Default
 """""""

doc/src/fix_numdiff_virial.rst

@@ -0,0 +1,115 @@
+.. index:: fix numdiff/virial
+
+fix numdiff/virial command
+==========================
+
+Syntax
+""""""
+
+.. parsed-literal::
+
+   fix ID group-ID numdiff/virial Nevery delta
+
+* ID, group-ID are documented in :doc:`fix <fix>` command
+* numdiff/virial = style name of this fix command
+* Nevery = calculate virial by finite difference every this many timesteps
+* delta = magnitude of strain fields (dimensionless)
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix 1 all numdiff/stress 10 1e-6
+
+Description
+"""""""""""
+
+Calculate the virial stress tensor through a finite difference calculation of
+energy versus strain.  These values can be compared to the analytic virial
+tensor computed by pair styles, bond styles, etc.  This can be useful for
+debugging or other purposes. The specified group must be "all".
+
+This fix applies linear strain fields of magnitude *delta* to all the
+atoms relative to a point at the center of the box.  The
+strain fields are in six different directions, corresponding to the
+six Cartesian components of the stress tensor defined by LAMMPS.
+For each direction it applies the strain field in both the positive
+and negative senses, and the new energy of the entire system
+is calculated after each. The difference in these two energies
+divided by two times *delta*, approximates the corresponding
+component of the virial stress tensor, after applying
+a suitable unit conversion.
+
+.. note::
+
+   It is important to choose a suitable value for delta, the magnitude of
+   strains that are used to generate finite difference
+   approximations to the exact virial stress.  For typical systems, a value in
+   the range of 1 part in 1e5 to 1e6 will be sufficient.
+   However, the best value will depend on a multitude of factors
+   including the stiffness of the interatomic potential, the thermodynamic
+   state of the material being probed, and so on. The only way to be sure
+   that you have made a good choice is to do a sensitivity study on a
+   representative atomic configuration, sweeping over a wide range of
+   values of delta.  If delta is too small, the output values will vary
+   erratically due to truncation effects. If delta is increased beyond a
+   certain point, the output values will start to vary smoothly with
+   delta, due to growing contributions from higher order derivatives. In
+   between these two limits, the numerical virial values should be largely
+   independent of delta.
+
+----------
+
+The *Nevery* argument specifies on what timesteps the force will
+be used calculated by finite difference.
+
+The *delta* argument specifies the size of the displacement each
+atom will undergo.
+
+----------
+
+Restart, fix_modify, output, run start/stop, minimize info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+No information about this fix is written to :doc:`binary restart files
+<restart>`.  None of the :doc:`fix_modify <fix_modify>` options are
+relevant to this fix.
+
+This fix produces a global vector which can be accessed by various
+:doc:`output commands <Howto_output>`, which stores the components of
+the virial stress tensor as calculated by finite difference.  The
+global vector can only be accessed on timesteps that are multiples
+of *Nevery* since that is when the finite difference virial is
+calculated. See the examples in *examples/numdiff* directory
+to see how this fix can be used to directly compare with
+the analytic virial stress tensor computed by LAMMPS.
+
+The order of the virial stress tensor components is *xx*, *yy*, *zz*,
+*yz*, *xz*, and *xy*, consistent with Voigt notation. Note that
+the vector produced by :doc:`compute pressure <compute_pressure>`
+uses a different ordering, with *yz* and *xy* swapped.
+
+The vector values calculated by this compute are
+"intensive".  The vector values will be in pressure
+:doc:`units <units>`.
+
+No parameter of this fix can be used with the *start/stop* keywords of
+the :doc:`run <run>` command.  This fix is invoked during :doc:`energy
+minimization <minimize>`.
+
+Restrictions
+""""""""""""
+
+This fix is part of the EXTRA-FIX package.  It is only enabled if LAMMPS
+was built with that package.  See the :doc:`Build package <Build_package>` page for more info.
+
+Related commands
+""""""""""""""""
+
+:doc:`fix numdiff <fix_numdiff>`, :doc:`compute pressure <compute_pressure>`
+
+Default
+"""""""
+
+none

doc/src/fix_nvt_sllod.rst

@@ -66,7 +66,10 @@ equivalent to Newton's equations of motion for shear flow by
 :ref:`(Evans and Morriss) <Evans3>`. They were later shown to generate
 the desired velocity gradient and the correct production of work by
 stresses for all forms of homogeneous flow by :ref:`(Daivis and Todd)
-<Daivis>`.  As implemented in LAMMPS, they are coupled to a
+<Daivis>`.
+The LAMMPS implementation corresponds to the p-SLLOD variant
+of SLLOD. :ref:`(Edwards) <Edwards>`.
+The equations of motion are coupled to a
 Nose/Hoover chain thermostat in a velocity Verlet formulation, closely
 following the implementation used for the :doc:`fix nvt <fix_nh>`
 command.
@@ -180,6 +183,10 @@ Same as :doc:`fix nvt <fix_nh>`, except tchain = 1.
 
 **(Daivis and Todd)** Daivis and Todd, J Chem Phys, 124, 194103 (2006).
 
+.. _Edwards:
+
+**(Edwards)** Edwards, Baig, and Keffer, J Chem Phys 124, 194104 (2006).
+
 .. _Daivis-sllod:
 
 **(Daivis and Todd)** Daivis and Todd, Nonequilibrium Molecular Dynamics (book),

doc/src/fix_oneway.rst

@@ -51,7 +51,7 @@ the :doc:`run <run>` command.  This fix is not invoked during :doc:`energy minim
 Restrictions
 """"""""""""
 
-This fix is part of the MISC package.  It is only enabled if LAMMPS
+This fix is part of the EXTRA-FIX package.  It is only enabled if LAMMPS
 was built with that package.  See the :doc:`Build package <Build_package>` page for more info.
 
 Related commands

doc/src/fix_smd.rst

@@ -144,7 +144,7 @@ the :doc:`run <run>` command.  This fix is not invoked during
 Restrictions
 """"""""""""
 
-This fix is part of the MISC package.  It is only enabled if
+This fix is part of the EXTRA-FIX package.  It is only enabled if
 LAMMPS was built with that package.  See the :doc:`Build package <Build_package>` page for more info.
 
 Related commands

doc/src/fix_viscosity.rst

@@ -108,10 +108,11 @@ fluid, in appropriate units.  See the :ref:`Muller-Plathe paper <Muller-Plathe2>
 
 An alternative method for calculating a viscosity is to run a NEMD
 simulation, as described on the :doc:`Howto nemd <Howto_nemd>` doc page.
-NEMD simulations deform the simulation box via the :doc:`fix deform <fix_deform>` command.  Thus they cannot be run on a charged
-system using a :doc:`PPPM solver <kspace_style>` since PPPM does not
-currently support non-orthogonal boxes.  Using fix viscosity keeps the
-box orthogonal; thus it does not suffer from this limitation.
+NEMD simulations deform the simulation box via the :doc:`fix deform <fix_deform>` command.
+
+Some features or combination of settings in LAMMPS do not support
+non-orthogonal boxes.  Using fix viscosity keeps the box orthogonal;
+thus it does not suffer from these limitations.
 
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""

doc/src/kspace_style.rst

@@ -310,7 +310,7 @@ Forschungszentrum Juelich.
 
 The library is available for download at "http://scafacos.de" or can
 be cloned from the git-repository
-"git://github.com/scafacos/scafacos.git".
+"https://github.com/scafacos/scafacos.git".
 
 In order to use this KSpace style, you must download and build the
 ScaFaCoS library, then build LAMMPS with the SCAFACOS package

doc/src/package.rst

@@ -460,7 +460,7 @@ using *neigh/thread* *on*, a full neighbor list must also be used. Using
 is turned on by default only when there are 16K atoms or less owned by
 an MPI rank and when using a full neighbor list. Not all KOKKOS-enabled
 potentials support this keyword yet, and only thread over atoms. Many
-simple pair-wise potentials such as Lennard-Jones do support threading
+simple pairwise potentials such as Lennard-Jones do support threading
 over both atoms and neighbors.
 
 The *newton* keyword sets the Newton flags for pairwise and bonded

doc/src/pair_charmm.rst

@@ -119,7 +119,7 @@ name are the older, original LAMMPS implementations.  They compute the
 LJ and Coulombic interactions with an energy switching function (esw,
 shown in the formula below as S(r)), which ramps the energy smoothly
 to zero between the inner and outer cutoff.  This can cause
-irregularities in pair-wise forces (due to the discontinuous second
+irregularities in pairwise forces (due to the discontinuous second
 derivative of energy at the boundaries of the switching region), which
 in some cases can result in detectable artifacts in an MD simulation.
 

doc/src/pair_dpd.rst

@@ -50,7 +50,7 @@ Style *dpd* computes a force field for dissipative particle dynamics
 
 Style *dpd/tstat* invokes a DPD thermostat on pairwise interactions,
 which is equivalent to the non-conservative portion of the DPD force
-field.  This pair-wise thermostat can be used in conjunction with any
+field.  This pairwise thermostat can be used in conjunction with any
 :doc:`pair style <pair_style>`, and in leiu of per-particle thermostats
 like :doc:`fix langevin <fix_langevin>` or ensemble thermostats like
 Nose Hoover as implemented by :doc:`fix nvt <fix_nh>`.  To use

doc/src/pair_granular.rst

@@ -205,7 +205,7 @@ For *damping mass_velocity*, the normal damping is given by:
    \eta_n = \eta_{n0} m_{eff}
 
 Here, :math:`\eta_{n0}` is the damping coefficient specified for the normal
-contact model, in units of *mass*\ /\ *time* and
+contact model, in units of 1/\ *time* and
 :math:`m_{eff} = m_i m_j/(m_i + m_j)` is the effective mass.
 Use *damping mass_velocity* to reproduce the damping behavior of
 *pair gran/hooke/\**.

doc/src/pair_harmonic_cut.rst

@@ -0,0 +1,90 @@
+.. index:: pair_style harmonic/cut
+.. index:: pair_style harmonic/cut/omp
+
+pair_style harmonic/cut command
+===============================
+
+Accelerator Variants: *harmonic/cut/omp*
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   pair_style style
+
+* style = *harmonic/cut*
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   pair_style harmonic/cut 2.5
+   pair_coeff * * 0.2 2.0
+   pair_coeff 1 1 0.5 2.5
+
+Description
+"""""""""""
+
+Style *harmonic/cut* computes pairwise repulsive-only harmonic interactions with the formula
+
+.. math::
+
+   E = k (r_c - r)^2  \qquad r < r_c
+
+:math:`r_c` is the cutoff.
+
+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:`k` (energy units)
+* :math:`r_c` (distance units)
+
+----------
+
+.. include:: accel_styles.rst
+
+----------
+
+Mixing, shift, table, tail correction, restart, rRESPA info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+For atom type pairs I,J and I != J, the :math:`k` and :math:`r_c`
+coefficients can be mixed. The default mix value is *geometric*.
+See the "pair_modify" command for details.
+
+Since the potential is zero at and beyond the cutoff parameter by
+construction, there is no need to support support the :doc:`pair_modify
+<pair_modify>` shift or tail options for the energy and pressure of the
+pair interaction.
+
+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
+""""""""""""
+
+The *harmonic/cut* pair style is only enabled if LAMMPS was
+built with the EXTRA-PAIR package.
+See the :doc:`Build package <Build_package>` page for more info.
+
+Related commands
+""""""""""""""""
+
+:doc:`pair_coeff <pair_coeff>`
+
+Default
+"""""""
+
+none

doc/src/pair_hybrid.rst

@@ -74,14 +74,17 @@ atoms interact with each other via an *eam* potential, the surface atoms
 interact with each other via a *lj/cut* potential, and the metal/surface
 interaction is also computed via a *lj/cut* potential.  The
 *hybrid/overlay* style could be used as in the second example above,
-where multiple potentials are superposed in an additive fashion to
+where multiple potentials are superimposed in an additive fashion to
 compute the interaction between atoms.  In this example, using *lj/cut*
 and *coul/long* together gives the same result as if the
 *lj/cut/coul/long* potential were used by itself.  In this case, it
 would be more efficient to use the single combined potential, but in
 general any combination of pair potentials can be used together in to
 produce an interaction that is not encoded in any single pair_style
-file, e.g. adding Coulombic forces between granular particles.
+file, e.g. adding Coulombic forces between granular particles.  Another
+limitation of using the *hybrid/overlay* variant, that it does not generate
+*lj/cut* parameters for mixed atom types from a mixing rule due to
+restrictions discussed below.
 
 If the *hybrid/scaled* style is used instead of *hybrid/overlay*,
 contributions from sub-styles are weighted by their scale factors, which
@@ -150,10 +153,14 @@ with Tersoff, and the cross-interactions with Lennard-Jones:
    pair_coeff * * tersoff 2 C.tersoff NULL C
    pair_coeff 1 2 lj/cut 1.0 1.5
 
-If pair coefficients are specified in the data file read via the
-:doc:`read_data <read_data>` command, then the same rule applies.
-E.g. "eam/alloy" or "lj/cut" must be added after the atom type, for
-each line in the "Pair Coeffs" section, e.g.
+
+It is not recommended to read pair coefficients for a hybrid style from a "Pair Coeffs"
+or "PairIJ Coeffs" section of a data file via the :doc:`read_data <read_data>` command,
+since those sections expect a fixed number of lines, either one line per atom type or
+one line pair pair of atom types, respectively.  When reading from a data file, the
+lines of the "Pair Coeffs" and "PairIJ Coeffs" are changed in the same way as the *pair_coeff*
+command, i.e. the name of the pair style to which the parameters apply must follow the
+atom type (or atom types), e.g.
 
 .. parsed-literal::
 
@@ -162,6 +169,11 @@ each line in the "Pair Coeffs" section, e.g.
    1 lj/cut/coul/cut 1.0 1.0
    ...
 
+   PairIJ Coeffs
+
+   1 1 lj/cut/coul/cut 1.0 1.0
+   ...
+
 Note that the pair_coeff command for some potentials such as
 :doc:`pair_style eam/alloy <pair_eam>` includes a mapping specification
 of elements to all atom types, which in the hybrid case, can include
@@ -208,12 +220,22 @@ examples above, or in the data file read by the :doc:`read_data
 <read_data>`, or by mixing as described below.  Also all sub-styles
 must be used at least once in a :doc:`pair_coeff <pair_coeff>` command.
 
-.. note::
+.. warning::
 
-   LAMMPS never performs mixing of parameters from different sub-styles,
-   **even** if they use the same type of coefficients, e.g. contain
-   a Lennard-Jones potential variant.  Those parameters must be provided
-   explicitly.
+   With hybrid pair styles the use of mixing to generate pair
+   coefficients is significantly limited compared to the individual pair
+   styles.  LAMMPS **never** performs mixing of parameters from
+   different sub-styles, **even** if they use the same type of
+   coefficients, e.g. contain a Lennard-Jones potential variant.  Those
+   parameters must be provided explicitly.  Also for *hybrid/overlay*
+   and *hybrid/scaled* mixing is **only** performed for pairs of atom
+   types for which only a single pair style is assigned.
+
+   Thus it is strongly recommended to provide all mixed terms
+   explicitly.  For non-hybrid styles those could be generated and
+   written out using the :doc:`write_coeff command <write_coeff>` and
+   then edited as needed to comply with the requirements for hybrid
+   styles as explained above.
 
 If you want there to be no interactions between a particular pair of
 atom types, you have 3 choices.  You can assign the pair of atom types

doc/src/pair_ilp_graphene_hbn.rst

@@ -159,6 +159,8 @@ Related commands
 :doc:`pair_none <pair_none>`,
 :doc:`pair_style hybrid/overlay <pair_hybrid>`,
 :doc:`pair_style drip <pair_drip>`,
+:doc:`pair_style ilp_tmd <pair_ilp_tmd>`,
+:doc:`pair_style saip_metal <pair_saip_metal>`,
 :doc:`pair_style pair_kolmogorov_crespi_z <pair_kolmogorov_crespi_z>`,
 :doc:`pair_style pair_kolmogorov_crespi_full <pair_kolmogorov_crespi_full>`,
 :doc:`pair_style pair_lebedeva_z <pair_lebedeva_z>`,

doc/src/pair_ilp_tmd.rst

@@ -0,0 +1,157 @@
+.. index:: pair_style ilp/tmd
+
+pair_style ilp/tmd command
+===================================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   pair_style [hybrid/overlay ...] ilp/tmd cutoff tap_flag
+
+* cutoff = global cutoff (distance units)
+* tap_flag = 0/1 to turn off/on the taper function
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   pair_style  hybrid/overlay ilp/tmd 16.0 1
+   pair_coeff  * * ilp/tmd  TMD.ILP Mo S S
+
+   pair_style  hybrid/overlay sw/mod sw/mod ilp/tmd 16.0
+   pair_coeff  * * sw/mod 1  tmd.sw.mod Mo S S NULL NULL NULL
+   pair_coeff  * * sw/mod 2  tmd.sw.mod NULL NULL NULL Mo S S
+   pair_coeff  * * ilp/tmd   TMD.ILP    Mo S S Mo S S
+
+Description
+"""""""""""
+
+The *ilp/tmd* style computes the registry-dependent interlayer
+potential (ILP) potential for transition metal dichalcogenides (TMD)
+as described in :ref:`(Ouyang7) <Ouyang7>`.
+
+.. math::
+
+   E  = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij} \\
+   V_{ij}  = & {\rm Tap}(r_{ij})\left \{ e^{-\alpha (r_{ij}/\beta -1)}
+                \left [ \epsilon + f(\rho_{ij}) + f(\rho_{ji})\right ] -
+                 \frac{1}{1+e^{-d\left [ \left ( r_{ij}/\left (s_R \cdot r^{eff} \right ) \right )-1 \right ]}}
+                 \cdot \frac{C_6}{r^6_{ij}} \right \}\\
+   \rho_{ij}^2 = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_i)^2 \\
+   \rho_{ji}^2  = & r_{ij}^2 - ({\bf r}_{ij} \cdot {\bf n}_j)^2 \\
+   f(\rho)  = &  C e^{ -( \rho / \delta )^2 } \\
+   {\rm Tap}(r_{ij})  = & 20\left ( \frac{r_{ij}}{R_{cut}} \right )^7 -
+                           70\left ( \frac{r_{ij}}{R_{cut}} \right )^6 +
+                           84\left ( \frac{r_{ij}}{R_{cut}} \right )^5 -
+                           35\left ( \frac{r_{ij}}{R_{cut}} \right )^4 + 1
+
+Where :math:`\mathrm{Tap}(r_{ij})` is the taper function which provides
+a continuous cutoff (up to third derivative) for interatomic separations
+larger than :math:`r_c` :doc:`pair_style ilp_graphene_hbn <pair_ilp_graphene_hbn>`.
+
+It is important to include all the pairs to build the neighbor list for
+calculating the normals.
+
+.. note::
+
+   Since each MX2 (M = Mo, W and X = S, Se Te) layer contains two
+   sub-layers of X atoms and one sub-layer of M atoms, the definition of the
+   normal vectors used for graphene and h-BN is no longer valid for TMDs.
+   In :ref:`(Ouyang7) <Ouyang7>`, a new definition is proposed, where for
+   each atom `i`, its six nearest neighboring atoms belonging to the same
+   sub-layer are chosen to define the normal vector `{\bf n}_i`.
+
+The parameter file (e.g. TMD.ILP), is intended for use with *metal*
+:doc:`units <units>`, with energies in meV. Two additional parameters,
+*S*, and *rcut* are included in the parameter file. *S* is designed to
+facilitate scaling of energies. *rcut* is designed to build the neighbor
+list for calculating the normals for each atom pair.
+
+.. note::
+
+   The parameters presented in the parameter file (e.g. TMD.ILP),
+   are fitted with taper function by setting the cutoff equal to 16.0
+   Angstrom.  Using different cutoff or taper function should be careful.
+   These parameters provide a good description in both short- and long-range
+   interaction regimes. This feature is essential for simulations in high pressure
+   regime (i.e., the interlayer distance is smaller than the equilibrium
+   distance). The benchmark tests and comparison of these parameters can
+   be found in :ref:`(Ouyang7) <Ouyang7>`.
+
+This potential must be used in combination with hybrid/overlay.
+Other interactions can be set to zero using pair_style *none*\ .
+
+This pair style tallies a breakdown of the total interlayer potential
+energy into sub-categories, which can be accessed via the :doc:`compute pair <compute_pair>` command as a vector of values of length 2.
+The 2 values correspond to the following sub-categories:
+
+1. *E_vdW* = vdW (attractive) energy
+2. *E_Rep* = Repulsive energy
+
+To print these quantities to the log file (with descriptive column
+headings) the following commands could be included in an input script:
+
+.. code-block:: LAMMPS
+
+   compute 0 all pair ilp/tmd
+   variable Evdw  equal c_0[1]
+   variable Erep  equal c_0[2]
+   thermo_style custom step temp epair v_Erep v_Evdw
+
+----------
+
+Mixing, shift, table, tail correction, restart, rRESPA info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This pair style does not support the pair_modify mix, shift, table, and
+tail options.
+
+This pair style does not write their information to binary restart
+files, since it is stored in potential files. Thus, you need to
+re-specify the pair_style and pair_coeff commands in an input script
+that reads a restart file.
+
+Restrictions
+""""""""""""
+
+This pair style is part of the INTERLAYER package.  It is only enabled
+if LAMMPS was built with that package.  See the :doc:`Build package
+<Build_package>` page for more info.
+
+This pair style requires the newton setting to be *on* for pair
+interactions.
+
+The TMD.ILP potential file provided with LAMMPS (see the potentials
+directory) are parameterized for *metal* units.  You can use this
+potential with any LAMMPS units, but you would need to create your
+BNCH.ILP potential file with coefficients listed in the appropriate
+units, if your simulation does not use *metal* units.
+
+Related commands
+""""""""""""""""
+
+:doc:`pair_coeff <pair_coeff>`,
+:doc:`pair_none <pair_none>`,
+:doc:`pair_style hybrid/overlay <pair_hybrid>`,
+:doc:`pair_style drip <pair_drip>`,
+:doc:`pair_style saip_metal <pair_saip_metal>`,
+:doc:`pair_style ilp_graphene_hbn <pair_ilp_graphene_hbn>`,
+:doc:`pair_style pair_kolmogorov_crespi_z <pair_kolmogorov_crespi_z>`,
+:doc:`pair_style pair_kolmogorov_crespi_full <pair_kolmogorov_crespi_full>`,
+:doc:`pair_style pair_lebedeva_z <pair_lebedeva_z>`,
+:doc:`pair_style pair_coul_shield <pair_coul_shield>`.
+
+Default
+"""""""
+
+tap_flag = 1
+
+
+----------
+
+.. _Ouyang7:
+
+**(Ouyang7)** W. Ouyang, et al., J. Chem. Theory Comput. 17, 7237 (2021).

doc/src/pair_lebedeva_z.rst

@@ -26,15 +26,29 @@ Examples
 Description
 """""""""""
 
-The *lebedeva/z* style computes the Lebedeva interaction
-potential as described in :ref:`(Lebedeva et al.) <Leb01>`. An important simplification is made,
-which is to take all normals along the z-axis.
+The *lebedeva/z* pair style computes the Lebedeva interaction potential
+as described in :ref:`(Lebedeva1) <Leb01>` and :ref:`(Lebedeva2)
+<Leb02>`.  An important simplification is made, which is to take all
+normals along the z-axis.
+
+The Lebedeva potential is intended for the description of the interlayer
+interaction between graphene layers.  To perform a realistic simulation,
+this potential must be used in combination with an intralayer potential
+such as :doc:`AIREBO <pair_airebo>` or :doc:`Tersoff <pair_tersoff>`
+facilitated by using pair style :doc:`hybrid/overlay <pair_hybrid>`.  To
+keep the intralayer properties unaffected, the interlayer interaction
+within the same layers should be avoided.  This can be achieved by
+assigning different atom types to atoms of different layers (e.g. 1 and
+2 in the examples above).
+
+Other interactions can be set to zero using pair_style *none*\ .
+
 
 .. math::
 
-   E       = & \frac{1}{2} \sum_i \sum_{i \neq j} V_{ij}\\
+   E       = & \frac{1}{2} \sum_i \sum_{j \neq i} V_{ij}\\
    V_{ij}  = & B e^{-\alpha(r_{ij} - z_0)} \\
-             & + C(1 + D_1\rho^2_{ij} + D_2\rho^4_{ij} e^{-\lambda_1\rho^2_{ij}} e^{-\lambda_2 (z^2_{ij} - z^2_0)} \\
+             & + C(1 + D_1\rho^2_{ij} + D_2\rho^4_{ij}) e^{-\lambda_1\rho^2_{ij}} e^{-\lambda_2 (z^2_{ij} - z^2_0)} \\
              & - A \left(\frac{z_0}{r_ij}\right)^6 + A \left( \frac{z_0}{r_c} \right)^6 \\
    \rho^2_{ij} = & x^2_{ij} + y^2_{ij} \qquad (\mathbf{n_i} \equiv \mathbf{\hat{z}})
 
@@ -43,12 +57,15 @@ Energies are shifted so that they go continuously to zero at the cutoff assuming
 that the exponential part of :math:`V_{ij}` (first term) decays sufficiently fast.
 This shift is achieved by the last term in the equation for :math:`V_{ij}` above.
 
-The parameter file (e.g. CC.Lebedeva), is intended for use with metal
-:doc:`units <units>`, with energies in meV. An additional parameter, *S*,
-is available to facilitate scaling of energies.
+The provided parameter file (CC.Lebedeva) contains two sets of parameters.
 
-This potential must be used in combination with hybrid/overlay.
-Other interactions can be set to zero using pair_style *none*\ .
+- The first set (element name "C") is suitable for normal conditions and
+  is taken from :ref:`(Popov1) <Popov>`
+- The second set (element name "C1") is suitable for high-pressure
+  conditions and is taken from :ref:`(Koziol1) <Koziol>`
+
+Both sets contain an additional parameter, *S*, that can be used to
+facilitate scaling of energies and is set to 1.0 by default.
 
 Restrictions
 """"""""""""
@@ -77,4 +94,16 @@ none
 
 .. _Leb01:
 
-**(Lebedeva et al.)** I. V. Lebedeva, A. A. Knizhnik, A. M. Popov, Y. E. Lozovik, B. V. Potapkin, Phys. Rev. B, 84, 245437 (2011)
+**(Lebedeva1)** I. V. Lebedeva, A. A. Knizhnik, A. M. Popov, Y. E. Lozovik, B. V. Potapkin, Phys. Rev. B, 84, 245437 (2011)
+
+.. _Leb02:
+
+**(Lebedeva2)** I. V. Lebedeva, A. A. Knizhnik, A. M. Popov, Y. E. Lozovik, B. V. Potapkin, Physica E: 44, 949-954 (2012)
+
+.. _Popov:
+
+**(Popov1)** A.M. Popov, I. V. Lebedeva, A. A. Knizhnik, Y. E. Lozovik and B. V. Potapkin, Chem. Phys. Lett. 536, 82-86 (2012).
+
+.. _Koziol:
+
+**(Koziol1)** Z. Koziol, G. Gawlik and J. Jagielski, Chinese Phys. B 28, 096101 (2019).

doc/src/pair_local_density.rst

@@ -26,23 +26,25 @@ Examples
 Description
 """""""""""
 
-The local density (LD) potential is a mean-field manybody potential, and, in some
-sense,a generalization of embedded atom models (EAM). The name "local density
-potential" arises from the fact that it assigns an energy to an atom depending
-on the number of neighboring atoms of given type around it within a predefined
-spherical volume (i.e., within a cutoff). The bottom-up coarse-graining (CG)
-literature suggests that such potentials can be widely useful  in capturing
-effective multibody forces in a computationally efficient manner so as to
-improve the quality of CG models of implicit solvation:ref:`(Sanyal1) <Sanyal1>` and
-phase-segregation in liquid mixtures:ref:`(Sanyal2) <Sanyal2>`, and provide guidelines
-to determine the extent of manybody correlations present in a CG
-model.:ref:`(Rosenberger) <Rosenberger>` The LD potential in LAMMPS is primarily
-intended to be used as a corrective potential over traditional pair potentials
-in bottom-up CG models, i.e., as a hybrid pair style with
-other explicit pair interaction terms (e.g., table spline, Lennard Jones, etc.).
-Because the LD potential is not a pair potential per se,  it is implemented
-simply as a single auxiliary file with all specifications that will be read
-upon initialization.
+The local density (LD) potential is a mean-field manybody potential,
+and, in some way, a generalization of embedded atom models (EAM).  The
+name "local density potential" arises from the fact that it assigns an
+energy to an atom depending on the number of neighboring atoms of a
+given type around it within a predefined spherical volume (i.e., within
+the cutoff).  The bottom-up coarse-graining (CG) literature suggests
+that such potentials can be widely useful in capturing effective
+multibody forces in a computationally efficient manner and thus improve
+the quality of CG models of implicit solvation :ref:`(Sanyal1)
+<Sanyal1>` and phase-segregation in liquid mixtures :ref:`(Sanyal2)
+<Sanyal2>`, and provide guidelines to determine the extent of manybody
+correlations present in a CG model :ref:`(Rosenberger) <Rosenberger>`.
+The LD potential in LAMMPS is primarily intended to be used as a
+corrective potential over traditional pair potentials in bottom-up CG
+models via :doc:`hybrid/overlay pair style <pair_hybrid>` with other
+explicit pair interaction terms (e.g., tabulated, Lennard-Jones, Morse
+etc.).  Because the LD potential is not a pair potential per se, it is
+implemented simply as a single auxiliary file with all specifications
+that will be read upon initialization.
 
 .. note::
 

doc/src/pair_meam.rst

@@ -28,16 +28,16 @@ Description
    as of November 2010; see description below of the mixture_ref_t
    parameter
 
-Style *meam* computes pairwise interactions for a variety of materials
-using modified embedded-atom method (MEAM) potentials
+Pair style *meam* computes non-bonded interactions for a variety of materials
+using the modified embedded-atom method (MEAM)
 :ref:`(Baskes) <Baskes>`.  Conceptually, it is an extension to the original
-:doc:`EAM potentials <pair_eam>` which adds angular forces.  It is
+:doc:`EAM method <pair_eam>` which adds angular forces.  It is
 thus suitable for modeling metals and alloys with fcc, bcc, hcp and
-diamond cubic structures, as well as covalently bonded materials like
-silicon and carbon. Style *meam* is a translation of the (now obsolete)
-*meam* code from Fortran to C++. It is functionally equivalent to *meam*
-but more efficient, and thus *meam* has been removed from LAMMPS after
-the 12 December 2018 release.
+diamond cubic structures, as well as materials with covalent interactions
+like silicon and carbon. This *meam* pair style is a translation of the
+original Fortran version to C++. It is functionally equivalent but more
+efficient and has additional features. The Fortran version of the *meam*
+pair style has been removed from LAMMPS after the 12 December 2018 release.
 
 In the MEAM formulation, the total energy E of a system of atoms is
 given by:

doc/src/pair_modify.rst

@@ -71,21 +71,23 @@ The *mix* keyword affects pair coefficients for interactions between
 atoms of type I and J, when I != J and the coefficients are not
 explicitly set in the input script.  Note that coefficients for I = J
 must be set explicitly, either in the input script via the
-:doc:`pair_coeff <pair_coeff>` command or in the "Pair Coeffs" section of the
-:doc:`data file <read_data>`.  For some pair styles it is not
+:doc:`pair_coeff <pair_coeff>` command or in the "Pair Coeffs" or "PairIJ Coeffs"
+sections of the :doc:`data file <read_data>`.  For some pair styles it is not
 necessary to specify coefficients when I != J, since a "mixing" rule
 will create them from the I,I and J,J settings.  The pair_modify
 *mix* value determines what formulas are used to compute the mixed
 coefficients.  In each case, the cutoff distance is mixed the same way
 as sigma.
 
-Note that not all pair styles support mixing and some mix options
-are not available for certain pair styles. Also, there are additional
-restrictions when using :doc:`pair style hybrid or hybrid/overlay <pair_hybrid>`.
-See the page for individual pair styles for those restrictions.  Note also that the
-:doc:`pair_coeff <pair_coeff>` command also can be used to directly set
-coefficients for a specific I != J pairing, in which case no mixing is
-performed.
+Note that not all pair styles support mixing and some mix options are
+not available for certain pair styles. Also, there are additional
+restrictions when using :doc:`pair style hybrid or hybrid/overlay
+<pair_hybrid>`.  See the page for individual pair styles for those
+restrictions.  Note also that the :doc:`pair_coeff <pair_coeff>` command
+also can be used to directly set coefficients for a specific I != J
+pairing, in which case no mixing is performed.  If possible, LAMMPS will
+print an informational message about how many of the mixed pair
+coefficients were generated and which mixing rule was applied.
 
 - mix *geometric*
 

doc/src/pair_nm.rst

@@ -1,4 +1,5 @@
 .. index:: pair_style nm/cut
+.. index:: pair_style nm/cut/split
 .. index:: pair_style nm/cut/coul/cut
 .. index:: pair_style nm/cut/coul/long
 .. index:: pair_style nm/cut/omp
@@ -10,6 +11,9 @@ pair_style nm/cut command
 
 Accelerator Variants: *nm/cut/omp*
 
+pair_style nm/cut/split command
+===============================
+
 pair_style nm/cut/coul/cut command
 ==================================
 
@@ -27,13 +31,15 @@ Syntax
 
    pair_style style args
 
-* style = *nm/cut* or *nm/cut/coul/cut* or *nm/cut/coul/long*
+* style = *nm/cut* or *nm/cut/split* or *nm/cut/coul/cut* or *nm/cut/coul/long*
 * args = list of arguments for a particular style
 
   .. parsed-literal::
 
        *nm/cut* args = cutoff
          cutoff = global cutoff for Pair interactions (distance units)
+       *nm/cut/split* args = cutoff
+         cutoff = global cutoff for Pair interactions (distance units)
        *nm/cut/coul/cut* args = cutoff (cutoff2)
          cutoff = global cutoff for Pair (and Coulombic if only 1 arg) (distance units)
          cutoff2 = global cutoff for Coulombic (optional) (distance units)
@@ -50,6 +56,10 @@ Examples
    pair_coeff * * 0.01 5.4 8.0 7.0
    pair_coeff 1 1 0.01 4.4 7.0 6.0
 
+   pair_style nm/cut/split 1.12246
+   pair_coeff 1 1 1.0 1.1246 12 6
+   pair_coeff * * 1.0 1.1246 11 6
+
    pair_style nm/cut/coul/cut 12.0 15.0
    pair_coeff * * 0.01 5.4 8.0 7.0
    pair_coeff 1 1 0.01 4.4 7.0 6.0
@@ -71,7 +81,15 @@ interaction has the following form:
    E = \frac{E_0}{(n-m)} \left[ m \left(\frac{r_0}{r}\right)^n - n
    \left(\frac{r_0}{r}\right)^m \right] \qquad r < r_c
 
-where :math:`r_c` is the cutoff.
+where :math:`r_c` is the cutoff and :math:`r_0` is the minimum of the
+potential.  Please note that this differs from the convention used for
+other Lennard-Jones potentials in LAMMPS where :math:`\sigma` represents
+the location where the energy is zero.
+
+Style *nm/cut/split* applies the standard LJ (12-6) potential above
+:math:`r_0 = 2^\frac{1}{6}\sigma`.  Style *nm/cut/split* is employed in
+polymer equilibration protocols that combine core-softening approaches
+with topology-changing moves :ref:`Dietz <Dietz>`.
 
 Style *nm/cut/coul/cut* adds a Coulombic pairwise interaction given by
 
@@ -155,7 +173,6 @@ the :doc:`run_style respa <run_style>` command.  They do not support the
 
 Restrictions
 """"""""""""
-
 These pair styles are part of the EXTRA-PAIR package.  They are only enabled if
 LAMMPS was built with that package.  See the
 :doc:`Build package <Build_package>` page for more info.
@@ -163,7 +180,7 @@ LAMMPS was built with that package.  See the
 Related commands
 """"""""""""""""
 
-:doc:`pair_coeff <pair_coeff>`
+:doc:`pair_coeff <pair_coeff>`, :doc:`pair style lj/cut <pair_lj>`, :doc:`bond style fene/nm <bond_fene>`
 
 Default
 """""""
@@ -175,3 +192,7 @@ none
 .. _Clarke:
 
 **(Clarke)** Clarke and Smith, J Chem Phys, 84, 2290 (1986).
+
+.. _Dietz:
+
+**(Dietz)** Dietz and Hoy, J. Chem Phys, 156, 014103 (2022).