Merge pull request #3706 from akohlmey/next_patch_release

Update version strings for feature release

.github/CODEOWNERS

@@ -150,12 +150,12 @@ tools/vim/*           @hammondkd
 unittest/*            @akohlmey
 
 # cmake
-cmake/*               @junghans @rbberger
+cmake/*               @rbberger
 cmake/Modules/LAMMPSInterfacePlugin.cmake @akohlmey
 cmake/Modules/MPI4WIN.cmake @akohlmey
 cmake/Modules/OpenCLLoader.cmake @akohlmey
-cmake/Modules/Packages/COLVARS.cmake @junghans @rbberger @giacomofiorin
-cmake/Modules/Packages/KIM.cmake @junghans @rbberger @ellio167
+cmake/Modules/Packages/COLVARS.cmake @rbberger @giacomofiorin
+cmake/Modules/Packages/KIM.cmake @rbberger @ellio167
 cmake/presets/*.cmake @akohlmey
 
 # python

SECURITY.md

@@ -32,17 +32,21 @@ for unicode characters and only all-ASCII source code is accepted.
 
 LAMMPS follows a continuous release development model.  We aim to keep
 the development version (`develop` branch) always fully functional and
-employ a variety of automatic testing procedures to detect failures
-of existing functionality from adding or modifying features.  Most of
-those tests are run on pull requests *before* merging to the `develop`
-branch.  The `develop` branch is protected, so all changes *must* be
-submitted as a pull request and thus cannot avoid the automated tests.
+employ a variety of automatic testing procedures to detect failures of
+existing functionality from adding or modifying features.  Most of those
+tests are run on pull requests and must be passed *before* merging to
+the `develop` branch.  The `develop` branch is protected, so all changes
+*must* be submitted as a pull request and thus cannot avoid the
+automated tests.
 
 Additional tests are run *after* merging.  Before releases are made
 *all* tests must have cleared.  Then a release tag is applied and the
-`release` branch is fast-forwarded to that tag.  This is often referred
-to as a patch release. Bug fixes and updates are
-applied first to the `develop` branch.  Later, they appear in the `release`
-branch when the next patch release occurs.
-For stable releases, selected bug fixes, updates, and new functionality
-are pushed to the `stable` branch and a new stable tag is applied.
+`release` branch is fast-forwarded to that tag.  This is referred to to
+as a "feature release".  Bug fixes and updates are applied first to the
+`develop` branch.  Later, they appear in the `release` branch when the
+next patch release occurs.  For stable releases, backported bug fixes
+and infrastructure updates are first applied to the `maintenance` branch
+and then merged to `stable` and published as "updates".  For a new
+stable release the `stable` branch is updated to the corresponding state
+of the `release` branch and a new stable tag is applied in addition to
+the release tag.

cmake/CMakeLists.txt

@@ -538,7 +538,10 @@ set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine
 separate_arguments(CMAKE_TUNE_FLAGS)
 foreach(_FLAG ${CMAKE_TUNE_FLAGS})
   target_compile_options(lammps PRIVATE ${_FLAG})
-  target_compile_options(lmp PRIVATE ${_FLAG})
+  # skip these flags when linking the main executable
+  if(NOT (("${_FLAG}" STREQUAL "-Xcudafe") OR (("${_FLAG}" STREQUAL "--diag_suppress=unrecognized_pragma"))))
+    target_compile_options(lmp PRIVATE ${_FLAG})
+  endif()
 endforeach()
 ########################################################################
 # Basic system tests (standard libraries, headers, functions, types)   #
@@ -838,9 +841,8 @@ if(BUILD_SHARED_LIBS)
   set(LIBLAMMPS_SHARED_BINARY ${MY_BUILD_DIR}/liblammps${LAMMPS_MACHINE}${CMAKE_SHARED_LIBRARY_SUFFIX})
   if(Python_EXECUTABLE)
     add_custom_target(
-      install-python ${CMAKE_COMMAND} -E remove_directory build
-      COMMAND ${Python_EXECUTABLE} ${LAMMPS_PYTHON_DIR}/install.py -p ${LAMMPS_PYTHON_DIR}/lammps
-              -l ${LIBLAMMPS_SHARED_BINARY} -w ${MY_BUILD_DIR}
+      install-python ${Python_EXECUTABLE} ${LAMMPS_PYTHON_DIR}/install.py -p ${LAMMPS_PYTHON_DIR}/lammps
+      -l ${LIBLAMMPS_SHARED_BINARY} -w ${MY_BUILD_DIR} -v ${LAMMPS_SOURCE_DIR}/version.h
       COMMENT "Installing LAMMPS Python module")
   else()
     add_custom_target(
@@ -853,35 +855,6 @@ else()
     ${CMAKE_COMMAND} -E echo "Must build LAMMPS as a shared library to use the Python module")
 endif()
 
-###############################################################################
-# Add LAMMPS python module to "install" target. This is taylored for building
-# LAMMPS for package managers and with different prefix settings.
-# This requires either a shared library or that the PYTHON package is included.
-###############################################################################
-if(BUILD_SHARED_LIBS OR PKG_PYTHON)
-  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.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})
-    endif()
-  else()
-    # backward compatibility
-    if(PYTHON_EXECUTABLE)
-      set(Python_EXECUTABLE ${PYTHON_EXECUTABLE})
-    endif()
-    find_package(Python COMPONENTS Interpreter)
-  endif()
-  if(Python_EXECUTABLE)
-    file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/python/lib)
-    file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/python/src)
-    file(COPY ${LAMMPS_SOURCE_DIR}/version.h  DESTINATION ${CMAKE_BINARY_DIR}/python/src)
-    file(COPY ${LAMMPS_PYTHON_DIR}/README ${LAMMPS_PYTHON_DIR}/pyproject.toml ${LAMMPS_PYTHON_DIR}/setup.py ${LAMMPS_PYTHON_DIR}/lammps  DESTINATION ${CMAKE_BINARY_DIR}/python/lib)
-    install(CODE "if(\"\$ENV{DESTDIR}\" STREQUAL \"\")\n execute_process(COMMAND ${Python_EXECUTABLE} -m pip install -v ${CMAKE_BINARY_DIR}/python/lib --prefix=${CMAKE_INSTALL_PREFIX})\n else()\n execute_process(COMMAND ${Python_EXECUTABLE} -m pip install -v ${CMAKE_BINARY_DIR}/python/lib --prefix=${CMAKE_INSTALL_PREFIX} --root=\$ENV{DESTDIR})\n endif()")
-  endif()
-endif()
-
 include(Testing)
 include(CodeCoverage)
 include(CodingStandard)

cmake/Modules/LAMMPSInterfacePlugin.cmake

@@ -88,6 +88,18 @@ function(get_lammps_version version_header variable)
     set(${variable} "${date}" PARENT_SCOPE)
 endfunction()
 
+# determine canonical URL for downloading backup copy from download.lammps.org/thirdparty
+function(GetFallbackURL input output)
+  string(REPLACE "_URL" "" _tmp ${input})
+  string(TOLOWER ${_tmp} libname)
+  string(REGEX REPLACE "^https://.*/([^/]+gz)" "${LAMMPS_THIRDPARTY_URL}/${libname}-\\1" newurl "${${input}}")
+  if ("${newurl}" STREQUAL "${${input}}")
+    set(${output} "" PARENT_SCOPE)
+  else()
+    set(${output} ${newurl} PARENT_SCOPE)
+  endif()
+endfunction(GetFallbackURL)
+
 #################################################################################
 # LAMMPS C++ interface. We only need the header related parts except on windows.
 add_library(lammps INTERFACE)

cmake/Modules/LAMMPSUtils.cmake

@@ -159,6 +159,7 @@ if((CMAKE_SYSTEM_NAME STREQUAL "Linux") AND (EXISTS /etc/os-release))
   set(CMAKE_DISTRO_VERSION ${disversion})
 endif()
 
+# determine canonical URL for downloading backup copy from download.lammps.org/thirdparty
 function(GetFallbackURL input output)
   string(REPLACE "_URL" "" _tmp ${input})
   string(TOLOWER ${_tmp} libname)

cmake/Modules/Packages/GPU.cmake

@@ -60,9 +60,9 @@ if(GPU_API STREQUAL "CUDA")
   option(CUDA_MPS_SUPPORT "Enable tweaks to support CUDA Multi-process service (MPS)" OFF)
   if(CUDA_MPS_SUPPORT)
     if(CUDPP_OPT)
-      message(FATAL_ERROR "Must use -DCUDPP_OPT=OFF with -DGPU_CUDA_MPS_SUPPORT=ON")
+      message(FATAL_ERROR "Must use -DCUDPP_OPT=OFF with -DCUDA_MPS_SUPPORT=ON")
     endif()
-    set(GPU_CUDA_MPS_FLAGS "-DCUDA_PROXY")
+    set(GPU_CUDA_MPS_FLAGS "-DCUDA_MPS_SUPPORT")
   endif()
 
   set(GPU_ARCH "sm_50" CACHE STRING "LAMMPS GPU CUDA SM primary architecture (e.g. sm_60)")
@@ -98,9 +98,11 @@ if(GPU_API STREQUAL "CUDA")
   # comparison chart according to: https://en.wikipedia.org/wiki/CUDA#GPUs_supported
   if(CUDA_VERSION VERSION_LESS 8.0)
     message(FATAL_ERROR "CUDA Toolkit version 8.0 or later is required")
-  elseif(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+  elseif(CUDA_VERSION VERSION_GREATER_EQUAL "13.0")
     message(WARNING "Untested CUDA Toolkit version ${CUDA_VERSION}. Use at your own risk")
     set(GPU_CUDA_GENCODE "-arch=all")
+  elseif(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+    set(GPU_CUDA_GENCODE "-arch=all")
   else()
     # Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
     if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
@@ -175,8 +177,6 @@ if(GPU_API STREQUAL "CUDA")
     target_compile_definitions(gpu PRIVATE -DUSE_CUDPP)
   endif()
 
-  target_link_libraries(lammps PRIVATE gpu)
-
   add_executable(nvc_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
   target_compile_definitions(nvc_get_devices PRIVATE -DUCL_CUDADR)
   target_link_libraries(nvc_get_devices PRIVATE ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
@@ -249,12 +249,12 @@ elseif(GPU_API STREQUAL "OPENCL")
   else()
     target_compile_definitions(gpu PRIVATE -DMPI_GERYON -DGERYON_NUMA_FISSION -DUCL_NO_EXIT)
   endif()
-  target_link_libraries(lammps PRIVATE gpu)
 
   add_executable(ocl_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
   target_compile_definitions(ocl_get_devices PRIVATE -DUCL_OPENCL)
   target_link_libraries(ocl_get_devices PRIVATE OpenCL::OpenCL)
   add_dependencies(ocl_get_devices OpenCL::OpenCL)
+
 elseif(GPU_API STREQUAL "HIP")
   if(NOT DEFINED HIP_PATH)
       if(NOT DEFINED ENV{HIP_PATH})
@@ -285,7 +285,7 @@ elseif(GPU_API STREQUAL "HIP")
 
   set(ENV{HIP_PLATFORM} ${HIP_PLATFORM})
 
-  if(HIP_PLATFORM STREQUAL "hcc" OR HIP_PLATFORM STREQUAL "amd")
+  if(HIP_PLATFORM STREQUAL "amd")
     set(HIP_ARCH "gfx906" CACHE STRING "HIP target architecture")
   elseif(HIP_PLATFORM STREQUAL "spirv")
     set(HIP_ARCH "spirv" CACHE STRING "HIP target architecture")
@@ -358,7 +358,7 @@ elseif(GPU_API STREQUAL "HIP")
     set(CUBIN_FILE   "${LAMMPS_LIB_BINARY_DIR}/gpu/${CU_NAME}.cubin")
     set(CUBIN_H_FILE "${LAMMPS_LIB_BINARY_DIR}/gpu/${CU_NAME}_cubin.h")
 
-    if(HIP_PLATFORM STREQUAL "hcc" OR HIP_PLATFORM STREQUAL "amd")
+    if(HIP_PLATFORM STREQUAL "amd")
         configure_file(${CU_FILE} ${CU_CPP_FILE} COPYONLY)
 
         if(HIP_COMPILER STREQUAL "clang")
@@ -412,7 +412,8 @@ elseif(GPU_API STREQUAL "HIP")
       set_property(TARGET gpu PROPERTY CXX_STANDARD 14)
     endif()
     # add hipCUB
-    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
+    find_package(hipcub REQUIRED)
+    target_link_libraries(gpu PRIVATE hip::hipcub)
     target_compile_definitions(gpu PRIVATE -DUSE_HIP_DEVICE_SORT)
 
     if(HIP_PLATFORM STREQUAL "nvcc")
@@ -461,35 +462,25 @@ elseif(GPU_API STREQUAL "HIP")
 
   add_executable(hip_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
   target_compile_definitions(hip_get_devices PRIVATE -DUCL_HIP)
-  target_link_libraries(hip_get_devices hip::host)
+  target_link_libraries(hip_get_devices PRIVATE hip::host)
 
   if(HIP_PLATFORM STREQUAL "nvcc")
     target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_NVCC__)
-    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
     target_include_directories(gpu PRIVATE ${CUDA_INCLUDE_DIRS})
     target_link_libraries(gpu PRIVATE ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
 
     target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_NVCC__)
-    target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/include)
     target_include_directories(hip_get_devices PRIVATE ${CUDA_INCLUDE_DIRS})
     target_link_libraries(hip_get_devices PRIVATE ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
-  elseif(HIP_PLATFORM STREQUAL "hcc")
-    target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_HCC__)
-    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
-
-    target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_HCC__)
-    target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/../include)
-  elseif(HIP_PLATFORM STREQUAL "amd")
-    target_compile_definitions(gpu PRIVATE -D__HIP_PLATFORM_AMD__)
-    target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
-
-    target_compile_definitions(hip_get_devices PRIVATE -D__HIP_PLATFORM_AMD__)
-    target_include_directories(hip_get_devices PRIVATE ${HIP_ROOT_DIR}/../include)
   endif()
-
-  target_link_libraries(lammps PRIVATE gpu)
 endif()
 
+if(BUILD_OMP)
+  find_package(OpenMP COMPONENTS CXX REQUIRED)
+  target_link_libraries(gpu PRIVATE OpenMP::OpenMP_CXX)
+endif()
+target_link_libraries(lammps PRIVATE gpu)
+
 set_property(GLOBAL PROPERTY "GPU_SOURCES" "${GPU_SOURCES}")
 # detect styles which have a GPU version
 RegisterStylesExt(${GPU_SOURCES_DIR} gpu GPU_SOURCES)

cmake/Modules/Packages/KIM.cmake

@@ -19,7 +19,7 @@ if(CURL_FOUND)
     target_compile_definitions(lammps PRIVATE -DLMP_NO_SSL_CHECK)
   endif()
 endif()
-set(KIM_EXTRA_UNITTESTS OFF CACHE STRING "Set extra unit tests verbose mode on/off. If on, extra tests are included.")
+option(KIM_EXTRA_UNITTESTS "Enable extra unit tests for the KIM package." OFF)
 mark_as_advanced(KIM_EXTRA_UNITTESTS)
 find_package(PkgConfig QUIET)
 set(DOWNLOAD_KIM_DEFAULT ON)

cmake/Modules/Packages/KOKKOS.cmake

@@ -72,13 +72,11 @@ if(DOWNLOAD_KOKKOS)
   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.7.01 REQUIRED CONFIG)
   target_link_libraries(lammps PRIVATE Kokkos::kokkos)
-  target_link_libraries(lmp PRIVATE Kokkos::kokkos)
 else()
   set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)
   set(LAMMPS_LIB_KOKKOS_BIN_DIR ${LAMMPS_LIB_BINARY_DIR}/kokkos)
@@ -98,7 +96,6 @@ else()
                           ${LAMMPS_LIB_KOKKOS_BIN_DIR})
   target_include_directories(lammps PRIVATE ${Kokkos_INCLUDE_DIRS})
   target_link_libraries(lammps PRIVATE kokkos)
-  target_link_libraries(lmp PRIVATE kokkos)
   if(BUILD_SHARED_LIBS_WAS_ON)
     set(BUILD_SHARED_LIBS ON)
   endif()

cmake/Modules/Packages/MDI.cmake

@@ -8,8 +8,8 @@ option(DOWNLOAD_MDI "Download and compile the MDI library instead of using an al
 
 if(DOWNLOAD_MDI)
   message(STATUS "MDI download requested - we will build our own")
-  set(MDI_URL "https://github.com/MolSSI-MDI/MDI_Library/archive/v1.4.12.tar.gz" CACHE STRING "URL for MDI tarball")
-  set(MDI_MD5 "7a222353ae8e03961d5365e6cd48baee" CACHE STRING "MD5 checksum for MDI tarball")
+  set(MDI_URL "https://github.com/MolSSI-MDI/MDI_Library/archive/v1.4.16.tar.gz" CACHE STRING "URL for MDI tarball")
+  set(MDI_MD5 "407db44e2d79447ab5c1233af1965f65" CACHE STRING "MD5 checksum for MDI tarball")
   mark_as_advanced(MDI_URL)
   mark_as_advanced(MDI_MD5)
   GetFallbackURL(MDI_URL MDI_FALLBACK)

cmake/Modules/Packages/MSCG.cmake

@@ -7,8 +7,8 @@ else()
 endif()
 option(DOWNLOAD_MSCG "Download MSCG library instead of using an already installed one)" ${DOWNLOAD_MSCG_DEFAULT})
 if(DOWNLOAD_MSCG)
-  set(MSCG_URL "https://github.com/uchicago-voth/MSCG-release/archive/1.7.3.1.tar.gz" CACHE STRING "URL for MSCG tarball")
-  set(MSCG_MD5 "8c45e269ee13f60b303edd7823866a91" CACHE STRING "MD5 checksum of MSCG tarball")
+  set(MSCG_URL "https://github.com/uchicago-voth/MSCG-release/archive/491270a73539e3f6951e76f7dbe84e258b3ebb45.tar.gz" CACHE STRING "URL for MSCG tarball")
+  set(MSCG_MD5 "7ea50748fba5c3a372e0266bd31d2f11" CACHE STRING "MD5 checksum of MSCG tarball")
   mark_as_advanced(MSCG_URL)
   mark_as_advanced(MSCG_MD5)
 

cmake/Modules/Packages/PLUMED.cmake

@@ -54,8 +54,8 @@ if(DOWNLOAD_PLUMED)
     set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumedWrapper${CMAKE_STATIC_LIBRARY_PREFIX}")
   endif()
 
-  set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.8.1/plumed-src-2.8.1.tgz" CACHE STRING "URL for PLUMED tarball")
-  set(PLUMED_MD5 "6bfe72ebdae63dc38a9ca27d9b0e08f8" CACHE STRING "MD5 checksum of PLUMED tarball")
+  set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.8.2/plumed-src-2.8.2.tgz" CACHE STRING "URL for PLUMED tarball")
+  set(PLUMED_MD5 "599092b6a0aa6fff992612537ad98994" CACHE STRING "MD5 checksum of PLUMED tarball")
 
   mark_as_advanced(PLUMED_URL)
   mark_as_advanced(PLUMED_MD5)

cmake/Modules/StyleHeaderUtils.cmake

@@ -95,73 +95,76 @@ function(RegisterIntegrateStyle path)
 endfunction(RegisterIntegrateStyle)
 
 function(RegisterStyles search_path)
-    FindStyleHeaders(${search_path} ANGLE_CLASS     angle_     ANGLE     ) # angle     ) # force
-    FindStyleHeaders(${search_path} ATOM_CLASS      atom_vec_  ATOM_VEC  ) # atom      ) # atom      atom_vec_hybrid
-    FindStyleHeaders(${search_path} BODY_CLASS      body_      BODY      ) # body      ) # atom_vec_body
-    FindStyleHeaders(${search_path} BOND_CLASS      bond_      BOND      ) # bond      ) # force
-    FindStyleHeaders(${search_path} COMMAND_CLASS   "[^.]"     COMMAND   ) # command   ) # input
-    FindStyleHeaders(${search_path} COMPUTE_CLASS   compute_   COMPUTE   ) # compute   ) # modify
-    FindStyleHeaders(${search_path} DIHEDRAL_CLASS  dihedral_  DIHEDRAL  ) # dihedral  ) # force
-    FindStyleHeaders(${search_path} DUMP_CLASS      dump_      DUMP      ) # dump      ) # output    write_dump
-    FindStyleHeaders(${search_path} FIX_CLASS       fix_       FIX       ) # fix       ) # modify
-    FindStyleHeaders(${search_path} IMPROPER_CLASS  improper_  IMPROPER  ) # improper  ) # force
-    FindStyleHeaders(${search_path} INTEGRATE_CLASS "[^.]"     INTEGRATE ) # integrate ) # update
-    FindStyleHeaders(${search_path} KSPACE_CLASS    "[^.]"     KSPACE    ) # kspace    ) # force
-    FindStyleHeaders(${search_path} MINIMIZE_CLASS  min_       MINIMIZE  ) # minimize  ) # update
-    FindStyleHeaders(${search_path} NBIN_CLASS      nbin_      NBIN      ) # nbin      ) # neighbor
-    FindStyleHeaders(${search_path} NPAIR_CLASS     npair_     NPAIR     ) # npair     ) # neighbor
-    FindStyleHeaders(${search_path} NSTENCIL_CLASS  nstencil_  NSTENCIL  ) # nstencil  ) # neighbor
-    FindStyleHeaders(${search_path} NTOPO_CLASS     ntopo_     NTOPO     ) # ntopo     ) # neighbor
-    FindStyleHeaders(${search_path} PAIR_CLASS      pair_      PAIR      ) # pair      ) # force
-    FindStyleHeaders(${search_path} READER_CLASS    reader_    READER    ) # reader    ) # read_dump
-    FindStyleHeaders(${search_path} REGION_CLASS    region_    REGION    ) # region    ) # domain
+    FindStyleHeaders(${search_path} ANGLE_CLASS        angle_        ANGLE        ) # angle        ) # force
+    FindStyleHeaders(${search_path} ATOM_CLASS         atom_vec_     ATOM_VEC     ) # atom         ) # atom      atom_vec_hybrid
+    FindStyleHeaders(${search_path} BODY_CLASS         body_         BODY         ) # body         ) # atom_vec_body
+    FindStyleHeaders(${search_path} BOND_CLASS         bond_         BOND         ) # bond         ) # force
+    FindStyleHeaders(${search_path} COMMAND_CLASS      "[^.]"        COMMAND      ) # command      ) # input
+    FindStyleHeaders(${search_path} COMPUTE_CLASS      compute_      COMPUTE      ) # compute      ) # modify
+    FindStyleHeaders(${search_path} DIHEDRAL_CLASS     dihedral_     DIHEDRAL     ) # dihedral     ) # force
+    FindStyleHeaders(${search_path} DUMP_CLASS         dump_         DUMP         ) # dump         ) # output    write_dump
+    FindStyleHeaders(${search_path} FIX_CLASS          fix_          FIX          ) # fix          ) # modify
+    FindStyleHeaders(${search_path} GRAN_SUB_MOD_CLASS gran_sub_mod_ GRAN_SUB_MOD ) # gran_sub_mod ) # granular_model
+    FindStyleHeaders(${search_path} IMPROPER_CLASS     improper_     IMPROPER     ) # improper     ) # force
+    FindStyleHeaders(${search_path} INTEGRATE_CLASS    "[^.]"        INTEGRATE    ) # integrate    ) # update
+    FindStyleHeaders(${search_path} KSPACE_CLASS       "[^.]"        KSPACE       ) # kspace       ) # force
+    FindStyleHeaders(${search_path} MINIMIZE_CLASS     min_          MINIMIZE     ) # minimize     ) # update
+    FindStyleHeaders(${search_path} NBIN_CLASS         nbin_         NBIN         ) # nbin         ) # neighbor
+    FindStyleHeaders(${search_path} NPAIR_CLASS        npair_        NPAIR        ) # npair        ) # neighbor
+    FindStyleHeaders(${search_path} NSTENCIL_CLASS     nstencil_     NSTENCIL     ) # nstencil     ) # neighbor
+    FindStyleHeaders(${search_path} NTOPO_CLASS        ntopo_        NTOPO        ) # ntopo        ) # neighbor
+    FindStyleHeaders(${search_path} PAIR_CLASS         pair_         PAIR         ) # pair         ) # force
+    FindStyleHeaders(${search_path} READER_CLASS       reader_       READER       ) # reader       ) # read_dump
+    FindStyleHeaders(${search_path} REGION_CLASS       region_       REGION       ) # region       ) # domain
 endfunction(RegisterStyles)
 
 function(RegisterStylesExt search_path extension sources)
-    FindStyleHeadersExt(${search_path} ANGLE_CLASS     ${extension}  ANGLE     ${sources})
-    FindStyleHeadersExt(${search_path} ATOM_CLASS      ${extension}  ATOM_VEC  ${sources})
-    FindStyleHeadersExt(${search_path} BODY_CLASS      ${extension}  BODY      ${sources})
-    FindStyleHeadersExt(${search_path} BOND_CLASS      ${extension}  BOND      ${sources})
-    FindStyleHeadersExt(${search_path} COMMAND_CLASS   ${extension}  COMMAND   ${sources})
-    FindStyleHeadersExt(${search_path} COMPUTE_CLASS   ${extension}  COMPUTE   ${sources})
-    FindStyleHeadersExt(${search_path} DIHEDRAL_CLASS  ${extension}  DIHEDRAL  ${sources})
-    FindStyleHeadersExt(${search_path} DUMP_CLASS      ${extension}  DUMP      ${sources})
-    FindStyleHeadersExt(${search_path} FIX_CLASS       ${extension}  FIX       ${sources})
-    FindStyleHeadersExt(${search_path} IMPROPER_CLASS  ${extension}  IMPROPER  ${sources})
-    FindStyleHeadersExt(${search_path} INTEGRATE_CLASS ${extension}  INTEGRATE ${sources})
-    FindStyleHeadersExt(${search_path} KSPACE_CLASS    ${extension}  KSPACE    ${sources})
-    FindStyleHeadersExt(${search_path} MINIMIZE_CLASS  ${extension}  MINIMIZE  ${sources})
-    FindStyleHeadersExt(${search_path} NBIN_CLASS      ${extension}  NBIN      ${sources})
-    FindStyleHeadersExt(${search_path} NPAIR_CLASS     ${extension}  NPAIR     ${sources})
-    FindStyleHeadersExt(${search_path} NSTENCIL_CLASS  ${extension}  NSTENCIL  ${sources})
-    FindStyleHeadersExt(${search_path} NTOPO_CLASS     ${extension}  NTOPO     ${sources})
-    FindStyleHeadersExt(${search_path} PAIR_CLASS      ${extension}  PAIR      ${sources})
-    FindStyleHeadersExt(${search_path} READER_CLASS    ${extension}  READER    ${sources})
-    FindStyleHeadersExt(${search_path} REGION_CLASS    ${extension}  REGION    ${sources})
+    FindStyleHeadersExt(${search_path} ANGLE_CLASS        ${extension}  ANGLE        ${sources})
+    FindStyleHeadersExt(${search_path} ATOM_CLASS         ${extension}  ATOM_VEC     ${sources})
+    FindStyleHeadersExt(${search_path} BODY_CLASS         ${extension}  BODY         ${sources})
+    FindStyleHeadersExt(${search_path} BOND_CLASS         ${extension}  BOND         ${sources})
+    FindStyleHeadersExt(${search_path} COMMAND_CLASS      ${extension}  COMMAND      ${sources})
+    FindStyleHeadersExt(${search_path} COMPUTE_CLASS      ${extension}  COMPUTE      ${sources})
+    FindStyleHeadersExt(${search_path} DIHEDRAL_CLASS     ${extension}  DIHEDRAL     ${sources})
+    FindStyleHeadersExt(${search_path} DUMP_CLASS         ${extension}  DUMP         ${sources})
+    FindStyleHeadersExt(${search_path} FIX_CLASS          ${extension}  FIX          ${sources})
+    FindStyleHeadersExt(${search_path} GRAN_SUB_MOD_CLASS ${extension}  GRAN_SUB_MOD ${sources})
+    FindStyleHeadersExt(${search_path} IMPROPER_CLASS     ${extension}  IMPROPER     ${sources})
+    FindStyleHeadersExt(${search_path} INTEGRATE_CLASS    ${extension}  INTEGRATE    ${sources})
+    FindStyleHeadersExt(${search_path} KSPACE_CLASS       ${extension}  KSPACE       ${sources})
+    FindStyleHeadersExt(${search_path} MINIMIZE_CLASS     ${extension}  MINIMIZE     ${sources})
+    FindStyleHeadersExt(${search_path} NBIN_CLASS         ${extension}  NBIN         ${sources})
+    FindStyleHeadersExt(${search_path} NPAIR_CLASS        ${extension}  NPAIR        ${sources})
+    FindStyleHeadersExt(${search_path} NSTENCIL_CLASS     ${extension}  NSTENCIL     ${sources})
+    FindStyleHeadersExt(${search_path} NTOPO_CLASS        ${extension}  NTOPO        ${sources})
+    FindStyleHeadersExt(${search_path} PAIR_CLASS         ${extension}  PAIR         ${sources})
+    FindStyleHeadersExt(${search_path} READER_CLASS       ${extension}  READER       ${sources})
+    FindStyleHeadersExt(${search_path} REGION_CLASS       ${extension}  REGION       ${sources})
 endfunction(RegisterStylesExt)
 
 function(GenerateStyleHeaders output_path)
     message(STATUS "Generating style headers...")
-    GenerateStyleHeader(${output_path} ANGLE      angle     ) # force
-    GenerateStyleHeader(${output_path} ATOM_VEC   atom      ) # atom      atom_vec_hybrid
-    GenerateStyleHeader(${output_path} BODY       body      ) # atom_vec_body
-    GenerateStyleHeader(${output_path} BOND       bond      ) # force
-    GenerateStyleHeader(${output_path} COMMAND    command   ) # input
-    GenerateStyleHeader(${output_path} COMPUTE    compute   ) # modify
-    GenerateStyleHeader(${output_path} DIHEDRAL   dihedral  ) # force
-    GenerateStyleHeader(${output_path} DUMP       dump      ) # output    write_dump
-    GenerateStyleHeader(${output_path} FIX        fix       ) # modify
-    GenerateStyleHeader(${output_path} IMPROPER   improper  ) # force
-    GenerateStyleHeader(${output_path} INTEGRATE  integrate ) # update
-    GenerateStyleHeader(${output_path} KSPACE     kspace    ) # force
-    GenerateStyleHeader(${output_path} MINIMIZE   minimize  ) # update
-    GenerateStyleHeader(${output_path} NBIN       nbin      ) # neighbor
-    GenerateStyleHeader(${output_path} NPAIR      npair     ) # neighbor
-    GenerateStyleHeader(${output_path} NSTENCIL   nstencil  ) # neighbor
-    GenerateStyleHeader(${output_path} NTOPO      ntopo     ) # neighbor
-    GenerateStyleHeader(${output_path} PAIR       pair      ) # force
-    GenerateStyleHeader(${output_path} READER     reader    ) # read_dump
-    GenerateStyleHeader(${output_path} REGION     region    ) # domain
+    GenerateStyleHeader(${output_path} ANGLE        angle        ) # force
+    GenerateStyleHeader(${output_path} ATOM_VEC     atom         ) # atom      atom_vec_hybrid
+    GenerateStyleHeader(${output_path} BODY         body         ) # atom_vec_body
+    GenerateStyleHeader(${output_path} BOND         bond         ) # force
+    GenerateStyleHeader(${output_path} COMMAND      command      ) # input
+    GenerateStyleHeader(${output_path} COMPUTE      compute      ) # modify
+    GenerateStyleHeader(${output_path} DIHEDRAL     dihedral     ) # force
+    GenerateStyleHeader(${output_path} DUMP         dump         ) # output    write_dump
+    GenerateStyleHeader(${output_path} FIX          fix          ) # modify
+    GenerateStyleHeader(${output_path} GRAN_SUB_MOD gran_sub_mod ) # granular_model
+    GenerateStyleHeader(${output_path} IMPROPER     improper     ) # force
+    GenerateStyleHeader(${output_path} INTEGRATE    integrate    ) # update
+    GenerateStyleHeader(${output_path} KSPACE       kspace       ) # force
+    GenerateStyleHeader(${output_path} MINIMIZE     minimize     ) # update
+    GenerateStyleHeader(${output_path} NBIN         nbin         ) # neighbor
+    GenerateStyleHeader(${output_path} NPAIR        npair        ) # neighbor
+    GenerateStyleHeader(${output_path} NSTENCIL     nstencil     ) # neighbor
+    GenerateStyleHeader(${output_path} NTOPO        ntopo        ) # neighbor
+    GenerateStyleHeader(${output_path} PAIR         pair         ) # force
+    GenerateStyleHeader(${output_path} READER       reader       ) # read_dump
+    GenerateStyleHeader(${output_path} REGION       region       ) # domain
 endfunction(GenerateStyleHeaders)
 
 function(DetectBuildSystemConflict lammps_src_dir)

doc/Makefile

@@ -94,10 +94,11 @@ html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
 		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
 		echo "############################################" ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \
 		rst_anchor_check src/*.rst ;\
-		python $(BUILDDIR)/utils/check-packages.py -s ../src -d src ;\
+		$(PYTHON) $(BUILDDIR)/utils/check-packages.py -s ../src -d src ;\
 		env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
 		env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst ;\
-		python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
+		env LC_ALL=C grep -n ' `[^`]\+<[a-z][^`]\+`[^_]' $(RSTDIR)/*.rst ;\
+		$(PYTHON) $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
 		echo "############################################" ;\
 		deactivate ;\
 	)
@@ -174,10 +175,11 @@ pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
 		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
 		echo "############################################" ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \
 		rst_anchor_check src/*.rst ;\
-		python utils/check-packages.py -s ../src -d src ;\
+		$(PYTHON) utils/check-packages.py -s ../src -d src ;\
 		env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
 		env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst ;\
-		python utils/check-styles.py -s ../src -d src ;\
+		env LC_ALL=C grep -n ' `[^`]\+<[a-z][^`]\+`[^_]' $(RSTDIR)/*.rst ;\
+		$(PYTHON) utils/check-styles.py -s ../src -d src ;\
 		echo "############################################" ;\
 		deactivate ;\
 	)
@@ -208,14 +210,14 @@ anchor_check : $(ANCHORCHECK)
 style_check : $(VENV)
 	@(\
 		. $(VENV)/bin/activate ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \
-		python utils/check-styles.py -s ../src -d src ;\
+		$(PYTHON) utils/check-styles.py -s ../src -d src ;\
 		deactivate ;\
 	)
 
 package_check : $(VENV)
 	@(\
-		. $(VENV)/bin/activate ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \\
-		python utils/check-packages.py -s ../src -d src ;\
+		. $(VENV)/bin/activate ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \
+		$(PYTHON) utils/check-packages.py -s ../src -d src ;\
 		deactivate ;\
 	)
 
@@ -224,6 +226,14 @@ char_check :
 
 role_check :
 	@( env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst && exit 1 || : )
+	@( env LC_ALL=C grep -n ' `[^`]\+<[a-z][^`]\+`[^_]' $(RSTDIR)/*.rst && exit 1 || : )
+
+link_check : $(VENV) html
+	@(\
+		. $(VENV)/bin/activate ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \
+		linkchecker -F html --check-extern html/Manual.html ;\
+		deactivate ;\
+	)
 
 xmlgen : doxygen/xml/index.xml
 

doc/github-development-workflow.md

@@ -1,12 +1,12 @@
 # Outline of the GitHub Development Workflow
 
-This purpose of this document is to provide a point of reference for the
+The purpose of this document is to provide a point of reference for the
 core LAMMPS developers and other LAMMPS contributors to understand the
 choices the LAMMPS developers have agreed on. Git and GitHub provide the
 tools, but do not set policies, so it is up to the developers to come to
 an agreement as to how to define and interpret policies. This document
-is likely to change as our experiences and needs change and we try to
-adapt accordingly. Last change 2021-09-02.
+is likely to change as our experiences and needs change, and we try to
+adapt it accordingly. Last change 2023-02-10.
 
 ## Table of Contents
 
@@ -22,47 +22,50 @@ adapt accordingly. Last change 2021-09-02.
 ## GitHub Merge Management
 
 In the interest of consistency, ONLY ONE of the core LAMMPS developers
-should doing the merging itself.  This is currently
+should do the merging.  This is currently
 [@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer).  If this
 assignment needs to be changed, it shall be done right after a stable
 release.  If the currently assigned developer cannot merge outstanding
 pull requests in a timely manner, or in other extenuating circumstances,
-other core LAMMPS developers with merge rights can merge pull requests,
-when necessary.
+other core LAMMPS developers with merge permission may merge pull
+requests.
 
 ## Pull Requests
 
-ALL changes to the LAMMPS code and documentation, however trivial, MUST
-be submitted as a pull request to GitHub. All changes to the "develop"
-branch must be made exclusively through merging pull requests. The
-"release" and "stable" branches, respectively are only to be updated
-upon patch or stable releases with fast-forward merges based on the
-associated tags. Pull requests may also be submitted to (long-running)
-feature branches created by LAMMPS developers inside the LAMMPS project,
-if needed. Those are not subject to the merge and review restrictions
-discussed in this document, though, but get managed as needed on a
-case-by-case basis.
+*ALL* changes to the LAMMPS code and documentation, however trivial,
+MUST be submitted as a pull request to GitHub.  All changes to the
+"develop" branch must be made exclusively through merging pull requests.
+The "release" and "stable" branches, respectively, are only to be
+updated upon feature or stable releases based on the associated
+tags.  Updates to the stable release in between stable releases
+(for example, back-ported bug fixes) are first merged into the "maintenance"
+branch and then into the "stable" branch as update releases.
+
+Pull requests may also be submitted to (long-running) feature branches
+created by LAMMPS developers inside the LAMMPS project, if needed. Those
+are not subject to the merge and review restrictions discussed in this
+document, though, but get managed as needed on a case-by-case basis.
 
 ### Pull Request Assignments
 
 Pull requests can be "chaperoned" by one of the LAMMPS core developers.
-This is indicated by who the pull request is assigned to. LAMMPS core
-developers can self-assign or they can decide to assign a pull request
+This is indicated by whom the pull request is assigned to.  LAMMPS core
+developers can self-assign, or they can decide to assign a pull request
 to a different LAMMPS developer. Being assigned to a pull request means,
 that this pull request may need some work and the assignee is tasked to
-determine whether this might be needed or not, and may either implement
-the required changes or ask the submitter of the pull request to implement
-them.  Even though, all LAMMPS developers may have write access to pull
-requests (if enabled by the submitter, which is the default), only the
-submitter or the assignee of a pull request may do so.  During this
-period the `work_in_progress` label may be applied to the pull
-request.  The assignee gets to decide what happens to the pull request
-next, e.g. whether it should be assigned to a different developer for
-additional checks and changes, or is recommended to be merged.  Removing
-the `work_in_progress` label and assigning the pull request to the
-developer tasked with merging signals that a pull request is ready to be
-merged. In addition, a `ready_for_merge` label may also be assigned
-to signal urgency to merge this pull request quickly.
+determine whether this might be needed or not. The assignee may either
+choose to implement required changes or ask the submitter of the pull
+request to implement them.  Even though, all LAMMPS developers may have
+write access to pull requests (if enabled by the submitter, which is the
+default), only the submitter or the assignee of a pull request should do
+so.  During this period, the `work_in_progress` label may be applied to
+the pull request.  The assignee gets to decide what happens to the pull
+request next, e.g. whether it should be assigned to a different
+developer for additional checks and changes, or is recommended to be
+merged.  Removing the `work_in_progress` label and assigning the pull
+request to the developer tasked with merging signals that a pull request
+is ready to be merged. In addition, a `ready_for_merge` label may also
+be assigned to signal urgency to merge this pull request quickly.
 
 ### Pull Request Reviews
 
@@ -70,32 +73,33 @@ People can be assigned to review a pull request in two ways:
 
   * They can be assigned manually to review a pull request
     by the submitter or a LAMMPS developer
-  * They can be automatically assigned, because a developers matches
-    a file pattern in the `.github/CODEOWNERS` file, which associates
-    developers with the code they contributed and maintain.
+  * They can be automatically assigned, because a developer's GitHub
+    handle matches a file pattern in the `.github/CODEOWNERS` file,
+    which associates developers with the code they contributed and
+    maintain.
 
 Reviewers are requested to state their appraisal of the proposed changes
 and either approve or request changes. People may unassign themselves
 from review, if they feel not competent about the changes proposed. At
-least two approvals from LAMMPS developers with write access are required
-before merging in addition to the automated compilation tests.
-Merging counts as implicit approval, so does submission of a pull request
-(by a LAMMPS developer). So the person doing the merge may not also submit
-an approving review. The feature, that reviews from code owners are "hard"
-reviews (i.e. they must all be approved before merging is allowed), is
-currently disabled and it is in the discretion of the merge maintainer to
-assess when a sufficient degree of approval, especially from external
-contributors, has been reached in these cases.  Reviews may be
-(automatically) dismissed, when the reviewed code has been changed,
-and then approval is required a second time.
+least two approvals from LAMMPS developers with write access are
+required before merging, in addition to passing all automated
+compilation and unit tests.  Merging counts as implicit approval, so
+does submission of a pull request (by a LAMMPS developer). So the person
+doing the merge may not also submit an approving review.  The GitHub
+feature, that reviews from code owners are "hard" reviews (i.e. they
+must all approve before merging is allowed), is currently disabled.
+It is in the discretion of the merge maintainer to assess when a
+sufficient degree of approval has been reached, especially from external
+collaborators.  Reviews may be (automatically) dismissed, when the
+reviewed code has been changed. Review may be requested a second time.
 
 ### Pull Request Discussions
 
 All discussions about a pull request should be kept as much as possible
 on the pull request discussion page on GitHub, so that other developers
 can later review the entire discussion after the fact and understand the
-rationale behind choices made.  Exceptions to this policy are technical
-discussions, that are centered on tools or policies themselves
+rationale behind choices that were made.  Exceptions to this policy are
+technical discussions, that are centered on tools or policies themselves
 (git, GitHub, c++) rather than on the content of the pull request.
 
 ## GitHub Issues
@@ -109,39 +113,47 @@ marker in the subject. This is automatically done when using the
 corresponding template for submitting an issue.  Issues may be assigned
 to one or more developers, if they are working on this feature or
 working to resolve an issue.  Issues that have nobody working
-on them at the moment or in the near future, have the label
+on them at the moment, or in the near future, have the label
 `volunteer needed` attached.
 
-When an issue, say `#125` is resolved by a specific pull request,
-the comment for the pull request shall contain the text `closes #125`
-or `fixes #125`, so that the issue is automatically deleted when
-the pull request is merged.  The template for pull requests includes
-a header where connections between pull requests and issues can be listed
-and thus were this comment should be placed.
+When an issue, say `#125` is resolved by a specific pull request, the
+comment for the pull request shall contain the text `closes #125` or
+`fixes #125`, so that the issue is automatically deleted when the pull
+request is merged.  The template for pull requests includes a header
+where connections between pull requests and issues can be listed, and
+thus where this comment should be placed.
 
-## Milestones and Release Planning
+## Release Planning
 
 LAMMPS uses a continuous release development model with incremental
-changes, i.e. significant effort is made - including automated pre-merge
-testing - that the code in the branch "develop" does not get easily
+changes, i.e. significant effort is made -- including automated pre-merge
+testing -- that the code in the branch "develop" does not get easily
 broken.  These tests are run after every update to a pull request.  More
-extensive and time consuming tests (including regression testing) are
-performed after code is merged to the "develop" branch. There are patch
-releases of LAMMPS every 3-5 weeks at a point, when the LAMMPS
-developers feel, that a sufficient amount of changes have happened, and
-the post-merge testing has been successful. These patch releases are
+extensive and time-consuming tests (including regression testing) are
+performed after code is merged to the "develop" branch.  There are feature
+releases of LAMMPS made about every 4-6 weeks at a point, when the LAMMPS
+developers feel, that a sufficient number of changes have been included
+and all post-merge testing has been successful.  These feature releases are
 marked with a `patch_<version date>` tag and the "release" branch
-follows only these versions (and thus is always supposed to be of
-production quality, unlike "develop", which may be temporary broken, in
-the case of larger change sets or unexpected incompatibilities or side
-effects.
+follows only these versions with fast-forward merges.  While "develop" may
+be temporarily broken through issues only detected by the post-merge tests,
+The "release" branch is always supposed to be of production quality.
 
-About 1-2 times each year, there are going to be "stable" releases of
-LAMMPS.  These have seen additional, manual testing and review of
-results from testing with instrumented code and static code analysis.
-Also, the last 1-3 patch releases before a stable release are "release
-candidate" versions which only contain bugfixes and documentation
-updates.  For release planning and the information of code contributors,
-issues and pull requests being actively worked on are assigned a
-"milestone", which corresponds to the next stable release or the stable
-release after that, with a tentative release date.
+About once each year, there is a "stable" release of LAMMPS.  These have
+seen additional, manual testing and review of results from testing with
+instrumented code and static code analysis.  Also, the last few feature
+releases before a stable release are "release candidate" versions which
+only contain bug fixes, feature additions to peripheral functionality,
+and documentation updates.  In between stable releases, bug fixes and
+infrastructure updates are back-ported from the "develop" branch to the
+"maintenance" branch and occasionally merged into "stable" and published
+as update releases.
+
+## Project Management
+
+For release planning and the information of code contributors, issues
+and pull requests are being managed with GitHub Project Boards.  There
+are currently three boards: LAMMPS Feature Requests, LAMMPS Bug Reports,
+and LAMMPS Pull Requests.  Each board is organized in columns where
+submissions are categorized.  Within each column the entries are
+(manually) sorted according their priority.

doc/lammps.1

@@ -1,7 +1,7 @@
-.TH LAMMPS "1" "8 February 2023" "2023-02-08"
+.TH LAMMPS "1" "28 March 2023" "2023-03-28"
 .SH NAME
 .B LAMMPS
-\- Molecular Dynamics Simulator.  Version 8 February 2023
+\- Molecular Dynamics Simulator.  Version 28 March 2023
 
 .SH SYNOPSIS
 .B lmp

doc/msi2lmp.1

@@ -1,11 +1,11 @@
-.TH MSI2LMP "1" "v3.9.9" "2018-11-05"
+.TH MSI2LMP "1" "v3.9.10" "2023-03-10"
 .SH NAME
 .B MSI2LMP
 \- Converter for Materials Studio files to LAMMPS
 
 .SH SYNOPSIS
 .B msi2lmp
-<ROOTNAME> [-class <I|1|II|2|O|0>] [-frc <path to frc file>] [-print #] [-ignore] [-nocenter] [-oldstyle] [-shift <x> <y> <z>]
+[-help] <ROOTNAME> [-class <I|1|II|2|O|0>] [-frc <path to frc file>] [-print #] [-ignore] [-nocenter] [-oldstyle] [-shift <x> <y> <z>]
 
 .SH DESCRIPTION
 .PP
@@ -22,6 +22,9 @@ needed between .frc and .car/.mdf files are the atom types.
 
 .SH OPTIONS
 .TP
+\fB\-h\fR, \fB\-help\fR,
+Print detailed help message to the screen and stop.
+.TP
 \fB\<ROOTNAME>\fR
 This has to be the first argument and is a
 .B mandatory

doc/src/Build_development.rst

@@ -523,6 +523,8 @@ The following options are available.
 These should help to make source and documentation files conforming
 to some the coding style preferences of the LAMMPS developers.
 
+.. _clang-format:
+
 Clang-format support
 --------------------
 

doc/src/Build_extras.rst

@@ -181,6 +181,9 @@ way no local OpenCL development headers or library needs to be present and only
 OpenCL compatible drivers need to be installed to use OpenCL.  If this is not
 desired, you can set :code:`USE_STATIC_OPENCL_LOADER` to :code:`no`.
 
+The GPU library has some multi-thread support using OpenMP.  If LAMMPS is built
+with ``-D BUILD_OMP=on`` this will also be enabled.
+
 If you are compiling with HIP, note that before running CMake you will have to
 set appropriate environment variables. Some variables such as
 :code:`HCC_AMDGPU_TARGET` (for ROCm <= 4.0) or :code:`CUDA_PATH` are necessary for :code:`hipcc`
@@ -274,10 +277,13 @@ To enable GPU binning via CUDA performance primitives set the Makefile variable
 most modern GPUs.
 
 To support the CUDA multiprocessor server you can set the define
-``-DCUDA_PROXY``.  Please note that in this case you must **not** use
+``-DCUDA_MPS_SUPPORT``.  Please note that in this case you must **not** use
 the CUDA performance primitives and thus set the variable ``CUDPP_OPT``
 to empty.
 
+The GPU library has some multi-thread support using OpenMP.  You need to add
+the compiler flag that enables OpenMP to the ``CUDR_OPTS`` Makefile variable.
+
 If the library build is successful, 3 files should be created:
 ``lib/gpu/libgpu.a``\ , ``lib/gpu/nvc_get_devices``\ , and
 ``lib/gpu/Makefile.lammps``\ .  The latter has settings that enable LAMMPS
@@ -1135,7 +1141,7 @@ VORONOI package
 -----------------------------
 
 To build with this package, you must download and build the
-`Voro++ library <https://math.lbl.gov/voro++>`_ or install a
+`Voro++ library <https://math.lbl.gov/voro++/>`_ or install a
 binary package provided by your operating system.
 
 .. tabs::
@@ -1964,10 +1970,10 @@ OPENMP package
    Apple offers the `Xcode package and IDE
    <https://developer.apple.com/xcode/>`_ for compiling software on
    macOS, so you have likely installed it to compile LAMMPS.  Their
-   compiler is based on `Clang <https://clang.llvm.org/>`, but while it
+   compiler is based on `Clang <https://clang.llvm.org/>`_, but while it
    is capable of processing OpenMP directives, the necessary header
    files and OpenMP runtime library are missing.  The `R developers
-   <https://www.r-project.org/>` have figured out a way to build those
+   <https://www.r-project.org/>`_ have figured out a way to build those
    in a compatible fashion. One can download them from
    `https://mac.r-project.org/openmp/
    <https://mac.r-project.org/openmp/>`_.  Simply adding those files as

doc/src/Build_manual.rst

@@ -33,7 +33,7 @@ various tools and files.  Some of them have to be installed (see below).  For
 the rest the build process will attempt to download and install them into
 a python virtual environment and local folders.
 
-A current version of the manual (latest patch release, that is the state
+A current version of the manual (latest feature release, that is the state
 of the *release* branch) is is available online at:
 `https://docs.lammps.org/ <https://docs.lammps.org/>`_.
 A version of the manual corresponding to the ongoing development (that is
@@ -48,9 +48,9 @@ Build using GNU make
 
 The LAMMPS manual is written in `reStructuredText <rst_>`_ format which
 can be translated to different output format using the `Sphinx
-<https://sphinx-doc.org>`_ document generator tool.  It also
+<https://www.sphinx-doc.org/>`_ document generator tool.  It also
 incorporates programmer documentation extracted from the LAMMPS C++
-sources through the `Doxygen <https://doxygen.nl>`_ program.  Currently
+sources through the `Doxygen <https://doxygen.nl/>`_ program.  Currently
 the translation to HTML, PDF (via LaTeX), ePUB (for many e-book readers)
 and MOBI (for Amazon Kindle readers) are supported.  For that to work a
 Python 3 interpreter, the ``doxygen`` tools and internet access to
@@ -87,6 +87,7 @@ folder.  The following ``make`` commands are available:
    make anchor_check  # check for duplicate anchor labels
    make style_check   # check for complete and consistent style lists
    make package_check # check for complete and consistent package lists
+   make link_check    # check for broken or outdated URLs
    make spelling      # spell-check the manual
 
 ----------

doc/src/Commands_bond.rst

@@ -42,6 +42,7 @@ OPT.
    * :doc:`gaussian <bond_gaussian>`
    * :doc:`gromos (o) <bond_gromos>`
    * :doc:`harmonic (iko) <bond_harmonic>`
+   * :doc:`harmonic/restrain <bond_harmonic_restrain>`
    * :doc:`harmonic/shift (o) <bond_harmonic_shift>`
    * :doc:`harmonic/shift/cut (o) <bond_harmonic_shift_cut>`
    * :doc:`lepton (o) <bond_lepton>`

doc/src/Commands_compute.rst

@@ -52,6 +52,8 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`dilatation/atom <compute_dilatation_atom>`
    * :doc:`dipole <compute_dipole>`
    * :doc:`dipole/chunk <compute_dipole_chunk>`
+   * :doc:`dipole/tip4p <compute_dipole>`
+   * :doc:`dipole/tip4p/chunk <compute_dipole_chunk>`
    * :doc:`displace/atom <compute_displace_atom>`
    * :doc:`dpd <compute_dpd>`
    * :doc:`dpd/atom <compute_dpd_atom>`
@@ -104,6 +106,7 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`pe/tally <compute_tally>`
    * :doc:`plasticity/atom <compute_plasticity_atom>`
    * :doc:`pressure <compute_pressure>`
+   * :doc:`pressure/alchemy <compute_pressure_alchemy>`
    * :doc:`pressure/uef <compute_pressure_uef>`
    * :doc:`property/atom <compute_property_atom>`
    * :doc:`property/chunk <compute_property_chunk>`

doc/src/Commands_fix.rst

@@ -29,6 +29,7 @@ OPT.
    * :doc:`adapt/fep <fix_adapt_fep>`
    * :doc:`addforce <fix_addforce>`
    * :doc:`addtorque <fix_addtorque>`
+   * :doc:`alchemy <fix_alchemy>`
    * :doc:`amoeba/bitorsion <fix_amoeba_bitorsion>`
    * :doc:`amoeba/pitorsion <fix_amoeba_pitorsion>`
    * :doc:`append/atoms <fix_append_atoms>`
@@ -69,6 +70,7 @@ OPT.
    * :doc:`dt/reset (k) <fix_dt_reset>`
    * :doc:`edpd/source <fix_dpd_source>`
    * :doc:`efield <fix_efield>`
+   * :doc:`efield/tip4p <fix_efield>`
    * :doc:`ehex <fix_ehex>`
    * :doc:`electrode/conp (i) <fix_electrode>`
    * :doc:`electrode/conq (i) <fix_electrode>`
@@ -92,6 +94,7 @@ OPT.
    * :doc:`grem <fix_grem>`
    * :doc:`halt <fix_halt>`
    * :doc:`heat <fix_heat>`
+   * :doc:`heat/flow <fix_heat_flow>`
    * :doc:`hyper/global <fix_hyper_global>`
    * :doc:`hyper/local <fix_hyper_local>`
    * :doc:`imd <fix_imd>`
@@ -108,6 +111,7 @@ OPT.
    * :doc:`lineforce <fix_lineforce>`
    * :doc:`manifoldforce <fix_manifoldforce>`
    * :doc:`mdi/qm <fix_mdi_qm>`
+   * :doc:`mdi/qmmm <fix_mdi_qmmm>`
    * :doc:`meso/move <fix_meso_move>`
    * :doc:`mol/swap <fix_mol_swap>`
    * :doc:`momentum (k) <fix_momentum>`
@@ -168,7 +172,7 @@ OPT.
    * :doc:`pafi <fix_pafi>`
    * :doc:`pair <fix_pair>`
    * :doc:`phonon <fix_phonon>`
-   * :doc:`pimd <fix_pimd>`
+   * :doc:`pimd/nvt <fix_pimd>`
    * :doc:`planeforce <fix_planeforce>`
    * :doc:`plumed <fix_plumed>`
    * :doc:`poems <fix_poems>`
@@ -263,6 +267,7 @@ OPT.
    * :doc:`wall/lj1043 <fix_wall>`
    * :doc:`wall/lj126 <fix_wall>`
    * :doc:`wall/lj93 (k) <fix_wall>`
+   * :doc:`wall/lepton <fix_wall>`
    * :doc:`wall/morse <fix_wall>`
    * :doc:`wall/piston <fix_wall_piston>`
    * :doc:`wall/reflect (k) <fix_wall_reflect>`
@@ -270,4 +275,5 @@ OPT.
    * :doc:`wall/region <fix_wall_region>`
    * :doc:`wall/region/ees <fix_wall_ees>`
    * :doc:`wall/srd <fix_wall_srd>`
+   * :doc:`wall/table <fix_wall>`
    * :doc:`widom <fix_widom>`

doc/src/Commands_pair.rst

@@ -55,6 +55,7 @@ OPT.
    * :doc:`born/coul/msm (o) <pair_born>`
    * :doc:`born/coul/wolf (go) <pair_born>`
    * :doc:`born/coul/wolf/cs (g) <pair_cs>`
+   * :doc:`born/gauss <pair_born_gauss>`
    * :doc:`bpm/spring <pair_bpm_spring>`
    * :doc:`brownian (o) <pair_brownian>`
    * :doc:`brownian/poly (o) <pair_brownian>`

doc/src/Developer_comm_ops.rst

@@ -77,7 +77,7 @@ buffer, and they will be communicated together to minimize
 communication overhead.  The communication buffers are defined vectors
 containing ``double`` values.  To correctly store integers that may be
 64-bit (bigint, tagint, imageint) in the buffer, you need to use the
-`ubuf union <Communication buffer coding with ubuf>`_ construct.
+:ref:`ubuf union <communication_buffer_coding_with_ubuf>` construct.
 
 The *Fix*, *Compute*, and *Dump* classes can also invoke the same kind
 of forward and reverse communication operations using the same *Comm*

doc/src/Developer_notes.rst

@@ -11,6 +11,7 @@ Available topics are:
 
 - `Reading and parsing of text and text files`_
 - `Requesting and accessing neighbor lists`_
+- `Choosing between a custom atom style, fix property/atom, and fix STORE/ATOM`_
 - `Fix contributions to instantaneous energy, virial, and cumulative energy`_
 - `KSpace PPPM FFT grids`_
 
@@ -73,6 +74,8 @@ when converting "12.5", while the ValueTokenizer class will throw an
 :cpp:func:`ValueTokenizer::next_int()
 <LAMMPS_NS::ValueTokenizer::next_int>` is called on the same string.
 
+.. _request-neighbor-list:
+
 Requesting and accessing neighbor lists
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -216,6 +219,30 @@ command:
 
    neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL);
 
+Choosing between a custom atom style, fix property/atom, and fix STORE/ATOM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are multiple ways to manage per-atom data within LAMMPS.  Often
+the per-atom storage is only used locally and managed by the class that
+uses it.  If the data has to persist between multiple time steps and
+migrate with atoms when they move from sub-domain to sub-domain or
+across periodic boundaries, then using a custom atom style, or :doc:`fix
+property/atom <fix_property_atom>`, or the internal fix STORE/ATOM are
+possible options.
+
+- Using the atom style is usually the most programming effort and mostly
+  needed when the per-atom data is an integral part of the model like a
+  per-atom charge or diameter and thus should be part of the Atoms
+  section of a :doc:`data file <read_data>`.
+
+- Fix property/atom is useful if the data is optional or should be
+  entered by the user, or accessed as a (named) custom property. In this
+  case the fix should be entered as part of the input (and not
+  internally) which allows to enter and store its content with data files.
+
+- Fix STORE/ATOM should be used when the data should be accessed internally
+  only and thus the fix can be created internally.
+
 Fix contributions to instantaneous energy, virial, and cumulative energy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/src/Developer_updating.rst

@@ -24,6 +24,7 @@ Available topics in mostly chronological order are:
 - `Use of "override" instead of "virtual"`_
 - `Simplified and more compact neighbor list requests`_
 - `Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM`_
+- `Rename of fix STORE/PERATOM to fix STORE/ATOM and change of arguments`_
 - `Use Output::get_dump_by_id() instead of Output::find_dump()`_
 - `Refactored grid communication using Grid3d/Grid2d classes instead of GridComm`_
 
@@ -385,6 +386,34 @@ New:
 
 This change is **required** or else the code will not compile.
 
+Rename of fix STORE/PERATOM to fix STORE/ATOM and change of arguments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 28Mar2023
+
+The available functionality of the internal fix to store per-atom
+properties was expanded to enable storing data with ghost atoms and to
+support binary restart files.  With those changes, the fix was renamed
+to fix STORE/ATOM and the number and order of (required) arguments has
+changed.
+
+Old syntax: ``ID group-ID STORE/PERATOM rflag n1 n2 [n3]``
+
+- *rflag* = 0/1, *no*/*yes* store per-atom values in restart file
+- :math:`n1 = 1, n2 = 1, \mathrm{no}\;n3 \to` per-atom vector, single value per atom
+- :math:`n1 = 1, n2 > 1, \mathrm{no}\;n3 \to` per-atom array, *n2* values per atom
+- :math:`n1 = 1, n2 > 0, n3 > 0 \to` per-atom tensor, *n2* x *n3* values per atom
+
+New syntax:  ``ID group-ID STORE/ATOM n1 n2 gflag rflag``
+
+- :math:`n1 = 1, n2 = 0 \to` per-atom vector, single value per atom
+- :math:`n1 > 1, n2 = 0 \to` per-atom array, *n1* values per atom
+- :math:`n1 > 0, n2 > 0 \to` per-atom tensor, *n1* x *n2* values per atom
+- *gflag* = 0/1, *no*/*yes* communicate per-atom values with ghost atoms
+- *rflag* = 0/1, *no*/*yes* store per-atom values in restart file
+
+Since this is an internal fix, there is no user visible change.
+
 Use Output::get_dump_by_id() instead of Output::find_dump()
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/src/Developer_utils.rst

@@ -643,6 +643,8 @@ Tohoku University (under MIT license)
 
 ---------------------------
 
+.. _communication_buffer_coding_with_ubuf:
+
 Communication buffer coding with *ubuf*
 ---------------------------------------
 

doc/src/Developer_write.rst

@@ -6,250 +6,9 @@ be extended by writing new classes that derive from existing
 parent classes in LAMMPS.  Here, some specific coding
 details are provided for writing code for LAMMPS.
 
-Writing a new fix style
-^^^^^^^^^^^^^^^^^^^^^^^
 
-Writing fixes is a flexible way of extending LAMMPS.  Users can
-implement many things using fixes:
-
-- changing particles attributes (positions, velocities, forces, etc.). Examples: FixNVE, FixFreeze.
-- reading/writing data. Example: FixRestart.
-- adding or modifying properties due to geometry. Example: FixWall.
-- interacting with other subsystems or external code: Examples: FixTTM, FixExternal, FixLATTE
-- saving information for analysis or future use (previous positions,
-  for instance). Examples: Fix AveTime, FixStoreState.
-
-
-All fixes are derived from the Fix base class and must have a
-constructor with the signature: ``FixPrintVel(class LAMMPS *, int, char **)``.
-
-Every fix must be registered in LAMMPS by writing the following lines
-of code in the header before include guards:
-
-.. code-block:: c++
-
-   #ifdef FIX_CLASS
-   // clang-format off
-   FixStyle(print/vel,FixPrintVel);
-   // clang-format on
-   #else
-   /* the definition of the FixPrintVel class comes here */
-   ...
-   #endif
-
-Where ``print/vel`` is the style name of your fix in the input script and
-``FixPrintVel`` is the name of the class. The header file would be called
-``fix_print_vel.h`` and the implementation file ``fix_print_vel.cpp``.
-These conventions allow LAMMPS to automatically integrate it into the
-executable when compiling and associate your new fix class with the designated
-keyword when it parses the input script.
-
-Let's write a simple fix which will print the average velocity at the end
-of each timestep. First of all, implement a constructor:
-
-.. code-block:: c++
-
-   FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
-   : Fix(lmp, narg, arg)
-   {
-     if (narg < 4)
-       error->all(FLERR,"Illegal fix print/vel command");
-
-     nevery = utils::inumeric(FLERR,arg[3],false,lmp);
-     if (nevery <= 0)
-       error->all(FLERR,"Illegal fix print/vel command");
-   }
-
-In the constructor you should parse your fix arguments which are
-specified in the script. All fixes have pretty much the same syntax:
-``fix <fix-ID> <fix group> <fix name> <fix arguments ...>``. The
-first 3 parameters are parsed by Fix base class constructor, while
-``<fix arguments>`` should be parsed by you. In our case, we need to
-specify how often we want to print an average velocity. For instance,
-once in 50 timesteps: ``fix 1 print/vel 50``. There is a special variable
-in the Fix class called ``nevery`` which specifies how often the method
-``end_of_step()`` is called. Thus all we need to do is just set it up.
-
-The next method we need to implement is ``setmask()``:
-
-.. code-block:: c++
-
-   int FixPrintVel::setmask()
-   {
-     int mask = 0;
-     mask |= FixConst::END_OF_STEP;
-     return mask;
-   }
-
-Here the user specifies which methods of your fix should be called
-during execution. The constant ``END_OF_STEP`` corresponds to the
-``end_of_step()`` method. The most important available methods that
-are called during a timestep and the order in which they are called
-are shown in the previous section.
-
-.. code-block:: c++
-
-   void FixPrintVel::end_of_step()
-   {
-     // for add3, scale3
-     using namespace MathExtra;
-
-     double** v = atom->v;
-     int nlocal = atom->nlocal;
-     double localAvgVel[4]; // 4th element for particles count
-     memset(localAvgVel, 0, 4 * sizeof(double));
-     for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
-       add3(localAvgVel, v[particleInd], localAvgVel);
-     }
-     localAvgVel[3] = nlocal;
-     double globalAvgVel[4];
-     memset(globalAvgVel, 0, 4 * sizeof(double));
-     MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world);
-     scale3(1.0 / globalAvgVel[3], globalAvgVel);
-     if ((comm->me == 0) && screen) {
-       fmt::print(screen,"{}, {}, {}\n",
-                  globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]);
-     }
-   }
-
-In the code above, we use MathExtra routines defined in
-``math_extra.h``.  There are bunch of math functions to work with
-arrays of doubles as with math vectors.  It is also important to note
-that LAMMPS code should always assume to be run in parallel and that
-atom data is thus distributed across the MPI ranks.  Thus you can
-only process data from local atoms directly and need to use MPI library
-calls to combine or exchange data.  For serial execution, LAMMPS
-comes bundled with the MPI STUBS library that contains the MPI library
-function calls in dummy versions that only work for a single MPI rank.
-
-In this code we use an instance of Atom class. This object is stored
-in the Pointers class (see ``pointers.h``) which is the base class of
-the Fix base class. This object contains references to various class
-instances (the original instances are created and held by the LAMMPS
-class) with all global information about the simulation system.
-Data from the Pointers class is available to all classes inherited from
-it using protected inheritance. Hence when you write you own class,
-which is going to use LAMMPS data, don't forget to inherit from Pointers
-or pass an Pointer to it to all functions that need access. When writing
-fixes we inherit from class Fix which is inherited from Pointers so
-there is no need to inherit from it directly.
-
-The code above computes average velocity for all particles in the
-simulation.  Yet you have one unused parameter in fix call from the
-script: ``group_name``.  This parameter specifies the group of atoms
-used in the fix. So we should compute average for all particles in the
-simulation only if ``group_name == "all"``, but it can be any group.
-The group membership information of an atom is contained in the *mask*
-property of and atom and the bit corresponding to a given group is
-stored in the groupbit variable which is defined in Fix base class:
-
-.. code-block:: c++
-
-   for (int i = 0; i < nlocal; ++i) {
-     if (atom->mask[i] & groupbit) {
-     // Do all job here
-     }
-   }
-
-Class Atom encapsulates atoms positions, velocities, forces, etc. User
-can access them using particle index. Note, that particle indexes are
-usually changed every few timesteps because of neighbor list rebuilds
-and spatial sorting (to improve cache efficiency).
-
-Let us consider another Fix example: We want to have a fix which stores
-atoms position from previous time step in your fix. The local atoms
-indexes may not be valid on the next iteration. In order to handle
-this situation there are several methods which should be implemented:
-
-- ``double memory_usage()``: return how much memory the fix uses (optional)
-- ``void grow_arrays(int)``: do reallocation of the per particle arrays in your fix
-- ``void copy_arrays(int i, int j, int delflag)``: copy i-th per-particle
-  information to j-th. Used when atom sorting is performed. if delflag is set
-  and atom j owns a body, move the body information to atom i.
-- ``void set_arrays(int i)``: sets i-th particle related information to zero
-
-Note, that if your class implements these methods, it must call add calls of
-add_callback and delete_callback to constructor and destructor. Since we want
-to store positions of atoms from previous timestep, we need to add
-``double** xold`` to the header file. Than add allocation code
-to the constructor:
-
-.. code-block:: c++
-
-   FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr)
-   {
-   //...
-     memory->create(xold, atom->nmax, 3, "FixSavePos:x");
-     atom->add_callback(0);
-   }
-
-   FixSavePos::~FixSavePos() {
-     atom->delete_callback(id, 0);
-     memory->destroy(xold);
-   }
-
-Implement the aforementioned methods:
-
-.. code-block:: c++
-
-   double FixSavePos::memory_usage()
-   {
-     int nmax = atom->nmax;
-     double bytes = 0.0;
-     bytes += nmax * 3 * sizeof(double);
-     return bytes;
-   }
-
-   void FixSavePos::grow_arrays(int nmax)
-   {
-     memory->grow(xold, nmax, 3, "FixSavePos:xold");
-   }
-
-   void FixSavePos::copy_arrays(int i, int j, int delflag)
-   {
-     memcpy(xold[j], xold[i], sizeof(double) * 3);
-   }
-
-   void FixSavePos::set_arrays(int i)
-   {
-     memset(xold[i], 0, sizeof(double) * 3);
-   }
-
-   int FixSavePos::pack_exchange(int i, double *buf)
-   {
-     int m = 0;
-     buf[m++] = xold[i][0];
-     buf[m++] = xold[i][1];
-     buf[m++] = xold[i][2];
-
-     return m;
-   }
-
-   int FixSavePos::unpack_exchange(int nlocal, double *buf)
-   {
-     int m = 0;
-     xold[nlocal][0] = buf[m++];
-     xold[nlocal][1] = buf[m++];
-     xold[nlocal][2] = buf[m++];
-
-     return m;
-   }
-
-Now, a little bit about memory allocation. We use the Memory class which
-is just a bunch of template functions for allocating 1D and 2D
-arrays. So you need to add include ``memory.h`` to have access to them.
-
-Finally, if you need to write/read some global information used in
-your fix to the restart file, you might do it by setting flag
-``restart_global = 1`` in the constructor and implementing methods void
-``write_restart(FILE *fp)`` and ``void restart(char *buf)``.
-If, in addition, you want to write the per-atom property to restart
-files additional settings and functions are needed:
-
-- a fix flag indicating this needs to be set ``restart_peratom = 1;``
-- ``atom->add_callback()`` and ``atom->delete_callback()`` must be called
-  a second time with the final argument set to 1 instead of 0 (indicating
-  restart processing instead of per-atom data memory management).
-- the functions ``void pack_restart(int i, double *buf)`` and
-  ``void unpack_restart(int nlocal, int nth)`` need to be implemented
+.. toctree::
+   :maxdepth: 1
 
+   Developer_write_pair
+   Developer_write_fix

doc/src/Developer_write_fix.rst

@@ -0,0 +1,245 @@
+Writing a new fix style
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Writing fix styles is a flexible way of extending LAMMPS.  Users can
+implement many things using fixes.  Some fix styles are only used
+internally to support compute styles or pair styles:
+
+- change particles attributes (positions, velocities, forces, etc.). Examples: ``FixNVE``, ``FixFreeze``.
+- read or write data.  Example: ``FixRestart``.
+- adding or modifying properties due to geometry. Example: ``FixWall``.
+- interacting with other subsystems or external code: Examples: ``FixTTM``, ``FixExternal``, ``FixMDI``
+- saving information for analysis or future use (previous positions,
+  for instance). Examples: ``FixAveTime``, ``FixStoreState``.
+
+All fixes are derived from the ``Fix`` base class and must have a
+constructor with the signature: ``FixPrintVel(class LAMMPS *, int, char **)``.
+
+Every fix must be registered in LAMMPS by writing the following lines
+of code in the header before include guards:
+
+.. code-block:: c++
+
+   #ifdef FIX_CLASS
+   // clang-format off
+   FixStyle(print/vel,FixPrintVel);
+   // clang-format on
+   #else
+   /* the definition of the FixPrintVel class comes here */
+   ...
+   #endif
+
+Where ``print/vel`` is the style name of your fix in the input script and
+``FixPrintVel`` is the name of the class. The header file would be called
+``fix_print_vel.h`` and the implementation file ``fix_print_vel.cpp``.
+These conventions allow LAMMPS to automatically integrate it into the
+executable when compiling and associate your new fix class with the designated
+keyword when it parses the input script.
+
+Let's write a simple fix which will print the average velocity at the end
+of each timestep. First of all, implement a constructor:
+
+.. code-block:: c++
+
+   FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
+   : Fix(lmp, narg, arg)
+   {
+     if (narg < 4) utils::missing_cmd_args(FLERR, "fix print/vel", error);
+
+     nevery = utils::inumeric(FLERR,arg[3],false,lmp);
+     if (nevery <= 0)
+       error->all(FLERR,"Illegal fix print/vel nevery value: {}", nevery);
+   }
+
+In the constructor you should parse the fix arguments which are
+specified in the script.  All fixes have pretty much the same syntax:
+``fix <fix-ID> <fix group> <fix name> <fix arguments ...>``. The first 3
+parameters are parsed by Fix base class constructor, while ``<fix
+arguments>`` should be parsed by you.  In our case, we need to specify
+how often we want to print an average velocity. For instance, once in 50
+timesteps: ``fix 1 print/vel 50``. There is a special variable in the
+Fix class called ``nevery`` which specifies how often the method
+``end_of_step()`` is called.  Thus all we need to do is just set it up.
+
+The next method we need to implement is ``setmask()``:
+
+.. code-block:: c++
+
+   int FixPrintVel::setmask()
+   {
+     int mask = 0;
+     mask |= FixConst::END_OF_STEP;
+     return mask;
+   }
+
+Here the we specify which methods of the fix should be called during
+:doc:`execution of a timestep <Developer_flow>`.  The constant
+``END_OF_STEP`` corresponds to the ``end_of_step()`` method. The most
+important available methods that are called during a timestep.
+
+.. code-block:: c++
+
+   void FixPrintVel::end_of_step()
+   {
+     // for add3, scale3
+     using namespace MathExtra;
+
+     double** v = atom->v;
+     int nlocal = atom->nlocal;
+     double localAvgVel[4]; // 4th element for particles count
+     memset(localAvgVel, 0, 4 * sizeof(double));
+     for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
+       add3(localAvgVel, v[particleInd], localAvgVel);
+     }
+     localAvgVel[3] = nlocal;
+     double globalAvgVel[4];
+     memset(globalAvgVel, 0, 4 * sizeof(double));
+     MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world);
+     scale3(1.0 / globalAvgVel[3], globalAvgVel);
+     if ((comm->me == 0) && screen) {
+       fmt::print(screen,"{}, {}, {}\n",
+                  globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]);
+     }
+   }
+
+In the code above, we use MathExtra routines defined in
+``math_extra.h``.  There are bunch of math functions to work with
+arrays of doubles as with math vectors.  It is also important to note
+that LAMMPS code should always assume to be run in parallel and that
+atom data is thus distributed across the MPI ranks.  Thus you can
+only process data from local atoms directly and need to use MPI library
+calls to combine or exchange data.  For serial execution, LAMMPS
+comes bundled with the MPI STUBS library that contains the MPI library
+function calls in dummy versions that only work for a single MPI rank.
+
+In this code we use an instance of Atom class. This object is stored
+in the Pointers class (see ``pointers.h``) which is the base class of
+the Fix base class. This object contains references to various class
+instances (the original instances are created and held by the LAMMPS
+class) with all global information about the simulation system.
+Data from the Pointers class is available to all classes inherited from
+it using protected inheritance. Hence when you write you own class,
+which is going to use LAMMPS data, don't forget to inherit from Pointers
+or pass a Pointer to it to all functions that need access. When writing
+fixes we inherit from class Fix which is inherited from Pointers so
+there is no need to inherit from it directly.
+
+The code above computes average velocity for all particles in the
+simulation.  Yet you have one unused parameter in fix call from the
+script: ``group_name``.  This parameter specifies the group of atoms
+used in the fix. So we should compute average for all particles in the
+simulation only if ``group_name == "all"``, but it can be any group.
+The group membership information of an atom is contained in the *mask*
+property of an atom and the bit corresponding to a given group is
+stored in the groupbit variable which is defined in Fix base class:
+
+.. code-block:: c++
+
+   for (int i = 0; i < nlocal; ++i) {
+     if (atom->mask[i] & groupbit) {
+     // Do all job here
+     }
+   }
+
+Class Atom encapsulates atoms positions, velocities, forces, etc. Users
+can access them using particle index. Note, that particle indexes are
+usually changed every few timesteps because of neighbor list rebuilds
+and spatial sorting (to improve cache efficiency).
+
+Let us consider another Fix example: We want to have a fix which stores
+atoms position from the previous time step in your fix. The local atoms
+indexes may not be valid on the next iteration. In order to handle
+this situation there are several methods which should be implemented:
+
+- ``double memory_usage()``: return how much memory the fix uses (optional)
+- ``void grow_arrays(int)``: do reallocation of the per-particle arrays in your fix
+- ``void copy_arrays(int i, int j, int delflag)``: copy i-th per-particle
+  information to j-th. Used when atom sorting is performed. if delflag is set
+  and atom j owns a body, move the body information to atom i.
+- ``void set_arrays(int i)``: sets i-th particle related information to zero
+
+Note, that if your class implements these methods, it must add calls of
+add_callback and delete_callback to the constructor and destructor. Since we want
+to store positions of atoms from the previous timestep, we need to add
+``double** xold`` to the header file. Than add allocation code
+to the constructor:
+
+.. code-block:: c++
+
+   FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr)
+   {
+   //...
+     memory->create(xold, atom->nmax, 3, "FixSavePos:x");
+     atom->add_callback(0);
+   }
+
+   FixSavePos::~FixSavePos() {
+     atom->delete_callback(id, 0);
+     memory->destroy(xold);
+   }
+
+Implement the aforementioned methods:
+
+.. code-block:: c++
+
+   double FixSavePos::memory_usage()
+   {
+     int nmax = atom->nmax;
+     double bytes = 0.0;
+     bytes += nmax * 3 * sizeof(double);
+     return bytes;
+   }
+
+   void FixSavePos::grow_arrays(int nmax)
+   {
+     memory->grow(xold, nmax, 3, "FixSavePos:xold");
+   }
+
+   void FixSavePos::copy_arrays(int i, int j, int delflag)
+   {
+     memcpy(xold[j], xold[i], sizeof(double) * 3);
+   }
+
+   void FixSavePos::set_arrays(int i)
+   {
+     memset(xold[i], 0, sizeof(double) * 3);
+   }
+
+   int FixSavePos::pack_exchange(int i, double *buf)
+   {
+     int m = 0;
+     buf[m++] = xold[i][0];
+     buf[m++] = xold[i][1];
+     buf[m++] = xold[i][2];
+
+     return m;
+   }
+
+   int FixSavePos::unpack_exchange(int nlocal, double *buf)
+   {
+     int m = 0;
+     xold[nlocal][0] = buf[m++];
+     xold[nlocal][1] = buf[m++];
+     xold[nlocal][2] = buf[m++];
+
+     return m;
+   }
+
+Now, a little bit about memory allocation. We use the Memory class which
+is just a bunch of template functions for allocating 1D and 2D
+arrays. So you need to add include ``memory.h`` to have access to them.
+
+Finally, if you need to write/read some global information used in
+your fix to the restart file, you might do it by setting flag
+``restart_global = 1`` in the constructor and implementing methods void
+``write_restart(FILE *fp)`` and ``void restart(char *buf)``.
+If, in addition, you want to write the per-atom property to restart
+files additional settings and functions are needed:
+
+- a fix flag indicating this needs to be set ``restart_peratom = 1;``
+- ``atom->add_callback()`` and ``atom->delete_callback()`` must be called
+  a second time with the final argument set to 1 instead of 0 (indicating
+  restart processing instead of per-atom data memory management).
+- the functions ``void pack_restart(int i, double *buf)`` and
+  ``void unpack_restart(int nlocal, int nth)`` need to be implemented
+

doc/src/Errors_debug.rst

@@ -75,7 +75,7 @@ Using the GDB debugger to get a stack trace
 There are two options to use the GDB debugger for identifying the origin
 of the segmentation fault or similar crash. The GDB debugger has many
 more features and options, as can be seen for example its `online
-documentation <https://sourceware.org/gdb/current/onlinedocs/gdb/>`_.
+documentation <https://www.sourceware.org/gdb/documentation/>`_.
 
 Run LAMMPS from within the debugger
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/src/Fortran.rst

@@ -2155,7 +2155,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type
 
    The LAMMPS :doc:`dump style movie <dump_image>` supports generating movies
    from images on-the-fly via creating a pipe to the
-   `ffmpeg <https://ffmpeg.org/ffmpeg/>`_ program.
+   `ffmpeg <https://ffmpeg.org/>`_ program.
    This function checks whether this feature was
    :ref:`enabled at compile time <graphics>`.
    It does **not** check whether the ``ffmpeg`` itself is installed and usable.

doc/src/Howto.rst

@@ -70,6 +70,7 @@ Force fields howto
    Howto_amoeba
    Howto_tip3p
    Howto_tip4p
+   Howto_tip5p
    Howto_spc
 
 Packages howto

doc/src/Howto_github.rst

@@ -476,16 +476,25 @@ to your remote(s) as well:
 
 **Recent changes in the workflow**
 
-Some changes to the workflow are not captured in this tutorial.  For
-example, in addition to the *develop* branch, to which all new features
-should be submitted, there is also a *release* and a *stable* branch;
-these have the same content as *develop*, but are only updated after a
-patch release or stable release was made.  Furthermore, the naming of
-the patches now follow the pattern "patch_<Day><Month><Year>" to
-simplify comparisons between releases.  Finally, all patches and
-submissions are subject to automatic testing and code checks to make
-sure they at the very least compile.
+Some recent changes to the workflow are not captured in this tutorial.
+For example, in addition to the *develop* branch, to which all new
+features should be submitted, there is also a *release*, a *stable*, and
+a *maintenance* branch; the *release* branch is updated from the
+*develop* as part of a feature release, and *stable* (together with
+*release*) are updated from *develop* when a stable release is made. In
+between stable releases, selected bug fixes and infrastructure updates
+are back-ported from the *develop* branch to the *maintenance* branch
+and occasionally merged to *stable* as an update release.
 
-A discussion of the LAMMPS developer GitHub workflow can be found in the
-file `doc/github-development-workflow.md
+Furthermore, the naming of the release tags now follow the pattern
+"patch_<Day><Month><Year>" to simplify comparisons between releases.
+For stable releases additional "stable_<Day><Month><Year>" tags are
+applied and update releases are tagged with
+"stable_<Day><Month><Year>_update<Number>", Finally, all releases and
+submissions are subject to automatic testing and code checks to make
+sure they compile with a variety of compilers and popular operating
+systems.  Some unit and regression testing is applied as well.
+
+A detailed discussion of the LAMMPS developer GitHub workflow can be
+found in the file `doc/github-development-workflow.md
 <https://github.com/lammps/lammps/blob/develop/doc/github-development-workflow.md>`_

doc/src/Howto_granular.rst

@@ -43,6 +43,15 @@ The fix style *freeze* zeroes both the force and torque of frozen
 atoms, and should be used for granular system instead of the fix style
 *setforce*\ .
 
+To model heat conduction, one must add the temperature and heatflow
+atom variables with:
+* :doc:`fix property/atom <fix_property_atom>`
+a temperature integration fix
+* :doc:`fix heat/flow <fix_heat_flow>`
+and a heat conduction option defined in both
+* :doc:`pair_style granular <pair_granular>`
+* :doc:`fix wall/gran <fix_wall_gran>`
+
 For computational efficiency, you can eliminate needless pairwise
 computations between frozen atoms by using this command:
 
@@ -55,3 +64,6 @@ computations between frozen atoms by using this command:
    will be the same as in 3d.  If you wish to model granular particles in
    2d as 2d discs, see the note on this topic on the :doc:`Howto 2d <Howto_2d>`
    doc page, where 2d simulations are discussed.
+
+To add custom granular contact models, see the
+:doc:`modifying granular sub-models page <Modify_gran_sub_mod>`.

doc/src/Howto_mdi.rst

@@ -63,22 +63,29 @@ The package also provides a :doc:`mdi plugin <mdi>` command, which
 enables LAMMPS to operate as an MDI driver and load an MDI engine as a
 plugin library.
 
-The package furthermore includes a `fix mdi/qm <fix_mdi_qm>` command, in
-which LAMMPS operates as an MDI driver in conjunction with a quantum
-mechanics code as an MDI engine.  The post_force() method of the
-``fix_mdi_qm.cpp`` file shows how a driver issues MDI commands to another
-code.  This command can be used to couple to an MDI engine, which is
-either a stand-alone code or a plugin library.
+The package furthermore includes a :doc:`fix mdi/qm <fix_mdi_qm>`
+command, in which LAMMPS operates as an MDI driver in conjunction with a
+quantum mechanics code as an MDI engine.  The post_force() method of the
+``fix_mdi_qm.cpp`` file shows how a driver issues MDI commands to
+another code.  This command can be used to couple to an MDI engine,
+which is either a stand-alone code or a plugin library.
 
-As explained in the `fix mdi/qm <fix_mdi_qm>` command documentation, it
-can be used to perform *ab initio* MD simulations or energy
-minimizations, or to evaluate the quantum energy and forces for a series
-of independent systems.  The ``examples/mdi`` directory has example
-input scripts for all of these use cases.
+As explained in the :doc:`fix mdi/qm <fix_mdi_qm>` command
+documentation, it can be used to perform *ab initio* MD simulations or
+energy minimizations, or to evaluate the quantum energy and forces for a
+series of independent systems.  The ``examples/mdi`` directory has
+example input scripts for all of these use cases.
+
+The package also has a :doc:`fix mdi/qmmm <fix_mdi_qmmm>` command in
+which LAMMPS operates as an MDI driver in conjunction with a quantum
+mechanics code as an MDI engine to perform QM/MM simulations.  The
+LAMMPS input script partitions the system into QM and MM (molecular
+mechanics) atoms.  As described below the ``examples/QUANTUM`` directory
+has examples for coupling to 3 different quantum codes in this manner.
 
 ----------
 
-The examples/mdi directory contains Python scripts and LAMMPS input
+The ``examples/mdi`` directory contains Python scripts and LAMMPS input
 script which use LAMMPS as either an MDI driver or engine, or both.
 Currently, 5 example use cases are provided:
 
@@ -119,45 +126,26 @@ as a plugin library.
 
 -------------
 
-Currently, there are at least two quantum DFT codes which have direct MDI
+As of March 2023, these are quantum codes with MDI support provided via
+Python wrapper scripts included in the LAMMPS distribution.  These can
+be used with the fix mdi/qm and fix mdi/qmmm commands to perform QM
+calculations of an entire system (e.g. AIMD) or QM/MM simulations.  See
+the ``examples/QUANTUM`` sub-directories for more details:
+
+* LATTE - AIMD only
+* PySCF - QM/MM only
+* NWChem - AIMD or QM/MM
+
+There are also at least two quantum codes which have direct MDI
 support, `Quantum ESPRESSO (QE) <https://www.quantum-espresso.org/>`_
-and `INQ <https://qsg.llnl.gov/node/101.html>`_.  There are also several
-QM codes which have indirect support through QCEngine or i-PI.  The
-former means they require a wrapper program (QCEngine) with MDI support
-which writes/read files to pass data to the quantum code itself.  The
-list of QCEngine-supported and i-PI-supported quantum codes is on the
-`MDI webpage
+and `INQ <https://qsg.llnl.gov/node/101.html>`_.  There are also
+several QM codes which have indirect support through QCEngine or i-PI.
+The former means they require a wrapper program (QCEngine) with MDI
+support which writes/read files to pass data to the quantum code
+itself.  The list of QCEngine-supported and i-PI-supported quantum
+codes is on the `MDI webpage
 <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
 
-Here is how to build QE as a stand-alone ``pw.x`` file which can be
-used in stand-alone mode:
-
-.. code-block:: bash
-
-   git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
-   build the executable pw.x, following the `QE build guide <https://gitlab.com/QEF/q-e/-/wikis/Developers/CMake-build-system>`_
-
-Here is how to build QE as a shared library which can be used in plugin mode,
-which results in a ``libqemdi.so`` file in ``<base_path>/q-e/MDI/src``:
-
-.. code-block:: bash
-
-   git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
-   cd <base_path>/q-e
-   ./configure --enable-parallel --enable-openmp --enable-shared FFLAGS="-fPIC" FCFLAGS="-fPIC" CFLAGS="-fPIC" foxflags="-fPIC" try_foxflags="-fPIC"
-   make -j 4 mdi
-
-INQ cannot be built as a stand-alone code; it is by design a library.
-Here is how to build INQ as a shared library which can be used in
-plugin mode, which results in a ``libinqmdi.so`` file in
-``<base_path>/inq/build/examples``:
-
-.. code-block:: bash
-
-   git clone --branch mdi --recurse-submodules https://gitlab.com/taylor-a-barnes/inq.git <base_path>/inq
-   cd <base_path>/inq
-   mkdir -p build
-   cd build
-   ../configure --prefix=<install_path>/install
-   make -j 4
-   make install
+These direct- and indirect-support codes should be usable for full
+system calculations (e.g. AIMD).  Whether they support QM/MM models
+depends on the individual QM code.

doc/src/Howto_spc.rst

@@ -20,7 +20,6 @@ atoms and the water molecule to run a rigid SPC model.
 | LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
 | :math:`r_0` of OH bond = 1.0
 | :math:`\theta_0` of HOH angle = 109.47\ :math:`^{\circ}`
-|
 
 Note that as originally proposed, the SPC model was run with a 9
 Angstrom cutoff for both LJ and Coulomb terms.  It can also be used
@@ -33,16 +32,123 @@ the partial charge assignments change:
 
 | O charge = -0.8476
 | H charge = 0.4238
-|
 
 See the :ref:`(Berendsen) <howto-Berendsen>` reference for more details on both
 the SPC and SPC/E models.
 
+Below is the code for a LAMMPS input file and a molecule file
+(``spce.mol``) of SPC/E water for use with the :doc:`molecule command
+<molecule>` demonstrating how to set up a small bulk water system for
+SPC/E with rigid bonds.
+
+.. code-block:: LAMMPS
+
+   units real
+   atom_style full
+   region box block -5 5 -5 5 -5 5
+   create_box 2 box  bond/types 1 angle/types 1 &
+                   extra/bond/per/atom 2 extra/angle/per/atom 1 extra/special/per/atom 2
+
+   mass 1 15.9994
+   mass 2 1.008
+
+   pair_style lj/cut/coul/cut 10.0
+   pair_coeff 1 1 0.1553 3.166
+   pair_coeff 1 2 0.0    1.0
+   pair_coeff 2 2 0.0    1.0
+
+   bond_style zero
+   bond_coeff 1 1.0
+
+   angle_style zero
+   angle_coeff 1 109.47
+
+   molecule water spce.mol
+   create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
+
+   timestep 1.0
+   fix rigid     all shake 0.0001 10 10000 b 1 a 1
+   minimize 0.0 0.0 1000 10000
+   run 0 post no
+   reset_timestep 0
+   velocity all create 300.0 5463576
+   fix integrate all nvt temp 300.0 300.0 1.0
+
+   thermo_style custom step temp press etotal density pe ke
+   thermo 1000
+   run 20000 upto
+   write_data tip4p.data nocoeff
+
+.. _spce_molecule:
+.. code-block::
+
+   # Water molecule. SPC/E geometry
+
+   3 atoms
+   2 bonds
+   1 angles
+
+   Coords
+
+   1    0.00000  -0.06461   0.00000
+   2    0.81649   0.51275   0.00000
+   3   -0.81649   0.51275   0.00000
+
+   Types
+
+   1        1   # O
+   2        2   # H
+   3        2   # H
+
+   Charges
+
+   1       -0.8476
+   2        0.4238
+   3        0.4238
+
+   Bonds
+
+   1   1      1      2
+   2   1      1      3
+
+   Angles
+
+   1   1      2      1      3
+
+   Shake Flags
+
+   1 1
+   2 1
+   3 1
+
+   Shake Atoms
+
+   1 1 2 3
+   2 1 2 3
+   3 1 2 3
+
+   Shake Bond Types
+
+   1 1 1 1
+   2 1 1 1
+   3 1 1 1
+
+   Special Bond Counts
+
+   1 2 0 0
+   2 1 1 0
+   3 1 1 0
+
+   Special Bonds
+
+   1 2 3
+   2 1 3
+   3 1 2
+
 Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wiki/Water_model>`_.
 
 ----------
 
 .. _howto-Berendsen:
 
-**(Berendsen)** Berendsen, Grigera, Straatsma, J Phys Chem, 91,
-6269-6271 (1987).
+**(Berendsen)** Berendsen, Grigera, Straatsma, J Phys Chem, 91, 6269-6271 (1987).

doc/src/Howto_tip3p.rst

@@ -1,53 +1,211 @@
 TIP3P water model
 =================
 
-The TIP3P water model as implemented in CHARMM
-:ref:`(MacKerell) <howto-tip3p>` specifies a 3-site rigid water molecule with
-charges and Lennard-Jones parameters assigned to each of the 3 atoms.
-In LAMMPS the :doc:`fix shake <fix_shake>` command can be used to hold
-the two O-H bonds and the H-O-H angle rigid.  A bond style of
-*harmonic* and an angle style of *harmonic* or *charmm* should also be
-used.
+The TIP3P water model as implemented in CHARMM :ref:`(MacKerell)
+<howto-tip3p>` specifies a 3-site rigid water molecule with charges and
+Lennard-Jones parameters assigned to each of the 3 atoms.
 
-These are the additional parameters (in real units) to set for O and H
-atoms and the water molecule to run a rigid TIP3P-CHARMM model with a
-cutoff.  The K values can be used if a flexible TIP3P model (without
-fix shake) is desired.  If the LJ epsilon and sigma for HH and OH are
-set to 0.0, it corresponds to the original 1983 TIP3P model
-:ref:`(Jorgensen) <Jorgensen1>`.
+A suitable pair style with cutoff Coulomb would be:
 
-| O mass = 15.9994
-| H mass = 1.008
-| O charge = -0.834
-| H charge = 0.417
-| LJ :math:`\epsilon` of OO = 0.1521
-| LJ :math:`\sigma` of OO = 3.1507
-| LJ :math:`\epsilon` of HH = 0.0460
-| LJ :math:`\sigma` of HH = 0.4000
-| LJ :math:`\epsilon` of OH = 0.0836
-| LJ :math:`\sigma` of OH = 1.7753
-| K of OH bond = 450
-| :math:`r_0` of OH bond = 0.9572
-| K of HOH angle = 55
-| :math:`\theta` of HOH angle = 104.52\ :math:`^{\circ}`
-|
+* :doc:`pair_style lj/cut/coul/cut <pair_lj_cut_coul>`
 
-These are the parameters to use for TIP3P with a long-range Coulomb
-solver (e.g. Ewald or PPPM in LAMMPS), see :ref:`(Price) <Price1>` for
-details:
+or these commands for a long-range Coulomb model:
+
+* :doc:`pair_style lj/cut/coul/long <pair_lj_cut_coul>`
+* :doc:`pair_style lj/cut/coul/long/soft <pair_fep_soft>`
+* :doc:`kspace_style pppm <kspace_style>`
+* :doc:`kspace_style pppm/disp <kspace_style>`
+
+In LAMMPS the :doc:`fix shake or fix rattle <fix_shake>` command can be
+used to hold the two O-H bonds and the H-O-H angle rigid.  A bond style
+of :doc:`harmonic <bond_harmonic>` and an angle style of :doc:`harmonic
+<angle_harmonic>` or :doc:`charmm <angle_charmm>` should also be used.
+In case of rigid bonds also bond style :doc:`zero <bond_zero>` and angle
+style :doc:`zero <angle_zero>` can be used.
+
+The table below lists the force field parameters (in real :doc:`units
+<units>`) to for the water molecule atoms to run a rigid or flexible
+TIP3P-CHARMM model with a cutoff, the original 1983 TIP3P model
+:ref:`(Jorgensen) <Jorgensen1>`, or a TIP3P model with parameters
+optimized for a long-range Coulomb solver (e.g. Ewald or PPPM in LAMMPS)
+:ref:`(Price) <Price1>`.   The K values can be used if a flexible TIP3P
+model (without fix shake) is desired, for rigid bonds/angles they are
+ignored.
+
+   .. list-table::
+      :header-rows: 1
+      :widths: auto
+
+      * - Parameter
+        - TIP3P-CHARMM
+        - TIP3P (original)
+        - TIP3P (Ewald)
+      * - O mass (amu)
+        - 15.9994
+        - 15.9994
+        - 15.9994
+      * - H mass (amu)
+        - 1.008
+        - 1.008
+        - 1.008
+      * - O charge (:math:`e`)
+        - -0.834
+        - -0.834
+        - -0.834
+      * - H charge (:math:`e`)
+        - 0.417
+        - 0.417
+        - 0.417
+      * - LJ :math:`\epsilon` of OO (kcal/mole)
+        - 0.1521
+        - 0.1521
+        - 0.1020
+      * - LJ :math:`\sigma` of OO (:math:`\AA`)
+        - 3.1507
+        - 3.1507
+        - 3.188
+      * - LJ :math:`\epsilon` of HH (kcal/mole)
+        - 0.0460
+        - 0.0
+        - 0.0
+      * - LJ :math:`\sigma` of HH (:math:`\AA`)
+        - 0.4
+        - 1.0
+        - 1.0
+      * - LJ :math:`\epsilon` of OH (kcal/mole)
+        - 0.0836
+        - 0.0
+        - 0.0
+      * - LJ :math:`\sigma` of OH (:math:`\AA`)
+        - 1.7753
+        - 1.0
+        - 1.0
+      * - K of OH bond (kcal/mole/:math:`\AA^2`)
+        - 450
+        - 450
+        - 450
+      * - :math:`r_0` of OH bond (:math:`\AA`)
+        - 0.9572
+        - 0.9572
+        - 0.9572
+      * - K of HOH angle (kcal/mole)
+        - 55.0
+        - 55.0
+        - 55.0
+      * - :math:`\theta_0` of HOH angle
+        - 104.52\ :math:`^{\circ}`
+        - 104.52\ :math:`^{\circ}`
+        - 104.52\ :math:`^{\circ}`
+
+Below is the code for a LAMMPS input file and a molecule file
+(``tip3p.mol``) of TIP3P water for use with the :doc:`molecule command
+<molecule>` demonstrating how to set up a small bulk water system for
+TIP3P with rigid bonds.
+
+.. code-block:: LAMMPS
+
+    units real
+    atom_style full
+    region box block -5 5 -5 5 -5 5
+    create_box 2 box bond/types 1 angle/types 1 &
+                extra/bond/per/atom 2 extra/angle/per/atom 1 extra/special/per/atom 2
+
+    mass 1 15.9994
+    mass 2 1.008
+
+    pair_style lj/cut/coul/cut 8.0
+    pair_coeff 1 1 0.1521 3.1507
+    pair_coeff 2 2 0.0    1.0
+
+    bond_style zero
+    bond_coeff 1 0.9574
+
+    angle_style zero
+    angle_coeff 1 104.52
+
+    molecule water tip3p.mol
+    create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
+
+    fix rigid all shake 0.001 10 10000 b 1 a 1
+    minimize 0.0 0.0 1000 10000
+    run 0 post no
+
+    reset_timestep 0
+    velocity all create 300.0 5463576
+    fix integrate all nvt temp 300 300 1.0
+
+    thermo_style custom step temp press etotal pe
+
+    thermo 1000
+    run 20000
+    write_data tip3p.data nocoeff
+
+.. _tip3p_molecule:
+.. code-block::
+
+   # Water molecule. TIP3P geometry
+
+   3 atoms
+   2 bonds
+   1 angles
+
+   Coords
+
+   1    0.00000  -0.06556   0.00000
+   2    0.75695   0.52032   0.00000
+   3   -0.75695   0.52032   0.00000
+
+   Types
+
+   1        1   # O
+   2        2   # H
+   3        2   # H
+
+   Charges
+
+   1       -0.834
+   2        0.417
+   3        0.417
+
+   Bonds
+
+   1   1      1      2
+   2   1      1      3
+
+   Angles
+
+   1   1      2      1      3
+
+   Shake Flags
+
+   1 1
+   2 1
+   3 1
+
+   Shake Atoms
+
+   1 1 2 3
+   2 1 2 3
+   3 1 2 3
+
+   Shake Bond Types
+
+   1 1 1 1
+   2 1 1 1
+   3 1 1 1
+
+   Special Bond Counts
+
+   1 2 0 0
+   2 1 1 0
+   3 1 1 0
+
+   Special Bonds
+
+   1 2 3
+   2 1 3
+   3 1 2
 
-| O mass = 15.9994
-| H mass = 1.008
-| O charge = -0.830
-| H charge = 0.415
-| LJ :math:`\epsilon` of OO = 0.102
-| LJ :math:`\sigma` of OO = 3.188
-| LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
-| K of OH bond = 450
-| :math:`r_0` of OH bond = 0.9572
-| K of HOH angle = 55
-| :math:`\theta` of HOH angle = 104.52\ :math:`^{\circ}`
-|
 
 Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wiki/Water_model>`_.
 

doc/src/Howto_tip4p.rst

@@ -2,100 +2,138 @@ TIP4P water model
 =================
 
 The four-point TIP4P rigid water model extends the traditional
-three-point TIP3P model by adding an additional site, usually
-massless, where the charge associated with the oxygen atom is placed.
-This site M is located at a fixed distance away from the oxygen along
-the bisector of the HOH bond angle.  A bond style of *harmonic* and an
-angle style of *harmonic* or *charmm* should also be used.
+:doc:`three-point TIP3P <Howto_tip3p>` model by adding an additional
+site M, usually massless, where the charge associated with the oxygen
+atom is placed.  This site M is located at a fixed distance away from
+the oxygen along the bisector of the HOH bond angle.  A bond style of
+:doc:`harmonic <bond_harmonic>` and an angle style of :doc:`harmonic
+<angle_harmonic>` or :doc:`charmm <angle_charmm>` should also be used.
+In case of rigid bonds also bond style :doc:`zero <bond_zero>` and angle
+style :doc:`zero <angle_zero>` can be used.
 
-A TIP4P model is run with LAMMPS using either these commands
-for a cutoff model:
+There are two ways to implement TIP4P water in LAMMPS:
 
-* :doc:`pair_style tip4p/cut <pair_lj_cut_tip4p>`
-* :doc:`pair_style lj/cut/tip4p/cut <pair_lj_cut_tip4p>`
+#. Use a specially written pair style that uses the :ref:`TIP3P geometry
+   <tip3p_molecule>` without the point M. The point M location is then
+   implicitly derived from the other atoms or each water molecule and
+   used during the force computation.  The forces on M are then
+   projected on the oxygen and the two hydrogen atoms.  This is
+   computationally very efficient, but the charge distribution in space
+   is only correct within the tip4p labeled styles.  So all other
+   computations using charges will "see" the negative charge incorrectly
+   on the oxygen atom.
 
-or these commands for a long-range model:
+   This can be done with the following pair styles for Coulomb with a cutoff:
 
-* :doc:`pair_style tip4p/long <pair_coul>`
-* :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>`
-* :doc:`pair_style lj/long/tip4p/long <pair_lj_long>`
-* :doc:`pair_style tip4p/long/soft <pair_fep_soft>`
-* :doc:`pair_style lj/cut/tip4p/long/soft <pair_fep_soft>`
-* :doc:`kspace_style pppm/tip4p <kspace_style>`
-* :doc:`kspace_style pppm/disp/tip4p <kspace_style>`
+   * :doc:`pair_style tip4p/cut <pair_lj_cut_tip4p>`
+   * :doc:`pair_style lj/cut/tip4p/cut <pair_lj_cut_tip4p>`
 
-The bond lengths and bond angles should be held fixed using the
-:doc:`fix shake <fix_shake>` or :doc:`fix rattle <fix_shake>` command,
-unless a parameterization for a flexible TIP4P model is used.  The
-parameter sets listed below are all for rigid TIP4P model variants and
-thus the bond and angle force constants are not used and can be set to
-any legal value; only equilibrium length and angle are used.
+   or these commands for a long-range Coulomb treatment:
 
-These are the additional parameters (in real units) to set for O and H
-atoms and the water molecule to run a rigid TIP4P model with a cutoff
-:ref:`(Jorgensen) <Jorgensen5>`.  Note that the OM distance is specified in
-the :doc:`pair_style <pair_style>` command, not as part of the pair
-coefficients.
+   * :doc:`pair_style tip4p/long <pair_coul>`
+   * :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>`
+   * :doc:`pair_style lj/long/tip4p/long <pair_lj_long>`
+   * :doc:`pair_style tip4p/long/soft <pair_fep_soft>`
+   * :doc:`pair_style lj/cut/tip4p/long/soft <pair_fep_soft>`
+   * :doc:`kspace_style pppm/tip4p <kspace_style>`
+   * :doc:`kspace_style pppm/disp/tip4p <kspace_style>`
 
-| O mass = 15.9994
-| H mass = 1.008
-| O charge = -1.040
-| H charge = 0.520
-| :math:`r_0` of OH bond = 0.9572
-| :math:`\theta` of HOH angle = 104.52\ :math:`^{\circ}`
-| OM distance = 0.15
-| LJ :math:`\epsilon` of O-O = 0.1550
-| LJ :math:`\sigma` of O-O = 3.1536
-| LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
-| Coulomb cutoff = 8.5
-|
+   The bond lengths and bond angles should be held fixed using the
+   :doc:`fix shake <fix_shake>` or :doc:`fix rattle <fix_shake>` command,
+   unless a parameterization for a flexible TIP4P model is used.  The
+   parameter sets listed below are all for rigid TIP4P model variants and
+   thus the bond and angle force constants are not used and can be set to
+   any legal value; only equilibrium length and angle are used.
 
-For the TIP4/Ice model (J Chem Phys, 122, 234511 (2005);
-https://doi.org/10.1063/1.1931662) these values can be used:
+#. Use an :ref:`explicit 4 point TIP4P geometry <tip4p_molecule>` where
+   the oxygen atom carries no charge and the M point no Lennard-Jones
+   interactions.  Since :doc:`fix shake <fix_shake>` or :doc:`fix rattle
+   <fix_shake>` may not be applied to this kind of geometry, :doc:`fix
+   rigid or fix rigid/small <fix_rigid>` or its thermostatted variants
+   are required to maintain a rigid geometry.  This avoids some of the
+   issues with respect to analysis and non-tip4p styles, but it is a
+   more costly force computation (more atoms in the same volume and thus
+   more neighbors in the neighbor lists) and requires a much shorter
+   timestep for stable integration of the rigid body motion.  Since no
+   bonds or angles are required, they do not need to be defined and atom
+   style charge would be sufficient for a bulk TIP4P water system.  In
+   order to avoid that LAMMPS produces an error due to the massless M
+   site a tiny non-zero mass needs to be assigned.
 
-| O mass = 15.9994
-| H mass =  1.008
-| O charge = -1.1794
-| H charge =  0.5897
-| :math:`r_0` of OH bond = 0.9572
-| :math:`\theta` of HOH angle = 104.52\ :math:`^{\circ}`
-| OM distance = 0.1577
-| LJ :math:`\epsilon` of O-O = 0.21084
-| LJ :math:`\sigma` of O-O = 3.1668
-| LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
-| Coulomb cutoff = 8.5
-|
+The table below lists the force field parameters (in real :doc:`units
+<units>`) to for a selection of popular variants of the TIP4P model.
+There is the rigid TIP4P model with a cutoff :ref:`(Jorgensen)
+<Jorgensen5>`, the TIP4/Ice model :ref:`(Abascal1) <Abascal1>`, the
+TIP4P/2005 model :ref:`(Abascal2) <Abascal2>` and a version of TIP4P
+parameters adjusted for use with a long-range Coulombic solver
+(e.g. Ewald or PPPM in LAMMPS).  Note that for implicit TIP4P models the
+OM distance is specified in the :doc:`pair_style <pair_style>` command,
+not as part of the pair coefficients.
 
-For the TIP4P/2005 model (J Chem Phys, 123, 234505 (2005);
-https://doi.org/10.1063/1.2121687), these values can be used:
+   .. list-table::
+      :header-rows: 1
+      :widths: auto
 
-| O mass = 15.9994
-| H mass =  1.008
-| O charge = -1.1128
-| H charge = 0.5564
-| :math:`r_0` of OH bond = 0.9572
-| :math:`\theta` of HOH angle = 104.52\ :math:`^{\circ}`
-| OM distance = 0.1546
-| LJ :math:`\epsilon` of O-O = 0.1852
-| LJ :math:`\sigma` of O-O = 3.1589
-| LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
-| Coulomb cutoff = 8.5
-|
-
-These are the parameters to use for TIP4P with a long-range Coulombic
-solver (e.g. Ewald or PPPM in LAMMPS):
-
-| O mass = 15.9994
-| H mass = 1.008
-| O charge = -1.0484
-| H charge = 0.5242
-| :math:`r_0` of OH bond = 0.9572
-| :math:`\theta` of HOH angle = 104.52\ :math:`^{\circ}`
-| OM distance = 0.1250
-| LJ :math:`\epsilon` of O-O = 0.16275
-| LJ :math:`\sigma` of O-O = 3.16435
-| LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
-|
+      * - Parameter
+        - TIP4P (original)
+        - TIP4P/Ice
+        - TIP4P/2005
+        - TIP4P (Ewald)
+      * - O mass (amu)
+        - 15.9994
+        - 15.9994
+        - 15.9994
+        - 15.9994
+      * - H mass (amu)
+        - 1.008
+        - 1.008
+        - 1.008
+        - 1.008
+      * - O or M charge (:math:`e`)
+        - -1.040
+        - -1.1794
+        - -1.1128
+        - -1.04844
+      * - H charge (:math:`e`)
+        - 0.520
+        - 0.5897
+        - 0.5564
+        - 0.52422
+      * - LJ :math:`\epsilon` of OO (kcal/mole)
+        - 0.1550
+        - 0.1577
+        - 0.1852
+        - 0.16275
+      * - LJ :math:`\sigma` of OO (:math:`\AA`)
+        - 3.1536
+        - 3.1668
+        - 3.1589
+        - 3.16435
+      * - LJ :math:`\epsilon` of HH, MM, OH, OM, HM (kcal/mole)
+        - 0.0
+        - 0.0
+        - 0.0
+        - 0.0
+      * - LJ :math:`\sigma` of HH, MM, OH, OM, HM (:math:`\AA`)
+        - 1.0
+        - 1.0
+        - 1.0
+        - 1.0
+      * - :math:`r_0` of OH bond (:math:`\AA`)
+        - 0.9572
+        - 0.9572
+        - 0.9572
+        - 0.9572
+      * - :math:`\theta_0` of HOH angle
+        - 104.52\ :math:`^{\circ}`
+        - 104.52\ :math:`^{\circ}`
+        - 104.52\ :math:`^{\circ}`
+        - 104.52\ :math:`^{\circ}`
+      * - OM distance (:math:`\AA`)
+        - 0.15
+        - 0.1577
+        - 0.1546
+        - 0.1250
 
 Note that the when using the TIP4P pair style, the neighbor list cutoff
 for Coulomb interactions is effectively extended by a distance 2 \* (OM
@@ -108,6 +146,117 @@ trade-off for your model.  The OM distance and the LJ and Coulombic
 cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long
 <pair_lj_cut_tip4p>` command.
 
+Below is the code for a LAMMPS input file using the implicit method and
+the :ref:`TIP3P molecule file <tip3p_molecule>`.  Because the TIP4P
+charges are different from TIP3P they need to be reset (or the molecule
+file changed):
+
+.. code-block:: LAMMPS
+
+    units real
+    atom_style full
+    region box block -5 5 -5 5 -5 5
+    create_box 2 box bond/types 1 angle/types 1 &
+                extra/bond/per/atom 2 extra/angle/per/atom 1 extra/special/per/atom 2
+
+    mass 1 15.9994
+    mass 2 1.008
+
+    pair_style lj/cut/tip4p/cut 1 2 1 1 0.15 8.0
+    pair_coeff 1 1 0.1550 3.1536
+    pair_coeff 2 2 0.0    1.0
+
+    bond_style zero
+    bond_coeff 1 0.9574
+
+    angle_style zero
+    angle_coeff 1 104.52
+
+    molecule water tip3p.mol  # this uses the TIP3P geometry
+    create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
+    # must change charges for TIP4P
+    set type 1 charge -1.040
+    set type 2 charge  0.520
+
+    fix rigid all shake 0.001 10 10000 b 1 a 1
+    minimize 0.0 0.0 1000 10000
+    run 0 post no
+
+    reset_timestep 0
+    velocity all create 300.0 5463576
+    fix integrate all nvt temp 300 300 1.0
+
+    thermo_style custom step temp press etotal pe
+
+    thermo 1000
+    run 20000
+    write_data tip3p.data nocoeff
+
+Below is the code for a LAMMPS input file using the explicit method and
+a TIP4P molecule file.  Because of using :doc:`fix rigid/nvt/small
+<fix_rigid>` no bonds need to be defined and thus no extra storage needs
+to be reserved for them, but we need to switch to atom style full or use
+:doc:`fix property/atom mol <fix_property_atom>` so that fix
+rigid/nvt/small can identify rigid bodies by their molecule ID:
+
+.. code-block:: LAMMPS
+
+    units real
+    atom_style charge
+    region box block -5 5 -5 5 -5 5
+    create_box 3 box
+
+    mass 1 15.9994
+    mass 2 1.008
+    mass 3 1.0e-100
+
+    pair_style lj/cut/coul/cut 8.0
+    pair_coeff 1 1 0.1550 3.1536
+    pair_coeff 2 2 0.0    1.0
+    pair_coeff 3 3 0.0    1.0
+
+    fix mol all property/atom mol
+    molecule water tip4p.mol
+    create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
+
+    timestep 0.1
+    fix integrate all rigid/nvt/small molecule temp 300.0 300.0 1.0
+    velocity all create 300.0 5463576
+
+    thermo_style custom step temp press etotal density pe ke
+    thermo 1000
+    run 20000
+    write_data tip4p.data nocoeff
+
+.. _tip4p_molecule:
+.. code-block::
+
+   # Water molecule. Explicit TIP4P geometry for use with fix rigid
+
+   4 atoms
+
+   Coords
+
+   1    0.00000  -0.06556   0.00000
+   2    0.75695   0.52032   0.00000
+   3   -0.75695   0.52032   0.00000
+   4    0.00000   0.08444   0.00000
+
+   Types
+
+   1        1   # O
+   2        2   # H
+   3        2   # H
+   4        3   # M
+
+   Charges
+
+   1        0.000
+   2        0.520
+   3        0.520
+   4       -1.040
+
+
 Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wiki/Water_model>`_.
 
 ----------
@@ -116,3 +265,13 @@ Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wik
 
 **(Jorgensen)** Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem
 Phys, 79, 926 (1983).
+
+.. _Abascal1:
+
+**(Abascal1)** Abascal, Sanz, Fernandez, Vega, J Chem Phys, 122, 234511 (2005)
+   https://doi.org/10.1063/1.1931662
+
+.. _Abascal2:
+
+**(Abascal2)** Abascal, J Chem Phys, 123, 234505 (2005)
+   https://doi.org/10.1063/1.2121687

doc/src/Howto_tip5p.rst

@@ -0,0 +1,161 @@
+TIP5P water model
+=================
+
+The five-point TIP5P rigid water model extends the :doc:`three-point
+TIP3P model <Howto_tip3p>` by adding two additional sites L, usually
+massless, where the charge associated with the oxygen atom is placed.
+These sites L are located at a fixed distance away from the oxygen atom,
+forming a tetrahedral angle that is rotated by 90 degrees from the HOH
+plane.  Those sites thus somewhat approximate lone pairs of the oxygen
+and consequently improve the water structure to become even more
+"tetrahedral" in comparison to the :doc:`four-point TIP4P model
+<Howto_tip4p>`.
+
+A suitable pair style with cutoff Coulomb would be:
+
+* :doc:`pair_style lj/cut/coul/cut <pair_lj_cut_coul>`
+
+or these commands for a long-range model:
+
+* :doc:`pair_style lj/cut/coul/long <pair_lj_cut_coul>`
+* :doc:`pair_style lj/cut/coul/long/soft <pair_fep_soft>`
+* :doc:`kspace_style pppm <kspace_style>`
+* :doc:`kspace_style pppm/disp <kspace_style>`
+
+A TIP5P model *must* be run using a :doc:`rigid fix <fix_rigid>` since
+there is no other option to keep this kind of structure rigid in LAMMPS.
+In order to avoid that LAMMPS produces an error due to the massless L
+sites, those need to be assigned a tiny non-zero mass.
+
+The table below lists the force field parameters (in real :doc:`units
+<units>`) to for a the TIP5P model with a cutoff :ref:`(Mahoney)
+<Mahoney>` and the TIP5P-E model :ref:`(Rick) <Rick>` for use with a
+long-range Coulombic solver (e.g. Ewald or PPPM in LAMMPS).
+
+   .. list-table::
+      :header-rows: 1
+      :widths: auto
+
+      * - Parameter
+        - TIP5P
+        - TIP5P-E
+      * - O mass (amu)
+        - 15.9994
+        - 15.9994
+      * - H mass (amu)
+        - 1.008
+        - 1.008
+      * - O charge (:math:`e`)
+        - 0.0
+        - 0.0
+      * - L charge (:math:`e`)
+        - -0.241
+        - -0.241
+      * - H charge (:math:`e`)
+        - 0.241
+        - 0.241
+      * - LJ :math:`\epsilon` of OO (kcal/mole)
+        - 0.1600
+        - 0.1780
+      * - LJ :math:`\sigma` of OO (:math:`\AA`)
+        - 3.1200
+        - 3.0970
+      * - LJ :math:`\epsilon` of HH, LL, OH, OL, HL (kcal/mole)
+        - 0.0
+        - 0.0
+      * - LJ :math:`\sigma` of HH, LL, OH, OL, HL (:math:`\AA`)
+        - 1.0
+        - 1.0
+      * - :math:`r_0` of OH bond (:math:`\AA`)
+        - 0.9572
+        - 0.9572
+      * - :math:`\theta_0` of HOH angle
+        - 104.52\ :math:`^{\circ}`
+        - 104.52\ :math:`^{\circ}`
+      * - OL distance (:math:`\AA`)
+        - 0.70
+        - 0.70
+      * - :math:`\theta_0` of LOL angle
+        - 109.47\ :math:`^{\circ}`
+        - 109.47\ :math:`^{\circ}`
+
+Below is the code for a LAMMPS input file for setting up a simulation of
+TIP5P water with a molecule file.  Because of using :doc:`fix
+rigid/nvt/small <fix_rigid>` no bonds need to be defined and thus no
+extra storage needs to be reserved for them, but we need to switch to
+atom style full or use :doc:`fix property/atom mol <fix_property_atom>`
+so that fix rigid/nvt/small can identify rigid bodies by their molecule
+ID:
+
+.. code-block:: LAMMPS
+
+    units real
+    atom_style charge
+    region box block -5 5 -5 5 -5 5
+    create_box 3 box
+
+    mass 1 15.9994
+    mass 2 1.008
+    mass 3 1.0e-100
+
+    pair_style lj/cut/coul/cut 8.0
+    pair_coeff 1 1 0.160  3.12
+    pair_coeff 2 2 0.0    1.0
+    pair_coeff 3 3 0.0    1.0
+
+    fix mol all property/atom mol
+    molecule water tip5p.mol
+    create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
+
+    timestep 0.20
+    fix integrate all rigid/nvt/small molecule temp 300.0 300.0 1.0
+    reset_timestep 0
+    velocity all create 300.0 5463576
+
+    thermo_style custom step temp press etotal density pe ke
+    thermo 1000
+    run 20000
+    write_data tip5p.data nocoeff
+
+.. _tip5p_molecule:
+.. code-block::
+
+   # Water molecule. Explicit TIP5P geometry for use with fix rigid
+
+   5 atoms
+
+   Coords
+
+   1    0.00000  -0.06556   0.00000
+   2    0.75695   0.52032   0.00000
+   3   -0.75695   0.52032   0.00000
+   4    0.00000  -0.46971   0.57154
+   5    0.00000  -0.46971  -0.57154
+
+   Types
+
+   1        1   # O
+   2        2   # H
+   3        2   # H
+   4        3   # L
+   5        3   # L
+
+   Charges
+
+   1        0.000
+   2        0.241
+   3        0.241
+   4       -0.241
+   5       -0.241
+
+Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wiki/Water_model>`_.
+
+----------
+
+.. _Mahoney:
+
+**(Mahoney)** Mahoney, Jorgensen, J Chem Phys 112, 8910 (2000)
+
+.. _Rick:
+
+**(Rick)** Rick, J Chem Phys 120, 6085 (2004)

doc/src/Howto_wsl.rst

@@ -11,12 +11,14 @@ LAMMPS in workshop settings, we had to redirect Windows users to
 Linux Virtual Machines such as VirtualBox or Unix-like compilation with
 Cygwin.
 
-With the latest updates in Windows 10 (Version 2004, Build 19041 or higher),
-Microsoft has added a new way to work on Linux-based code. The Windows
-Subsystem for Linux (WSL). With WSL Version 2, you now get a Linux Virtual
-Machine that transparently integrates into Windows. All you need is to ensure
-you have the latest Windows updates installed and enable this new feature.
-Linux VMs are then easily installed using the Microsoft Store.
+With the latest updates in Windows 10 (Version 2004, Build 19041 or
+higher), Microsoft has added a new way to work on Linux-based code. The
+`Windows Subsystem for Linux (WSL)
+<https://learn.microsoft.com/en-us/windows/wsl/>`_.  With WSL Version 2,
+you now get a Linux Virtual Machine that transparently integrates into
+Windows.  All you need is to ensure you have the latest Windows updates
+installed and enable this new feature.  Linux VMs are then easily
+installed using the Microsoft Store.
 
 In this tutorial, I'll show you how to set up and compile LAMMPS for both serial
 and MPI usage in WSL2.

doc/src/Install_git.rst

@@ -26,15 +26,18 @@ provides `limited support for subversion clients <svn_>`_.
 .. _git: https://git-scm.com
 .. _svn: https://help.github.com/en/github/importing-your-projects-to-github/working-with-subversion-on-github
 
-You can follow the LAMMPS development on 3 different git branches:
+You can follow the LAMMPS development on 4 different git branches:
 
-* **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 or feature release;
   updates are always "fast-forward" merges from *develop*
 * **develop**  :  this branch follows the ongoing development and
   is updated with every merge commit of a pull request
+* **stable**   :  this branch is updated from the *release* branch with
+  every stable release version and also has selected bug fixes with every
+  update release when the *maintenance* branch is merged into it
+* **maintenance**  :  this branch collects back-ported bug fixes from the
+  *develop* branch to the *stable* branch. It is used to update *stable*
+  for update releases and it synchronized with *stable* at each stable release.
 
 To access the git repositories on your box, use the clone command to
 create a local copy of the LAMMPS repository with a command like:
@@ -60,17 +63,17 @@ between them at any time using "git checkout <branch name>".)
    *--depth* git command line flag.  That will create a "shallow clone"
    of the repository, which 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.  If you later need more of the git history, you can always
-   convert the shallow clone into a "full clone".
+   commits of the *develop*, the *release*, and the *maintenance*
+   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
-the HTML documentation files are not included.  They can be fetched
-from the LAMMPS website by typing ``make fetch`` in the doc directory.
-Or they can be generated from the content provided in ``doc/src`` by
-typing ``make html`` from the ``doc`` directory.
+the HTML documentation files are not included. They can be generated
+from the content provided in ``doc/src`` by typing ``make html`` from
+the ``doc`` directory.
 
 After initial cloning, as bug fixes and new features are added to
 LAMMPS you can stay up-to-date by typing the following git commands
@@ -79,8 +82,9 @@ from within the "mylammps" directory:
 .. code-block:: bash
 
    git checkout release      # not needed if you always stay in this branch
-   git checkout stable       # use one of these 3 checkout commands
+   git checkout stable       # use one of these 4 checkout commands
    git checkout develop      # to choose the branch to follow
+   git checkout maintenance
    git pull
 
 Doing a "pull" will not change any files you have added to the LAMMPS
@@ -145,7 +149,7 @@ changed.  How to do this depends on the build system you are using.
       to enforce consistency of the source between the src folder
       and package directories.  This is OK to do even if you don't
       use any packages. The ``make purge`` command removes any deprecated
-      src files if they were removed by the patch from a package
+      src files if they were removed by the update from a package
       subdirectory.
 
       .. warning::
@@ -159,10 +163,10 @@ 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 "https://" access protocol for
+   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".
+   ``git@github.com:lammps/lammps.git``.
 
 The LAMMPS GitHub project is currently overseen by Axel Kohlmeyer
 (Temple U, akohlmey at gmail.com).

doc/src/Install_linux.rst

@@ -3,6 +3,7 @@ Download an executable for Linux
 
 Binaries are available for different versions of Linux:
 
+- :ref:`Pre-built static Linux x86_64 executables <static>`
 - :ref:`Pre-built Ubuntu and Debian Linux executables <ubuntu>`
 - :ref:`Pre-built Fedora Linux executables <fedora>`
 - :ref:`Pre-built EPEL Linux executables (RHEL, CentOS) <epel>`
@@ -21,6 +22,33 @@ Binaries are available for different versions of Linux:
 
 ----------
 
+.. _static:
+
+Pre-built static Linux x86_64 executables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pre-built LAMMPS executables for Linux, that are statically linked and
+compiled for 64-bit x86 CPUs (x86_64 or AMD64) are available for download
+at `https://download.lammps.org/static/ <https://download.lammps.org/static/>`_.
+Because of that static linkage (and unlike the Linux distribution specific
+packages listed below), they do not depend on any installed software and
+thus should run on *any* 64-bit x86 machine with *any* Linux version.
+
+These executable include most of the available packages and multi-thread
+parallelization (via INTEL, KOKKOS, or OPENMP package).  They are **not**
+compatible with MPI.  Several of the LAMMPS tools executables (e.g. ``msi2lmp``)
+and the ``lammps-shell`` program are included as well.  Because of the
+static linkage, there is no ``liblammps.so`` library file and thus also the
+LAMMPS python module, which depends on it, is not included.
+
+The compressed tar archives available for download have names following
+the pattern ``lammps-linux-x86_64-<version>.tar.gz`` and will all unpack
+into a ``lammps-static`` folder.  The executables are then in the
+``lammps-static/bin/`` folder.  Since they do not depend on any other
+software, they may be freely moved or copied around.
+
+----------
+
 .. _ubuntu:
 
 Pre-built Ubuntu and Debian Linux executables
@@ -144,7 +172,7 @@ Pre-built EPEL Linux executable
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Pre-built LAMMPS (and KIM) packages for stable releases are available
-in the `Extra Packages for Enterprise Linux (EPEL) repository <https://fedoraproject.org/wiki/EPEL>`_
+in the `Extra Packages for Enterprise Linux (EPEL) repository <https://docs.fedoraproject.org/en-US/epel/>`_
 for use with Red Hat Enterprise Linux (RHEL) or CentOS version 7.x
 and compatible Linux distributions. Names of packages, executable,
 and content are the same as described above for Fedora Linux.
@@ -232,7 +260,7 @@ There are three scripts available, named `lammps
 <https://aur.archlinux.org/packages/lammps>`_, `lammps-beta
 <https://aur.archlinux.org/packages/lammps>`_ and `lammps-git
 <https://aur.archlinux.org/packages/lammps>`_.  They respectively
-package the stable, patch and git releases.
+package the stable, feature, and git releases.
 
 To install, you will need to have the git package installed. You may use
 any of the above names in-place of lammps.

doc/src/Install_tarball.rst

@@ -10,15 +10,15 @@ of the `LAMMPS website <lws_>`_.
 .. _lws: https://www.lammps.org
 
 You have two choices of tarballs, either the most recent stable release
-or the most current patch or feature release.  Stable releases occur a
-few times per year, and undergo more testing before release.  Feature
-releases occur every 4 to 8 weeks.  The new contents in all feature
-releases are listed on the `bug and feature page <bug_>`_ of the LAMMPS
-homepage.
+or the most recent feature release.  Stable releases occur a few times
+per year, and undergo more testing before release.  Also, between stable
+releases bug fixes from the feature releases are back-ported and the
+tarball occasionally updated.  Feature releases occur every 4 to 8
+weeks.  The new contents in all feature releases are listed on the `bug
+and feature page <bug_>`_ of the LAMMPS homepage.
 
 Both tarballs include LAMMPS documentation (HTML and PDF files)
-corresponding to that version.  The download page also has an option
-to download the current-version LAMMPS documentation by itself.
+corresponding to that version.
 
 Tarballs of older LAMMPS versions can also be downloaded from `this page
 <older_>`_.
@@ -44,7 +44,8 @@ with the following command, to create a lammps-<version> directory:
 
    unzip lammps*.zip
 
-This version corresponds to the selected LAMMPS patch or stable release.
+This version corresponds to the selected LAMMPS feature or stable
+release.
 
 .. _git: https://github.com/lammps/lammps/releases
 

doc/src/Install_windows.rst

@@ -17,11 +17,12 @@ install the Windows MPI package (MPICH2 from Argonne National Labs),
 needed to run in parallel with MPI.
 
 The LAMMPS binaries contain *all* :doc:`optional packages <Packages>`
-included in the source distribution except: KIM, KOKKOS, MSCG, PYTHON,
-ADIOS, H5MD, NETCDF, QMMM, ML-QUIP, and VTK.
-The serial version also does not include the MPIIO and
-LATBOLTZ packages.  The GPU package is compiled for OpenCL with
-mixed precision kernels.
+included in the source distribution except: ADIOS, H5MD, KIM, ML-PACE,
+ML-QUIP, MSCG, NETCDF, PLUMED, QMMM, SCAFACOS, and VTK.  The serial
+version also does not include the MPIIO and LATBOLTZ packages.  The
+PYTHON package is only available in the Python installers that bundle a
+Python runtime.  The GPU package is compiled for OpenCL with mixed
+precision kernels.
 
 The LAMMPS library is compiled as a shared library and the
 :doc:`LAMMPS Python module <Python_module>` is installed, so that

doc/src/Intro_citing.rst

@@ -46,7 +46,7 @@ In addition there are DOIs generated for individual stable releases:
 
 - 3 March 2020 version: `DOI:10.5281/zenodo.3726417 <https://dx.doi.org/10.5281/zenodo.3726417>`_
 - 29 October 2020 version: `DOI:10.5281/zenodo.4157471 <https://dx.doi.org/10.5281/zenodo.4157471>`_
-- 29 September 2021 version: `DOI:10.5281/zenodo.6386596 <https//dx.doi.org/10.5281/zenodo.6386596>`_
+- 29 September 2021 version: `DOI:10.5281/zenodo.6386596 <https://dx.doi.org/10.5281/zenodo.6386596>`_
 
 Home page
 ^^^^^^^^^

doc/src/Intro_features.rst

@@ -195,7 +195,7 @@ Multi-replica models
 * :doc:`parallel replica dynamics <prd>`
 * :doc:`temperature accelerated dynamics <tad>`
 * :doc:`parallel tempering <temper>`
-* path-integral MD: `first variant <fix_pimd>`, `second variant <fix_ipi>`
+* path-integral MD: :doc:`first variant <fix_pimd>`, :doc:`second variant <fix_ipi>`
 * multi-walker collective variables with :doc:`Colvars <fix_colvars>` and :doc:`Plumed <fix_plumed>`
 
 .. _prepost:

doc/src/Intro_nonfeatures.rst

@@ -34,7 +34,7 @@ Here are suggestions on how to perform these tasks:
   a true molecular builder that will generate complex molecular models.
   See the :doc:`Tools <Tools>` page for details on tools packaged with
   LAMMPS.  The `Pre-/post-processing page
-  <https:/www.lammps.org/prepost.html>`_ of the LAMMPS homepage
+  <https://www.lammps.org/prepost.html>`_ of the LAMMPS homepage
   describes a variety of third party tools for this task.  Furthermore,
   some internal LAMMPS commands allow reconstructing, or selectively adding
   topology information, as well as provide the option to insert molecule
@@ -66,10 +66,9 @@ Here are suggestions on how to perform these tasks:
   these various options.
 * **Visualization:** LAMMPS can produce NETPBM, JPG, or PNG format
   snapshot images on-the-fly via its :doc:`dump image <dump_image>`
-  command and pass them to an external program, `FFmpeg
-  <https://www.ffmpeg.org>`_, to generate movies from them.  For
-  high-quality, interactive visualization, there are many excellent and
-  free tools available.  See the `Visualization Tools
+  command and pass them to an external program, `FFmpeg  <https://ffmpeg.org/>`_,
+  to generate movies from them.  For high-quality, interactive visualization,
+  there are many excellent and free tools available.  See the `Visualization Tools
   <https://www.lammps.org/viz.html>`_ page of the LAMMPS website for
   visualization packages that can process LAMMPS output data.
 * **Plotting:** See the next bullet about Pizza.py as well as the

doc/src/Manual_version.rst

@@ -12,13 +12,12 @@ into pull requests.  Pull requests will be merged into the *develop*
 branch of the git repository after they pass automated testing and code
 review by the LAMMPS developers.  When a sufficient number of changes
 have accumulated *and* the *develop* branch version passes an extended
-set of automated tests, we release it as a *feature release* (or patch
-release), which are currently made every 4 to 8 weeks.  The *release*
-branch of the git repository is updated with every such release.  A
-summary of the most important changes of the patch releases are on `this
-website page <https://www.lammps.org/bug.html>`_.  More detailed release
-notes are `available on GitHub
-<https://github.com/lammps/lammps/releases/>`_.
+set of automated tests, we release it as a *feature release*, which are
+currently made every 4 to 8 weeks.  The *release* branch of the git
+repository is updated with every such release.  A summary of the most
+important changes of the patch releases are on `this website page
+<https://www.lammps.org/bug.html>`_.  More detailed release notes are
+`available on GitHub <https://github.com/lammps/lammps/releases/>`_.
 
 Once or twice a year, we have a "stabilization period" where we apply
 only bug fixes and small, non-intrusive changes to the *develop*
@@ -28,13 +27,14 @@ several variants of static code analysis are run to improve the overall
 code quality, consistency, and compliance with programming standards,
 best practices and style conventions.
 
-The latest 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 updates to the stable release
-containing only bug fixes and updates back-ported from the *develop*
-branch and update the *stable* branch accordingly.
+The release after such a stabilization period is called a *stable*
+version and both, the *release* and the *stable* branches are updated
+with it.  Between stable releases, we collect back-ported bug fixes and
+updates from the *develop* branch in the *maintenance* branch.  From the
+*maintenance* branch we make occasional update releases and update the
+*stable* branch accordingly.
 
-Each version of LAMMPS contains all the documented features up to and
+Each version of LAMMPS contains all the documented *features* up to and
 including its version date.  For recently added features, we add markers
 to the documentation at which specific LAMMPS version a feature or
 keyword was added or significantly changed.
@@ -45,7 +45,7 @@ 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 of the online version of the LAMMPS
-  manual, they will by default describe the most current patch release
+  manual, they will by default describe the most current feature 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 documentation corresponding to the state of

doc/src/Modify.rst

@@ -34,5 +34,6 @@ style requirements and recommendations <Modify_style>`.
    Modify_min
    Modify_region
    Modify_body
+   Modify_gran_sub_mod
    Modify_thermo
    Modify_variable

doc/src/Modify_contribute.rst

@@ -80,8 +80,8 @@ integrated via pull requests on GitHub and cannot be merged without
 passing the automated testing and an approving review by a LAMMPS core
 developer.  Thus before submitting your contribution, you should first
 make certain, that your added or modified code compiles and works
-correctly with the latest patch-level or development version of LAMMPS
-and contains all bug fixes from it.
+correctly with the latest development version of LAMMPS and contains all
+bug fixes from it.
 
 Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial
 <Howto_github>` page for instructions on how to submit your changes or

doc/src/Modify_gran_sub_mod.rst

@@ -0,0 +1,177 @@
+Granular Sub-Model styles
+===============================
+
+In granular models, particles are spheres with a finite radius and rotational
+degrees of freedom as further described in the
+:doc:`Howto granular page <Howto_granular>`. Interactions between pair of
+particles or particles and walls may therefore depend on many different modes
+of motion as described in :doc:`pair granular <pair_granular>` and
+:doc:`fix wall/gran <fix_wall_gran>`. In both cases, the exchange of forces,
+torques, and heat flow between two types of bodies is defined using a
+GranularModel class. The GranularModel class organizes the details of an
+interaction using a series of granular sub-models each of which describe a
+particular interaction mode (e.g. normal forces or rolling friction). From a
+parent GranSubMod class, several types of sub-model classes are derived:
+
+* GranSubModNormal: normal force sub-model
+* GranSubModDamping: normal damping sub-model
+* GranSubModTangential: tangential forces and sliding friction sub-model
+* GranSubModRolling: rolling friction sub-model
+* GranSubModTwisting: twisting friction sub-model
+* GranSubModHeat: heat conduction sub-model
+
+For each type of sub-model, more classes are further derived, each describing a
+specific implementation. For instance, from the GranSubModNormal class the
+GranSubModNormalHooke, GranSubModNormalHertz, and GranSubModNormalJKR classes
+are derived which calculate Hookean, Hertzian, or JKR normal forces,
+respectively.  This modular structure simplifies the addition of new granular
+contact models as one only needs to create a new GranSubMod class without
+having to modify the more complex PairGranular, FixGranWall, and GranularModel
+classes. Most GranSubMod methods are also already defined by the parent classes
+so new contact models typically only require edits to a few relevant methods
+(e.g. methods that define coefficients and calculate forces).
+
+Each GranSubMod class has a pointer to both the LAMMPS class and the GranularModel
+class which owns it, ``lmp`` and ``gm``, respectively. The GranularModel class
+includes several public variables that describe the geometry/dynamics of the
+contact such as
+
+.. list-table::
+
+   * - ``xi`` and ``xj``
+     - Positions of the two contacting bodies
+   * - ``vi`` and ``vj``
+     - Velocities of the two contacting bodies
+   * - ``omegai`` and ``omegaj``
+     - Angular velocities of the two contacting bodies
+   * - ``dx`` and ``nx``
+     - The displacement and normalized displacement vectors
+   * - ``r``, ``rsq``, and ``rinv``
+     - The distance, distance squared, and inverse distance
+   * - ``radsum``
+     - The sum of particle radii
+   * - ``vr``, ``vn``, and ``vt``
+     - The relative velocity vector and its normal and tangential components
+   * - ``wr``
+     - The relative rotational velocity
+
+These quantities, among others, are calculated in the ``GranularModel->check_contact()``
+and ``GranularModel->calculate_forces()`` methods which can be referred to for more
+details.
+
+To create a new GranSubMod class, it is recommended that one first looks at similar
+GranSubMod classes. All GranSubMod classes share several general methods which may
+need to be defined
+
+.. list-table::
+
+   * - ``GranSubMod->mix_coeff()``
+     - Optional method to define how coefficients are mixed for different atom types. By default, coefficients are mixed using a geometric mean.
+   * - ``GranSubMod->coeffs_to_local()``
+     - Parses coefficients to define local variables. Run once at model construction.
+   * - ``GranSubMod->init()``
+     - Optional method to define local variables after other GranSubMod types were created. For instance, this method may be used by a tangential model that derives parameters from the normal model.
+
+There are also several type-specific methods
+
+.. list-table::
+
+   * - ``GranSubModNormal->touch()``
+     - Optional method to test when particles are in contact. By default, this is when particles overlap.
+   * - ``GranSubModNormal->pulloff_distance()``
+     - Optional method to return the distance at which particles stop interacting. By default, this is when particles no longer overlap.
+   * - ``GranSubModNormal->calculate_area()``
+     - Optional method to return the surface area of the contact. By default, this returns the geometric cross section.
+   * - ``GranSubModNormal->set_fncrit()``
+     - Optional method that defines the critical force to break the contact used by some tangential, rolling, and twisting sub-models. By default, this is the current total normal force including damping.
+   * - ``GranSubModNormal->calculate_forces()``
+     - Required method that returns the normal contact force
+   * - ``GranSubModDamping->calculate_forces()``
+     - Required method that returns the normal damping force
+   * - ``GranSubModTangential->calculate_forces()``
+     - Required method that calculates tangential forces/torques
+   * - ``GranSubModTwisting->calculate_forces()``
+     - Required method that calculates twisting friction forces/torques
+   * - ``GranSubModRolling->calculate_forces()``
+     - Required method that calculates rolling friction forces/torques
+   * - ``GranSubModHeat->calculate_heat()``
+     - Required method that returns the rate of heat flow
+
+As an example, say one wanted to create a new normal force option that consisted
+of a Hookean force with a piecewise stiffness. This could be done by adding a new
+set of files ``gran_sub_mod_custom.h``:
+
+.. code-block:: c++
+
+   #ifdef GranSubMod_CLASS
+   // clang-format off
+   GranSubModStyle(hooke/piecewise,
+            GranSubModNormalHookePiecewise,
+            NORMAL);
+   // clang-format on
+   #else
+
+   #ifndef GRAN_SUB_MOD_CUSTOM_H_
+   #define GRAN_SUB_MOD_CUSTOM_H_
+
+   #include "gran_sub_mod.h"
+   #include "gran_sub_mod_normal.h"
+
+   namespace LAMMPS_NS {
+   namespace Granular_NS {
+
+   class GranSubModNormalHookePiecewise : public GranSubModNormal {
+    public:
+     GranSubModNormalHookePiecewise(class GranularModel *, class LAMMPS *);
+     void coeffs_to_local() override;
+     double calculate_forces();
+    protected:
+     double k1, k2, delta_switch;
+   };
+
+   }    // namespace Granular_NS
+   }    // namespace LAMMPS_NS
+
+   #endif /*GRAN_SUB_MOD_CUSTOM_H_ */
+   #endif /*GRAN_SUB_MOD_CLASS_H_ */
+
+
+and ``gran_sub_mod_custom.cpp``
+
+.. code-block:: c++
+
+   #include "gran_sub_mod_custom.h"
+   #include "gran_sub_mod_normal.h"
+   #include "granular_model.h"
+
+   using namespace LAMMPS_NS;
+   using namespace Granular_NS;
+
+   GranSubModNormalHookePiecewise::GranSubModNormalHookePiecewise(GranularModel *gm, LAMMPS *lmp) :  GranSubModNormal(gm, lmp)
+   {
+     num_coeffs = 4;
+   }
+
+   /* ---------------------------------------------------------------------- */
+
+   void GranSubModNormalHookePiecewise::coeffs_to_local()
+   {
+     k1 = coeffs[0];
+     k2 = coeffs[1];
+     damp = coeffs[2];
+     delta_switch = coeffs[3];
+   }
+
+   /* ---------------------------------------------------------------------- */
+
+   double GranSubModNormalHookePiecewise::calculate_forces()
+   {
+     double Fne;
+     if (gm->delta >= delta_switch) {
+       Fne = k1 * delta_switch + k2 * (gm->delta - delta_switch);
+     } else {
+       Fne = k1 * gm->delta;
+     }
+     return Fne;
+   }
+

doc/src/Modify_pair.rst

@@ -2,11 +2,11 @@ Pair styles
 ===========
 
 Classes that compute pairwise non-bonded interactions are derived from
-the Pair class.  In LAMMPS, pairwise calculation include many-body
-potentials such as EAM, Tersoff, or ReaxFF where particles interact
-without an explicit bond topology but include interactions beyond
-pairwise non-bonded contributions.  New styles can be created to add
-support for additional pair potentials to LAMMPS.  When the
+the ``Pair`` class.  In LAMMPS, pairwise force calculations include
+many-body potentials such as EAM, Tersoff, or ReaxFF where particles
+interact without an explicit bond topology but include interactions
+beyond pairwise non-bonded contributions.  New styles can be created to
+add support for additional pair potentials to LAMMPS.  When the
 modifications are small, sometimes it is more effective to derive from
 an existing pair style class.  This latter approach is also used by
 :doc:`Accelerator packages <Speed_packages>` where the accelerated style
@@ -15,10 +15,13 @@ names differ from their base classes by an appended suffix.
 The file ``src/pair_lj_cut.cpp`` is an example of a Pair class with a
 very simple potential function.  It includes several optional methods to
 enable its use with :doc:`run_style respa <run_style>` and :doc:`compute
-group/group <compute_group_group>`.
+group/group <compute_group_group>`.  :doc:`Developer_write_pair` contains
+a detailed discussion of writing new pair styles from scratch, and how
+simple and more complex pair styles can be implemented with examples
+from existing pair styles.
 
 Here is a brief list of some the class methods in the Pair class that
-*must* be or *may* be overridden in a derived class.
+*must* be or *may* be overridden in a derived class for a new pair style.
 
 +---------------------------------+---------------------------------------------------------------------+
 | Required                        | "pure" methods that *must* be overridden in a derived class         |

doc/src/Packages_details.rst

@@ -228,8 +228,9 @@ conversion of atomic information to continuum fields.
 
 **Install:**
 
-This package has :ref:`specific installation instructions <atc>` on the :doc:`Build extras <Build_extras>` page.
-The ATC package requires that also the `MANYBODY <PKG-MANYBODY>`_ package is installed.
+This package has :ref:`specific installation instructions <atc>` on the
+:doc:`Build extras <Build_extras>` page.  The ATC package requires that
+also the :ref:`MANYBODY <PKG-MANYBODY>` package is installed.
 
 **Supporting info:**
 
@@ -391,8 +392,8 @@ rigid-body integrators with improved stability.
 
 **Install:**
 
-The CG-DNA package requires that also the `MOLECULE <PKG-MOLECULE>`_ and
-`ASPHERE <PKG-ASPHERE>`_ packages are installed.
+The CG-DNA package requires that also the :ref:`MOLECULE <PKG-MOLECULE>`
+and :ref:`ASPHERE <PKG-ASPHERE>` packages are installed.
 
 **Supporting info:**
 
@@ -1114,15 +1115,15 @@ INTEL package
 
 **Contents:**
 
-Dozens of pair, fix, bond, angle, dihedral, improper, and kspace
-styles which are optimized for Intel CPUs and KNLs (Knights Landing).
-All of them have an "intel" in their style name.  The
-:doc:`INTEL package <Speed_intel>` page gives details of what hardware and
-compilers are required on your system, and how to build and use this
-package.  Its styles can be invoked at run time via the "-sf intel" or
-"-suffix intel" :doc:`command-line switches <Run_options>`.  Also see
-the :ref:`KOKKOS <PKG-KOKKOS>`, :ref:`OPT <PKG-OPT>`, and :ref:`OPENMP <PKG-OPENMP>` packages,
-which have styles optimized for CPUs and KNLs.
+Dozens of pair, fix, bond, angle, dihedral, improper, and kspace styles
+which are optimized for Intel CPUs and KNLs (Knights Landing).  All of
+them have an "intel" in their style name.  The :doc:`INTEL package
+<Speed_intel>` page gives details of what hardware and compilers are
+required on your system, and how to build and use this package.  Its
+styles can be invoked at run time via the "-sf intel" or "-suffix intel"
+:doc:`command-line switches <Run_options>`.  Also see the :ref:`KOKKOS
+<PKG-KOKKOS>`, :ref:`OPT <PKG-OPT>`, and :ref:`OPENMP <PKG-OPENMP>`
+packages, which have styles optimized for CPUs and KNLs.
 
 You need to have an Intel compiler, version 14 or higher to take full
 advantage of this package. While compilation with GNU compilers is
@@ -1249,12 +1250,13 @@ Dozens of atom, pair, bond, angle, dihedral, improper, fix, compute
 styles adapted to compile using the Kokkos library which can convert
 them to OpenMP or CUDA code so that they run efficiently on multicore
 CPUs, KNLs, or GPUs.  All the styles have a "kk" as a suffix in their
-style name.  The :doc:`KOKKOS package <Speed_kokkos>` page gives
-details of what hardware and software is required on your system, and
-how to build and use this package.  Its styles can be invoked at run
-time via the "-sf kk" or "-suffix kk" :doc:`command-line switches <Run_options>`.  Also see the :ref:`GPU <PKG-GPU>`, :ref:`OPT <PKG-OPT>`,
-:ref:`INTEL <PKG-INTEL>`, and :ref:`OPENMP <PKG-OPENMP>` packages, which
-have styles optimized for CPUs, KNLs, and GPUs.
+style name.  The :doc:`KOKKOS package <Speed_kokkos>` page gives details
+of what hardware and software is required on your system, and how to
+build and use this package.  Its styles can be invoked at run time via
+the "-sf kk" or "-suffix kk" :doc:`command-line switches <Run_options>`.
+Also see the :ref:`GPU <PKG-GPU>`, :ref:`OPT <PKG-OPT>`, :ref:`INTEL
+<PKG-INTEL>`, and :ref:`OPENMP <PKG-OPENMP>` packages, which have styles
+optimized for CPUs, KNLs, and GPUs.
 
 You must have a C++14 compatible compiler to use this package.
 KOKKOS makes extensive use of advanced C++ features, which can
@@ -2328,7 +2330,7 @@ and third order tensor from finite differences.
 
 **Install:**
 
-The PHONON package requires that also the `KSPACE <PKG-KSPACE>`_
+The PHONON package requires that also the :ref:`KSPACE <PKG-KSPACE>`
 package is installed.
 
 
@@ -2929,11 +2931,9 @@ VORONOI package
 **Contents:**
 
 A compute command which calculates the Voronoi tesselation of a
-collection of atoms by wrapping the `Voro++ library <voro-home_>`_.  This
-can be used to calculate the local volume or each atoms or its near
-neighbors.
-
-.. _voro-home: https://math.lbl.gov/voro++
+collection of atoms by wrapping the `Voro++ library
+<https://math.lbl.gov/voro++/>`_.  This can be used to calculate the
+local volume or each atoms or its near neighbors.
 
 To use this package you must have the Voro++ library available on your
 system.

doc/src/Python_install.rst

@@ -15,9 +15,6 @@ Two components are necessary for Python to be able to invoke LAMMPS code:
   ``liblammps.dll``) from the folder where you compiled LAMMPS.
 
 .. _ctypes: https://docs.python.org/3/library/ctypes.html
-.. _python_virtualenv: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
-.. _python_venv: https://docs.python.org/3/library/venv.html
-.. _python_pep405: https://www.python.org/dev/peps/pep-0405
 
 .. _python_install_guides:
 
@@ -30,140 +27,36 @@ interpreter can find it and installing the LAMMPS shared library into a
 folder that the dynamic loader searches or inside of the installed
 ``lammps`` package folder.  There are multiple ways to achieve this.
 
-#. Do a full LAMMPS installation of libraries, executables, selected
-   headers, documentation (if enabled), and supporting files (only
-   available via CMake), which can also be either system-wide or into
-   user specific folders.
-
 #. Install both components into a Python ``site-packages`` folder, either
    system-wide or in the corresponding user-specific folder. This way no
    additional environment variables need to be set, but the shared
    library is otherwise not accessible.
 
-#. Do an installation into a virtual environment. This can either be an
-   installation of the Python package only or a full installation of LAMMPS.
+#. Do an installation into a virtual environment.
 
 #. Leave the files where they are in the source/development tree and
    adjust some environment variables.
 
 .. tabs::
 
-   .. tab:: Full install (CMake-only)
-
-      :ref:`Build the LAMMPS executable and library <library>` with
-      ``-DBUILD_SHARED_LIBS=on``, ``-DLAMMPS_EXCEPTIONS=on`` and
-      ``-DPKG_PYTHON=on`` (The first option is required, the other two
-      are optional by recommended).  The exact file name of the shared
-      library depends on the platform (Unix/Linux, macOS, Windows) and
-      the build configuration being used.  The installation base folder
-      is already set by default to the ``$HOME/.local`` directory, but
-      it can be changed to a custom location defined by the
-      ``CMAKE_INSTALL_PREFIX`` CMake variable.  This uses a folder
-      called ``build`` to store files generated during compilation.
-
-      .. code-block:: bash
-
-         # create build folder
-         mkdir build
-         cd build
-
-         # configure LAMMPS compilation
-         cmake -C ../cmake/presets/basic.cmake -D BUILD_SHARED_LIBS=on \
-               -D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on ../cmake
-
-         # compile LAMMPS
-         cmake --build .
-
-         # install LAMMPS into $HOME/.local
-         cmake --install .
-
-
-      This leads to an installation to the following locations:
-
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
-      | File                   | Location                                                        | Notes                                                       |
-      +========================+=================================================================+=============================================================+
-      | LAMMPS Python package  | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``$HOME/.local/lib/`` (32bit)                                 | Set shared loader environment variable to this path         |
-      |                        | * ``$HOME/.local/lib64/`` (64bit)                               | (see below for more info on this)                           |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS executable      | * ``$HOME/.local/bin/``                                         |                                                             |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/``                     | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
-
-      For a system-wide installation you need to set
-      ``CMAKE_INSTALL_PREFIX`` to a system folder like ``/usr`` (or
-      ``/usr/local``); the default is ``${HOME}/.local``.  The
-      installation step for a system folder installation (**not** the
-      configuration/compilation) needs to be done with superuser
-      privilege, e.g. by using ``sudo cmake --install .``.  The
-      installation folders will then be changed to (assuming ``/usr`` as
-      prefix):
-
-      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
-      | File                   | Location                                                | Notes                                                       |
-      +========================+=========================================================+=============================================================+
-      | LAMMPS Python package  | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
-      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``/usr/lib/`` (32bit)                                 |                                                             |
-      |                        | * ``/usr/lib64/`` (64bit)                               |                                                             |
-      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS executable      | * ``/usr/bin/``                                         |                                                             |
-      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS potential files | * ``/usr/share/lammps/potentials/``                     |                                                             |
-      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
-
-      To be able to use the "user" installation you have to ensure that
-      the folder containing the LAMMPS shared library is either included
-      in a path searched by the shared linker (e.g. like
-      ``/usr/lib64/``) or part of the ``LD_LIBRARY_PATH`` environment
-      variable (or ``DYLD_LIBRARY_PATH`` on macOS).  Otherwise you will
-      get an error when trying to create a LAMMPS object through the
-      Python module.
-
-      .. code-block:: bash
-
-         # Unix/Linux
-         export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
-
-         # macOS
-         export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
-
-      If you plan to use the LAMMPS executable (e.g., ``lmp``), you may
-      also need to adjust the ``PATH`` environment variable (but many
-      newer Linux distributions already have ``$HOME/.local/bin``
-      included). Example:
-
-      .. code-block:: bash
-
-         export PATH=$HOME/.local/bin:$PATH
-
-      To make those changes permanent, you can add the commands to your
-      ``$HOME/.bashrc`` file.  For a system-wide installation is is not
-      necessary due to files installed in system folders that are loaded
-      automatically when a login shell is started.
-
-   .. tab:: Python package only
+   .. tab:: Python package
 
       Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
       :doc:`traditional make <Build_make>` procedure in :ref:`shared
-      mode <exe>`.  After compilation has finished type (in the
+      mode <exe>`.  After compilation has finished, type (in the
       compilation folder):
 
       .. code-block:: bash
 
          make install-python
 
-      This will try to build a so-called (binary) 'wheel', a compressed
-      binary python package and then install it with the python package
-      manager 'pip'.  Installation will be attempted into a system-wide
-      ``site-packages`` folder and if that fails into the corresponding
-      folder in the user's home directory.  For a system-wide installation you
-      would have to gain superuser privilege, e.g. though ``sudo``
+      This will try to build a so-called (binary) wheel file, a
+      compressed binary python package and then install it with the
+      python package manager 'pip'.  Installation will be attempted into
+      a system-wide ``site-packages`` folder and if that fails into the
+      corresponding folder in the user's home directory.  For a
+      system-wide installation you usually would have to gain superuser
+      privilege first, e.g. though ``sudo``
 
       +------------------------+----------------------------------------------------------+-------------------------------------------------------------+
       | File                   | Location                                                 | Notes                                                       |
@@ -214,10 +107,11 @@ folder that the dynamic loader searches or inside of the installed
 
       .. code-block:: bash
 
-         python install.py -p <python package> -l <shared library> [-n]
+         python install.py -p <python package> -l <shared library> -v <version.h file> [-n]
 
       * The ``-p`` flag points to the ``lammps`` Python package folder to be installed,
       * the ``-l`` flag points to the LAMMPS shared library file to be installed,
+      * the ``-v`` flag points to the LAMMPS version header file to extract the version date,
       * and the optional ``-n`` instructs the script to only build a wheel file
         but not attempt to install it.
 
@@ -232,11 +126,11 @@ folder that the dynamic loader searches or inside of the installed
       install (newer/different) versions of Python packages that would
       potentially conflict with already installed system packages.  It
       also does not requite any superuser privileges. See `PEP 405:
-      Python Virtual Environments <python_pep405>`_ for more
+      Python Virtual Environments <https://peps.python.org/pep-0405/>`_ for more
       information.
 
       To create a virtual environment in the folder ``$HOME/myenv``,
-      use the `venv <python_venv>`_ module as follows.
+      use the `venv <https://docs.python.org/3/library/venv.html>`_ module as follows.
 
       .. code-block:: bash
 
@@ -244,8 +138,9 @@ folder that the dynamic loader searches or inside of the installed
          python3 -m venv $HOME/myenv
 
       For Python versions prior 3.3 you can use `virtualenv
-      <python_virtualenv>`_ command instead of "python3 -m venv".  This
-      step has to be done only once.
+      <https://packaging.python.org/en/latest/key_projects/#virtualenv>`_
+      command instead of "python3 -m venv".  This step has to be done
+      only once.
 
       To activate the virtual environment type:
 
@@ -274,38 +169,6 @@ folder that the dynamic loader searches or inside of the installed
       | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps``  | ``X.Y`` depends on the installed Python version             |
       +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
 
-      If you do a full installation (CMake only) with "install", this
-      leads to the following installation locations:
-
-      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
-      | File                   | Location                                               | Notes                                                       |
-      +========================+========================================================+=============================================================+
-      | LAMMPS Python Module   | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps``  | ``X.Y`` depends on the installed Python version             |
-      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/`` (32bit)                        | Set shared loader environment variable to this path         |
-      |                        | * ``$VIRTUAL_ENV/lib64/`` (64bit)                      | (see below for more info on this)                           |
-      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS executable      | * ``$VIRTUAL_ENV/bin/``                                |                                                             |
-      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/``            | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
-      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
-
-      In that case you need to modify the ``$HOME/myenv/bin/activate``
-      script in a similar fashion you need to update your
-      ``$HOME/.bashrc`` file to include the shared library and
-      executable locations in ``LD_LIBRARY_PATH`` (or
-      ``DYLD_LIBRARY_PATH`` on macOS) and ``PATH``, respectively.
-
-      For example with:
-
-      .. code-block:: bash
-
-         # Unix/Linux
-         echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
-
-         # macOS
-         echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$DYLD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
-
    .. tab:: In place usage
 
       You can also :doc:`compile LAMMPS <Build>` as usual in
@@ -414,10 +277,8 @@ follows:
 
      sudo pip install mpi4py
 
-.. _mpi4py_install: https://mpi4py.readthedocs.io/en/stable/install.html
-
 For more detailed installation instructions and additional options,
-please see the `mpi4py installation <mpi4py_install>`_ page.
+please see the `mpi4py installation <https://mpi4py.readthedocs.io/en/stable/install.html>`_ page.
 
 
 To use ``mpi4py`` and LAMMPS in parallel from Python, you **must** make

doc/src/Tools.rst

@@ -320,7 +320,8 @@ eam generate tool
 -----------------------------
 
 The tools/eam_generate directory contains several one-file C programs
-that convert an analytic formula into a tabulated :doc:`embedded atom method (EAM) <pair_eam>` setfl potential file.  The potentials they
+that convert an analytic formula into a tabulated :doc:`embedded atom
+method (EAM) <pair_eam>` setfl potential file.  The potentials they
 produce are in the potentials directory, and can be used with the
 :doc:`pair_style eam/alloy <pair_eam>` command.
 

doc/src/atom_style.rst

@@ -161,15 +161,14 @@ and each stores a per-particle diameter and mass.  If the diameter >
 0.0, the particle is a finite-size sphere.  If the diameter = 0.0, it
 is a point particle.  Note that by use of the *disc* keyword with the
 :doc:`fix nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere
-<fix_nvt_sphere>`, :doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix
-npt/sphere <fix_npt_sphere>` commands for the *sphere* style, spheres
-can be effectively treated as 2d discs for a 2d simulation if desired.
-See also the :doc:`set density/disc <set>` command.  The *sphere* and
-*bpm/sphere* styles take an optional 0 or 1 argument.  A value of 0
-means the radius of each sphere is constant for the duration of the
-simulation.  A value of 1 means the radii may vary dynamically during
-the simulation, e.g. due to use of the :doc:`fix adapt <fix_adapt>`
-command.
+<fix_nvt_sphere>`, :doc:`fix nph/sphere <fix_nph_sphere>`,
+:doc:`fix npt/sphere <fix_npt_sphere>` commands for the *sphere* style,
+spheres can be effectively treated as 2d discs for a 2d simulation if
+desired.  See also the :doc:`set density/disc <set>` command.  These
+styles take an optional 0 or 1 argument.  A value of 0 means the
+radius of each sphere is constant for the duration of the simulation.
+A value of 1 means the radii may vary dynamically during the simulation,
+e.g. due to use of the :doc:`fix adapt <fix_adapt>` command.
 
 For the *ellipsoid* style, the particles are ellipsoids and each
 stores a flag which indicates whether it is a finite-size ellipsoid or

doc/src/balance.rst

@@ -53,6 +53,7 @@ Syntax
              name = name of the atom-style variable
            *store* name = store weight in custom atom property defined by :doc:`fix property/atom <fix_property_atom>` command
              name = atom property name (without d\_ prefix)
+       *sort* arg = *no* or *yes*
        *out* arg = filename
          filename = write each processor's subdomain to a file
 
@@ -492,6 +493,14 @@ different kinds of custom atom vectors or arrays as arguments.
 
 ----------
 
+The *sort* keyword determines whether the communication of per-atom
+data to other processors during load-balancing will be random or
+deterministic.  Random is generally faster; deterministic will ensure
+the new ordering of atoms on each processor is the same each time the
+same simulation is run.  This can be useful for debugging purposes.
+Since the balance command is a one-time operation, the default is
+*yes* to perform sorting.
+
 The *out* keyword writes a text file to the specified *filename* with
 the results of the balancing operation.  The file contains the bounds
 of the subdomain for each processor after the balancing operation
@@ -569,4 +578,5 @@ Related commands
 Default
 """""""
 
-none
+The default setting is sort = yes.
+

doc/src/bond_bpm_rotational.rst

@@ -10,7 +10,7 @@ Syntax
 
    bond_style bpm/rotational keyword value attribute1 attribute2 ...
 
-* optional keyword = *overlay/pair* or *store/local* or *smooth*
+* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break/no*
 
   .. parsed-literal::
 
@@ -30,6 +30,9 @@ Syntax
        *smooth* value = *yes* or *no*
           smooths bond forces near the breaking point
 
+       *break/no*
+          indicates that bonds should not break during a run
+
 Examples
 """"""""
 
@@ -140,6 +143,12 @@ the *overlay/pair* keyword. These settings require specific
 restrictions.  Further details can be found in the `:doc: how to
 <Howto_BPM>` page on BPMs.
 
+.. versionadded:: 28Mar2023
+
+If the *break/no* keyword is used, then LAMMPS assumes bonds should not break
+during a simulation run. This will prevent some unnecessary calculation.
+However, if a bond does break, it will trigger an error.
+
 If the *store/local* keyword is used, an internal fix will track bonds that
 break during the simulation. Whenever a bond breaks, data is processed
 and transferred to an internal fix labeled *fix_ID*. This allows the

doc/src/bond_bpm_spring.rst

@@ -10,7 +10,7 @@ Syntax
 
    bond_style bpm/spring keyword value attribute1 attribute2 ...
 
-* optional keyword = *overlay/pair* or *store/local* or *smooth*
+* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break/no*
 
   .. parsed-literal::
 
@@ -30,6 +30,9 @@ Syntax
        *smooth* value = *yes* or *no*
           smooths bond forces near the breaking point
 
+       *break/no*
+          indicates that bonds should not break during a run
+
 Examples
 """"""""
 
@@ -47,7 +50,7 @@ Description
 
 .. versionadded:: 4May2022
 
-The *bpm/spring* bond style computes forces and torques based on
+The *bpm/spring* bond style computes forces based on
 deviations from the initial reference state of the two atoms.  The
 reference state is stored by each bond when it is first computed in
 the setup of a run. Data is then preserved across run commands and is
@@ -56,7 +59,8 @@ the system will not reset the reference state of a bond.
 
 This bond style only applies central-body forces which conserve the
 translational and rotational degrees of freedom of a bonded set of
-particles. The force has a magnitude of
+particles based on a model described by Clemmer and Robbins
+:ref:`(Clemmer) <fragment-Clemmer>`. The force has a magnitude of
 
 .. math::
 
@@ -105,6 +109,12 @@ the *overlay/pair* keyword. These settings require specific
 restrictions.  Further details can be found in the `:doc: how to
 <Howto_BPM>` page on BPMs.
 
+.. versionadded:: 28Mar2023
+
+If the *break/no* keyword is used, then LAMMPS assumes bonds should not break
+during a simulation run. This will prevent some unnecessary calculation.
+However, if a bond does break, it will trigger an error.
+
 If the *store/local* keyword is used, an internal fix will track bonds that
 break during the simulation. Whenever a bond breaks, data is processed
 and transferred to an internal fix labeled *fix_ID*. This allows the
@@ -200,6 +210,10 @@ The option defaults are *smooth* = *yes*
 
 ----------
 
+.. _fragment-Clemmer:
+
+**(Clemmer)** Clemmer and Robbins, Phys. Rev. Lett. (2022).
+
 .. _Groot4:
 
 **(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997).

doc/src/bond_fene.rst

@@ -51,7 +51,7 @@ in the same form as in pair style :doc:`nm/cut <pair_nm>`. The bond energy is th
 
 .. 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]
+  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

doc/src/bond_harmonic_restrain.rst

@@ -0,0 +1,90 @@
+.. index:: bond_style harmonic/restrain
+
+bond_style harmonic/restrain command
+====================================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   bond_style harmonic/restrain
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   bond_style harmonic
+   bond_coeff 5 80.0
+
+Description
+"""""""""""
+
+.. versionadded:: 28Mar2023
+
+The *harmonic/restrain* bond style uses the potential
+
+.. math::
+
+   E = K (r - r_{t=0})^2
+
+where :math:`r_{t=0}` is the distance between the bonded atoms at the
+beginning of the first :doc:`run <run>` or :doc:`minimize <minimize>`
+command after the bond style has been defined (*t=0*).  Note that the
+usual 1/2 factor is included in :math:`K`.  This will effectively
+restrain bonds to their initial length, whatever that is.  This is where
+this bond style differs from :doc:`bond style harmonic <bond_harmonic>`
+where the bond length is set through the per bond type coefficients.
+
+The following coefficient 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)
+
+This bond style differs from other options to add harmonic restraints
+like :doc:`fix restrain <fix_restrain>` or :doc:`pair style list
+<pair_list>` or :doc:`fix colvars <fix_colvars>` in that it requires a
+bond topology, and thus the defined bonds will trigger exclusion of
+special neighbors from the neighbor list according to the
+:doc:`special_bonds <special_bonds>` settings.
+
+Restart info
+""""""""""""
+
+This bond style supports the :doc:`write_restart <write_restart>` and
+:doc:`read_restart <read_restart>` commands. The state of the initial
+bond lengths is stored with restart files and read back.
+
+Restrictions
+""""""""""""
+
+This 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.
+
+This bond style maintains internal data to determine the original bond
+lengths :math:`r_{t=0}`.  This information will be written to
+:doc:`binary restart files <write_restart>` but **not** to :doc:`data
+files <write_data>`.  Thus, continuing a simulation is *only* possible
+with :doc:`read_restart <read_restart>`.  When using the :doc:`read_data
+command <read_data>`, the reference bond lengths :math:`r_{t=0}` will be
+re-initialized from the current geometry.
+
+This bond style cannot be used with :doc:`fix shake or fix rattle
+<fix_shake>`, with :doc:`fix filter/corotate <fix_filter_corotate>`, or
+any :doc:`tip4p pair style <pair_lj_cut_tip4p>` since there is no specific
+equilibrium distance for a given bond type.
+
+Related commands
+""""""""""""""""
+
+:doc:`bond_coeff <bond_coeff>`,  :doc:`bond_harmonic <bond_harmonic>`,
+:doc:`fix restrain <fix_restrain>`, :doc:`pair style list <pair_list>`
+
+Default
+"""""""
+
+none

doc/src/bond_style.rst

@@ -10,7 +10,7 @@ Syntax
 
    bond_style style args
 
-* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
+* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/restrain* *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
 
 * args = none for any style except *hybrid*
 
@@ -93,6 +93,7 @@ accelerated styles exist.
 * :doc:`gaussian <bond_gaussian>` - multicentered Gaussian-based bond potential
 * :doc:`gromos <bond_gromos>` - GROMOS force field bond
 * :doc:`harmonic <bond_harmonic>` - harmonic bond
+* :doc:`harmonic/restrain <bond_harmonic_restrain>` - harmonic bond to restrain to original bond distance
 * :doc:`harmonic/shift <bond_harmonic_shift>` - shifted harmonic bond
 * :doc:`harmonic/shift/cut <bond_harmonic_shift_cut>` - shifted harmonic bond with a cutoff
 * :doc:`lepton <bond_lepton>` - bond potential from evaluating a string

doc/src/bond_table.rst

@@ -112,8 +112,9 @@ are estimated (less accurately) by the first two and last two force
 values in the table.
 
 The "EQ" parameter is also optional.  If used, it is followed by a the
-equilibrium bond length, which is used, for example, by the :doc:`fix shake <fix_shake>` command.  If not used, the equilibrium bond
-length is to the distance in the table with the lowest potential energy.
+equilibrium bond length, which is used, for example, by the :doc:`fix
+shake <fix_shake>` command.  If not used, the equilibrium bond length is
+to the distance in the table with the lowest potential energy.
 
 Following a blank line, the next N lines list the tabulated values.
 On each line, the first value is the index from 1 to N, the second value is
@@ -135,16 +136,15 @@ one that matches the specified keyword.
 
 ----------
 
-Restart, fix_modify, output, run start/stop, minimize info
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Restart info
+""""""""""""
 
-This bond style writes the settings for the "bond_style table"
-command to :doc:`binary restart files <restart>`, so a bond_style
-command does not need to specified in an input script that reads a
-restart file.  However, the coefficient information is not stored in
-the restart file, since it is tabulated in the potential files.  Thus,
-bond_coeff commands do need to be specified in the restart input
-script.
+This bond style writes the settings for the "bond_style table" command
+to :doc:`binary restart files <restart>`, so a bond_style command does
+not need to specified in an input script that reads a restart file.
+However, the coefficient information is not stored in the restart file,
+since it is tabulated in the potential files.  Thus, bond_coeff commands
+do need to be specified in the restart input script.
 
 Restrictions
 """"""""""""

doc/src/bond_write.rst

@@ -70,7 +70,7 @@ be specified even if the potential has a finite value at r = 0.0.
 Related commands
 """"""""""""""""
 
-:doc:`bond_style table <bond_table>`, `angle_write <angle_write>`,
+:doc:`bond_style table <bond_table>`, :doc:`angle_write <angle_write>`,
 :doc:`bond_style <bond_style>`, :doc:`bond_coeff <bond_coeff>`
 
 Default

doc/src/comm_modify.rst

@@ -69,6 +69,7 @@ For many systems this is an efficient algorithm, but for systems with
 widely varying cutoffs for different type pairs, the *multi* or *multi/old* mode can
 be faster.  In *multi*, each atom is assigned to a collection which should
 correspond to a set of atoms with similar interaction cutoffs.
+See the :doc:`neighbor <neighbor>` command for a detailed description of collections.
 In this case, each atom collection is assigned its own distance
 cutoff for communication purposes, and fewer atoms will be
 communicated. in *multi/old*, a similar technique is used but atoms

doc/src/compute.rst

@@ -206,6 +206,8 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
 * :doc:`dilatation/atom <compute_dilatation_atom>` - Peridynamic dilatation for each atom
 * :doc:`dipole <compute_dipole>` - dipole vector and total dipole
 * :doc:`dipole/chunk <compute_dipole_chunk>` - dipole vector and total dipole for each chunk
+* :doc:`dipole/tip4p <compute_dipole>` - dipole vector and total dipole with TIP4P pair style
+* :doc:`dipole/tip4p/chunk <compute_dipole_chunk>` - dipole vector and total dipole for each chunk with TIP4P pair style
 * :doc:`displace/atom <compute_displace_atom>` - displacement of each atom
 * :doc:`dpd <compute_dpd>` - total values of internal conductive energy, internal mechanical energy, chemical energy, and harmonic average of internal temperature
 * :doc:`dpd/atom <compute_dpd_atom>` - per-particle values of internal conductive energy, internal mechanical energy, chemical energy, and internal temperature
@@ -258,6 +260,7 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
 * :doc:`pe/tally <compute_tally>` - potential energy between two groups of atoms via the tally callback mechanism
 * :doc:`plasticity/atom <compute_plasticity_atom>` - Peridynamic plasticity for each atom
 * :doc:`pressure <compute_pressure>` - total pressure and pressure tensor
+* :doc:`pressure/alchemy <compute_pressure_alchemy>` - mixed system total pressure and pressure tensor for :doc:`fix alchemy <fix_alchemy>` runs
 * :doc:`pressure/uef <compute_pressure_uef>` - pressure tensor in the reference frame of an applied flow field
 * :doc:`property/atom <compute_property_atom>` - convert atom attributes to per-atom vectors/arrays
 * :doc:`property/chunk <compute_property_chunk>` - extract various per-chunk attributes

doc/src/compute_dipole.rst

@@ -1,6 +1,10 @@
 .. index:: compute dipole
+.. index:: compute dipole/tip4p
 
 compute dipole command
+======================
+
+compute dipole/tip4p command
 ============================
 
 Syntax
@@ -8,10 +12,10 @@ Syntax
 
 .. code-block:: LAMMPS
 
-   compute ID group-ID dipole arg
+   compute ID group-ID style arg
 
 * ID, group-ID are documented in :doc:`compute <compute>` command
-* dipole = style name of this compute command
+* style = *dipole* or *dipole/tip4p*
 * arg = *mass* or *geometry* = use COM or geometric center for charged chunk correction (optional)
 
 Examples
@@ -21,6 +25,7 @@ Examples
 
    compute 1 fluid dipole
    compute dw water dipole geometry
+   compute dw water dipole/tip4p
 
 Description
 """""""""""
@@ -28,13 +33,20 @@ Description
 Define a computation that calculates the dipole vector and total dipole
 for a group of atoms.
 
-This compute calculates the x,y,z coordinates of the dipole vector
-and the total dipole moment for the atoms in the compute group.
-This includes all effects due to atoms passing through periodic boundaries.
-For a group with a net charge the resulting dipole is made position independent
-by subtracting the position vector of the center of mass or geometric center
-times the net charge from the computed dipole vector. Both per-atom charges
-and per-atom dipole moments, if present, contribute to the computed dipole.
+These computes calculate the x,y,z coordinates of the dipole vector and
+the total dipole moment for the atoms in the compute group.  This
+includes all effects due to atoms passing through periodic boundaries.
+For a group with a net charge the resulting dipole is made position
+independent by subtracting the position vector of the center of mass or
+geometric center times the net charge from the computed dipole
+vector.  Both per-atom charges and per-atom dipole moments, if present,
+contribute to the computed dipole.
+
+.. versionadded:: 28Mar2023
+
+Compute *dipole/tip4p* includes adjustments for the charge carrying
+point M in molecules with TIP4P water geometry.  The corresponding
+parameters are extracted from the pair style.
 
 .. note::
 
@@ -49,10 +61,10 @@ and per-atom dipole moments, if present, contribute to the computed dipole.
 Output info
 """""""""""
 
-This compute calculations a global scalar containing the magnitude of
-the computed dipole moment and a global vector of length 3 with the
-dipole vector.  See the :doc:`Howto output <Howto_output>` page for
-an overview of LAMMPS output options.
+These computes calculate a global scalar containing the magnitude of the
+computed dipole moment and a global vector of length 3 with the dipole
+vector.  See the :doc:`Howto output <Howto_output>` page for an overview
+of LAMMPS output options.
 
 The computed values are "intensive".  The array values will be in
 dipole units (i.e., charge :doc:`units <units>` times distance
@@ -60,7 +72,12 @@ dipole units (i.e., charge :doc:`units <units>` times distance
 
 Restrictions
 """"""""""""
- none
+
+Compute style *dipole/tip4p* 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.
+
+Compute style *dipole/tip4p* can only be used with tip4p pair styles.
 
 Related commands
 """"""""""""""""

doc/src/compute_dipole_chunk.rst

@@ -1,17 +1,21 @@
 .. index:: compute dipole/chunk
+.. index:: compute dipole/tip4p/chunk
 
 compute dipole/chunk command
 ============================
 
+compute dipole/tip4p/chunk command
+==================================
+
 Syntax
 """"""
 
 .. code-block:: LAMMPS
 
-   compute ID group-ID dipole/chunk chunkID arg
+   compute ID group-ID style chunkID arg
 
 * ID, group-ID are documented in :doc:`compute <compute>` command
-* dipole/chunk = style name of this compute command
+* style = *dipole/chunk* or *dipole/tip4p/chunk*
 * chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
 * arg = *mass* or *geometry* = use COM or geometric center for charged chunk correction (optional)
 
@@ -38,13 +42,20 @@ or atoms in a spatial bin.  See the :doc:`compute chunk/atom
 details of how chunks can be defined and examples of how they can be
 used to measure properties of a system.
 
-This compute calculates the :math:`(x,y,z)` coordinates of the dipole vector
-and the total dipole moment for each chunk, which includes all effects due
-to atoms passing through periodic boundaries. For chunks with a net
-charge the resulting dipole is made position independent by subtracting
-the position vector of the center of mass or geometric center times the
-net charge from the computed dipole vector. Both per-atom charges and
-per-atom dipole moments, if present, contribute to the computed dipole.
+These computes calculate the :math:`(x,y,z)` coordinates of the dipole
+vector and the total dipole moment for each chunk, which includes all
+effects due to atoms passing through periodic boundaries.  For chunks
+with a net charge the resulting dipole is made position independent by
+subtracting the position vector of the center of mass or geometric
+center times the net charge from the computed dipole vector.  Both
+per-atom charges and per-atom dipole moments, if present, contribute to
+the computed dipole.
+
+.. versionadded:: 28Mar2023
+
+Compute *dipole/tip4p/chunk* includes adjustments for the charge
+carrying point M in molecules with TIP4P water geometry.  The
+corresponding parameters are extracted from the pair style.
 
 Note that only atoms in the specified group contribute to the
 calculation.  The :doc:`compute chunk/atom <compute_chunk_atom>` command
@@ -78,12 +89,12 @@ command, for example:
 Output info
 """""""""""
 
-This compute calculates a global array where the number of rows = the
+These computes calculate a global array where the number of rows = the
 number of chunks *Nchunk* as calculated by the specified :doc:`compute
-chunk/atom <compute_chunk_atom>` command.  The number of columns is 4 for
-the :math:`(x,y,z)` dipole vector components and the total dipole of each
-chunk. These values can be accessed by any command that uses global
-array values from a compute as input.  See the :doc:`Howto output
+chunk/atom <compute_chunk_atom>` command.  The number of columns is 4
+for the :math:`(x,y,z)` dipole vector components and the total dipole of
+each chunk.  These values can be accessed by any command that uses
+global array values from a compute as input.  See the :doc:`Howto output
 <Howto_output>` page for an overview of LAMMPS output options.
 
 The array values are "intensive".  The array values will be in
@@ -92,7 +103,13 @@ dipole units (i.e., charge :doc:`units <units>` times distance
 
 Restrictions
 """"""""""""
- none
+
+Compute style *dipole/tip4p/chunk* 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.
+
+Compute style *dipole/tip4p/chunk* can only be used with tip4p pair
+styles.
 
 Related commands
 """"""""""""""""

doc/src/compute_pressure_alchemy.rst

@@ -0,0 +1,80 @@
+.. index:: compute pressure/alchemy
+
+compute pressure/alchemy command
+================================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   compute ID group-ID pressure/alchemy fix-ID
+
+* ID, group-ID are documented in :doc:`compute <compute>` command
+* pressure/alchemy = style name of this compute command
+* fix-ID = ID of :doc:`fix alchemy <fix_alchemy>` command
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix trans all alchemy
+   compute mixed all pressure/alchemy trans
+   thermo_modify press mixed
+
+Description
+"""""""""""
+
+.. versionadded:: 28Mar2023
+
+Define a compute style that makes the "mixed" system pressure available
+for a system that uses the :doc:`fix alchemy <fix_alchemy>` command to
+transform one topology to another.  This can be used in combination with
+either :doc:`thermo_modify press <thermo_modify>` or :doc:`fix_modify
+press <fix_modify>` to output and access a pressure consistent with the
+simulated combined two topology system.
+
+The actual pressure is determined with :doc:`compute pressure
+<compute_pressure>` commands that are internally used by :doc:`fix
+alchemy <fix_alchemy>` for each topology individually and then combined.
+This command just extracts the information from the fix.
+
+The ``examples/PACKAGES/alchemy`` folder contains an example input for this command.
+
+----------
+
+Output info
+"""""""""""
+
+This compute calculates a global scalar (the pressure) and a global
+vector of length 6 (the pressure tensor), which can be accessed by
+indices 1--6.  These values can be used by any command that uses global
+scalar or vector values from a compute as input.  See the :doc:`Howto
+output <Howto_output>` page for an overview of LAMMPS output options.
+
+The ordering of values in the symmetric pressure tensor is as follows:
+:math:`p_{xx},` :math:`p_{yy},` :math:`p_{zz},` :math:`p_{xy},`
+:math:`p_{xz},` :math:`p_{yz}.`
+
+The scalar and vector values calculated by this compute are "intensive".
+The scalar and vector values will be in pressure :doc:`units <units>`.
+
+Restrictions
+""""""""""""
+
+This compute is part of the REPLICA 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 alchemy <fix_alchemy>`, :doc:`compute pressure <compute_pressure>`,
+:doc:`thermo_modify <thermo_modify>`, :doc:`fix_modify <fix_modify>`
+
+Default
+"""""""
+
+none

doc/src/compute_smd_contact_radius.rst

@@ -29,7 +29,7 @@ contact radius is used only to prevent particles belonging to
 different physical bodies from penetrating each other. It is used by
 the contact pair styles, e.g., smd/hertz and smd/tri_surface.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 The value of the contact radius will be 0.0 for particles not in the

doc/src/compute_smd_damage.rst

@@ -26,7 +26,7 @@ Description
 Define a computation that calculates the damage status of SPH particles
 according to the damage model which is defined via the SMD SPH pair styles, e.g., the maximum plastic strain failure criterion.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to use Smooth Mach Dynamics in LAMMPS.
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to use Smooth Mach Dynamics in LAMMPS.
 
 **Output Info:**
 

doc/src/compute_smd_hourglass_error.rst

@@ -34,7 +34,7 @@ configuration.  This compute is only really useful for debugging the
 hourglass control mechanism which is part of the Total-Lagrangian SPH
 pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to use Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to use Smooth
 Mach Dynamics in LAMMPS.
 
 **Output Info:**

doc/src/compute_smd_internal_energy.rst

@@ -26,7 +26,7 @@ Description
 Define a computation which outputs the per-particle enthalpy, i.e.,
 the sum of potential energy and heat.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to use Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to use Smooth
 Mach Dynamics in LAMMPS.
 
 Output Info

doc/src/compute_smd_plastic_strain.rst

@@ -27,7 +27,7 @@ Define a computation that outputs the equivalent plastic strain per
 particle.  This command is only meaningful if a material model with
 plasticity is defined.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to use Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to use Smooth
 Mach Dynamics in LAMMPS.
 
 **Output Info:**

doc/src/compute_smd_plastic_strain_rate.rst

@@ -27,7 +27,7 @@ Define a computation that outputs the time rate of the equivalent
 plastic strain.  This command is only meaningful if a material model
 with plasticity is defined.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to use Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to use Smooth
 Mach Dynamics in LAMMPS.
 
 **Output Info:**

doc/src/compute_smd_rho.rst

@@ -28,7 +28,7 @@ The mass density is the mass of a particle which is constant during
 the course of a simulation, divided by its volume, which can change
 due to mechanical deformation.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to use Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to use Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_tlsph_defgrad.rst

@@ -27,7 +27,7 @@ Define a computation that calculates the deformation gradient.  It is
 only meaningful for particles which interact according to the
 Total-Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to use Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to use Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_tlsph_dt.rst

@@ -32,7 +32,7 @@ time step.  This calculation is performed automatically in the
 relevant SPH pair styles and this compute only serves to make the
 stable time increment accessible for output purposes.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_tlsph_num_neighs.rst

@@ -27,7 +27,7 @@ Define a computation that calculates the number of particles inside of
 the smoothing kernel radius for particles interacting via the
 Total-Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_tlsph_shape.rst

@@ -28,7 +28,7 @@ associated with a particle as a rotated ellipsoid.  It is only
 meaningful for particles which interact according to the
 Total-Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to use Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to use Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_tlsph_strain.rst

@@ -26,7 +26,7 @@ Description
 Define a computation that calculates the Green-Lagrange strain tensor
 for particles interacting via the Total-Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_tlsph_strain_rate.rst

@@ -26,7 +26,7 @@ Description
 Define a computation that calculates the rate of the strain tensor for
 particles interacting via the Total-Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_tlsph_stress.rst

@@ -26,7 +26,7 @@ Description
 Define a computation that outputs the Cauchy stress tensor for
 particles interacting via the Total-Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_triangle_vertices.rst

@@ -26,7 +26,7 @@ Description
 Define a computation that returns the coordinates of the vertices
 corresponding to the triangle-elements of a mesh created by the :doc:`fix smd/wall_surface <fix_smd_wall_surface>`.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_ulsph_effm.rst

@@ -26,7 +26,7 @@ Description
 Define a computation that outputs the effective shear modulus for
 particles interacting via the updated Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_ulsph_num_neighs.rst

@@ -27,7 +27,7 @@ Define a computation that returns the number of neighbor particles
 inside of the smoothing kernel radius for particles interacting via
 the updated Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_ulsph_strain.rst

@@ -26,7 +26,7 @@ Description
 Define a computation that outputs the logarithmic strain tensor.  for
 particles interacting via the updated Lagrangian SPH pair style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_ulsph_strain_rate.rst

@@ -27,7 +27,7 @@ Define a computation that outputs the rate of the logarithmic strain
 tensor for particles interacting via the updated Lagrangian SPH pair
 style.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_ulsph_stress.rst

@@ -25,7 +25,7 @@ Description
 
 Define a computation that outputs the Cauchy stress tensor.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_smd_vol.rst

@@ -26,7 +26,7 @@ Description
 Define a computation that provides the per-particle volume and the sum
 of the per-particle volumes of the group for which the fix is defined.
 
-See `this PDF guide <PDF/SMD_LAMMPS_userguide.pdf>`_ to using Smooth
+See `this PDF guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_ to using Smooth
 Mach Dynamics in LAMMPS.
 
 Output info

doc/src/compute_sna_atom.rst

@@ -451,7 +451,10 @@ piece of python code:
            for j in range(j1-j2,min(twojmax,j1+j2)+1,2):
                if (j>=j1): print j1/2.,j2/2.,j/2.
 
-For even twojmax = 2(*m*\ -1), :math:`K = m(m+1)(2m+1)/6`, the *m*\ -th pyramidal number. For odd twojmax = 2 *m*\ -1, :math:`K = m(m+1)(m+2)/3`, twice the *m*\ -th tetrahedral number.
+There are :math:`m(m+1)/2` descriptors with last index *j*,
+where *m* = :math:`\lfloor j \rfloor + 1`.
+Hence, for even *twojmax* = 2(*m*\ -1), :math:`K = m(m+1)(2m+1)/6`, the *m*\ -th pyramidal number,
+and for odd *twojmax* = 2 *m*\ -1, :math:`K = m(m+1)(m+2)/3`, twice the *m*\ -th tetrahedral number.
 
 .. note::
 

doc/src/dump.rst

@@ -111,6 +111,7 @@ Syntax
                                q, mux, muy, muz, mu,
                                radius, diameter, omegax, omegay, omegaz,
                                angmomx, angmomy, angmomz, tqx, tqy, tqz,
+                               heatflow, temperature,
                                c_ID, c_ID[I], f_ID, f_ID[I], v_name,
                                i_name, d_name, i2_name[I], d2_name[I]
 
@@ -133,10 +134,12 @@ Syntax
            q = atom charge
            mux,muy,muz = orientation of dipole moment of atom
            mu = magnitude of dipole moment of atom
-           radius,diameter = radius,diameter of spherical particle
+           radius,diameter = radius, diameter of spherical particle
            omegax,omegay,omegaz = angular velocity of spherical particle
            angmomx,angmomy,angmomz = angular momentum of aspherical particle
            tqx,tqy,tqz = torque on finite-size particles
+           heatflow = rate of heat flow into particle
+           temperature = temperature of particle
            c_ID = per-atom vector calculated by a compute with ID
            c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below)
            f_ID = per-atom vector calculated by a fix with ID
@@ -375,7 +378,7 @@ output with each snapshot:
    nx ny nz
 
 The value dim will be 2 or 3 for 2d or 3d simulations.  It is included
-so that post-processing tools like `OVITO <https://www.ovito.org>`,
+so that post-processing tools like `OVITO <https://www.ovito.org>`_,
 which can visualize grid-based quantities know how to draw each grid
 cell.  The grid size will match the input script parameters for
 grid(s) created by the computes or fixes which are referenced by the

doc/src/dump_image.rst

@@ -218,13 +218,13 @@ is used.
 .. _png_format: https://en.wikipedia.org/wiki/Portable_Network_Graphics
 .. _ppm_format: https://en.wikipedia.org/wiki/Netpbm
 
-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
-<https://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.
+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
+<https://ffmpeg.org/>`_.  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
@@ -651,7 +651,7 @@ MPEG or other movie file you can use:
      cat snap.*.ppm | ffmpeg -y -f image2pipe -c:v ppm -i - -b:v 2400k movie.avi
 
   Front ends for FFmpeg exist for multiple platforms. For more
-  information see the `FFmpeg homepage <https://www.ffmpeg.org/>`_
+  information see the `FFmpeg homepage <https://ffmpeg.org/>`_
 
 ----------
 

doc/src/fix.rst

@@ -181,6 +181,7 @@ accelerated styles exist.
 * :doc:`adapt/fep <fix_adapt_fep>` - enhanced version of fix adapt
 * :doc:`addforce <fix_addforce>` - add a force to each atom
 * :doc:`addtorque <fix_addtorque>` - add a torque to a group of atoms
+* :doc:`alchemy <fix_alchemy>` - perform an "alchemical transformation" between two partitions
 * :doc:`amoeba/bitorsion <fix_amoeba_bitorsion>` - torsion/torsion terms in AMOEBA force field
 * :doc:`amoeba/pitorsion <fix_amoeba_pitorsion>` - 6-body terms in AMOEBA force field
 * :doc:`append/atoms <fix_append_atoms>` - append atoms to a running simulation
@@ -221,6 +222,7 @@ accelerated styles exist.
 * :doc:`dt/reset <fix_dt_reset>` - reset the timestep based on velocity, forces
 * :doc:`edpd/source <fix_dpd_source>` - add heat source to eDPD simulations
 * :doc:`efield <fix_efield>` - impose electric field on system
+* :doc:`efield/tip4p <fix_efield>` - impose electric field on system with TIP4P molecules
 * :doc:`ehex <fix_ehex>` - enhanced heat exchange algorithm
 * :doc:`electrode/conp <fix_electrode>` - impose electric potential
 * :doc:`electrode/conq <fix_electrode>` - impose total electric charge
@@ -244,6 +246,7 @@ accelerated styles exist.
 * :doc:`grem <fix_grem>` - implements the generalized replica exchange method
 * :doc:`halt <fix_halt>` - terminate a dynamics run or minimization
 * :doc:`heat <fix_heat>` - add/subtract momentum-conserving heat
+* :doc:`heat/flow <fix_heat_flow>` - plain time integration of heat flow with per-atom temperature updates
 * :doc:`hyper/global <fix_hyper_global>` - global hyperdynamics
 * :doc:`hyper/local <fix_hyper_local>` - local hyperdynamics
 * :doc:`imd <fix_imd>` - implements the "Interactive MD" (IMD) protocol
@@ -259,7 +262,8 @@ accelerated styles exist.
 * :doc:`lb/viscous <fix_lb_viscous>` - :doc:`fix viscous <fix_viscous>` replacement for use with a lattice-Boltzmann fluid
 * :doc:`lineforce <fix_lineforce>` - constrain atoms to move in a line
 * :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
-* :doc:`mdi/qm <fix_mdi_qm>` - LAMMPS operates as driver for a quantum code via the MolSSI Driver Interface (MDI)
+* :doc:`mdi/qm <fix_mdi_qm>` - LAMMPS operates as a client for a quantum code via the MolSSI Driver Interface (MDI)
+* :doc:`mdi/qmmm <fix_mdi_qmmm>` - LAMMPS operates as client for QM/MM simulation with a quantum code via the MolSSI Driver Interface (MDI)
 * :doc:`meso/move <fix_meso_move>` - move mesoscopic SPH/SDPD particles in a prescribed fashion
 * :doc:`mol/swap <fix_mol_swap>` - Monte Carlo atom type swapping with a molecule
 * :doc:`momentum <fix_momentum>` - zero the linear and/or angular momentum of a group of atoms
@@ -320,7 +324,7 @@ accelerated styles exist.
 * :doc:`pafi <fix_pafi>` - constrained force averages on hyper-planes to compute free energies (PAFI)
 * :doc:`pair <fix_pair>` - access per-atom info from pair styles
 * :doc:`phonon <fix_phonon>` - calculate dynamical matrix from MD simulations
-* :doc:`pimd <fix_pimd>` - Feynman path integral molecular dynamics
+* :doc:`pimd/nvt <fix_pimd>` - Feynman path integral molecular dynamics with Nose-Hoover thermostat
 * :doc:`planeforce <fix_planeforce>` - constrain atoms to move in a plane
 * :doc:`plumed <fix_plumed>` - wrapper on PLUMED free energy library
 * :doc:`poems <fix_poems>` - constrain clusters of atoms to move as coupled rigid bodies
@@ -415,6 +419,7 @@ accelerated styles exist.
 * :doc:`wall/lj1043 <fix_wall>` - Lennard-Jones 10--4--3 wall
 * :doc:`wall/lj126 <fix_wall>` - Lennard-Jones 12--6 wall
 * :doc:`wall/lj93 <fix_wall>` - Lennard-Jones 9--3 wall
+* :doc:`wall/lepton <fix_wall>` - Custom Lepton expression wall
 * :doc:`wall/morse <fix_wall>` - Morse potential wall
 * :doc:`wall/piston <fix_wall_piston>` - moving reflective piston wall
 * :doc:`wall/reflect <fix_wall_reflect>` - reflecting wall(s)
@@ -422,6 +427,7 @@ accelerated styles exist.
 * :doc:`wall/region <fix_wall_region>` - use region surface as wall
 * :doc:`wall/region/ees <fix_wall_ees>` - use region surface as wall for ellipsoidal particles
 * :doc:`wall/srd <fix_wall_srd>` - slip/no-slip wall for SRD particles
+* :doc:`wall/table <fix_wall>` - Tabulated potential wall wall
 * :doc:`widom <fix_widom>` - Widom insertions of atoms or molecules
 
 Restrictions

doc/src/fix_adapt.rst

@@ -133,13 +133,15 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`born/coul/long, born/coul/msm <pair_born>`                             | coulombic_cutoff                                 | type global |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
+| :doc:`born/gauss <pair_born_gauss>`                                          | biga0,biga1,r0                                   | type pairs  |
++------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`buck, buck/coul/cut  <pair_buck>`                                      | a,c                                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`buck/coul/long, buck/coul/msm <pair_buck>`                             | a,c,coulombic_cutoff                             | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`buck/mdf <pair_mdf>`                                                   | a,c                                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
-| :doc:`coul/cut <pair_coul>`                                                  | scale                                            | type pairs  |
+| :doc:`coul/cut, coul/cut/global <pair_coul>`                                 | scale                                            | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`coul/cut/soft <pair_fep_soft>`                                         | lambda                                           | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
@@ -151,10 +153,16 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`coul/long/soft <pair_fep_soft>`                                        | scale, lambda, coulombic_cutoff                  | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
+| :doc:`coul/slater/long <pair_coul_slater>`                                   | scale                                            | type pairs  |
++------------------------------------------------------------------------------+--------------------------------------------------+-------------+
+| :doc:`coul/streitz <pair_coul>`                                              | scale                                            | type pairs  |
++------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`eam, eam/alloy, eam/fs <pair_eam>`                                     | scale                                            | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`gauss <pair_gauss>`                                                    | a                                                | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
+| :doc:`harmonic/cut <pair_harmonic_cut>`                                      | k, cutoff                                        | type pairs  |
++------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lennard/mdf <pair_mdf>`                                                | A,B                                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lj/class2 <pair_class2>`                                               | epsilon,sigma                                    | type pairs  |
@@ -181,6 +189,8 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lubricate <pair_lubricate>`                                            | mu                                               | global      |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
+| :doc:`meam <pair_meam>`                                                      | scale                                            | type pairs  |
++------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`mie/cut <pair_mie>`                                                    | epsilon,sigma,gamma_repulsive,gamma_attractive   | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`morse, morse/smooth/linear <pair_morse>`                               | D0,R0,alpha                                      | type pairs  |
@@ -191,7 +201,7 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`nm/cut/coul/cut, nm/cut/coul/long <pair_nm>`                           | E0,R0,m,n,coulombic_cutoff                       | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
-| :doc:`reaxff <pair_reaxff>`                                                  | chi, eta, gamma                                  | type global |
+| :doc:`pace, pace/extrapolation <pair_pace>`                                  | scale                                            | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`snap <pair_snap>`                                                      | scale                                            | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
@@ -203,11 +213,13 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`spin/neel <pair_spin_neel>`                                            | coulombic_cutoff                                 | type global |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
+| :doc:`soft <pair_soft>`                                                      | a                                                | type pairs  |
++------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`table <pair_table>`                                                    | table_cutoff                                     | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`ufm <pair_ufm>`                                                        | epsilon,sigma                                    | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
-| :doc:`soft <pair_soft>`                                                      | a                                                | type pairs  |
+| :doc:`wf/cut <pair_wf_cut>`                                                  | epsilon,sigma,nu,mu                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 
 .. note::

doc/src/fix_alchemy.rst

@@ -0,0 +1,173 @@
+.. index:: fix alchemy
+
+fix alchemy command
+===================
+
+Syntax
+""""""
+
+.. parsed-literal::
+
+   fix ID group-ID alchemy v_name
+
+* ID, group-ID are documented in :doc:`fix <fix>` command
+* alchemy = style name of this fix command
+* v_name = variable with name that determines the :math:`\lambda_R` value
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix trans all alchemy v_ramp
+
+Description
+"""""""""""
+
+.. versionadded:: 28Mar2023
+
+This fix command enables an "alchemical transformation" to be performed
+between two systems, whereby one system slowly transforms into the other
+over the course of a molecular dynamics run.  This is useful for
+measuring thermodynamic differences between two different systems.  It
+also allows transformations that are not easily possible with the
+:doc:`pair style hybrid/scaled <pair_hybrid>`, :doc:`fix adapt
+<fix_adapt>` or :doc:`fix adapt/fep <fix_adapt_fep>` commands.
+
+Example inputs are included in the ``examples/PACKAGES/alchemy``
+directory for (a) transforming a pure copper system into a
+copper/aluminum bronze alloy and (b) transforming two water molecules
+in a box of water into a hydronium and a hydroxyl ion.
+
+The two systems must be defined as :doc:`separate replica
+<Howto_replica>` and run in separate partitions of processors using the
+:doc:`-partition <Run_options>` command-line switch.  Exactly two
+partitions must be specified, and each partition must use the same number
+of processors and the same domain decomposition.
+
+Because the forces applied to the atoms are the same mix of the forces
+from each partition and the simulation starts with the same atom
+positions across both partitions, they will generate the same trajectory
+of coordinates for each atom, and the same simulation box size and
+shape.  The latter two conditions are *enforced* by this fix; it
+exchanges coordinates and box information between the replicas.  This is
+not strictly required, but since MD simulations are an example of a
+chaotic system, even the tiniest random difference will eventually grow
+exponentially into an unwanted divergence.
+
+Otherwise, the properties of each atom (type, charge, bond and angle
+partners, etc.), as well as energy and forces between interacting atoms
+(pair, bond, angle styles, etc.) can be different in the two systems.
+
+This can be initialized in the same input script by using commands which
+only apply to one or the other replica.  The example scripts use a
+world-style :doc:`variable <variable>` command along with
+:doc:`if/then/else <if>` commands for this purpose.  The
+:doc:`partition <partition>` command can also be used.
+
+.. code-block:: LAMMPS
+
+   create_box 2 box
+   create_atoms 1 box
+   pair_style eam/alloy
+   pair_coeff * * AlCu.eam.alloy Cu Al
+
+   # replace 5% of copper with aluminum on the second partition only
+
+   variable name world pure alloy
+   if "${name} == alloy" then &
+     "set type 1 type/fraction 2 0.05 6745234"
+
+Both replicas must define an instance of this fix, but with a different
+*v_name* variable.  The named variable must be an equal-style or
+equivalent :doc:`variable <variable>`.  The two variables should be
+defined so that one ramps *down* from 1.0 to 0.0 for the *first* replica
+(*R=0*) and the other ramps *up* from 0.0 to 1.0 for the *second*
+replica (*R=1*).  A simple way is to do this is linearly, which can be
+done using the ramp() function of the :doc:`variable <variable>`
+command.  You could also define a variable which returns a value between
+0.0 and 1.0 as a non-linear function of the timestep.  Here is a linear
+example:
+
+.. code-block:: LAMMPS
+
+   partition yes 1 variable ramp equal ramp(1.0,0.0)
+   partition yes 2 variable ramp equal ramp(0.0,1.0)
+   fix 2 all alchemy v_ramp
+
+.. note::
+
+   For an alchemical transformation, the two variables should sum to
+   exactly 1.0 at any timestep.  LAMMPS does *NOT* check that this is
+   the case.
+
+If you use the ``ramp()`` function to define the two variables, this fix
+can easily be used across successive runs in the same input script by
+ensuring each instance of the :doc:`run <run>` command specifies the
+appropriate *start* or *stop* options.
+
+At each timestep of an MD run, the two instances of this fix evaluate
+their respective variables as a :math:`\lambda_R` factor, where *R* = 0
+or 1 for each replica.  The forces used by each system for the
+propagation of their atoms is set to the sum of the forces for the two
+systems, each scaled by their respective :math:`\lambda_R` factor.  Thus,
+during the MD run, the system will transform incrementally from the
+first system to the second system.
+
+.. note::
+
+   As mentioned above, the coordinates of the atoms and box size/shape
+   must be exactly the same in the two replicas.  Therefore, it is
+   generally not a good idea to initialize the two replicas by reading
+   different data files or creating them individually from scratch.
+   Rather, a single system should be initialized and then desired
+   modifications applied to the system to either replica.  If your
+   input script somehow induces the two systems to become different
+   (e.g. by performing :doc:`atom_modify sort <atom_modify>`
+   differently, or by adding or depositing a different number of atoms),
+   then LAMMPS will detect the mismatch and generate an error.  This is
+   done by ensuring that each step the number and ordering of atoms is
+   identical within each pair of processors in the two replicas.
+
+----------
+
+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 stores a global scalar (the current value of :math:`\lambda_R`)
+and a global vector of length 3 which contains the potential energy of
+the first partition, the second partition and the combined value,
+respectively. The global scalar is unitless and "intensive", the vector
+is in :doc:`energy units <units>` and "extensive".  These values can be
+used by any command that uses a global value from a fix as input.  See
+the :doc:`output howto <Howto_output>` page for an overview of LAMMPS
+output options.
+
+This fix is not invoked during :doc:`energy minimization <minimize>`.
+
+Restrictions
+""""""""""""
+
+This fix is part of the REPLICA package.  It is only enabled if LAMMPS
+was built with that package.  See the :doc:`Build package
+<Build_package>` page for more info.
+
+There may be only one instance of this fix in use at a time within
+each replica.
+
+
+Related commands
+""""""""""""""""
+
+:doc:`compute pressure/alchemy <compute_pressure_alchemy>` command,
+:doc:`fix adapt <fix_adapt>` command, :doc:`fix adapt/fep <fix_adapt_fep>`
+command, :doc:`pair_style hybrid/scaled <pair_hybrid>` command.
+
+Default
+"""""""
+
+none

doc/src/fix_ave_correlate_long.rst

@@ -15,7 +15,7 @@ Syntax
 * Nevery = use input values every this many time steps
 * Nfreq = save state of the time correlation functions every this many time steps
 * one or more input values can be listed
-* value = c_ID, c_ID[N], f_ID, f_ID[N], v_name
+* value = c_ID, c_ID[N], f_ID, f_ID[N], v_name, v_name[I]
 
   .. parsed-literal::
 
@@ -24,6 +24,7 @@ Syntax
        f_ID = global scalar calculated by a fix with ID
        f_ID[I] = Ith component of global vector calculated by a fix with ID
        v_name = global value calculated by an equal-style variable with name
+       v_name[I] = Ith component of global vector calculated by a vector-style variable with name
 
 * zero or more keyword/arg pairs may be appended
 * keyword = *type* or *start* or *file* or *overwrite* or *title1* or *title2* or *ncorr* or *nlen* or *ncount*

doc/src/fix_ave_spatial.rst

@@ -2,7 +2,7 @@ Fix ave/spatial command
 =======================
 
 .. meta::
-   :http-equiv=Refresh: 5; url='https://docs.lammps.org/Commands_removed.html#fix-ave-spatial-and-fix-ave-spatial-sphere'
+   :http-equiv=Refresh: 5; url=Commands_removed.html#fix-ave-spatial-and-fix-ave-spatial-sphere
 
 .. deprecated:: 11Dec2015
 

doc/src/fix_ave_spatial_sphere.rst

@@ -2,7 +2,7 @@ Fix ave/spatial command
 =======================
 
 .. meta::
-   :http-equiv=Refresh: 5; url='https://docs.lammps.org/Commands_removed.html#fix-ave-spatial-and-fix-ave-spatial-sphere'
+   :http-equiv=Refresh: 5; url=https://docs.lammps.org/Commands_removed.html#fix-ave-spatial-and-fix-ave-spatial-sphere
 
 .. deprecated:: 11Dec2015