Merge pull request #4613 from akohlmey/next_release

Set version date for next feature release

.github/release_steps.md

@@ -104,8 +104,8 @@ with a future release) from the `lammps-static` folder.
 rm -rf release-packages
 mkdir release-packages
 cd release-packages
-wget https://download.lammps.org/static/fedora41_musl.sif
-apptainer shell fedora41_musl.sif
+wget https://download.lammps.org/static/fedora41_musl_mingw.sif
+apptainer shell fedora41_musl_mingw.sif
 git clone -b release --depth 10 https://github.com/lammps/lammps.git lammps-release
 cmake -S lammps-release/cmake -B build-release -G Ninja -D CMAKE_INSTALL_PREFIX=$PWD/lammps-static -D CMAKE_TOOLCHAIN_FILE=/usr/musl/share/cmake/linux-musl.cmake -C lammps-release/cmake/presets/most.cmake -C lammps-release/cmake/presets/kokkos-openmp.cmake -D DOWNLOAD_POTENTIALS=OFF -D BUILD_MPI=OFF -D BUILD_TESTING=OFF -D CMAKE_BUILD_TYPE=Release -D PKG_ATC=ON -D PKG_AWPMD=ON -D PKG_MANIFOLD=ON -D PKG_MESONT=ON -D PKG_MGPT=ON -D PKG_ML-PACE=ON -D PKG_ML-RANN=ON -D PKG_MOLFILE=ON -D PKG_PTM=ON -D PKG_QTB=ON -D PKG_SMTBQ=ON
 cmake --build build-release --target all
@@ -204,7 +204,7 @@ cd ..
 rm -r release-packages
 ```
 
-#### Build Multi-arch App-bundle for macOS
+#### Build Multi-arch App-bundle with GUI for macOS
 
 Building app-bundles for macOS is not as easily automated and portable
 as some of the other steps.  It requires a machine actually running
@@ -251,7 +251,7 @@ attached to the GitHub release page.
 
 We are currently building the application images on macOS 12 (aka Monterey).
 
-#### Build Linux x86_64 binary tarball on Ubuntu 20.04LTS
+#### Build Linux x86_64 binary tarball with GUI on Ubuntu 20.04LTS
 
 While the flatpak Linux version uses portable runtime libraries provided
 by the flatpak environment, we also build regular Linux executables that

.github/workflows/check-cpp23.yml

@@ -1,4 +1,4 @@
-# GitHub action to build LAMMPS on Linux with gcc and C++23
+# GitHub action to build LAMMPS on Linux with gcc or clang and C++23
 name: "Check for C++23 Compatibility"
 
 on:
@@ -11,11 +11,19 @@ on:
 
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.event_name }}-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{github.event_name == 'pull_request'}}
+
 jobs:
   build:
     name: Build with C++23 support enabled
     if: ${{ github.repository == 'lammps/lammps' }}
     runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 2
+      matrix:
+        idx: [ gcc, clang ]
     env:
       CCACHE_DIR: ${{ github.workspace }}/.ccache
 
@@ -29,8 +37,11 @@ jobs:
       run: |
         sudo apt-get update
         sudo apt-get install -y ccache \
-                                libeigen3-dev \
+                                clang \
                                 libcurl4-openssl-dev \
+                                libeigen3-dev \
+                                libfftw3-dev \
+                                libomp-dev \
                                 mold \
                                 mpi-default-bin \
                                 mpi-default-dev \
@@ -58,14 +69,14 @@ jobs:
         cmake -S cmake -B build \
               -C cmake/presets/most.cmake \
               -C cmake/presets/kokkos-openmp.cmake \
+              -C cmake/presets/${{ matrix.idx }}.cmake \
               -D CMAKE_CXX_STANDARD=23 \
-              -D CMAKE_CXX_COMPILER=g++ \
-              -D CMAKE_C_COMPILER=gcc \
               -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \
               -D CMAKE_C_COMPILER_LAUNCHER=ccache \
               -D CMAKE_BUILD_TYPE=Debug \
               -D CMAKE_CXX_FLAGS_DEBUG="-Og -g" \
               -D DOWNLOAD_POTENTIALS=off \
+              -D FFT=KISS \
               -D BUILD_MPI=on \
               -D BUILD_SHARED_LIBS=on \
               -D BUILD_TOOLS=off \

README

@@ -34,6 +34,7 @@ lib                        additional provided or external libraries
 potentials                 interatomic potential files
 python                     Python module for LAMMPS
 src                        source files
+third_party                Copies of thirdparty software bundled with LAMMPS
 tools                      pre- and post-processing tools
 unittest                   test programs for use with CTest
 .github                    Git and GitHub related files and tools

cmake/CMakeLists.txt

@@ -7,6 +7,10 @@ if(CMAKE_VERSION VERSION_LESS 3.20)
   message(WARNING "LAMMPS is planning to require at least CMake version 3.20 by Summer 2025. Please upgrade!")
 endif()
 ########################################
+# initialize version variables with project command
+if(POLICY CMP0048)
+  cmake_policy(SET CMP0048 NEW)
+endif()
 # set policy to silence warnings about ignoring <PackageName>_ROOT but use it
 if(POLICY CMP0074)
   cmake_policy(SET CMP0074 NEW)
@@ -27,7 +31,10 @@ endif()
 
 ########################################
 
-project(lammps CXX)
+project(lammps
+        DESCRIPTION "The LAMMPS Molecular Dynamics Simulator"
+        HOMEPAGE_URL "https://www.lammps.org"
+        LANGUAGES CXX C)
 set(SOVERSION 0)
 get_property(BUILD_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
 
@@ -44,6 +51,7 @@ set(LAMMPS_DOC_DIR        ${LAMMPS_DIR}/doc)
 set(LAMMPS_TOOLS_DIR      ${LAMMPS_DIR}/tools)
 set(LAMMPS_PYTHON_DIR     ${LAMMPS_DIR}/python)
 set(LAMMPS_POTENTIALS_DIR ${LAMMPS_DIR}/potentials)
+set(LAMMPS_THIRDPARTY_DIR ${LAMMPS_DIR}/third_party)
 
 set(LAMMPS_DOWNLOADS_URL "https://download.lammps.org" CACHE STRING "Base URL for LAMMPS downloads")
 set(LAMMPS_POTENTIALS_URL "${LAMMPS_DOWNLOADS_URL}/potentials")
@@ -105,46 +113,35 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
       set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /Qrestrict")
     endif()
     if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)
-      set(CMAKE_TUNE_DEFAULT "/QxCOMMON-AVX512")
+      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /QxCOMMON-AVX512")
     else()
-      set(CMAKE_TUNE_DEFAULT "/QxHost")
+      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /QxHost")
     endif()
   else()
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -restrict")
     if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)
-      set(CMAKE_TUNE_DEFAULT "-xCOMMON-AVX512")
+      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -xCOMMON-AVX512")
     else()
-      set(CMAKE_TUNE_DEFAULT "-xHost -fp-model fast=2 -no-prec-div -qoverride-limits -diag-disable=10441 -diag-disable=11074 -diag-disable=11076 -diag-disable=2196")
+      set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -xHost -fp-model fast=2 -no-prec-div -qoverride-limits -diag-disable=10441 -diag-disable=11074 -diag-disable=11076 -diag-disable=2196")
     endif()
   endif()
 endif()
 
 # silence excessive warnings for new Intel Compilers
 if(CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")
-  set(CMAKE_TUNE_DEFAULT "-fp-model precise -Wno-tautological-constant-compare -Wno-unused-command-line-argument")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fp-model precise -Wno-tautological-constant-compare -Wno-unused-command-line-argument")
 endif()
 
 # silence excessive warnings for PGI/NVHPC compilers
 if((CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC") OR (CMAKE_CXX_COMPILER_ID STREQUAL "PGI"))
-  set(CMAKE_TUNE_DEFAULT "-Minform=severe")
-endif()
-
-# this hack is required to compile fmt lib with CrayClang version 15.0.2
-# CrayClang is only directly recognized by version 3.28 and later
-if(CMAKE_VERSION VERSION_LESS 3.28)
-  get_filename_component(_exe "${CMAKE_CXX_COMPILER}" NAME)
-  if((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (_exe STREQUAL "crayCC"))
-    set(CMAKE_TUNE_DEFAULT "-DFMT_STATIC_THOUSANDS_SEPARATOR")
-  endif()
-else()
-  if(CMAKE_CXX_COMPILER_ID STREQUAL "CrayClang")
-    set(CMAKE_TUNE_DEFAULT "-DFMT_STATIC_THOUSANDS_SEPARATOR")
-  endif()
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Minform=severe")
 endif()
 
 # silence nvcc warnings
-if((PKG_KOKKOS) AND (Kokkos_ENABLE_CUDA) AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "Clang"))
-  set(CMAKE_TUNE_DEFAULT "${CMAKE_TUNE_DEFAULT}" "-Xcudafe --diag_suppress=unrecognized_pragma,--diag_suppress=128")
+if((PKG_KOKKOS) AND (Kokkos_ENABLE_CUDA) AND NOT
+    ((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") OR (CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")
+    OR (CMAKE_CXX_COMPILER_ID STREQUAL "XLClang") OR (CMAKE_CXX_COMPILER_ID STREQUAL "CrayClang")))
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Xcudafe --diag_suppress=unrecognized_pragma,--diag_suppress=128")
 endif()
 
 # we *require* C++11 without extensions but prefer C++17.
@@ -206,6 +203,10 @@ if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND BUILD_SHARED_LIBS)
   set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
 endif()
 
+# do not include the (obsolete) MPI C++ bindings which makes for leaner object files
+# and avoids namespace conflicts. Put this early to increase its visbility.
+set(MPI_CXX_SKIP_MPICXX TRUE CACHE BOOL "Skip MPI C++ Bindings" FORCE)
+
 ########################################################################
 # User input options                                                   #
 ########################################################################
@@ -383,12 +384,12 @@ endforeach()
 # packages with special compiler needs or external libs
 ######################################################
 target_include_directories(lammps PUBLIC $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}>)
+target_include_directories(lammps PUBLIC $<BUILD_INTERFACE:${LAMMPS_THIRDPARTY_DIR}>)
 
 if(PKG_ADIOS)
   # The search for ADIOS2 must come before MPI because
   # it includes its own MPI search with the latest FindMPI.cmake
   # script that defines the MPI::MPI_C target
-  enable_language(C)
   find_package(ADIOS2 REQUIRED)
   if(BUILD_MPI)
     if(NOT ADIOS2_HAVE_MPI)
@@ -403,21 +404,18 @@ if(PKG_ADIOS)
 endif()
 
 if(NOT CMAKE_CROSSCOMPILING)
-  find_package(MPI QUIET)
+  find_package(MPI QUIET COMPONENTS CXX)
   option(BUILD_MPI "Build MPI version" ${MPI_FOUND})
 else()
   option(BUILD_MPI "Build MPI version" OFF)
 endif()
 
 if(BUILD_MPI)
-  # do not include the (obsolete) MPI C++ bindings which makes
-  # for leaner object files and avoids namespace conflicts
-  set(MPI_CXX_SKIP_MPICXX TRUE)
   # We use a non-standard procedure to cross-compile with MPI on Windows
   if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND CMAKE_CROSSCOMPILING)
     include(MPI4WIN)
   else()
-    find_package(MPI REQUIRED)
+    find_package(MPI REQUIRED COMPONENTS CXX)
     option(LAMMPS_LONGLONG_TO_LONG "Workaround if your system or MPI version does not recognize 'long long' data types" OFF)
     if(LAMMPS_LONGLONG_TO_LONG)
       target_compile_definitions(lammps PRIVATE -DLAMMPS_LONGLONG_TO_LONG)
@@ -450,6 +448,19 @@ if(NOT ${LAMMPS_MEMALIGN} STREQUAL "0")
   target_compile_definitions(lammps PRIVATE -DLAMMPS_MEMALIGN=${LAMMPS_MEMALIGN})
 endif()
 
+# this hack is required to compile fmt lib with CrayClang version 15.0.2
+# CrayClang is only directly recognized by CMake version 3.28 and later
+if(CMAKE_VERSION VERSION_LESS 3.28)
+  get_filename_component(_exe "${CMAKE_CXX_COMPILER}" NAME)
+  if((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (_exe STREQUAL "crayCC"))
+    target_compile_definitions(lammps PRIVATE -DFMT_STATIC_THOUSANDS_SEPARATOR)
+  endif()
+else()
+  if(CMAKE_CXX_COMPILER_ID STREQUAL "CrayClang")
+    target_compile_definitions(lammps PRIVATE -DFMT_STATIC_THOUSANDS_SEPARATOR)
+  endif()
+endif()
+
 # "hard" dependencies between packages resulting
 # in an error instead of skipping over files
 pkg_depends(ML-IAP ML-SNAP)
@@ -507,13 +518,13 @@ if(BUILD_OMP)
   if(CMAKE_VERSION VERSION_LESS 3.28)
     get_filename_component(_exe "${CMAKE_CXX_COMPILER}" NAME)
     if((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (_exe STREQUAL "crayCC"))
-      set(CMAKE_SHARED_LINKER_FLAGS_${BTYPE} "${CMAKE_SHARED_LINKER_FLAGS_${BTYPE}} -fopenmp")
-      set(CMAKE_STATIC_LINKER_FLAGS_${BTYPE} "${CMAKE_STATIC_LINKER_FLAGS_${BTYPE}} -fopenmp")
+      set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -fopenmp")
+      set(CMAKE_STATIC_LINKER_FLAGS "${CMAKE_STATIC_LINKER_FLAGS} -fopenmp")
     endif()
   else()
     if(CMAKE_CXX_COMPILER_ID STREQUAL "CrayClang")
-      set(CMAKE_SHARED_LINKER_FLAGS_${BTYPE} "${CMAKE_SHARED_LINKER_FLAGS_${BTYPE}} -fopenmp")
-      set(CMAKE_STATIC_LINKER_FLAGS_${BTYPE} "${CMAKE_STATIC_LINKER_FLAGS_${BTYPE}} -fopenmp")
+      set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -fopenmp")
+      set(CMAKE_STATIC_LINKER_FLAGS "${CMAKE_STATIC_LINKER_FLAGS} -fopenmp")
     endif()
   endif()
 endif()
@@ -531,7 +542,6 @@ if((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_STANDARD GREATER_EQUA
 endif()
 
 if(PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE OR PKG_RHEO OR BUILD_TOOLS)
-  enable_language(C)
   if (NOT USE_INTERNAL_LINALG)
     find_package(LAPACK)
     find_package(BLAS)
@@ -628,10 +638,6 @@ if(WITH_SWIG)
   add_subdirectory(${LAMMPS_SWIG_DIR} swig)
 endif()
 
-set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine specific optimization flags (compilation only)")
-separate_arguments(CMAKE_TUNE_FLAGS)
-target_compile_options(lammps PRIVATE ${CMAKE_TUNE_FLAGS})
-target_compile_options(lmp PRIVATE ${CMAKE_TUNE_FLAGS})
 ########################################################################
 # Basic system tests (standard libraries, headers, functions, types)   #
 ########################################################################

cmake/Modules/LAMMPSInterfacePlugin.cmake

@@ -62,6 +62,9 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
 endif()
 set(CMAKE_POSITION_INDEPENDENT_CODE TRUE)
 
+# skip over obsolete MPI-2 C++ bindings
+set(MPI_CXX_SKIP_MPICXX TRUE)
+
 #######
 # helper functions from LAMMPSUtils.cmake
 function(validate_option name values)
@@ -128,8 +131,7 @@ endif()
 ################################################################################
 # MPI configuration
 if(NOT CMAKE_CROSSCOMPILING)
-  set(MPI_CXX_SKIP_MPICXX TRUE)
-  find_package(MPI QUIET)
+  find_package(MPI QUIET COMPONENTS CXX)
   option(BUILD_MPI "Build MPI version" ${MPI_FOUND})
 else()
   option(BUILD_MPI "Build MPI version" OFF)
@@ -141,78 +143,38 @@ if(BUILD_MPI)
   set(MPI_CXX_SKIP_MPICXX TRUE)
   # We use a non-standard procedure to cross-compile with MPI on Windows
   if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND CMAKE_CROSSCOMPILING)
-    # Download and configure MinGW compatible MPICH development files for Windows
-    option(USE_MSMPI "Use Microsoft's MS-MPI SDK instead of MPICH2-1.4.1" OFF)
-    if(USE_MSMPI)
-      message(STATUS "Downloading and configuring MS-MPI 10.1 for Windows cross-compilation")
-      set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/msmpi-win64-devel.tar.gz" CACHE STRING "URL for MS-MPI (win64) tarball")
-      set(MPICH2_WIN64_DEVEL_MD5 "86314daf1bffb809f1fcbefb8a547490" CACHE STRING "MD5 checksum of MS-MPI (win64) tarball")
-      mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
-      mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
+    message(STATUS "Downloading and configuring MS-MPI 10.1 for Windows cross-compilation")
+    set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/msmpi-win64-devel.tar.gz" CACHE STRING "URL for MS-MPI (win64) tarball")
+    set(MPICH2_WIN64_DEVEL_MD5 "86314daf1bffb809f1fcbefb8a547490" CACHE STRING "MD5 checksum of MS-MPI (win64) tarball")
+    mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
+    mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
 
-      include(ExternalProject)
-      if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
-        ExternalProject_Add(mpi4win_build
-          URL     ${MPICH2_WIN64_DEVEL_URL}
-          URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
-          CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
-          BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmsmpi.a)
-      else()
-        message(FATAL_ERROR "Only x86 64-bit builds are supported with MS-MPI")
-      endif()
-
-      ExternalProject_get_property(mpi4win_build SOURCE_DIR)
-      file(MAKE_DIRECTORY "${SOURCE_DIR}/include")
-      add_library(MPI::MPI_CXX UNKNOWN IMPORTED)
-      set_target_properties(MPI::MPI_CXX PROPERTIES
-        IMPORTED_LOCATION "${SOURCE_DIR}/lib/libmsmpi.a"
-        INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/include"
-        INTERFACE_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX")
-      add_dependencies(MPI::MPI_CXX mpi4win_build)
-
-      # set variables for status reporting at the end of CMake run
-      set(MPI_CXX_INCLUDE_PATH "${SOURCE_DIR}/include")
-      set(MPI_CXX_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX")
-      set(MPI_CXX_LIBRARIES "${SOURCE_DIR}/lib/libmsmpi.a")
+    include(ExternalProject)
+    if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
+      ExternalProject_Add(mpi4win_build
+        URL     ${MPICH2_WIN64_DEVEL_URL}
+        URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
+        CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
+        BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmsmpi.a)
     else()
-      # Download and configure custom MPICH files for Windows
-      message(STATUS "Downloading and configuring MPICH-1.4.1 for Windows")
-      set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win64-devel.tar.gz" CACHE STRING "URL for MPICH2 (win64) tarball")
-      set(MPICH2_WIN64_DEVEL_MD5 "4939fdb59d13182fd5dd65211e469f14" CACHE STRING "MD5 checksum of MPICH2 (win64) tarball")
-      mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
-      mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
-
-      include(ExternalProject)
-      if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
-        ExternalProject_Add(mpi4win_build
-          URL     ${MPICH2_WIN64_DEVEL_URL}
-          URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
-          CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
-          BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
-      else()
-        ExternalProject_Add(mpi4win_build
-          URL     ${MPICH2_WIN32_DEVEL_URL}
-          URL_MD5 ${MPICH2_WIN32_DEVEL_MD5}
-          CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
-          BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
-      endif()
-
-      ExternalProject_get_property(mpi4win_build SOURCE_DIR)
-      file(MAKE_DIRECTORY "${SOURCE_DIR}/include")
-      add_library(MPI::MPI_CXX UNKNOWN IMPORTED)
-      set_target_properties(MPI::MPI_CXX PROPERTIES
-        IMPORTED_LOCATION "${SOURCE_DIR}/lib/libmpi.a"
-        INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/include"
-        INTERFACE_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX")
-      add_dependencies(MPI::MPI_CXX mpi4win_build)
-
-      # set variables for status reporting at the end of CMake run
-      set(MPI_CXX_INCLUDE_PATH "${SOURCE_DIR}/include")
-      set(MPI_CXX_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX")
-      set(MPI_CXX_LIBRARIES "${SOURCE_DIR}/lib/libmpi.a")
+      message(FATAL_ERROR "Only x86 64-bit builds are supported with MS-MPI")
     endif()
+
+    ExternalProject_get_property(mpi4win_build SOURCE_DIR)
+    file(MAKE_DIRECTORY "${SOURCE_DIR}/include")
+    add_library(MPI::MPI_CXX UNKNOWN IMPORTED)
+    set_target_properties(MPI::MPI_CXX PROPERTIES
+      IMPORTED_LOCATION "${SOURCE_DIR}/lib/libmsmpi.a"
+      INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/include"
+      INTERFACE_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX=1")
+    add_dependencies(MPI::MPI_CXX mpi4win_build)
+
+    # set variables for status reporting at the end of CMake run
+    set(MPI_CXX_INCLUDE_PATH "${SOURCE_DIR}/include")
+    set(MPI_CXX_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX=1")
+    set(MPI_CXX_LIBRARIES "${SOURCE_DIR}/lib/libmsmpi.a")
   else()
-    find_package(MPI REQUIRED)
+    find_package(MPI REQUIRED COMPONENTS CXX)
     option(LAMMPS_LONGLONG_TO_LONG "Workaround if your system or MPI version does not recognize 'long long' data types" OFF)
     if(LAMMPS_LONGLONG_TO_LONG)
       target_compile_definitions(lammps INTERFACE -DLAMMPS_LONGLONG_TO_LONG)

cmake/Modules/LAMMPSUtils.cmake

@@ -30,7 +30,7 @@ function(check_omp_h_include)
   if(OpenMP_CXX_FOUND)
     set(CMAKE_REQUIRED_FLAGS ${OpenMP_CXX_FLAGS})
     set(CMAKE_REQUIRED_INCLUDES ${OpenMP_CXX_INCLUDE_DIRS})
-    set(CMAKE_REQUIRED_LINK_OPTIONS ${OpenMP_CXX_FLAGS})
+    separate_arguments(CMAKE_REQUIRED_LINK_OPTIONS NATIVE_COMMAND ${OpenMP_CXX_FLAGS}) # needs to be a list
     set(CMAKE_REQUIRED_LIBRARIES ${OpenMP_CXX_LIBRARIES})
     # there are all kinds of problems with finding omp.h
     # for Clang and derived compilers so we pretend it is there.
@@ -75,13 +75,25 @@ function(get_lammps_version version_header variable)
     list(FIND MONTHS "${month}" month)
     string(LENGTH ${day} day_length)
     string(LENGTH ${month} month_length)
-    if(day_length EQUAL 1)
-        set(day "0${day}")
+    # no leading zero needed for new version string with dots
+    # if(day_length EQUAL 1)
+    #   set(day "0${day}")
+    # endif()
+    # if(month_length EQUAL 1)
+    #   set(month "0${month}")
+    #endif()
+    file(STRINGS ${version_header} line REGEX LAMMPS_UPDATE)
+    string(REGEX REPLACE "#define LAMMPS_UPDATE \"Update ([0-9]+)\"" "\\1" tweak "${line}")
+    if (line MATCHES "#define LAMMPS_UPDATE \"(Maintenance|Development)\"")
+      set(tweak "99")
     endif()
-    if(month_length EQUAL 1)
-        set(month "0${month}")
+    if(NOT tweak)
+      set(tweak "0")
     endif()
-    set(${variable} "${year}${month}${day}" PARENT_SCOPE)
+    # new version string with dots
+    set(${variable} "${year}.${month}.${day}.${tweak}" PARENT_SCOPE)
+    # old version string without dots
+    # set(${variable} "${year}${month}${day}" PARENT_SCOPE)
 endfunction()
 
 function(check_for_autogen_files source_dir)

cmake/Modules/MPI4WIN.cmake

@@ -1,74 +1,31 @@
-# Download and configure MinGW compatible MPICH development files for Windows
-option(USE_MSMPI "Use Microsoft's MS-MPI SDK instead of MPICH2-1.4.1" OFF)
+# set-up MS-MPI library for Windows with MinGW compatibility
+message(STATUS "Downloading and configuring MS-MPI 10.1 for Windows cross-compilation")
+set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/msmpi-win64-devel.tar.gz" CACHE STRING "URL for MS-MPI (win64) tarball")
+set(MPICH2_WIN64_DEVEL_MD5 "86314daf1bffb809f1fcbefb8a547490" CACHE STRING "MD5 checksum of MS-MPI (win64) tarball")
+mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
+mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
 
-if(USE_MSMPI)
-  message(STATUS "Downloading and configuring MS-MPI 10.1 for Windows cross-compilation")
-  set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/msmpi-win64-devel.tar.gz" CACHE STRING "URL for MS-MPI (win64) tarball")
-  set(MPICH2_WIN64_DEVEL_MD5 "86314daf1bffb809f1fcbefb8a547490" CACHE STRING "MD5 checksum of MS-MPI (win64) tarball")
-  mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
-  mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
-
-  include(ExternalProject)
-  if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
-    ExternalProject_Add(mpi4win_build
-      URL     ${MPICH2_WIN64_DEVEL_URL}
-      URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
-      CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
-      BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmsmpi.a)
-  else()
-    message(FATAL_ERROR "Only x86 64-bit builds are supported with MS-MPI")
-  endif()
-
-  ExternalProject_get_property(mpi4win_build SOURCE_DIR)
-  file(MAKE_DIRECTORY "${SOURCE_DIR}/include")
-  add_library(MPI::MPI_CXX UNKNOWN IMPORTED)
-  set_target_properties(MPI::MPI_CXX PROPERTIES
-    IMPORTED_LOCATION "${SOURCE_DIR}/lib/libmsmpi.a"
-    INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/include"
-    INTERFACE_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX")
-  add_dependencies(MPI::MPI_CXX mpi4win_build)
-
-  # set variables for status reporting at the end of CMake run
-  set(MPI_CXX_INCLUDE_PATH "${SOURCE_DIR}/include")
-  set(MPI_CXX_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX")
-  set(MPI_CXX_LIBRARIES "${SOURCE_DIR}/lib/libmsmpi.a")
+include(ExternalProject)
+if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
+  ExternalProject_Add(mpi4win_build
+    URL     ${MPICH2_WIN64_DEVEL_URL}
+    URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
+    CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
+    BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmsmpi.a)
 else()
-  message(STATUS "Downloading and configuring MPICH2-1.4.1 for Windows cross-compilation")
-  set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win64-devel.tar.gz" CACHE STRING "URL for MPICH2 (win64) tarball")
-  set(MPICH2_WIN32_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win32-devel.tar.gz" CACHE STRING "URL for MPICH2 (win32) tarball")
-  set(MPICH2_WIN64_DEVEL_MD5 "4939fdb59d13182fd5dd65211e469f14" CACHE STRING "MD5 checksum of MPICH2 (win64) tarball")
-  set(MPICH2_WIN32_DEVEL_MD5 "a61d153500dce44e21b755ee7257e031" CACHE STRING "MD5 checksum of MPICH2 (win32) tarball")
-  mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
-  mark_as_advanced(MPICH2_WIN32_DEVEL_URL)
-  mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
-  mark_as_advanced(MPICH2_WIN32_DEVEL_MD5)
-
-  include(ExternalProject)
-  if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
-    ExternalProject_Add(mpi4win_build
-      URL     ${MPICH2_WIN64_DEVEL_URL}
-      URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
-      CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
-      BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
-  else()
-    ExternalProject_Add(mpi4win_build
-      URL     ${MPICH2_WIN32_DEVEL_URL}
-      URL_MD5 ${MPICH2_WIN32_DEVEL_MD5}
-      CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
-      BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
-  endif()
-
-  ExternalProject_get_property(mpi4win_build SOURCE_DIR)
-  file(MAKE_DIRECTORY "${SOURCE_DIR}/include")
-  add_library(MPI::MPI_CXX UNKNOWN IMPORTED)
-  set_target_properties(MPI::MPI_CXX PROPERTIES
-    IMPORTED_LOCATION "${SOURCE_DIR}/lib/libmpi.a"
-    INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/include"
-    INTERFACE_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX")
-  add_dependencies(MPI::MPI_CXX mpi4win_build)
-
-  # set variables for status reporting at the end of CMake run
-  set(MPI_CXX_INCLUDE_PATH "${SOURCE_DIR}/include")
-  set(MPI_CXX_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX")
-  set(MPI_CXX_LIBRARIES "${SOURCE_DIR}/lib/libmpi.a")
+  message(FATAL_ERROR "Only x86 64-bit builds are supported with MS-MPI")
 endif()
+
+ExternalProject_get_property(mpi4win_build SOURCE_DIR)
+file(MAKE_DIRECTORY "${SOURCE_DIR}/include")
+add_library(MPI::MPI_CXX UNKNOWN IMPORTED)
+set_target_properties(MPI::MPI_CXX PROPERTIES
+  IMPORTED_LOCATION "${SOURCE_DIR}/lib/libmsmpi.a"
+  INTERFACE_INCLUDE_DIRECTORIES "${SOURCE_DIR}/include"
+  INTERFACE_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX=1")
+add_dependencies(MPI::MPI_CXX mpi4win_build)
+
+# set variables for status reporting at the end of CMake run
+set(MPI_CXX_INCLUDE_PATH "${SOURCE_DIR}/include")
+set(MPI_CXX_COMPILE_DEFINITIONS "MPICH_SKIP_MPICXX=1")
+set(MPI_CXX_LIBRARIES "${SOURCE_DIR}/lib/libmsmpi.a")

cmake/Modules/Packages/COLVARS.cmake

@@ -14,10 +14,6 @@ endif()
 
 add_library(colvars STATIC ${COLVARS_SOURCES})
 target_compile_definitions(colvars PRIVATE -DCOLVARS_LAMMPS)
-separate_arguments(CMAKE_TUNE_FLAGS)
-foreach(_FLAG ${CMAKE_TUNE_FLAGS})
-  target_compile_options(colvars PRIVATE ${_FLAG})
-endforeach()
 set_target_properties(colvars PROPERTIES OUTPUT_NAME lammps_colvars${LAMMPS_MACHINE})
 target_include_directories(colvars PUBLIC ${LAMMPS_LIB_SOURCE_DIR}/colvars)
 # The line below is needed to locate math_eigen_impl.h
@@ -30,6 +26,10 @@ if(BUILD_OMP)
   target_link_libraries(colvars PRIVATE OpenMP::OpenMP_CXX)
 endif()
 
+if(BUILD_MPI)
+  target_link_libraries(colvars PUBLIC MPI::MPI_CXX)
+endif()
+
 if(COLVARS_DEBUG)
   # Need to export the define publicly to be valid in interface code
   target_compile_definitions(colvars PUBLIC -DCOLVARS_DEBUG)

cmake/Modules/Packages/EXTRA-COMMAND.cmake

@@ -1,10 +1,18 @@
 # the geturl command needs libcurl
 
-find_package(CURL QUIET COMPONENTS HTTP HTTPS)
+find_package(CURL QUIET)
 option(WITH_CURL "Enable libcurl support" ${CURL_FOUND})
 if(WITH_CURL)
-  find_package(CURL REQUIRED COMPONENTS HTTP HTTPS)
   target_compile_definitions(lammps PRIVATE -DLAMMPS_CURL)
-  target_link_libraries(lammps PRIVATE CURL::libcurl)
+
+  # need to use pkgconfig for fully static bins to find custom static libs
+  if (CMAKE_SYSTEM_NAME STREQUAL "LinuxMUSL")
+    include(FindPkgConfig)
+    pkg_check_modules(CURL IMPORTED_TARGET libcurl libssl libcrypto)
+    target_link_libraries(lammps PUBLIC PkgConfig::CURL)
+  else()
+    find_package(CURL REQUIRED)
+    target_link_libraries(lammps PRIVATE CURL::libcurl)
+  endif()
 endif()
 

cmake/Modules/Packages/GPU.cmake

@@ -189,7 +189,7 @@ if(GPU_API STREQUAL "CUDA")
   endif()
 
   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_compile_definitions(nvc_get_devices PRIVATE -DUCL_CUDADR -DLAMMPS_${LAMMPS_SIZES})
   target_link_libraries(nvc_get_devices PRIVATE ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
   target_include_directories(nvc_get_devices PRIVATE ${CUDA_INCLUDE_DIRS})
 
@@ -489,7 +489,7 @@ else()
   target_link_libraries(gpu PRIVATE mpi_stubs)
 endif()
 
-target_compile_definitions(gpu PRIVATE -DLAMMPS_${LAMMPS_SIZES})
 set_target_properties(gpu PROPERTIES OUTPUT_NAME lammps_gpu${LAMMPS_MACHINE})
+target_compile_definitions(gpu PRIVATE -DLAMMPS_${LAMMPS_SIZES})
 target_sources(lammps PRIVATE ${GPU_SOURCES})
 target_include_directories(lammps PRIVATE ${GPU_SOURCES_DIR})

cmake/Modules/Packages/MC.cmake

@@ -7,3 +7,13 @@ if(NOT PKG_MANYBODY)
   list(REMOVE_ITEM LAMMPS_SOURCES ${LAMMPS_SOURCE_DIR}/MC/fix_sgcmc.cpp)
   set_property(TARGET lammps PROPERTY SOURCES "${LAMMPS_SOURCES}")
 endif()
+
+# fix neighbor/swap may only be installed if also the VORONOI package is installed
+if(NOT PKG_VORONOI)
+  get_property(LAMMPS_FIX_HEADERS GLOBAL PROPERTY FIX)
+  list(REMOVE_ITEM LAMMPS_FIX_HEADERS ${LAMMPS_SOURCE_DIR}/MC/fix_neighbor_swap.h)
+  set_property(GLOBAL PROPERTY FIX "${LAMMPS_FIX_HEADERS}")
+  get_target_property(LAMMPS_SOURCES lammps SOURCES)
+  list(REMOVE_ITEM LAMMPS_SOURCES ${LAMMPS_SOURCE_DIR}/MC/fix_neighbor_swap.cpp)
+  set_property(TARGET lammps PROPERTY SOURCES "${LAMMPS_SOURCES}")
+endif()

cmake/Modules/Packages/SCAFACOS.cmake

@@ -14,27 +14,16 @@ endif()
 option(DOWNLOAD_SCAFACOS "Download ScaFaCoS library instead of using an already installed one" ${DOWNLOAD_SCAFACOS_DEFAULT})
 if(DOWNLOAD_SCAFACOS)
   message(STATUS "ScaFaCoS download requested - we will build our own")
-  set(SCAFACOS_URL "https://github.com/scafacos/scafacos/releases/download/v1.0.1/scafacos-1.0.1.tar.gz" CACHE STRING "URL for SCAFACOS tarball")
-  set(SCAFACOS_MD5 "bd46d74e3296bd8a444d731bb10c1738" CACHE STRING "MD5 checksum of SCAFACOS tarball")
+  set(SCAFACOS_URL "https://github.com/scafacos/scafacos/releases/download/v1.0.4/scafacos-1.0.4.tar.gz" CACHE STRING "URL for SCAFACOS tarball")
+  set(SCAFACOS_MD5 "23867540ec32e63ce71d6ecc105278d2" CACHE STRING "MD5 checksum of SCAFACOS tarball")
   mark_as_advanced(SCAFACOS_URL)
   mark_as_advanced(SCAFACOS_MD5)
   GetFallbackURL(SCAFACOS_URL SCAFACOS_FALLBACK)
 
-
-  # version 1.0.1 needs a patch to compile and linke cleanly with GCC 10 and later.
-  file(DOWNLOAD ${LAMMPS_THIRDPARTY_URL}/scafacos-1.0.1-fix.diff ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
-          EXPECTED_HASH MD5=4baa1333bb28fcce102d505e1992d032)
-
-  find_program(HAVE_PATCH patch)
-  if(NOT HAVE_PATCH)
-    message(FATAL_ERROR "The 'patch' program is required to build the ScaFaCoS library")
-  endif()
-
   include(ExternalProject)
   ExternalProject_Add(scafacos_build
     URL     ${SCAFACOS_URL} ${SCAFACOS_FALLBACK}
     URL_MD5 ${SCAFACOS_MD5}
-    PATCH_COMMAND patch -p1 < ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
     CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR> --disable-doc
                                              --enable-fcs-solvers=fmm,p2nfft,direct,ewald,p3m
                                              --with-internal-fftw --with-internal-pfft

cmake/Modules/Testing.cmake

@@ -21,11 +21,11 @@ if(ENABLE_TESTING)
   # also only verified with Fedora Linux > 30 and Ubuntu 18.04 or 22.04+(Ubuntu 20.04 fails)
   if((CMAKE_SYSTEM_NAME STREQUAL "Linux")
       AND ((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") OR (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")))
-    if(((CMAKE_LINUX_DISTRO STREQUAL "Ubuntu") AND
-          ((CMAKE_DISTRO_VERSION VERSION_LESS_EQUAL 18.04) OR (CMAKE_DISTRO_VERSION VERSION_GREATER_EQUAL 22.04)))
+    if(((CMAKE_LINUX_DISTRO STREQUAL "Ubuntu") AND (CMAKE_DISTRO_VERSION VERSION_GREATER_EQUAL 22.04))
         OR ((CMAKE_LINUX_DISTRO STREQUAL "Fedora") AND (CMAKE_DISTRO_VERSION VERSION_GREATER 30)))
       include(CheckCXXCompilerFlag)
       set(CMAKE_CUSTOM_LINKER_DEFAULT default)
+      check_cxx_compiler_flag(--ld-path=${CMAKE_LINKER} HAVE_LD_PATH_FLAG)
       check_cxx_compiler_flag(-fuse-ld=mold HAVE_MOLD_LINKER_FLAG)
       check_cxx_compiler_flag(-fuse-ld=lld HAVE_LLD_LINKER_FLAG)
       check_cxx_compiler_flag(-fuse-ld=gold HAVE_GOLD_LINKER_FLAG)
@@ -50,6 +50,17 @@ if(ENABLE_TESTING)
       if(NOT "${CMAKE_CUSTOM_LINKER}" STREQUAL "default")
         target_link_options(lammps PUBLIC -fuse-ld=${CMAKE_CUSTOM_LINKER})
       endif()
+      if(HAVE_LD_PATH_FLAG)
+        if("${CMAKE_CUSTOM_LINKER}" STREQUAL "mold")
+          target_link_options(lammps PUBLIC --ld-path=${HAVE_MOLD_LINKER_BIN})
+        elseif("${CMAKE_CUSTOM_LINKER}" STREQUAL "lld")
+          target_link_options(lammps PUBLIC --ld-path=${HAVE_LLD_LINKER_BIN})
+        elseif("${CMAKE_CUSTOM_LINKER}" STREQUAL "gold")
+          target_link_options(lammps PUBLIC --ld-path=${HAVE_GOLD_LINKER_BIN})
+        elseif("${CMAKE_CUSTOM_LINKER}" STREQUAL "bfd")
+          target_link_options(lammps PUBLIC --ld-path=${HAVE_BFD_LINKER_BIN})
+        endif()
+      endif()
     endif()
   endif()
 

cmake/Modules/Tools.cmake

@@ -6,6 +6,10 @@ if(BUILD_TOOLS)
   add_executable(stl_bin2txt ${LAMMPS_TOOLS_DIR}/stl_bin2txt.cpp)
   install(TARGETS stl_bin2txt DESTINATION ${CMAKE_INSTALL_BINDIR})
 
+  add_executable(reformat-json ${LAMMPS_TOOLS_DIR}/json/reformat-json.cpp)
+  target_include_directories(reformat-json PRIVATE ${LAMMPS_SOURCE_DIR})
+  install(TARGETS reformat-json DESTINATION ${CMAKE_INSTALL_BINDIR})
+
   include(CheckGeneratorSupport)
   if(CMAKE_GENERATOR_SUPPORT_FORTRAN)
     include(CheckLanguage)

cmake/presets/hip_amd.cmake

@@ -19,12 +19,19 @@ set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
 
 set(MPI_CXX "hipcc" CACHE STRING "" FORCE)
 set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
+set(MPI_C "hipcc" CACHE STRING "" FORCE)
+set(MPI_C_COMPILER "mpicc" CACHE STRING "" FORCE)
+
+# change as needed. This is for Fedora Linux 41 and 42
+set(_libomp_root "/usr/lib/clang/18")
+# we need to explicitly specify the include dir, since hipcc will
+# compile each file twice and doesn't find omp.h the second time
 
 unset(HAVE_OMP_H_INCLUDE CACHE)
 set(OpenMP_C "hipcc" CACHE STRING "" FORCE)
-set(OpenMP_C_FLAGS "-fopenmp" CACHE STRING "" FORCE)
+set(OpenMP_C_FLAGS "-fopenmp=libomp -I${_libomp_root}/include" CACHE STRING "" FORCE)
 set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
 set(OpenMP_CXX "hipcc" CACHE STRING "" FORCE)
-set(OpenMP_CXX_FLAGS "-fopenmp" CACHE STRING "" FORCE)
+set(OpenMP_CXX_FLAGS "-fopenmp=libomp -I${_libomp_root}/include" CACHE STRING "" FORCE)
 set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
 set(OpenMP_omp_LIBRARY "libomp.so" CACHE PATH "" FORCE)

cmake/presets/kokkos-cuda.cmake

@@ -1,9 +1,8 @@
 # preset that enables KOKKOS and selects CUDA compilation with OpenMP
-# enabled as well. The GPU architecture *must* match your hardware
+# enabled as well. The GPU architecture *must* match your hardware (If not manually set, Kokkos will try to autodetect it).
 set(PKG_KOKKOS ON CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_SERIAL ON CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_CUDA   ON CACHE BOOL "" FORCE)
-set(Kokkos_ARCH_PASCAL60 ON CACHE BOOL "" FORCE)
 set(BUILD_OMP ON CACHE BOOL "" FORCE)
 get_filename_component(NVCC_WRAPPER_CMD ${CMAKE_CURRENT_SOURCE_DIR}/../lib/kokkos/bin/nvcc_wrapper ABSOLUTE)
 set(CMAKE_CXX_COMPILER ${NVCC_WRAPPER_CMD} CACHE FILEPATH "" FORCE)

cmake/presets/kokkos-hip.cmake

@@ -1,22 +1,21 @@
-# preset that enables KOKKOS and selects HIP compilation with OpenMP
-# enabled as well. Also sets some performance related compiler flags.
+# preset that enables KOKKOS and selects HIP compilation withOUT OpenMP.
+# Kokkos OpenMP is not compatible with the second pass of hipcc.
 set(PKG_KOKKOS ON CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_SERIAL ON CACHE BOOL "" FORCE)
-set(Kokkos_ENABLE_OPENMP ON CACHE BOOL "" FORCE)
+set(Kokkos_ENABLE_OPENMP OFF CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_CUDA   OFF CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_HIP    ON CACHE BOOL "" FORCE)
 set(Kokkos_ARCH_VEGA90A on CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_HIP_MULTIPLE_KERNEL_INSTANTIATIONS ON CACHE BOOL "" FORCE)
 set(BUILD_OMP ON CACHE BOOL "" FORCE)
 
-set(CMAKE_CXX_COMPILER hipcc CACHE STRING "" FORCE)
-set(CMAKE_TUNE_FLAGS "-munsafe-fp-atomics" CACHE STRING "" FORCE)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -munsafe-fp-atomics" CACHE STRING "" FORCE)
 
-# If KSPACE is also enabled, use CUFFT for FFTs
+# If KSPACE is also enabled, use HIPFFT for FFTs
 set(FFT_KOKKOS "HIPFFT" CACHE STRING "" FORCE)
 
 # hide deprecation warnings temporarily for stable release
-set(Kokkos_ENABLE_DEPRECATION_WARNINGS OFF CACHE BOOL "" FORCE)
+#set(Kokkos_ENABLE_DEPRECATION_WARNINGS OFF CACHE BOOL "" FORCE)
 
 # these flags are needed to build with Cray MPICH on OLCF Crusher
 #-D CMAKE_CXX_FLAGS="-I/${MPICH_DIR}/include"

cmake/presets/kokkos-sycl-intel.cmake

@@ -21,9 +21,10 @@ set(CMAKE_C_COMPILER icx CACHE STRING "" FORCE)
 set(CMAKE_Fortran_COMPILER "" CACHE STRING "" FORCE)
 set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
 set(CMAKE_CXX_STANDARD 17 CACHE STRING "" FORCE)
-# Silence everything
-set(CMAKE_CXX_FLAGS "-w" CACHE STRING "" FORCE)
+
+# set(_intel_sycl_flags " -w -fsycl -flink-huge-device-code -fsycl-targets=spir64_gen "
+set(_intel_sycl_flags " -w -fsycl -fsycl-device-code-split=per_kernel -fsycl-targets=spir64_gen ")
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${_intel_sycl_flags}" CACHE STRING "" FORCE)
+
 #set(CMAKE_EXE_LINKER_FLAGS "-fsycl -flink-huge-device-code -fsycl-targets=spir64_gen " CACHE STRING "" FORCE)
-#set(CMAKE_TUNE_FLAGS "-O3 -fsycl -fsycl-device-code-split=per_kernel -fsycl-targets=spir64_gen" CACHE STRING "" FORCE)
-set(CMAKE_EXE_LINKER_FLAGS "-fsycl -flink-huge-device-code " CACHE STRING "" FORCE)
-set(CMAKE_TUNE_FLAGS "-O3 -fsycl -fsycl-device-code-split=per_kernel " CACHE STRING "" FORCE)
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fsycl -flink-huge-device-code " CACHE STRING "" FORCE)

cmake/presets/kokkos-sycl-nvidia.cmake

@@ -14,5 +14,7 @@ set(Kokkos_ENABLE_DEPRECATION_WARNINGS OFF CACHE BOOL "" FORCE)
 set(CMAKE_CXX_COMPILER clang++ CACHE STRING "" FORCE)
 set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
 set(CMAKE_CXX_STANDARD 17 CACHE STRING "" FORCE)
-set(CMAKE_SHARED_LINKER_FLAGS "-Xsycl-target-frontend -O3" CACHE STRING "" FORCE)
-set(CMAKE_TUNE_FLAGS "-fgpu-inline-threshold=100000 -Xsycl-target-frontend -O3  -Xsycl-target-frontend -ffp-contract=on -Wno-unknown-cuda-version" CACHE STRING "" FORCE)
+set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Xsycl-target-frontend -O3 " CACHE STRING "" FORCE)
+
+set(_intel_sycl_flags "-fgpu-inline-threshold=100000 -Xsycl-target-frontend -O3  -Xsycl-target-frontend -ffp-contract=on -Wno-unknown-cuda-version")
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${_intel_sycl_flags}" CACHE STRING "" FORCE)

cmake/presets/mingw-cross.cmake

@@ -91,7 +91,7 @@ endif()
 set(DOWNLOAD_VORO ON CACHE BOOL "" FORCE)
 set(DOWNLOAD_EIGEN3 ON CACHE BOOL "" FORCE)
 set(LAMMPS_MEMALIGN "0" CACHE STRING "" FORCE)
-set(CMAKE_TUNE_FLAGS "-Wno-missing-include-dirs" CACHE STRING "" FORCE)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-missing-include-dirs" CACHE STRING "" FORCE)
 set(CMAKE_EXE_LINKER_FLAGS "-Wl,--enable-stdcall-fixup,--as-needed,-lssp" CACHE STRING "" FORCE)
 set(CMAKE_SHARED_LINKER_FLAGS "-Wl,--enable-stdcall-fixup,--as-needed,-lssp" CACHE STRING "" FORCE)
 set(BUILD_TOOLS ON CACHE BOOL "" FORCE)

cmake/presets/windows-intel-llvm.cmake

@@ -5,4 +5,4 @@ set(CMAKE_C_COMPILER "icx" CACHE STRING "" FORCE)
 set(CMAKE_Fortran_COMPILER "ifx" CACHE STRING "" FORCE)
 set(INTEL_LRT_MODE "C++11" CACHE STRING "" FORCE)
 unset(HAVE_OMP_H_INCLUDE CACHE)
-set(CMAKE_TUNE_FLAGS -Wno-unused-command-line-argument)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-unused-command-line-argument" CACHE STRING "" FORCE)

doc/graphviz/lammps-releases.dot

@@ -5,13 +5,13 @@ digraph releases {
     github -> develop [label="Merge commits"];
     {
         rank = "same";
-        work [shape="none" label="Development branches:"]
+        work [shape="none" label="Development branches:" fontname="bold"]
         develop [label="'develop' branch" height=0.75];
         maintenance [label="'maintenance' branch" height=0.75];
     };
     {
         rank = "same";
-        upload [shape="none" label="Release branches:"]
+        upload [shape="none" label="Release branches:" fontname="bold"]
         release [label="'release' branch" height=0.75];
         stable [label="'stable' branch" height=0.75];
     };
@@ -22,7 +22,7 @@ digraph releases {
     maintenance -> stable [label="Updates to stable release"];
     {
         rank = "same";
-        tag [shape="none" label="Applied tags:"];
+        tag [shape="none" label="Applied tags:" fontname="bold"];
         patchtag [shape="box" label="patch_<date>"];
         stabletag [shape="box" label="stable_<date>"];
         updatetag [shape="box" label="stable_<date>_update<num>"];

doc/lammps.1

@@ -1,7 +1,7 @@
-.TH LAMMPS "1" "2 April 2025" "2025-04-02"
+.TH LAMMPS "1" "12 June 2025" "2025-06-12"
 .SH NAME
 .B LAMMPS
-\- Molecular Dynamics Simulator.  Version 2 April 2025
+\- Molecular Dynamics Simulator.  Version 12 June 2025
 
 .SH SYNOPSIS
 .B lmp

doc/src/Build.rst

@@ -14,32 +14,10 @@ As an alternative, you can download a package with pre-built executables
 or automated build trees, as described in the :doc:`Install <Install>`
 section of the manual.
 
-Prerequisites
--------------
-
-Which software you need to compile and use LAMMPS strongly depends on
-which :doc:`features and settings <Build_settings>` and which
-:doc:`optional packages <Packages_list>` you are trying to include.
-Common to all is that you need a C++ and C compiler, where the C++
-compiler has to support at least the C++11 standard (note that some
-compilers require command-line flag to activate C++11 support).
-Furthermore, if you are building with CMake, you need at least CMake
-version 3.20 and a compatible build tool (make or ninja-build); if you
-are building the the legacy GNU make based build system you need GNU
-make (other make variants are not going to work since the build system
-uses features unique to GNU make) and a Unix-like build environment with
-a Bourne shell, and shell tools like "sed", "grep", "touch", "test",
-"tr", "cp", "mv", "rm", "ln", "diff" and so on. Parts of LAMMPS
-interface with or use Python version 3.6 or later.
-
-The LAMMPS developers aim to keep LAMMPS very portable and usable -
-at least in parts - on most operating systems commonly used for
-running MD simulations.  Please see the :doc:`section on portablility
-<Intro_portability>` for more details.
-
 .. toctree::
    :maxdepth: 1
 
+   Build_prerequisites
    Build_cmake
    Build_make
    Build_link

doc/src/Build_basics.rst

@@ -212,11 +212,7 @@ LAMMPS.
       You can tell CMake to look for a specific compiler with setting
       CMake variables (listed below) during configuration.  For a few
       common choices, there are also presets in the ``cmake/presets``
-      folder.  For convenience, there is a ``CMAKE_TUNE_FLAGS`` variable
-      that can be set to apply global compiler options (applied to
-      compilation only), to be used for adding compiler or host specific
-      optimization flags in addition to the "flags" variables listed
-      below. You may also specify the corresponding ``CMAKE_*_FLAGS``
+      folder.  You may also specify the corresponding ``CMAKE_*_FLAGS``
       variables individually, if you want to experiment with alternate
       optimization flags.  You should specify all 3 compilers, so that
       the (few) LAMMPS source files written in C or Fortran are built
@@ -266,10 +262,6 @@ LAMMPS.
       ``-C ../cmake/presets/pgi.cmake`` will switch the compiler to the PGI compilers,
       and ``-C ../cmake/presets/nvhpc.cmake`` will switch to the NVHPC compilers.
 
-      Furthermore, you can set ``CMAKE_TUNE_FLAGS`` to specifically add
-      compiler flags to tune for optimal performance on given hosts.
-      This variable is empty by default.
-
       .. note::
 
          When the cmake command completes, it prints a summary to the

doc/src/Build_prerequisites.rst

@@ -0,0 +1,22 @@
+Prerequisites
+-------------
+
+Which software you need to compile and use LAMMPS strongly depends on
+which :doc:`features and settings <Build_settings>` and which
+:doc:`optional packages <Packages_list>` you are trying to include.
+Common to all is that you need a C++ and C compiler, where the C++
+compiler has to support at least the C++11 standard (note that some
+compilers require command-line flag to activate C++11 support).
+Furthermore, if you are building with CMake, you need at least CMake
+version 3.20 and a compatible build tool (make or ninja-build); if you
+are building the the legacy GNU make based build system you need GNU
+make (other make variants are not going to work since the build system
+uses features unique to GNU make) and a Unix-like build environment with
+a Bourne shell, and shell tools like "sed", "grep", "touch", "test",
+"tr", "cp", "mv", "rm", "ln", "diff" and so on. Parts of LAMMPS
+interface with or use Python version 3.6 or later.
+
+The LAMMPS developers aim to keep LAMMPS very portable and usable -
+at least in parts - on most operating systems commonly used for
+running MD simulations.  Please see the :doc:`section on portablility
+<Intro_portability>` for more details.

doc/src/Build_settings.rst

@@ -18,7 +18,6 @@ explains how to do this for building both with CMake and make.
 * `Memory allocation alignment`_
 * `Workaround for long long integers`_
 * `Exception handling when using LAMMPS as a library`_ to capture errors
-* `Trigger selected floating-point exceptions`_
 
 ----------
 
@@ -659,40 +658,3 @@ code has to be set up to *catch* exceptions thrown from within LAMMPS.
    throw an exception and thus other MPI ranks may get stuck waiting for
    messages from the ones with errors.
 
-----------
-
-.. _trap_fpe:
-
-Trigger selected floating-point exceptions
-------------------------------------------
-
-Many kinds of CPUs have the capability to detect when a calculation
-results in an invalid math operation, like a division by zero or calling
-the square root with a negative argument.  The default behavior on
-most operating systems is to continue and have values for ``NaN`` (= not
-a number) or ``Inf`` (= infinity).  This allows software to detect and
-recover from such conditions.  This behavior can be changed, however,
-often through use of compiler flags.  On Linux systems (or more general
-on systems using the GNU C library), these so-called floating-point traps
-can also be selectively enabled through library calls.  LAMMPS supports
-that by setting the ``-DLAMMPS_TRAP_FPE`` pre-processor define.  As it is
-done in the ``main()`` function, this applies only to the standalone
-executable, not the library.
-
-.. tabs::
-
-   .. tab:: CMake build
-
-      .. code-block:: bash
-
-         -D CMAKE_TUNE_FLAGS=-DLAMMPS_TRAP_FPE
-
-   .. tab:: Traditional make
-
-      .. code-block:: make
-
-         LMP_INC = -DLAMMPS_TRAP_FPE  <other LMP_INC settings>
-
-After compilation with this flag set, the LAMMPS executable will stop
-and produce a core dump when a division by zero, overflow, illegal math
-function argument or other invalid floating point operation is encountered.

doc/src/Commands_fix.rst

@@ -29,6 +29,7 @@ OPT.
    * :doc:`ave/grid <fix_ave_grid>`
    * :doc:`ave/histo <fix_ave_histo>`
    * :doc:`ave/histo/weight <fix_ave_histo>`
+   * :doc:`ave/moments <fix_ave_moments>`
    * :doc:`ave/time <fix_ave_time>`
    * :doc:`aveforce <fix_aveforce>`
    * :doc:`balance <fix_balance>`
@@ -77,6 +78,7 @@ OPT.
    * :doc:`flow/gauss <fix_flow_gauss>`
    * :doc:`freeze (k) <fix_freeze>`
    * :doc:`gcmc <fix_gcmc>`
+   * :doc:`gjf <fix_gjf>`
    * :doc:`gld <fix_gld>`
    * :doc:`gle <fix_gle>`
    * :doc:`gravity (ko) <fix_gravity>`
@@ -216,6 +218,7 @@ OPT.
    * :doc:`rigid/small (o) <fix_rigid>`
    * :doc:`rx (k) <fix_rx>`
    * :doc:`saed/vtk <fix_saed_vtk>`
+   * :doc:`set <fix_set>`
    * :doc:`setforce (k) <fix_setforce>`
    * :doc:`setforce/spin <fix_setforce>`
    * :doc:`sgcmc <fix_sgcmc>`

doc/src/Commands_kspace.rst

@@ -31,3 +31,5 @@ OPT.
    * :doc:`pppm/dielectric <kspace_style>`
    * :doc:`pppm/electrode (i) <kspace_style>`
    * :doc:`scafacos <kspace_style>`
+   * :doc:`zero <kspace_style>`
+

doc/src/Commands_pair.rst

@@ -179,6 +179,7 @@ OPT.
    * :doc:`lj/long/dipole/long <pair_dipole>`
    * :doc:`lj/long/tip4p/long (o) <pair_lj_long>`
    * :doc:`lj/mdf <pair_mdf>`
+   * :doc:`lj/pirani (o) <pair_lj_pirani>`
    * :doc:`lj/relres (o) <pair_lj_relres>`
    * :doc:`lj/spica (gko) <pair_spica>`
    * :doc:`lj/spica/coul/long (gko) <pair_spica>`

doc/src/Commands_removed.rst

@@ -1,7 +1,7 @@
 Removed commands and packages
 =============================
 
-.. contents:: \
+.. contents::
 
 ------
 
@@ -12,10 +12,21 @@ stop LAMMPS and print a suitable error message in most cases, when a
 style/command is used that has been removed or will replace the command
 with the direct alternative (if available) and print a warning.
 
+GJF formulation in fix langevin
+-------------------------------
+
+.. deprecated:: 12Jun2025
+
+The *gjf* keyword in fix langevin is deprecated and will be removed
+soon.  The GJF functionality has been moved to its own fix style
+:doc:`fix gjf <fix_gjf>` and it is strongly recommended to use that
+fix instead.
+
+
 LAMMPS shell
 ------------
 
-.. versionchanged:: 29Aug2024
+.. deprecated:: 29Aug2024
 
 The LAMMPS shell has been removed from the LAMMPS distribution. Users
 are encouraged to use the :ref:`LAMMPS-GUI <lammps_gui>` tool instead.
@@ -23,7 +34,7 @@ are encouraged to use the :ref:`LAMMPS-GUI <lammps_gui>` tool instead.
 i-PI tool
 ---------
 
-.. versionchanged:: 27Jun2024
+.. deprecated:: 27Jun2024
 
 The i-PI tool has been removed from the LAMMPS distribution.  Instead,
 instructions to install i-PI from PyPI via pip are provided.

doc/src/Developer_plugins.rst

@@ -68,24 +68,25 @@ Members of ``lammpsplugin_t``
    * - author
      - String with the name and email of the author
    * - creator.v1
-     - Pointer to factory function for pair, bond, angle, dihedral, improper, kspace, or command styles
+     - Pointer to factory function for pair, bond, angle, dihedral, improper, kspace, command, or minimize styles
    * - creator.v2
-     - Pointer to factory function for compute, fix, or region styles
+     - Pointer to factory function for compute, fix, region, or run styles
    * - handle
      - Pointer to the open DSO file handle
 
 Only one of the two alternate creator entries can be used at a time and
 which of those is determined by the style of plugin. The "creator.v1"
 element is for factory functions of supported styles computing forces
-(i.e. pair, bond, angle, dihedral, or improper styles) or command styles
-and the function takes as single argument the pointer to the LAMMPS
-instance. The factory function is cast to the ``lammpsplugin_factory1``
-type before assignment.  The "creator.v2" element is for factory
-functions creating an instance of a fix, compute, or region style and
-takes three arguments: a pointer to the LAMMPS instance, an integer with
-the length of the argument list and a ``char **`` pointer to the list of
-arguments. The factory function pointer needs to be cast to the
-``lammpsplugin_factory2`` type before assignment.
+(i.e. pair, bond, angle, dihedral, or improper styles), command styles,
+or minimize styles and the function takes as single argument the pointer
+to the LAMMPS instance. The factory function is cast to the
+``lammpsplugin_factory1`` type before assignment.  The "creator.v2"
+element is for factory functions creating an instance of a fix, compute,
+region, or run style and takes three arguments: a pointer to the LAMMPS
+instance, an integer with the length of the argument list and a ``char
+**`` pointer to the list of arguments. The factory function pointer
+needs to be cast to the ``lammpsplugin_factory2`` type before
+assignment.
 
 Pair style example
 ^^^^^^^^^^^^^^^^^^
@@ -247,8 +248,8 @@ DSO handle.  The registration function is called with a pointer to the address
 of this struct and the pointer of the LAMMPS class.  The registration function
 will then add the factory function of the plugin style to the respective
 style map under the provided name.  It will also make a copy of the struct
-in a list of all loaded plugins and update the reference counter for loaded
-plugins from this specific DSO file.
+in a global list of all loaded plugins and update the reference counter for
+loaded plugins from this specific DSO file.
 
 The pair style itself (i.e. the PairMorse2 class in this example) can be
 written just like any other pair style that is included in LAMMPS.  For
@@ -263,6 +264,21 @@ the plugin will override the existing code.  This can be used to modify
 the behavior of existing styles or to debug new versions of them without
 having to re-compile or re-install all of LAMMPS.
 
+.. versionchanged:: 12Jun2025
+
+When using the :doc:`clear <clear>` command, plugins are not unloaded
+but restored to their respective style maps.  This also applies when
+multiple LAMMPS instances are created and deleted through the library
+interface.  The :doc:`plugin load <plugin>` load command may be issued
+again, but for existing plugins they will be skipped.  To replace
+plugins they must be explicitly unloaded with :doc:`plugin unload
+<plugin>`.  When multiple LAMMPS instances are created concurrently, any
+loaded plugins will be added to the global list of plugins, but are not
+immediately available to any LAMMPS instance that was created before
+loading the plugin.  To "import" such plugins, the :doc:`plugin restore
+<plugin>` may be used.  Plugins are only removed when they are explicitly
+unloaded or the LAMMPS interface is "finalized".
+
 Compiling plugins
 ^^^^^^^^^^^^^^^^^
 

doc/src/Developer_updating.rst

@@ -29,6 +29,7 @@ Available topics in mostly chronological order are:
 - `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`_
+- `FLERR as first argument to minimum image functions in Domain class`_
 
 ----
 
@@ -610,3 +611,47 @@ KSpace solvers which use distributed FFT grids:
 - ``src/KSPACE/pppm.cpp``
 
 This change is **required** or else the code will not compile.
+
+FLERR as first argument to minimum image functions in Domain class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 12Jun2025
+
+The ``Domain::minimum_image()`` and ``Domain::minimum_image_big()``
+functions were changed to take the ``FLERR`` macros as first argument.
+This way the error message indicates *where* the function was called
+instead of pointing to the implementation of the function.  Example:
+
+Old:
+
+.. code-block:: c++
+
+   double delx1 = x[i1][0] - x[i2][0];
+   double dely1 = x[i1][1] - x[i2][1];
+   double delz1 = x[i1][2] - x[i2][2];
+   domain->minimum_image(delx1, dely1, delz1);
+   double r1 = sqrt(delx1 * delx1 + dely1 * dely1 + delz1 * delz1);
+
+   double delx2 = x[i3][0] - x[i2][0];
+   double dely2 = x[i3][1] - x[i2][1];
+   double delz2 = x[i3][2] - x[i2][2];
+   domain->minimum_image_big(delx2, dely2, delz2);
+   double r2 = sqrt(delx2 * delx2 + dely2 * dely2 + delz2 * delz2);
+
+New:
+
+.. code-block:: c++
+
+   double delx1 = x[i1][0] - x[i2][0];
+   double dely1 = x[i1][1] - x[i2][1];
+   double delz1 = x[i1][2] - x[i2][2];
+   domain->minimum_image(FLERR, delx1, dely1, delz1);
+   double r1 = sqrt(delx1 * delx1 + dely1 * dely1 + delz1 * delz1);
+
+   double delx2 = x[i3][0] - x[i2][0];
+   double dely2 = x[i3][1] - x[i2][1];
+   double delz2 = x[i3][2] - x[i2][2];
+   domain->minimum_image_big(FLERR, delx2, dely2, delz2);
+   double r2 = sqrt(delx2 * delx2 + dely2 * dely2 + delz2 * delz2);
+
+This change is **required** or else the code will not compile.

doc/src/Errors_details.rst

@@ -159,13 +159,17 @@ angle, dihedral, or improper with just one atom in the actual
 sub-domain.  Typically, this cutoff is set to the largest cutoff from
 the :doc:`pair style(s) <pair_style>` plus the :doc:`neighbor list skin
 distance <neighbor>` and will typically be sufficient for all bonded
-interactions.  But if the pair style cutoff is small, this may not be
-enough.  LAMMPS will print a warning in this case using some heuristic
-based on the equilibrium bond length, but that still may not be
-sufficient for cases where the force constants are small and thus bonds
-may be stretched very far.  The communication cutoff can be adjusted
-with :doc:`comm_modify cutoff \<value\> <comm_modify>`, but setting this
-too large will waste CPU time and memory.
+interactions.  But if the pair style cutoff is small (e.g. with a
+repulsive-only Lennard-Jones potential) this may not be enough.  It is
+even worse if there is no pair style defined (or the pair style is set
+to "none"), since then there will be no ghost atoms created at all.
+
+The communication cutoff can be set or adjusted with :doc:`comm_modify
+cutoff \<value\> <comm_modify>`, but setting this too large will waste
+CPU time and memory.  LAMMPS will print warnings in these cases.  For
+bonds it uses some heuristic based on the equilibrium bond length, but
+that still may not be sufficient for cases where the force constants are
+small and thus bonds may be stretched very far.
 
 .. _hint09:
 
@@ -982,3 +986,59 @@ order of preference there are:
 - Send an email to ``developers@lammps.org``
 - Send an email to an :doc:`individual LAMMPS developer <Intro_authors>`
   that you know and trust
+
+.. _err0036:
+
+Neighbor list overflow, boost neigh_modify one
+----------------------------------------------
+
+The neighbor list code in LAMMPS uses a special memory allocation strategy
+to speed up building and accessing neighbor lists.
+
+Instead of making a memory allocation for each list of neighbors of the atoms
+LAMMPS allocates "pages" that have room for several neighbor lists.  This has
+two main advantages:
+
+#. It is not needed to first count how many neighbors there are for an
+   atom to determine the storage required.  Since the pages are much
+   larger than individual lists, LAMMPS just "fills up" the page until
+   there is not enough space left and then allocates a new page.
+
+#. There are fewer calls to the memory allocator functions (which can be
+   time consuming for long-running jobs and fragmented memory space) and
+   the resulting neighbor lists are close to each other physically which
+   improves cache efficiency.
+
+This is controlled by the two parameters "one" and "page", respectively,
+that can be set via the :doc:`neigh_modify command <neigh_modify>`. The
+parameter "one" is the maximum number of entries in a list of neighbors
+for a single atom.  If an atom has more neighbors as the "one" parameter
+allows, the "overflow" error message is triggered.  The parameter "page"
+sets the size of the page.  The neighbor list code checks, if there are
+"one" entries left in the current page.  If not, a new page is allocated.
+
+The default settings are suitable for most systems.  They need to be
+changed, for instance, when simulating a system with a very high density
+or when setting a very long cutoff (e.g. :math:`\gtrapprox 15 \AA` with
+:doc:`units real <units>`).  The value of "page" **must** be at least
+10x the value of "one", but 50x to 100x are recommended to avoid wasting
+memory.  The neighbor list storage is typically the largest amount of
+RAM required by a LAMMPS calculation.
+
+Even though the LAMMPS error message recommends to increase the "one"
+parameter, this may not always be the correct solution.  The neighbor
+list overflow can also be a symptom for some other error that cannot be
+easily detected.  For example, a frequent reason for an (unexpected)
+high density are incorrect box boundaries (since LAMMPS wraps atoms back
+into the principal box with periodic boundaries) or coordinates provided
+as fractional coordinates.  In both cases, LAMMPS cannot easily know
+whether the input geometry has such a high density (and thus requiring
+more neighbor list storage per atom) by intention.  Rather than blindly
+increasing the "one" parameter, it is thus worth checking if this is
+justified by the combination of density and cutoff.
+
+When boosting (= increasing) the "one" parameter, it is recommended to
+also increase the value for the "page" parameter to maintain the ratio
+between "one" and "page" to reduce waste of memory.  For some more
+details, please check out the documentation for the :doc:`neigh_modify
+command <neigh_modify>`.

doc/src/Fortran.rst

@@ -69,10 +69,11 @@ statement.  Internally, it will call either
 :cpp:func:`lammps_open_fortran` or :cpp:func:`lammps_open_no_mpi` from
 the C library API to create the class instance.  All arguments are
 optional and :cpp:func:`lammps_mpi_init` will be called automatically
-if it is needed.  Similarly, a possible call to
-:cpp:func:`lammps_mpi_finalize` is integrated into the :f:func:`close`
-function and triggered with the optional logical argument set to
-``.TRUE.``. Here is a simple example:
+if it is needed.  Similarly, optional calls to
+:cpp:func:`lammps_mpi_finalize`, :cpp:func:`lammps_kokkos_finalize`,
+:cpp:func:`lammps_python_finalize`, and :cpp:func:`lammps_plugin_finalize`
+are integrated into the :f:func:`close` function and triggered with the
+optional logical argument set to ``.TRUE.``. Here is a simple example:
 
 .. code-block:: fortran
 
@@ -521,8 +522,8 @@ Procedures Bound to the :f:type:`lammps` Derived Type
    This method will close down the LAMMPS instance through calling
    :cpp:func:`lammps_close`.  If the *finalize* argument is present and
    has a value of ``.TRUE.``, then this subroutine also calls
-   :cpp:func:`lammps_kokkos_finalize` and
-   :cpp:func:`lammps_mpi_finalize`.
+   :cpp:func:`lammps_kokkos_finalize`, :cpp:func:`lammps_mpi_finalize`,
+   :cpp:func:`lammps_python_finalize`, and :cpp:func:`lammps_plugin_finalize`.
 
    :o finalize: shut down the MPI environment of the LAMMPS
     library if ``.TRUE.``.
@@ -530,6 +531,8 @@ Procedures Bound to the :f:type:`lammps` Derived Type
    :to: :cpp:func:`lammps_close`
    :to: :cpp:func:`lammps_mpi_finalize`
    :to: :cpp:func:`lammps_kokkos_finalize`
+   :to: :cpp:func:`lammps_python_finalize`
+   :to: :cpp:func:`lammps_plugin_finalize`
 
 --------
 

doc/src/Howto.rst

@@ -66,6 +66,7 @@ Force fields howto
    :name: force_howto
    :maxdepth: 1
 
+   Howto_FFgeneral
    Howto_bioFF
    Howto_amoeba
    Howto_tip3p

doc/src/Howto_FFgeneral.rst

@@ -0,0 +1,55 @@
+Some general force field considerations
+=======================================
+
+A compact summary of the concepts, definitions, and properties of force
+fields with explicit bonded interactions (like the ones discussed in
+this HowTo) is given in :ref:`(Gissinger) <Typelabel2>`.
+
+A force field has 2 parts: the formulas that define its potential
+functions and the coefficients used for a particular system.  To assign
+parameters it is first required to assign atom types.  Those are not
+only based on the elements, but also on the chemical environment due to
+the atoms bound to them.  This often follows the chemical concept of
+*functional groups*.  Example: a carbon atom bound with a single bond to
+a single OH-group (alcohol) would be a different atom type than a carbon
+atom bound to a methyl CH3 group (aliphatic carbon).  The atom types
+usually then determine the non-bonded Lennard-Jones parameters and the
+parameters for bonds, angles, dihedrals, and impropers.  On top of that,
+partial charges have to be applied.  Those are usually independent of
+the atom types and are determined either for groups of atoms called
+residues with some fitting procedure based on quantum mechanical
+calculations, or based on some increment system that add or subtract
+increments from the partial charge of an atom based on the types of
+the neighboring atoms.
+
+Force fields differ in the strategies they employ to determine the
+parameters and charge distribution in how generic or specific they are
+which in turn has an impact on the accuracy (compare for example
+CGenFF to CHARMM and GAFF to Amber).  Because of the different
+strategies, it is not a good idea to use a mix of parameters from
+different force field *families* (like CHARMM, Amber, or GROMOS)
+and that extends to the parameters for the solvent, especially
+water.  The publication describing the parameterization of a force
+field will describe which water model to use.  Changing the water
+model usually leads to overall worse results (even if it may improve
+on the water itself).
+
+In addition, one has to consider that *families* of force fields like
+CHARMM, Amber, OPLS, or GROMOS have evolved over time and thus provide
+different *revisions* of the force field parameters.  These often
+corresponds to changes in the functional form or the parameterization
+strategies.  This may also result in changes required for simulation
+settings like the preferred cutoff or how Coulomb interactions are
+computed (cutoff, smoothed/shifted cutoff, or long-range with Ewald
+summation or equivalent).  Unless explicitly stated in the publication
+describing the force field, the Coulomb interaction cannot be chosen at
+will but must match the revision of the force field.  That said,
+liberties may be taken during the initial equilibration of a system to
+speed up the process, but not for production simulations.
+
+----------
+
+.. _Typelabel2:
+
+**(Gissinger)** J. R. Gissinger, I. Nikiforov, Y. Afshar, B. Waters, M. Choi, D. S. Karls, A. Stukowski, W. Im, H. Heinz, A. Kohlmeyer, and E. B. Tadmor, J Phys Chem B, 128, 3282-3297 (2024).
+

doc/src/Howto_bioFF.rst

@@ -1,22 +1,16 @@
 CHARMM, AMBER, COMPASS, DREIDING, and OPLS force fields
 =======================================================
 
-A compact summary of the concepts, definitions, and properties of
-force fields with explicit bonded interactions (like the ones discussed
-in this HowTo) is given in :ref:`(Gissinger) <Typelabel2>`.
-
-A force field has 2 parts: the formulas that define it and the
-coefficients used for a particular system.  Here we only discuss
-formulas implemented in LAMMPS that correspond to formulas commonly used
-in the CHARMM, AMBER, COMPASS, and DREIDING force fields.  Setting
-coefficients is done either from special sections in an input data file
-via the :doc:`read_data <read_data>` command or in the input script with
-commands like :doc:`pair_coeff <pair_coeff>` or :doc:`bond_coeff
-<bond_coeff>` and so on.  See the :doc:`Tools <Tools>` doc page for
-additional tools that can use CHARMM, AMBER, or Materials Studio
-generated files to assign force field coefficients and convert their
-output into LAMMPS input. LAMMPS input scripts can also be generated by
-`charmm-gui.org <https://charmm-gui.org/>`_.
+Here we only discuss formulas implemented in LAMMPS that correspond to
+formulas commonly used in the CHARMM, AMBER, COMPASS, and DREIDING force
+fields.  Setting coefficients is done either from special sections in an
+input data file via the :doc:`read_data <read_data>` command or in the
+input script with commands like :doc:`pair_coeff <pair_coeff>` or
+:doc:`bond_coeff <bond_coeff>` and so on.  See the :doc:`Tools <Tools>`
+doc page for additional tools that can use CHARMM, AMBER, or Materials
+Studio generated files to assign force field coefficients and convert
+their output into LAMMPS input. LAMMPS input scripts can also be
+generated by `charmm-gui.org <https://charmm-gui.org/>`_.
 
 CHARMM and AMBER
 ----------------
@@ -203,9 +197,11 @@ rather than individual force constants and geometric parameters that
 depend on the particular combinations of atoms involved in the bond,
 angle, or torsion terms.  DREIDING has an :doc:`explicit hydrogen bond
 term <pair_hbond_dreiding>` to describe interactions involving a
-hydrogen atom on very electronegative atoms (N, O, F).  Unlike CHARMM
-or AMBER, the DREIDING force field has not been parameterized for
-considering solvents (like water).
+hydrogen atom on very electronegative atoms (N, O, F).  Unlike CHARMM or
+AMBER, the DREIDING force field has not been parameterized for
+considering solvents (like water) and has no rules for assigning
+(partial) charges.  That will seriously limit its accuracy when used for
+simulating systems where those matter.
 
 See :ref:`(Mayo) <howto-Mayo>` for a description of the DREIDING force field
 
@@ -272,10 +268,6 @@ compatible with a subset of OPLS interactions.
 
 ----------
 
-.. _Typelabel2:
-
-**(Gissinger)** J. R. Gissinger, I. Nikiforov, Y. Afshar, B. Waters, M. Choi, D. S. Karls, A. Stukowski, W. Im, H. Heinz, A. Kohlmeyer, and E. B. Tadmor, J Phys Chem B, 128, 3282-3297 (2024).
-
 .. _howto-MacKerell:
 
 **(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al (1998).  J Phys Chem, 102, 3586 . https://doi.org/10.1021/jp973084f

doc/src/Howto_cmake.rst

@@ -285,7 +285,7 @@ when used before the CMake directory, there may be a space between the
 can have boolean values (on/off, yes/no, or 1/0 are all valid) or are
 strings representing a choice, or a path, or are free format. If the
 string would contain whitespace, it must be put in quotes, for example
-``-D CMAKE_TUNE_FLAGS="-ftree-vectorize -ffast-math"``.
+``-D CMAKE_CXX_FLAGS="-O3 -Wall -ftree-vectorize -ffast-math"``.
 
 CMake variables fall into two categories: 1) common CMake variables that
 are used by default for any CMake configuration setup and 2) project
@@ -341,8 +341,6 @@ Some common LAMMPS specific variables
      - compile some additional executables from the ``tools`` folder (default: ``off``)
    * - ``BUILD_DOC``
      - include building the HTML format documentation for packaging/installing (default: ``off``)
-   * - ``CMAKE_TUNE_FLAGS``
-     - common compiler flags, for optimization or instrumentation (default:)
    * - ``LAMMPS_MACHINE``
      - when set to ``name`` the LAMMPS executable and library will be called ``lmp_name`` and ``liblammps_name.a``
    * - ``FFT``

doc/src/Howto_github.rst

@@ -498,3 +498,7 @@ 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>`_
+
+.. raw:: latex
+
+   \clearpage

doc/src/Howto_lammps_gui.rst

@@ -1,35 +1,25 @@
 Using LAMMPS-GUI
 ================
 
+LAMMPS-GUI is a graphical text editor programmed using the `Qt Framework
+<https://www.qt.io/>`_ and customized for editing LAMMPS input files.  It
+is linked to the :ref:`LAMMPS library <lammps_c_api>` and thus can run
+LAMMPS directly using the contents of the editor's text buffer as input.
+
+It *differs* from other known interfaces to LAMMPS in that it can
+retrieve and display information from LAMMPS *while it is running*,
+display visualizations created with the :doc:`dump image command
+<dump_image>`, can launch the online LAMMPS documentation for known
+LAMMPS commands and styles, and directly integrates with a collection
+of LAMMPS tutorials (:ref:`Gravelle1 <Gravelle1>`).
+
 This document describes **LAMMPS-GUI version 1.6**.
 
 -----
 
-LAMMPS-GUI is a graphical text editor customized for editing LAMMPS
-input files that is linked to the :ref:`LAMMPS library <lammps_c_api>`
-and thus can run LAMMPS directly using the contents of the editor's text
-buffer as input.  It can retrieve and display information from LAMMPS
-while it is running, display visualizations created with the :doc:`dump
-image command <dump_image>`, and is adapted specifically for editing
-LAMMPS input files through text completion and reformatting, and linking
-to the online LAMMPS documentation for known LAMMPS commands and styles.
+.. contents::
 
-.. note::
-
-   Pre-compiled, ready-to-use LAMMPS-GUI executables for Linux x86\_64
-   (Ubuntu 20.04LTS or later and compatible), macOS (version 11 aka Big
-   Sur or later), and Windows (version 10 or later) :ref:`are available
-   <lammps_gui_install>` for download.  Non-MPI LAMMPS executables (as
-   ``lmp``) for running LAMMPS from the command-line and :doc:`some
-   LAMMPS tools <Tools>` compiled executables are also included.
-   Also, the pre-compiled LAMMPS-GUI packages include the WHAM executables
-   from http://membrane.urmc.rochester.edu/content/wham/ for use with
-   LAMMPS tutorials.
-
-   The source code for LAMMPS-GUI is included in the LAMMPS source code
-   distribution and can be found in the ``tools/lammps-gui`` folder.  It
-   can be compiled alongside LAMMPS when :doc:`compiling with CMake
-   <Build_cmake>`.
+----
 
 LAMMPS-GUI tries to provide an experience similar to what people
 traditionally would have running LAMMPS using a command-line window and
@@ -64,8 +54,8 @@ simple LAMMPS simulations.  It is very suitable for tutorials on LAMMPS
 since you only need to learn how to use a single program for most tasks
 and thus time can be saved and people can focus on learning LAMMPS.
 The tutorials at https://lammpstutorials.github.io/ are specifically
-updated for use with LAMMPS-GUI and can their tutorial materials can
-be downloaded and loaded directly from the GUI.
+updated for use with LAMMPS-GUI and their tutorial materials can
+be downloaded and edited directly from the GUI.
 
 Another design goal is to keep the barrier low when replacing part of
 the functionality of LAMMPS-GUI with external tools.  That said, LAMMPS-GUI
@@ -78,10 +68,31 @@ has some unique functionality that is not found elsewhere:
 - monitoring of simulation progress
 - interactive visualization using the :doc:`dump image <dump_image>`
   command with the option to copy-paste the resulting settings
-- automatic slide show generation from dump image out at runtime
-- automatic plotting of thermodynamics data at runtime
+- automatic slide show generation from dump image output at runtime
+- automatic plotting of thermodynamic data at runtime
 - inspection of binary restart files
 
+.. admonition:: Download LAMMPS-GUI for your platform
+   :class: Hint
+
+   Pre-compiled, ready-to-use LAMMPS-GUI executables for Linux x86\_64
+   (Ubuntu 20.04LTS or later and compatible), macOS (version 11 aka Big
+   Sur or later), and Windows (version 10 or later) :ref:`are available
+   <lammps_gui_install>` for download.  Non-MPI LAMMPS executables (as
+   ``lmp``) for running LAMMPS from the command-line and :doc:`some
+   LAMMPS tools <Tools>` compiled executables are also included.  Also,
+   the pre-compiled LAMMPS-GUI packages include the WHAM executables
+   from http://membrane.urmc.rochester.edu/content/wham/ for use with
+   LAMMPS tutorials documented in this paper (:ref:`Gravelle1
+   <Gravelle1>`).
+
+   The source code for LAMMPS-GUI is included in the LAMMPS source code
+   distribution and can be found in the ``tools/lammps-gui`` folder.  It
+   can be compiled alongside LAMMPS when :doc:`compiling with CMake
+   <Build_cmake>`.
+
+-----
+
 The following text provides a detailed tour of the features and
 functionality of LAMMPS-GUI.  Suggestions for new features and
 reports of bugs are always welcome.  You can use the :doc:`the same
@@ -92,9 +103,12 @@ channels as for LAMMPS itself <Errors_bugs>` for that purpose.
 Installing Pre-compiled LAMMPS-GUI Packages
 -------------------------------------------
 
-LAMMPS-GUI is available as pre-compiled binary packages for Linux
-x86\_64, macOS 11 and later, and Windows 10 and later.  Alternately, it
-can be compiled from source.
+LAMMPS-GUI is available for download as pre-compiled binary packages for
+Linux x86\_64 (Ubuntu 20.04LTS or later and compatible), macOS (version
+11 aka Big Sur or later), and Windows (version 10 or later) from the
+`LAMMPS release pages on GitHub <https://github.com/lammps/lammps/releases/>`_.
+A backup download location is at https://download.lammps.org/static/
+Alternately, LAMMPS-GUI can be compiled from source when building LAMMPS.
 
 Windows 10 and later
 ^^^^^^^^^^^^^^^^^^^^
@@ -294,7 +308,10 @@ of the *Output* window showing how many warnings and errors were
 detected and how many lines the entire output has.  By clicking on the
 button on the right with the warning symbol or by using the keyboard
 shortcut `Ctrl-N` (`Command-N` on macOS), you can jump to the next
-line with a warning or error.
+line with a warning or error.  If there is a URL pointing to additional
+explanations in the online manual, that URL will be highlighted and
+double-clicking on it shall open the corresponding manual page in
+the web browser.  The option is also available from the context menu.
 
 By default, the *Output* window is replaced each time a run is started.
 The runs are counted and the run number for the current run is displayed
@@ -349,8 +366,13 @@ data or both.  The smoothing uses a `Savitzky-Golay convolution filter
 window width (left) and order (right) parameters can be set in the boxes
 next to the drop down menu.  Default settings are 10 and 4 which means
 that the smoothing window includes 10 points each to the left and the
-right of the current data point and a fourth order polynomial is fit to
-the data in the window.
+right of the current data point for a total of 21 points and a fourth
+order polynomial is fitted to the data in the window.
+
+The "Title:" and "Y:" input boxes allow to edit the text shown as the
+plot title and the y-axis label, respectively.  The text entered in the
+"Title:" box is applied to *all* charts, while the "Y:" text changes
+only the y-axis label of the currently *selected* plot.
 
 You can use the mouse to zoom into the graph (hold the left button and
 drag to mark an area) or zoom out (right click) and you can reset the
@@ -382,6 +404,11 @@ here you get the compounded data set starting with the last change of
 output fields or timestep setting, while the export from the log will
 contain *all* YAML output but *segmented* into individual runs.
 
+The *Preferences* dialog has a *Charts* tab, where you can configure
+multiple chart-related settings, like the default title, colors for the
+graphs, default choice of the raw / smooth graph selection, and the
+default chart graph size.
+
 Image Slide Show
 ----------------
 
@@ -461,11 +488,11 @@ correspond to (via their mass) and then colorize them in the image and
 set their atom diameters accordingly.  If this is not possible, for
 instance when using reduced (= 'lj') :doc:`units <units>`, then
 LAMMPS-GUI will check the current pair style and if it is a
-Lennard-Jones type potential, it will extract the *sigma* parameter
-for each atom type and assign atom diameters from those numbers.
-For cases where atom diameters are not auto-detected, the *Atom size* field
-can be edited and a suitable value set manually. The default value
-is inferred from the x-direction lattice spacing.
+Lennard-Jones type potential, it will extract the *sigma* parameter for
+each atom type and assign atom diameters from those numbers.  For cases
+where atom diameters are not auto-detected, the *Atom size* field can be
+edited and a suitable value set manually. The default value is inferred
+from the x-direction lattice spacing.
 
 If elements cannot be detected the default sequence of colors of the
 :doc:`dump image <dump_image>` command is assigned to the different atom
@@ -480,22 +507,31 @@ types.
 |gui-image1|  |gui-image2|
 
 The default image size, some default image quality settings, the view
-style and some colors can be changed in the *Preferences* dialog
-window.  From the image viewer window further adjustments can be made:
-actual image size, high-quality (SSAO) rendering, anti-aliasing, view
-style, display of box or axes, zoom factor.  The view of the system can
-be rotated horizontally and vertically.  It is also possible to only
-display the atoms within a group defined in the input script (default is
-"all").  The image can also be re-centered on the center of mass of the
-selected group.  After each change, the image is rendered again and the
-display updated.  The small palette icon on the top left is colored
-while LAMMPS is running to render the new image; it is grayed out when
-LAMMPS is finished.  When there are many atoms to render and high
-quality images with anti-aliasing are requested, re-rendering may take
-several seconds.  From the *File* menu of the image window, the
-current image can be saved to a file (keyboard shortcut `Ctrl-S`) or
-copied to the clipboard (keyboard shortcut `Ctrl-C`) for pasting the
-image into another application.
+style and some colors can be changed in the *Preferences* dialog window.
+From the image viewer window further adjustments can be made: actual
+image size, high-quality (SSAO) rendering, anti-aliasing, view style,
+display of box or axes, zoom factor.  The view of the system can be
+rotated horizontally and vertically.
+
+It is also possible to display only the atoms within a :doc:`group
+defined in the input script <group>` (default is "all").  The available
+groups can be selected from the drop down list next to the "Group:"
+label.  Similarly, if there are :doc:`molecules defined in the input
+<molecule>`, it is possible to select one of them (default is "none")
+and visualize it (it will be shown at the center of the simulation box).
+While a molecule is selected, the group selection is disabled.  It can
+be restored by selecting the molecule "none".
+
+The image can also be re-centered on the center of mass of the selected
+group.  After each change, the image is rendered again and the display
+updated.  The small palette icon on the top left is colored while LAMMPS
+is running to render the new image; it is grayed out when LAMMPS is
+finished.  When there are many atoms to render and high quality images
+with anti-aliasing are requested, re-rendering may take several seconds.
+From the *File* menu of the image window, the current image can be saved
+to a file (keyboard shortcut `Ctrl-S`) or copied to the clipboard
+(keyboard shortcut `Ctrl-C`) for pasting the image into another
+application.
 
 From the *File* menu it is also possible to copy the current
 :doc:`dump image <dump_image>` and :doc:`dump_modify <dump_image>`
@@ -720,6 +756,22 @@ output, charts, slide show, variables, or snapshot images.  The
 default settings for their visibility can be changed in the
 *Preferences* dialog.
 
+Tutorials
+^^^^^^^^^
+
+The *Tutorials* menu is to support the set of LAMMPS tutorials for
+beginners and intermediate LAMMPS users documented in (:ref:`Gravelle1
+<Gravelle1>`).  From the drop down menu you can select which of the
+eight currently available tutorial sessions you want to begin.  This
+opens a 'wizard' dialog where you can choose in which folder you want to
+work, whether you want that folder to be wiped from *any* files, whether
+you want to download the solutions files (which can be large) to a
+``solution`` sub-folder, and whether you want the corresponding
+tutorial's online version opened in your web browser.  The dialog will
+then start downloading the files requested (download progress is
+reported in the status line) and load the first input file for the
+selected session into LAMMPS-GUI.
+
 About
 ^^^^^
 
@@ -783,18 +835,21 @@ look of LAMMPS-GUI.  The settings are grouped and each group is
 displayed within a tab.
 
 .. |guiprefs1| image:: JPG/lammps-gui-prefs-general.png
-   :width: 24%
+   :width: 19%
 
 .. |guiprefs2| image:: JPG/lammps-gui-prefs-accel.png
-   :width: 24%
+   :width: 19%
 
 .. |guiprefs3| image:: JPG/lammps-gui-prefs-image.png
-   :width: 24%
+   :width: 19%
 
 .. |guiprefs4| image:: JPG/lammps-gui-prefs-editor.png
-   :width: 24%
+   :width: 19%
 
-|guiprefs1|  |guiprefs2|  |guiprefs3|  |guiprefs4|
+.. |guiprefs5| image:: JPG/lammps-gui-prefs-charts.png
+   :width: 19%
+
+|guiprefs1|  |guiprefs2|  |guiprefs3|  |guiprefs4|  |guiprefs5|
 
 General Settings:
 ^^^^^^^^^^^^^^^^^
@@ -848,6 +903,11 @@ General Settings:
   the plots in the *Charts* window in milliseconds.  The default is to
   redraw the plots every 500 milliseconds.  This is just for the drawing,
   data collection is managed with the previous setting.
+- *HTTPS proxy setting:* Allows to enter a URL for an HTTPS proxy.  This
+  may be needed when the LAMMPS input contains :doc:`geturl commands <geturl>`
+  or for downloading tutorial files from the *Tutorials* menu.  If the
+  ``https_proxy`` environment variable was set externally, its value is
+  displayed but cannot be changed.
 
 Accelerators:
 ^^^^^^^^^^^^^
@@ -884,7 +944,7 @@ lists to select the background and box colors.
 Editor Settings:
 ^^^^^^^^^^^^^^^^
 
-This tab allows tweaking settings of the editor window.  Specifically
+This tab allows tweaking settings of the editor window.  Specifically,
 the amount of padding to be added to LAMMPS commands, types or type
 ranges, IDs (e.g. for fixes), and names (e.g. for groups).  The value
 set is the minimum width for the text element and it can be chosen in
@@ -896,6 +956,16 @@ the completion pop-up window, and whether auto-save mode is enabled.
 In auto-save mode the editor buffer is saved before a run or before
 exiting LAMMPS-GUI.
 
+Charts Settings:
+----------------
+
+This tab allows tweaking settings of the *Charts* window.  Specifically,
+one can set the default chart title (if the title contains '%f' it will
+be replaced with the name of the current input file), one can select
+whether by default the raw data, the smoothed data or both will be
+plotted, one can set the colors for the two lines, the default smoothing
+parameters, and the default size of the chart graph in pixels.
+
 -----------
 
 Keyboard Shortcuts
@@ -976,10 +1046,25 @@ available (On macOS use the Command key instead of Ctrl/Control).
      - Ctrl+Shift+T
      - LAMMPS Tutorial
 
-Further editing keybindings `are documented with the Qt documentation
+Further keybindings of the editor window `are documented with the Qt
+documentation
 <https://doc.qt.io/qt-5/qplaintextedit.html#editing-key-bindings>`_.  In
 case of conflicts the list above takes precedence.
 
 All other windows only support a subset of keyboard shortcuts listed
 above.  Typically, the shortcuts `Ctrl-/` (Stop Run), `Ctrl-W` (Close
 Window), and `Ctrl-Q` (Quit Application) are supported.
+
+-------------
+
+.. _Gravelle1:
+
+**(Gravelle1)** Gravelle, Gissinger, Kohlmeyer, `arXiv:2503.14020 \[physics.comp-ph\] <https://doi.org/10.48550/arXiv.2503.14020>`_ (2025)
+
+.. _Gravelle2:
+
+**(Gravelle2)** Gravelle https://lammpstutorials.github.io/
+
+.. raw:: latex
+
+   \clearpage

doc/src/Howto_spc.rst

@@ -1,5 +1,5 @@
-SPC water model
-===============
+SPC and SPC/E water model
+=========================
 
 The SPC water model specifies a 3-site rigid water molecule with
 charges and Lennard-Jones parameters assigned to each of the three atoms.

doc/src/Howto_thermostat.rst

@@ -21,9 +21,14 @@ can be invoked via the *dpd/tstat* pair style:
 * :doc:`fix nvt/sllod <fix_nvt_sllod>`
 * :doc:`fix temp/berendsen <fix_temp_berendsen>`
 * :doc:`fix temp/csvr <fix_temp_csvr>`
+* :doc:`fix ffl <fix_ffl>`
+* :doc:`fix gjf <fix_gjf>`
+* :doc:`fix gld <fix_gld>`
+* :doc:`fix gle <fix_gle>`
 * :doc:`fix langevin <fix_langevin>`
 * :doc:`fix temp/rescale <fix_temp_rescale>`
 * :doc:`pair_style dpd/tstat <pair_dpd>`
+* :doc:`pair_style dpd/ext/tstat <pair_dpd_ext>`
 
 :doc:`Fix nvt <fix_nh>` only thermostats the translational velocity of
 particles.  :doc:`Fix nvt/sllod <fix_nvt_sllod>` also does this,
@@ -82,10 +87,10 @@ that:
 
 .. note::
 
-   Only the nvt fixes perform time integration, meaning they update
+   Not all thermostat fixes perform time integration, meaning they update
    the velocities and positions of particles due to forces and velocities
    respectively.  The other thermostat fixes only adjust velocities; they
-   do NOT perform time integration updates.  Thus they should be used in
+   do NOT perform time integration updates.  Thus, they should be used in
    conjunction with a constant NVE integration fix such as these:
 
 * :doc:`fix nve <fix_nve>`

doc/src/Howto_tip4p.rst

@@ -1,5 +1,5 @@
-TIP4P water model
-=================
+TIP4P and OPC water models
+==========================
 
 The four-point TIP4P rigid water model extends the traditional
 :doc:`three-point TIP3P <Howto_tip3p>` model by adding an additional
@@ -9,9 +9,11 @@ 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.
+style :doc:`zero <angle_zero>` can be used.  Very similar to the TIP4P
+model is the OPC water model.  It can be realized the same way as TIP4P
+but has different geometry and force field parameters.
 
-There are two ways to implement TIP4P water in LAMMPS:
+There are two ways to implement TIP4P-like water in LAMMPS:
 
 #. Use a specially written pair style that uses the :ref:`TIP3P geometry
    <tip3p_molecule>` without the point M. The point M location is then
@@ -21,7 +23,10 @@ There are two ways to implement TIP4P water in LAMMPS:
    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.
+   located on the oxygen atom unless they are specially written for using
+   the TIP4P geometry internally as well, e.g. :doc:`compute dipole/tip4p
+   <compute_dipole>`, :doc:`fix efield/tip4p <fix_efield>`, or
+   :doc:`kspace_style pppm/tip4p <kspace_style>`.
 
    This can be done with the following pair styles for Coulomb with a cutoff:
 
@@ -68,77 +73,90 @@ 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.
+not as part of the pair coefficients. Also parameters for the OPC
+model (:ref:`Izadi <Izadi>`) are provided.
 
 .. list-table::
       :header-rows: 1
-      :widths: 36 19 13 15 17
+      :widths: 40 12 12 14 11 11
 
       * - Parameter
         - TIP4P (original)
         - TIP4P/Ice
         - TIP4P/2005
         - TIP4P (Ewald)
+        - OPC
       * - O mass (amu)
         - 15.9994
         - 15.9994
         - 15.9994
         - 15.9994
+        - 15.9994
       * - H mass (amu)
         - 1.008
         - 1.008
         - 1.008
         - 1.008
+        - 1.008
       * - O or M charge (:math:`e`)
         - -1.040
         - -1.1794
         - -1.1128
         - -1.04844
+        - -1.3582
       * - H charge (:math:`e`)
         - 0.520
         - 0.5897
         - 0.5564
         - 0.52422
+        - 0.6791
       * - LJ :math:`\epsilon` of OO (kcal/mole)
         - 0.1550
         - 0.21084
         - 0.1852
         - 0.16275
+        - 0.21280
       * - LJ :math:`\sigma` of OO (:math:`\AA`)
         - 3.1536
         - 3.1668
         - 3.1589
         - 3.16435
+        - 3.1660
       * - LJ :math:`\epsilon` of HH, MM, OH, OM, HM (kcal/mole)
         - 0.0
         - 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
+        - 1.0
       * - :math:`r_0` of OH bond (:math:`\AA`)
         - 0.9572
         - 0.9572
         - 0.9572
         - 0.9572
+        - 0.8724
       * - :math:`\theta_0` of HOH angle
         - 104.52\ :math:`^{\circ}`
         - 104.52\ :math:`^{\circ}`
         - 104.52\ :math:`^{\circ}`
         - 104.52\ :math:`^{\circ}`
+        - 103.60\ :math:`^{\circ}`
       * - OM distance (:math:`\AA`)
         - 0.15
         - 0.1577
         - 0.1546
         - 0.1250
+        - 0.1594
 
-Note that the when using the TIP4P pair style, the neighbor list cutoff
+Note that the when using a TIP4P pair style, the neighbor list cutoff
 for Coulomb interactions is effectively extended by a distance 2 \* (OM
 distance), to account for the offset distance of the fictitious charges
-on O atoms in water molecules.  Thus it is typically best in an
+on O atoms in water molecules.  Thus, it is typically best in an
 efficiency sense to use a LJ cutoff >= Coulomb cutoff + 2\*(OM
 distance), to shrink the size of the neighbor list.  This leads to
 slightly larger cost for the long-range calculation, so you can test the
@@ -192,6 +210,94 @@ file changed):
     run 20000
     write_data tip4p-implicit.data nocoeff
 
+When constructing an OPC model, we cannot use the ``tip3p.mol`` file due
+to the different geometry.  Below is a molecule file providing the 3
+sites of an implicit OPC geometry for use with TIP4P styles.  Note, that
+the "Shake" and "Special" sections are missing here.  Those will be
+auto-generated by LAMMPS when the molecule file is loaded *after* the
+simulation box has been created.  These sections are required only when
+the molecule file is loaded *before*.
+
+.. _opc3p_molecule:
+.. code-block::
+
+   # Water molecule. 3 point geometry for OPC model
+
+   3 atoms
+   2 bonds
+   1 angles
+
+   Coords
+
+   1    0.00000  -0.06037   0.00000
+   2    0.68558   0.50250   0.00000
+   3   -0.68558   0.50250   0.00000
+
+   Types
+
+   1        1   # O
+   2        2   # H
+   3        2   # H
+
+   Charges
+
+   1       -1.3582
+   2        0.6791
+   3        0.6791
+
+   Bonds
+
+   1   1      1      2
+   2   1      1      3
+
+   Angles
+
+   1   1      2      1      3
+
+Below is a LAMMPS input file using the implicit method to implement
+the OPC model using the molecule file from above and including the
+PPPM long-range Coulomb solver.
+
+.. 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/long 1 2 1 1 0.1594 12.0
+    pair_coeff 1 1 0.2128 3.166
+    pair_coeff 2 2 0.0    1.0
+
+    bond_style zero
+    bond_coeff 1 0.8724
+
+    angle_style zero
+    angle_coeff 1 103.6
+
+    kspace_style pppm/tip4p 1.0e-5
+
+    molecule water opc3p.mol  # this file has the OPC geometry but is without M
+    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
+
+    reset_timestep 0
+    timestep 1.0
+    velocity all create 300.0 5463576
+    fix integrate all nvt temp 300 300 100.0
+
+    thermo_style custom step temp press etotal pe
+
+    thermo 1000
+    run 20000
+    write_data opc-implicit.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/small
 <fix_rigid>` no bonds need to be defined and thus no extra storage needs
@@ -279,3 +385,8 @@ Phys, 79, 926 (1983).
 
 **(Abascal2)** Abascal, J Chem Phys, 123, 234505 (2005)
    https://doi.org/10.1063/1.2121687
+
+.. _Izadi:
+
+**(Izadi)** Izadi, Anandakrishnan, Onufriev, J. Phys. Chem. Lett., 5, 21, 3863 (2014)
+   https://doi.org/10.1021/jz501780a

doc/src/Install_git.rst

@@ -12,26 +12,17 @@ several advantages:
   LAMMPS.  For that, you should first create your own :doc:`fork on
   GitHub <Howto_github>`, though.
 
-You must have `git <git_>`_ installed on your system to use the
-commands explained below to communicate with the git servers on
-GitHub.  For people still using subversion (svn), GitHub also
-provides `limited support for subversion clients <svn_>`_.
-
-.. note::
-
-   As of October 2016, the official home of public LAMMPS development is
-   on GitHub.  The previously advertised LAMMPS git repositories on
-   git.lammps.org and bitbucket.org are now offline or deprecated.
+You must have `git <git_>`_ installed on your system to use the commands
+explained below to communicate with the git servers on GitHub.
 
 .. _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 4 different git branches:
 
 * **develop** : this branch follows the ongoing development and is
   updated with every merge commit of a pull request
-* **release** : this branch is updated with every "feature release";
-   updates are always "fast-forward" merges from *develop*
+* **release** : this branch is updated with every "feature release"
+  and updates are always "fast-forward" merges from *develop*
 * **maintenance** : this branch collects back-ported bug fixes from the
   *develop* branch to the *stable* branch.  It is used to update the
   *stable* branch for "stable update releases".

doc/src/Intro_authors.rst

@@ -84,8 +84,9 @@ lammps.org".  General questions about LAMMPS should be posted in the
 
    \normalsize
 
-Past developers include Paul Crozier and Mark Stevens, both at SNL,
-and Ray Shan, now at Materials Design.
+Past core developers include Paul Crozier and Mark Stevens, both at SNL,
+and Ray Shan while at SNL and later at Materials Design, now at Thermo
+Fisher Scientific.
 
 ----------
 

doc/src/Intro_portability.rst

@@ -28,8 +28,9 @@ Build systems
 LAMMPS can be compiled from source code using a (traditional) build
 system based on shell scripts, a few shell utilities (grep, sed, cat,
 tr) and the GNU make program. This requires running within a Bourne
-shell (``/bin/sh``).  Alternatively, a build system with different back
-ends can be created using CMake.  CMake must be at least version 3.16.
+shell (``/bin/sh`` or ``/bin/bash``).  Alternatively, a build system
+with different back ends can be created using CMake.  CMake must be
+at least version 3.16.
 
 Operating systems
 ^^^^^^^^^^^^^^^^^
@@ -40,11 +41,18 @@ Also, compilation and correct execution on macOS and Windows (using
 Microsoft Visual C++) is checked automatically for the largest part of
 the source code.  Some (optional) features are not compatible with all
 operating systems, either through limitations of the corresponding
-LAMMPS source code or through incompatibilities of source code or
-build system of required external libraries or packages.
+LAMMPS source code or through incompatibilities or build system
+limitations of required external libraries or packages.
 
-Executables for Windows may be created natively using either Cygwin or
-Visual Studio or with a Linux to Windows MinGW cross-compiler.
+Executables for Windows may be created either natively using Cygwin,
+MinGW, Intel, Clang, or Microsoft Visual C++ compilers, or with a Linux
+to Windows MinGW cross-compiler.  Native compilation is supported using
+Microsoft Visual Studio or a terminal window (using the CMake build
+system).
+
+Executables for macOS may be created either using Xcode or GNU compilers
+installed with Homebrew.  In the latter case, building of LAMMPS through
+Homebrew instead of a manual compile is also possible.
 
 Additionally, FreeBSD and Solaris have been tested successfully to
 run LAMMPS and produce results consistent with those on Linux.
@@ -61,8 +69,9 @@ CPU architectures
 ^^^^^^^^^^^^^^^^^
 
 The primary CPU architecture for running LAMMPS is 64-bit x86, but also
-32-bit x86, and 64-bit ARM and PowerPC (64-bit, Little Endian) are
-regularly tested.
+64-bit ARM and PowerPC (64-bit, Little Endian) are currently regularly
+tested.  Further architectures are tested by Linux distributions that
+bundle LAMMPS.
 
 Portability compliance
 ^^^^^^^^^^^^^^^^^^^^^^

doc/src/Library_create.rst

@@ -11,6 +11,7 @@ This section documents the following functions:
 - :cpp:func:`lammps_mpi_finalize`
 - :cpp:func:`lammps_kokkos_finalize`
 - :cpp:func:`lammps_python_finalize`
+- :cpp:func:`lammps_plugin_finalize`
 - :cpp:func:`lammps_error`
 
 --------------------
@@ -119,5 +120,10 @@ calling program.
 
 -----------------------
 
+.. doxygenfunction:: lammps_plugin_finalize
+   :project: progguide
+
+-----------------------
+
 .. doxygenfunction:: lammps_error
    :project: progguide

doc/src/Modify_compute.rst

@@ -1,19 +1,21 @@
 Compute styles
 ==============
 
-Classes that compute scalar and vector quantities like temperature
-and the pressure tensor, as well as classes that compute per-atom
-quantities like kinetic energy and the centro-symmetry parameter
-are derived from the Compute class.  New styles can be created
-to add new calculations to LAMMPS.
+Classes that compute scalar and vector quantities like temperature and
+the pressure tensor, as well as classes that compute per-atom quantities
+like kinetic energy and the centro-symmetry parameter are derived from
+the Compute class.  New styles can be created to add new calculations to
+LAMMPS.
 
-Compute_temp.cpp is a simple example of computing a scalar
-temperature.  Compute_ke_atom.cpp is a simple example of computing
-per-atom kinetic energy.
+The ``src/compute_temp.cpp`` file is a simple example of computing a
+scalar temperature. The ``src/compute_ke_atom.cpp`` file is a simple
+example of computing per-atom kinetic energy.
 
 Here is a brief description of methods you define in your new derived
-class.  See compute.h for details.
+class.  See ``src/compute.h`` for additional details.
 
++-----------------------+------------------------------------------------------------------+
+| post_constructor      | perform tasks that cannot be run in the constructor (optional)   |
 +-----------------------+------------------------------------------------------------------+
 | init                  | perform one time setup (required)                                |
 +-----------------------+------------------------------------------------------------------+
@@ -50,10 +52,11 @@ class.  See compute.h for details.
 | memory_usage          | tally memory usage (optional)                                    |
 +-----------------------+------------------------------------------------------------------+
 
-Tally-style computes are a special case, as their computation is done
-in two stages: the callback function is registered with the pair style
-and then called from the Pair::ev_tally() function, which is called for
-each pair after force and energy has been computed for this pair. Then
-the tallied values are retrieved with the standard compute_scalar or
-compute_vector or compute_peratom methods. The :doc:`compute styles in the TALLY package <compute_tally>`
-provide *examples* for utilizing this mechanism.
+Tally-style computes are a special case, as their computation is done in
+two stages: the callback function is registered with the pair style and
+then called from the Pair::ev_tally() function, which is called for each
+pair after force and energy has been computed for this pair. Then the
+tallied values are retrieved with the standard compute_scalar or
+compute_vector or compute_peratom methods. The :doc:`compute styles in
+the TALLY package <compute_tally>` provide *examples* for utilizing this
+mechanism.

doc/src/Modify_fix.rst

@@ -1,23 +1,25 @@
 Fix styles
 ==========
 
-In LAMMPS, a "fix" is any operation that is computed during
-timestepping that alters some property of the system.  Essentially
-everything that happens during a simulation besides force computation,
-neighbor list construction, and output, is a "fix".  This includes
-time integration (update of coordinates and velocities), force
-constraints or boundary conditions (SHAKE or walls), and diagnostics
-(compute a diffusion coefficient).  New styles can be created to add
-new options to LAMMPS.
+In LAMMPS, a "fix" is any operation that is computed during timestepping
+that alters some property of the system.  Essentially everything that
+happens during a simulation besides force computation, neighbor list
+construction, and output, is a "fix".  This includes time integration
+(update of coordinates and velocities), force constraints or boundary
+conditions (SHAKE or walls), and diagnostics (compute a diffusion
+coefficient).  New styles can be created to add new options to LAMMPS.
 
-Fix_setforce.cpp is a simple example of setting forces on atoms to
-prescribed values.  There are dozens of fix options already in LAMMPS;
-choose one as a template that is similar to what you want to
-implement.
+The file ``src/fix_setforce.cpp`` is a simple example of setting forces
+on atoms to prescribed values.  There are dozens of fix options already
+in LAMMPS; choose one as a template that is similar to what you want to
+implement.  There also is a detailed discussion of :doc:`how to write
+new fix styles <Developer_write_fix>` in LAMMPS.
 
 Here is a brief description of methods you can define in your new
-derived class.  See fix.h for details.
+derived class.  See ``src/fix.h`` for additional details.
 
++---------------------------+--------------------------------------------------------------------------------------------+
+| post_constructor          | perform tasks that cannot be run in the constructor (optional)                             |
 +---------------------------+--------------------------------------------------------------------------------------------+
 | setmask                   | determines when the fix is called during the timestep (required)                           |
 +---------------------------+--------------------------------------------------------------------------------------------+
@@ -130,10 +132,11 @@ derived class.  See fix.h for details.
 
 Typically, only a small fraction of these methods are defined for a
 particular fix.  Setmask is mandatory, as it determines when the fix
-will be invoked during the timestep.  Fixes that perform time
-integration (\ *nve*, *nvt*, *npt*\ ) implement initial_integrate() and
-final_integrate() to perform velocity Verlet updates.  Fixes that
-constrain forces implement post_force().
+will be invoked during :doc:`the evolution of a timestep
+<Developer_flow>`.  Fixes that perform time integration (\ *nve*, *nvt*,
+*npt*\ ) implement initial_integrate() and final_integrate() to perform
+velocity Verlet updates.  Fixes that constrain forces implement
+post_force().
 
 Fixes that perform diagnostics typically implement end_of_step().  For
 an end_of_step fix, one of your fix arguments must be the variable
@@ -143,13 +146,13 @@ is the first argument the fix defines (after the ID, group-ID, style).
 
 If the fix needs to store information for each atom that persists from
 timestep to timestep, it can manage that memory and migrate the info
-with the atoms as they move from processors to processor by
-implementing the grow_arrays, copy_arrays, pack_exchange, and
-unpack_exchange methods.  Similarly, the pack_restart and
-unpack_restart methods can be implemented to store information about
-the fix in restart files.  If you wish an integrator or force
-constraint fix to work with rRESPA (see the :doc:`run_style <run_style>`
-command), the initial_integrate, post_force_integrate, and
-final_integrate_respa methods can be implemented.  The thermo method
-enables a fix to contribute values to thermodynamic output, as printed
-quantities and/or to be summed to the potential energy of the system.
+with the atoms as they move from processors to processor by implementing
+the grow_arrays, copy_arrays, pack_exchange, and unpack_exchange
+methods.  Similarly, the pack_restart and unpack_restart methods can be
+implemented to store information about the fix in restart files.  If you
+wish an integrator or force constraint fix to work with rRESPA (see the
+:doc:`run_style <run_style>` command), the initial_integrate,
+post_force_integrate, and final_integrate_respa methods can be
+implemented.  The thermo method enables a fix to contribute values to
+thermodynamic output, as printed quantities and/or to be summed to the
+potential energy of the system.

doc/src/Modify_pair.rst

@@ -46,6 +46,8 @@ Here is a brief list of some the class methods in the Pair class that
 +---------------------------------+------------------------------------------------------------------------+
 | compute_inner/middle/outer      | versions of compute used by rRESPA                                     |
 +---------------------------------+------------------------------------------------------------------------+
+| compute_atomic_energy           | energy of one atom, equivalent to per-atom energy                      |
++---------------------------------+------------------------------------------------------------------------+
 | memory_usage                    | return estimated amount of memory used by the pair style               |
 +---------------------------------+------------------------------------------------------------------------+
 | modify_params                   | process arguments to pair_modify command                               |
@@ -122,3 +124,5 @@ setting.
 +---------------------------------+-------------------------------------------------------------+---------+
 | spinflag                        | 1 if compatible with spin kspace_style                      | 0       |
 +---------------------------------+-------------------------------------------------------------+---------+
+| atomic_energy_enable            | 1 if compute_atomic_energy() routine exists                 | 0       |
++---------------------------------+-------------------------------------------------------------+---------+

doc/src/Python_call.rst

@@ -5,18 +5,28 @@ LAMMPS has several commands which can be used to invoke Python
 code directly from an input script:
 
 * :doc:`python <python>`
-* :doc:`variable python <variable>`
+* :doc:`python-style variables <variable>`
+* :doc:`equal-style and atom-style variables with formulas containing Python function wrappers <variable>`
 * :doc:`fix python/invoke <fix_python_invoke>`
 * :doc:`pair_style python <pair_python>`
 
-The :doc:`python <python>` command which can be used to define and
-execute a Python function that you write the code for.  The Python
-function can also be assigned to a LAMMPS python-style variable via
-the :doc:`variable <variable>` command.  Each time the variable is
+The :doc:`python <python>` command can be used to define and execute a
+Python function that you write the code for.  The Python function can
+also be assigned to a LAMMPS python-style variable via the
+:doc:`variable <variable>` command.  Each time the variable is
 evaluated, either in the LAMMPS input script itself, or by another
 LAMMPS command that uses the variable, this will trigger the Python
 function to be invoked.
 
+The Python function can also be referenced in the formula used to
+define an :doc:`equal-style or atom-style variable <variable>`, using
+the syntax for a :doc:`Python function wrapper <variable>`.  This make
+it easy to pass LAMMPS-related arguments to the Python function, as
+well as to invoke it whenever the equal- or atom-style variable is
+evaluated.  For an atom-style variable it means the Python function
+can be invoked once per atom, using per-atom properties as arguments
+to the function.
+
 The Python code for the function can be included directly in the input
 script or in an auxiliary file.  The function can have arguments which
 are mapped to LAMMPS variables (also defined in the input script) and

doc/src/Python_launch.rst

@@ -1,7 +1,7 @@
 Running LAMMPS and Python in serial
 -----------------------------------
 
-To run a LAMMPS in serial, type these lines into Python
+To run a LAMMPS input in serial, type these lines into Python
 interactively from the ``bench`` directory:
 
 .. code-block:: python

doc/src/Python_scatter.rst

@@ -3,17 +3,16 @@ Scatter/gather operations
 
 .. code-block:: python
 
-   data = lmp.gather_atoms(name,type,count)  # return per-atom property of all atoms gathered into data, ordered by atom ID
-                                             # name = "x", "charge", "type", etc
-   data = lmp.gather_atoms_concat(name,type,count)  # ditto, but concatenated atom values from each proc (unordered)
-   data = lmp.gather_atoms_subset(name,type,count,ndata,ids)  # ditto, but for subset of Ndata atoms with IDs
+   data = lmp.gather_atoms(name,dtype,count)  # return per-atom property of all atoms gathered into data, ordered by atom ID
+                                              # name = "x", "q", "type", etc
+   data = lmp.gather_atoms_concat(name,dtype,count)  # ditto, but concatenated atom values from each proc (unordered)
+   data = lmp.gather_atoms_subset(name,dtype,count,ndata,ids)  # ditto, but for subset of Ndata atoms with IDs
 
-   lmp.scatter_atoms(name,type,count,data)   # scatter per-atom property to all atoms from data, ordered by atom ID
-                                             # name = "x", "charge", "type", etc
-                                             # count = # of per-atom values, 1 or 3, etc
-
-   lmp.scatter_atoms_subset(name,type,count,ndata,ids,data)  # ditto, but for subset of Ndata atoms with IDs
+   lmp.scatter_atoms(name,dtype,count,data)   # scatter per-atom property to all atoms from data, ordered by atom ID
+                                              # name = "x", "q", "type", etc
+                                              # count = # of per-atom values, 1 or 3, etc
 
+   lmp.scatter_atoms_subset(name,dtype,count,ndata,ids,data)  # ditto, but for subset of Ndata atoms with IDs
 
 The gather methods collect peratom info of the requested type (atom
 coords, atom types, forces, etc) from all processors, and returns the
@@ -22,6 +21,12 @@ functions do the inverse.  They distribute a vector of peratom values,
 passed by all calling processors, to individual atoms, which may be
 owned by different processors.
 
+The *dtype* parameter is 0 for ``int`` values and 1 for ``double``
+values.  The *count* parameter is 1 for per-atom vectors like "type"
+or "q" and 3 for per-atom arrays like "x", "v", "f". Use *count* = 3
+with name = "image" if you want the single integer storing the image
+flags unpacked into 3 components ("x", "y", and "z").
+
 Note that the data returned by the gather methods,
 e.g. :py:meth:`gather_atoms("x") <lammps.lammps.gather_atoms()>`, is
 different from the data structure returned by

doc/src/Speed_compare.rst

@@ -75,15 +75,34 @@ section below for examples where this has been done.
 **Differences between the GPU and KOKKOS packages:**
 
 * The GPU package accelerates only pair force, neighbor list, and (parts
-  of) PPPM calculations. The KOKKOS package attempts to run most of the
+  of) PPPM calculations (and runs the remaining force computations on
+  the CPU concurrently).  The KOKKOS package attempts to run most of the
   calculation on the GPU, but can transparently support non-accelerated
   code (with a performance penalty due to having data transfers between
   host and GPU).
+* The list of which styles are accelerated by the GPU or KOKKOS package
+  differs with some overlap.
 * The GPU package requires neighbor lists to be built on the CPU when using
   hybrid pair styles, exclusion lists, or a triclinic simulation box.
-* The GPU package can be compiled for CUDA, HIP, or OpenCL and thus supports
-  NVIDIA, AMD, and Intel GPUs well. On NVIDIA hardware, using CUDA is
-  typically resulting in equal or better performance over OpenCL.
-* OpenCL in the GPU package does theoretically also support Intel CPUs or
-  Intel Xeon Phi, but the native support for those in KOKKOS (or INTEL)
-  is superior.
+* The GPU package benefits from running multiple MPI processes (2-8) per
+  GPU to parallelize the non-GPU accelerated styles.  The KOKKOS package
+  usually not, especially when all parts of the calculation have KOKKOS
+  support.
+* The GPU package can be compiled for CUDA, HIP, or OpenCL and thus
+  supports NVIDIA, AMD, and Intel GPUs well. On NVIDIA or AMD hardware,
+  using native CUDA or HIP compilation, respectively, with either GPU or
+  KOKKOS results in equal or better performance over OpenCL.
+* OpenCL in the GPU package supports NVIDIA, AMD, and Intel GPUs at the
+  *same time* and with the *same executable*.  KOKKOS currently does not
+  support OpenCL.
+* The GPU package supports single precision floating point, mixed
+  precision floating point, and double precision floating point math on
+  the GPU.  This must be chosen at compile time.  KOKKOS currently only
+  supports double precision floating point math.  Using single or mixed
+  precision (recommended) results in significantly improved performance
+  on consumer GPUs for some loss in accuracy (which is rather small with
+  mixed precision).  Single and mixed precision support for KOKKOS is in
+  development (no ETA yet).
+* Some pair styles (for example :doc:`snap <pair_snap>`, :doc:`mliap
+  <pair_mliap>` or :doc:`reaxff <pair_reaxff>` in the KOKKOS package have
+  seen extensive optimizations and specializations for GPUs and CPUs.

doc/src/Speed_measure.rst

@@ -1,16 +1,218 @@
 Measuring performance
 =====================
 
-Before trying to make your simulation run faster, you should
-understand how it currently performs and where the bottlenecks are.
+Factors that influence performance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The best way to do this is run the your system (actual number of
-atoms) for a modest number of timesteps (say 100 steps) on several
-different processor counts, including a single processor if possible.
-Do this for an equilibrium version of your system, so that the
-100-step timings are representative of a much longer run.  There is
-typically no need to run for 1000s of timesteps to get accurate
-timings; you can simply extrapolate from short runs.
+Before trying to make your simulation run faster, you should understand
+how it currently performs and where the bottlenecks are.  We generally
+distinguish between serial performance (how fast can a single process do
+the calculations?) and parallel efficiency (how much faster does a
+calculation get by using more processes?).  There are many factors
+affecting either and below are some lists discussing some commonly
+known but also some less known factors.
+
+Factors affecting serial performance (in no specific order):
+
+* CPU hardware: clock rate, cache sizes, CPU architecture (instructions
+  per clock, vectorization support, fused multiply-add support and more)
+* RAM speed and number of channels that the CPU can use to access RAM
+* Cooling: CPUs can change the CPU clock based on thermal load, thus the
+  degree of cooling can affect the speed of a CPU.  Sometimes even the
+  temperature of neighboring compute nodes in a cluster can make a
+  difference.
+* Compiler optimization: most of LAMMPS is written to be easy to modify
+  and thus compiler optimization can speed up calculations. However, too
+  aggressive compiler optimization can produce incorrect results or
+  crashes (during compilation or at runtime).
+* Source code improvements: styles in the OPT, OPENMP, and INTEL package
+  can be faster than their base implementation due to improved data
+  access patterns, cache efficiency, or vectorization. Compiler optimization
+  is required to take full advantage of these.
+* Number and kind of fixes, computes, or variables used during a simulation,
+  especially if they result in collective communication operations
+* Pair style cutoffs and system density: calculations get slower the more
+  neighbors are in the neighbor list and thus for which interactions need
+  to be computed.  Force fields with pair styles that compute interactions
+  between triples or quadruples of atoms or that use embedding energies or
+  charge equilibration will need to walk the neighbor lists multiple times.
+* Neighbor list settings: tradeoff between neighbor list skin (larger
+  skin = more neighbors, more distances to compute before applying the
+  cutoff) and frequency of neighbor list builds (larger skin = fewer
+  neighbor list builds).
+* Proximity of per-atom data in physical memory that for atoms that are
+  close in space improves cache efficiency (thus LAMMPS will by default
+  sort atoms in local storage accordingly)
+* Using r-RESPA multi-timestepping or a SHAKE or RATTLE fix to constrain
+  bonds with higher-frequency vibrations may allow a larger (outer) timestep
+  and thus fewer force evaluations (usually the most time consuming step in
+  MD) for the same simulated time (with some tradeoff in accuracy).
+
+Factors affecting parallel efficiency (in no specific order):
+
+* Bandwidth and latency of communication between processes. This can vary a
+  lot between processes on the same CPU or physical node and processes
+  on different physical nodes and there vary between different
+  communication technologies (like Ethernet or InfiniBand or other
+  high-speed interconnects)
+* Frequency and complexity of communication patterns required
+* Number of "work units" (usually correlated with the number of atoms
+  and choice of force field) per MPI-process required for one time step
+  (if this number becomes too small, the cost of communication becomes
+  dominant).
+* Choice of parallelization method (MPI-only, OpenMP-only, MPI+OpenMP,
+  MPI+GPU, MPI+GPU+OpenMP)
+* Algorithmic complexity of the chosen force field (pair-wise vs. many-body
+  potential, Ewald vs. PPPM vs. (compensated or smoothed) cutoff-Coulomb)
+* Communication cutoff: a larger cutoff results in more ghost atoms and
+  thus more data that needs to be communicated
+* Frequency of neighbor list builds: during a neighbor list build the
+  domain decomposition is updated and the list of ghost atoms rebuilt
+  which requires multiple global communication steps
+* FFT-grid settings and number of MPI processes for kspace style PPPM:
+  PPPM uses parallel 3d FFTs which will drop much faster in parallel
+  efficiency with respect to the number of MPI processes than other
+  parts of the force computation.  Thus using MPI+OpenMP parallelization
+  or :doc:`run style verlet/split <run_style>` can improve parallel
+  efficiency by limiting the number of MPI processes used for the FFTs.
+* Load (im-)balance: LAMMPS' domain decomposition assumes that atoms are
+  evenly distributed across the entire simulation box. If there are
+  areas of vacuum, this may lead to different amounts of work for
+  different MPI processes. Using the :doc:`processors command
+  <processors>` to change the spatial decomposition, or MPI+OpenMP
+  parallelization instead of only-MPI to have larger sub-domains, or the
+  (fix) balance command (without or with switching to communication style
+  tiled) to change the sub-domain volumes are all methods that
+  can help to avoid load imbalances.
+
+Examples comparing serial performance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before looking at your own input deck(s), you should get some reference
+data from a known input so that you know what kind of performance you
+should expect from your input.  For the following we therefore use the
+``in.rhodo.scaled`` input file and ``data.rhodo`` data file from the
+``bench`` folder. This is a system of 32000 atoms using the CHARMM force
+field and long-range electrostatics running for 100 MD steps.  The
+performance data is printed at the end of a run and only measures the
+performance during propagation and excludes the setup phase.
+
+Running with a single MPI process on an AMD Ryzen Threadripper PRO
+9985WX CPU (64 cores, 128 threads, base clock: 3.2GHz, max. clock
+5.4GHz, L1/L2/L3 cache 5MB/64MB/256MB, 8 DDR5-6400 memory channels) one
+gets the following performance report:
+
+.. code-block::
+
+   Performance: 1.232 ns/day, 19.476 hours/ns, 7.131 timesteps/s, 228.197 katom-step/s
+   99.2% CPU use with 1 MPI tasks x 1 OpenMP threads
+
+The %CPU value should be at 100% or very close.  Lower values would
+be an indication that there are *other* processes also using the same
+CPU core and thus invalidating the performance data.  The katom-step/s
+value is best suited for comparisons, since it is fairly independent
+from the system size. The `in.rhodo.scaled` input can be easily made
+larger through replication in the three dimensions by settings variables
+"x", "y", "z" to values other than 1 from the command line with the
+"-var" flag. Example:
+
+- 32000 atoms: 228.8 katom-step/s
+- 64000 atoms: 231.6 katom-step/s
+- 128000 atoms: 231.1 katom-step/s
+- 256000 atoms: 226.4 katom-step/s
+- 864000 atoms: 229.6 katom-step/s
+
+Comparing to an AMD Ryzen 7 7840HS CPU (8 cores, 16 threads, base clock
+3.8GHz, max. clock 5.1GHz, L1/L2/L3 cache 512kB/8MB/16MB, 2 DDR5-5600
+memory channels), we get similar single core performance (~220
+katom-step/s vs. ~230 katom-step/s) due to the similar clock and
+architecture:
+
+- 32000 atoms: 219.8 katom-step/s
+- 64000 atoms: 222.5 katom-step/s
+- 128000 atoms: 216.8 katom-step/s
+- 256000 atoms: 221.0 katom-step/s
+- 864000 atoms: 221.1 katom-step/s
+
+Switching to an older Intel Xeon E5-2650 v4 CPU (12 cores, 12 threads,
+base clock 2.2GHz, max. clock 2.9GHz, L1/L2/L3 cache (64kB/256kB/30MB, 4
+DDR4-2400 memory channels) leads to a lower performance of approximately
+109 katom-step/s due to differences in architecture and clock.  In all
+cases, when looking at multiple runs, the katom-step/s property
+fluctuates by approximately 1% around the average.
+
+From here on we are looking at the performance for the 256000 atom system only
+and change several settings incrementally:
+
+#. No compiler optimization GCC (-Og -g): 183.8 katom-step/s
+#. Moderate optimization with debug info GCC (-O2 -g): 231.1 katom-step/s
+#. Full compiler optimization GCC (-DNDEBUG -O3): 236.0 katom-step/s
+#. Aggressive compiler optimization GCC (-O3 -ffast-math -march=native): 239.9 katom-step/s
+#. Source code optimization in OPENMP package (1 thread): 266.7 katom-step/s
+#. Use *fix nvt* instead of *fix npt* (compute virial only every 50 steps): 272.9 katom-step/s
+#. Increase pair style cutoff by 2 :math:`\AA`: 181.2 katom-step/s
+#. Use tight PPPM convergence (1.0e-6 instead of 1.0e-4): 161.9 katom-step/s
+#. Use Ewald summation instead of PPPM (at 1.0e-4 convergence): 19.9 katom-step/s
+
+The numbers show that gains from aggressive compiler optimizations are
+rather small in LAMMPS, the data access optimizations in the OPENMP (and
+OPT) packages are more prominent.  On the other side, using more
+accurate force field settings causes, not unexpectedly, a significant
+slowdown (to about half the speed).  Finally, using regular Ewald
+summation causes a massive slowdown due to the bad algorithmic scaling
+with system size.
+
+Examples comparing parallel performance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The parallel performance usually goes on top of the serial performance.
+Using twice as many processors should increase the performance metric
+by up to a factor of two.  With the number of processors *N* and the
+serial performance :math:`p_1` and the performance for *N* processors
+:math:`p_N` we can define a *parallel efficiency* in percent as follows:
+
+.. math::
+
+   P_{eff} = \frac{p_N}{p_1 \cdot N} \cdot 100\%
+
+For the AMD Ryzen Threadripper PRO 9985WX CPU and the serial
+simulation settings of point 6. from above, we get the following
+parallel efficiency data for the 256000 atom system:
+
+- 1 MPI task: 273.6 katom-step/s, :math:`P_{eff} = 100\%`
+- 2 MPI tasks: 530.6 katom-step/s, :math:`P_{eff} = 97\%`
+- 4 MPI tasks: 1.021 Matom-step/s, :math:`P_{eff} = 93\%`
+- 8 MPI tasks: 1.837 Matom-step/s, :math:`P_{eff} = 84\%`
+- 16 MPI tasks: 3.574 Matom-step/s, :math:`P_{eff} = 82\%`
+- 32 MPI tasks: 6.479 Matom-step/s, :math:`P_{eff} = 74\%`
+- 64 MPI tasks: 9.032 Matom-step/s, :math:`P_{eff} = 52\%`
+- 128 MPI tasks: 12.03 Matom-step/s, :math:`P_{eff} = 34\%`
+
+The 128 MPI tasks run uses CPU cores from hyper-threading.
+
+For a small system with only 32000 atoms the parallel efficiency
+drops off earlier when the number of work units is too small relative
+to the communication overhead:
+
+- 1 MPI task:  270.8  katom-step/s, :math:`P_{eff} = 100\%`
+- 2 MPI tasks: 529.3  katom-step/s, :math:`P_{eff} = 98\%`
+- 4 MPI tasks: 989.8  katom-step/s, :math:`P_{eff} = 91\%`
+- 8 MPI tasks: 1.832  Matom-step/s, :math:`P_{eff} = 85\%`
+- 16 MPI tasks: 3.463 Matom-step/s, :math:`P_{eff} = 80\%`
+- 32 MPI tasks: 5.970 Matom-step/s, :math:`P_{eff} = 69\%`
+- 64 MPI tasks: 7.477 Matom-step/s, :math:`P_{eff} = 42\%`
+- 128 MPI tasks: 8.069 Matom-step/s, :math:`P_{eff} = 23\%`
+
+Measuring performance of your input deck
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The best way to do this is run the your system (actual number of atoms)
+for a modest number of timesteps (say 100 steps) on several different
+processor counts, including a single processor if possible.  Do this for
+an equilibrium version of your system, so that the 100-step timings are
+representative of a much longer run.  There is typically no need to run
+for 1000s of timesteps to get accurate timings; you can simply
+extrapolate from short runs.
 
 For the set of runs, look at the timing data printed to the screen and
 log file at the end of each LAMMPS run.  The
@@ -28,12 +230,15 @@ breakdown and relative percentages.  For example, trying different
 options for speeding up the long-range solvers will have little impact
 if they only consume 10% of the run time.  If the pairwise time is
 dominating, you may want to look at GPU or OMP versions of the pair
-style, as discussed below.  Comparing how the percentages change as
-you increase the processor count gives you a sense of how different
-operations within the timestep are scaling.  Note that if you are
-running with a Kspace solver, there is additional output on the
-breakdown of the Kspace time.  For PPPM, this includes the fraction
-spent on FFTs, which can be communication intensive.
+style, as discussed below.  Comparing how the percentages change as you
+increase the processor count gives you a sense of how different
+operations within the timestep are scaling.  If you are using PPPM as
+Kspace solver, you can turn on an additional output with
+:doc:`kspace_modify fftbench yes <kspace_modify>` which measures the
+time spent during PPPM on the 3d FFTs, which can be communication
+intensive for larger processor counts.  This provides an indication
+whether it is worth trying out alternatives to the default FFT settings
+for additional performance.
 
 Another important detail in the timing info are the histograms of
 atoms counts and neighbor counts.  If these vary widely across

doc/src/Tools.rst

@@ -92,6 +92,7 @@ Miscellaneous tools
    * :ref:`LAMMPS coding standards <coding_standard>`
    * :ref:`emacs <emacs>`
    * :ref:`i-PI <ipi>`
+   * :ref:`JSON support <json>`
    * :ref:`kate <kate>`
    * :ref:`LAMMPS-GUI <lammps_gui>`
    * :ref:`LAMMPS magic patterns for file(1) <magic>`
@@ -364,7 +365,7 @@ These tools were provided by Aidan Thompson at Sandia
 .. _fep:
 
 fep tool
-------------------
+--------
 
 The tools/fep directory contains Python scripts useful for
 post-processing results from performing free-energy perturbation
@@ -379,7 +380,7 @@ See README file in the tools/fep directory.
 .. _ipi:
 
 i-PI tool
--------------------
+---------
 
 .. versionchanged:: 27June2024
 
@@ -432,6 +433,87 @@ tools/createatoms tool's input file.
 
 ----------
 
+.. _json:
+
+JSON support files
+------------------
+
+.. versionadded:: 12June2025
+
+The ``tools/json`` directory contains files and tools to support
+using `JSON format <https://www.json.org/>`_ files in LAMMPS.
+Currently only the :doc:`molecule command <molecule>` supports
+files in JSON format directly, but this is planned to be expanded
+in the future.
+
+JSON file validation
+^^^^^^^^^^^^^^^^^^^^
+
+The JSON syntax is independent of its content, and thus the data in the
+file must follow suitable conventions to be correctly parsed during
+input.  This can be done in a portable fashion using a `JSON schema file
+<https://json-schema.org/>`_ (which is in JSON format as well) to define
+those conventions.  A suitable JSON validator software can then validate
+JSON files against the requirements.  Validating a particular JSON file
+against a schema ensures that both, the syntax *and* the conventions
+are followed.  This is useful when writing or editing JSON files in a
+text editor or when writing a pre-processing script or tool to create
+JSON files for a specific purpose in LAMMPS.  It **cannot** check
+whether the file contents are physically meaningful, though.
+
+One such validator tool is `check-jsonschema
+<https://check-jsonschema.readthedocs.io/>`_ which is written in Python
+and can be installed using the `pip Python package manager
+<https://pypi.org/>`_, best in a virtual environment as shown below (for
+a Bourne Shell command line):
+
+.. code-block:: sh
+
+   python -m venv validate-json
+   source validate-json/bin/activate
+   pip install --upgrade pip
+   pip install check-jsonschema
+
+To validate a specific JSON file against a provided schema (here for
+a :doc:`molecule command file <molecule>` you would then run for example:
+
+.. code-block:: sh
+
+   check-jsonschema --schemafile molecule-schema.json tip3p.json
+
+The latest schema files are also maintained and available for download
+at https://download.lammps.org/json .  This enables validation of JSON
+files even if the LAMMPS sources are not locally available. Example:
+
+.. code-block:: sh
+
+   check-jsonschema --schemafile https://download.lammps.org/json/molecule-schema.json tip3p.json
+
+JSON file format normalization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are extensions to the strict JSON format that allow for comments
+or ignore additional (dangling) commas. The ``reformat-json.cpp`` tool
+will read JSON files in relaxed format, but write it out in strict format.
+It is also possible to change the level of indentation from -1 (all data
+one long line) to any positive integer value.  The original file will be
+backed up (.bak added to file name) and then overwritten.
+
+Manual compilation (it will be automatically included in the CMake build
+if building tools is requested during CMake configuration):
+
+.. code-block:: sh
+
+   g++ -I <path/to/lammps/src> -o reformat-json reformat-json.cpp
+
+Usage:
+
+.. parsed-literal::
+
+   reformat-json <indent-width> <json-file-1> [<json-file-2> ...]
+
+----------
+
 .. _kate:
 
 kate tool
@@ -475,9 +557,13 @@ beginners to start with LAMMPS, it is also the expectation that
 LAMMPS-GUI users will eventually transition to workflows that most
 experienced LAMMPS users employ.
 
-All features have been extensively exposed to keyboard shortcuts, so
-that there is also appeal for experienced LAMMPS users for prototyping
-and testing simulation setups.
+.. image:: JPG/lammps-gui-screen.png
+   :align: center
+   :scale: 50%
+
+Features have been extensively exposed to keyboard shortcuts, so that
+there is also appeal for experienced LAMMPS users for prototyping and
+testing simulation setups.
 
 Features
 ^^^^^^^^
@@ -502,7 +588,7 @@ Here are a few highlights of LAMMPS-GUI
 - Visualization of current state in Image Viewer (via calling :doc:`write_dump image <dump_image>`)
 - Capture of images created via :doc:`dump image <dump_image>` in Slide show window
 - Dialog to set variables, similar to the LAMMPS command-line flag '-v' / '-var'
-- Support for GPU, INTEL, KOKKOS/OpenMP, OPENMAP, and OPT and accelerator packages
+- Support for GPU, INTEL, KOKKOS/OpenMP, OPENMP, and OPT accelerator packages
 
 Parallelization
 ^^^^^^^^^^^^^^^
@@ -523,8 +609,8 @@ with CMake is required.
 The LAMMPS-GUI has been successfully compiled and tested on:
 
 - Ubuntu Linux 20.04LTS x86_64 using GCC 9, Qt version 5.12
-- Fedora Linux 40 x86\_64 using GCC 14 and Clang 17, Qt version 5.15LTS
-- Fedora Linux 40 x86\_64 using GCC 14, Qt version 6.7
+- Fedora Linux 41 x86\_64 using GCC 14 and Clang 17, Qt version 5.15LTS
+- Fedora Linux 41 x86\_64 using GCC 14, Qt version 6.8
 - Apple macOS 12 (Monterey) and macOS 13 (Ventura) with Xcode on arm64 and x86\_64, Qt version 5.15LTS
 - Windows 10 and 11 x86_64 with Visual Studio 2022 and Visual C++ 14.36, Qt version 5.15LTS
 - Windows 10 and 11 x86_64 with Visual Studio 2022 and Visual C++ 14.40, Qt version 6.7
@@ -1250,10 +1336,10 @@ tabulate tool
 
 .. versionadded:: 22Dec2022
 
-The ``tabulate`` folder contains Python scripts scripts to generate tabulated
-potential files for LAMMPS.  The bulk of the code is in the ``tabulate`` module
-in the ``tabulate.py`` file.  Some example files demonstrating its use are
-included.  See the README file for more information.
+The ``tabulate`` folder contains Python scripts scripts to generate and
+visualize tabulated potential files for LAMMPS.  The bulk of the code is in the
+``tabulate`` module in the ``tabulate.py`` file.  Some example files
+demonstrating its use are included.  See the README file for more information.
 
 ----------
 
@@ -1276,11 +1362,13 @@ Those scripts were written by Steve Plimpton sjplimp at gmail.com
 valgrind tool
 -------------
 
-The ``valgrind`` folder contains additional suppressions fur LAMMPS when using
-valgrind's memcheck tool to search for memory access violation and memory
-leaks. These suppressions are automatically invoked when running tests through
-CMake "ctest -T memcheck". See the provided README file to add these
-suppressions when running LAMMPS.
+The ``valgrind`` folder contains additional suppressions for LAMMPS when
+using `valgrind's <https://valgrind.org/>`_ ` `memcheck tool
+<https://valgrind.org/info/tools.html#memcheck>`_ to search for memory
+access violation and memory leaks.  These suppressions are automatically
+invoked when running tests through CMake "ctest -T memcheck".  See the
+instruction in the ``README`` file to add these suppressions when using
+valgrind with LAMMPS or other programs.
 
 ----------
 

doc/src/bond_bpm_rotational.rst

@@ -215,6 +215,9 @@ for an overview of LAMMPS output options.
 The vector or array will be floating point values that correspond to
 the specified attribute.
 
+Any settings with the *store/local* option are not saved to a restart
+file and must be redefined.
+
 The single() function of this bond style returns 0.0 for the energy
 of a bonded interaction, since energy is not conserved in these
 dissipative potentials.  It also returns only the normal component of

doc/src/bond_bpm_spring.rst

@@ -215,6 +215,9 @@ for an overview of LAMMPS output options.
 The vector or array will be floating point values that correspond to
 the specified attribute.
 
+Any settings with the *store/local* option are not saved to a restart
+file and must be redefined.
+
 The potential energy and the single() function of this bond style return
 :math:`k (r - r_0)^2 / 2` as a proxy of the energy of a bonded interaction,
 ignoring any volumetric/smoothing factors or dissipative forces.  The single()

doc/src/compute_angle_local.rst

@@ -53,15 +53,17 @@ The value *eng* is the interaction energy for the angle.
 
 The value *v_name* can be used together with the *set* keyword to
 compute a user-specified function of the angle theta.  The *name*
-specified for the *v_name* value is the name of an :doc:`equal-style variable <variable>` which should evaluate a formula based on a
+specified for the *v_name* value is the name of an :doc:`equal-style
+variable <variable>` which should evaluate a formula based on a
 variable which will store the angle theta.  This other variable must
-be an :doc:`internal-style variable <variable>` defined in the input
-script; its initial numeric value can be anything.  It must be an
-internal-style variable, because this command resets its value
-directly.  The *set* keyword is used to identify the name of this
-other variable associated with theta.
+be an :doc:`internal-style variable <variable>` specified by the *set*
+keyword.  It is an internal-style variable, because this command
+resets its value directly.  The internal-style variable does not need
+to be defined in the input script (though it can be); if it is not
+defined, then the *set* option creates an :doc:`internal-style
+variable <variable>` with the specified name.
 
-Note that the value of theta for each angle which stored in the
+Note that the value of theta for each angle which is stored in the
 internal variable is in radians, not degrees.
 
 As an example, these commands can be added to the bench/in.rhodo
@@ -70,7 +72,6 @@ system and output the statistics in various ways:
 
 .. code-block:: LAMMPS
 
-   variable t internal 0.0
    variable cos equal cos(v_t)
    variable cossq equal cos(v_t)*cos(v_t)
 

doc/src/compute_bond_local.rst

@@ -64,20 +64,32 @@ All these properties are computed for the pair of atoms in a bond,
 whether the two atoms represent a simple diatomic molecule, or are part
 of some larger molecule.
 
-The value *dist* is the current length of the bond.
-The values *dx*, *dy*, and *dz* are the xyz components of the
-*distance* between the pair of atoms. This value is always the
-distance from the atom of lower to the one with the higher id.
+.. versionchanged:: 12Jun2025
+
+   The sign of *dx*, *dy*, *dz* is no longer determined by the atom IDs
+   of the bonded atoms but by their order in the bond list to be
+   consistent with *fx*, *fy*, and *fz*.
+
+The value *dist* is the current length of the bond.  The values *dx*,
+*dy*, and *dz* are the :math:`(x,y,z)` components of the distance vector
+:math:`\vec{x_i} - \vec{x_j}` between the atoms in the bond.  The order
+of the atoms is determined by the bond list and the respective atom-IDs
+can be output with :doc:`compute property/local
+<compute_property_local>`.
 
 The value *engpot* is the potential energy for the bond,
 based on the current separation of the pair of atoms in the bond.
 
-The value *force* is the magnitude of the force acting between the
-pair of atoms in the bond.
+The value *force* is the magnitude of the force acting between the pair
+of atoms in the bond, which is positive for a repulsive force and
+negative for an attractive force.
 
-The values *fx*, *fy*, and *fz* are the xyz components of
-*force* between the pair of atoms in the bond. For bond styles that apply
-non-central forces, such as :doc:`bond_style bpm/rotational
+The values *fx*, *fy*, and *fz* are the :math:`(x,y,z)` components of
+the force on the first atom *i* in the bond due to the second atom *j*.
+Mathematically, they are obtained by multiplying the value of *force*
+from above with a unit vector created from the *dx*, *dy*, and *dz*
+components of the distance vector also described above.  For bond styles
+that apply non-central forces, such as :doc:`bond_style bpm/rotational
 <bond_bpm_rotational>`, these values only include the :math:`(x,y,z)`
 components of the normal force component.
 
@@ -118,13 +130,15 @@ moving apart.
 
 The value *v_name* can be used together with the *set* keyword to
 compute a user-specified function of the bond distance.  The *name*
-specified for the *v_name* value is the name of an :doc:`equal-style variable <variable>` which should evaluate a formula based on a
-variable which will store the bond distance.  This other variable must
-be an :doc:`internal-style variable <variable>` defined in the input
-script; its initial numeric value can be anything.  It must be an
-internal-style variable, because this command resets its value
-directly.  The *set* keyword is used to identify the name of this
-other variable associated with theta.
+specified for the *v_name* value is the name of an :doc:`equal-style
+variable <variable>` which should evaluate a formula based on a
+variable which stores the bond distance.  This other variable must be
+the :doc:`internal-style variable <variable>` specified by the *set*
+keyword.  It is an internal-style variable, because this command
+resets its value directly.  The internal-style variable does not need
+to be defined in the input script (though it can be); if it is not
+defined, then the *set* option creates an :doc:`internal-style
+variable <variable>` with the specified name.
 
 As an example, these commands can be added to the bench/in.rhodo
 script to compute the length\ :math:`^2` of every bond in the system and
@@ -132,7 +146,6 @@ output the statistics in various ways:
 
 .. code-block:: LAMMPS
 
-   variable d internal 0.0
    variable dsq equal v_d*v_d
 
    compute 1 all property/local batom1 batom2 btype

doc/src/compute_dihedral_local.rst

@@ -45,30 +45,31 @@ interactions.  The number of datums generated, aggregated across all
 processors, equals the number of dihedral angles in the system, modified
 by the group parameter as explained below.
 
-The value *phi* (:math:`\phi`) is the dihedral angle, as defined in the diagram
-on the :doc:`dihedral_style <dihedral_style>` doc page.
+The value *phi* (:math:`\phi`) is the dihedral angle, as defined in
+the diagram on the :doc:`dihedral_style <dihedral_style>` doc page.
 
-The value *v_name* can be used together with the *set* keyword to compute a
-user-specified function of the dihedral angle :math:`\phi`.  The *name*
-specified for the *v_name* value is the name of an
-:doc:`equal-style variable <variable>` which should evaluate a formula based on
-a variable which will store the angle :math:`\phi`.  This other variable must
-be an :doc:`internal-style variable <variable>` defined in the input
-script; its initial numeric value can be anything.  It must be an
-internal-style variable, because this command resets its value
-directly.  The *set* keyword is used to identify the name of this
-other variable associated with :math:`\phi`.
+The value *v_name* can be used together with the *set* keyword to
+compute a user-specified function of the dihedral angle :math:`\phi`.
+The *name* specified for the *v_name* value is the name of an
+:doc:`equal-style variable <variable>` which should evaluate a formula
+based on a variable which will store the angle :math:`\phi`.  This
+other variable must be an :doc:`internal-style variable <variable>`
+specified by the *set* keyword.  It is an internal-style variable,
+because this command resets its value directly.  The internal-style
+variable does not need to be defined in the input script (though it
+can be); if it is not defined, then the *set* option creates an
+:doc:`internal-style variable <variable>` with the specified name.
 
-Note that the value of :math:`\phi` for each angle which stored in the internal
-variable is in radians, not degrees.
+Note that the value of :math:`\phi` for each angle which stored in the
+internal variable is in radians, not degrees.
 
 As an example, these commands can be added to the bench/in.rhodo
-script to compute the :math:`\cos\phi` and :math:`\cos^2\phi` of every dihedral
-angle in the system and output the statistics in various ways:
+script to compute the :math:`\cos\phi` and :math:`\cos^2\phi` of every
+dihedral angle in the system and output the statistics in various
+ways:
 
 .. code-block:: LAMMPS
 
-   variable p internal 0.0
    variable cos equal cos(v_p)
    variable cossq equal cos(v_p)*cos(v_p)
 
@@ -100,10 +101,10 @@ no consistent ordering of the entries within the local vector or array
 from one timestep to the next.  The only consistency that is
 guaranteed is that the ordering on a particular timestep will be the
 same for local vectors or arrays generated by other compute commands.
-For example, dihedral output from the
-:doc:`compute property/local <compute_property_local>` command can be combined
-with data from this command and output by the :doc:`dump local <dump>`
-command in a consistent way.
+For example, dihedral output from the :doc:`compute property/local
+<compute_property_local>` command can be combined with data from this
+command and output by the :doc:`dump local <dump>` command in a
+consistent way.
 
 Here is an example of how to do this:
 

doc/src/compute_pair_local.rst

@@ -56,19 +56,33 @@ force cutoff distance for that interaction, as defined by the
 :doc:`pair_style <pair_style>` and :doc:`pair_coeff <pair_coeff>`
 commands.
 
-The value *dist* is the distance between the pair of atoms.
-The values *dx*, *dy*, and *dz* are the :math:`(x,y,z)` components of the
-*distance* between the pair of atoms. This value is always the
-distance from the atom of higher to the one with the lower atom ID.
+.. versionchanged:: 12Jun2025
+
+   The sign of *dx*, *dy*, *dz* is no longer determined by the value of
+   their atom-IDs but by their order in the neighbor list to be
+   consistent with *fx*, *fy*, and *fz*.
+
+The value *dist* is the distance between the pair of atoms.  The values
+*dx*, *dy*, and *dz* are the :math:`(x,y,z)` components of the distance
+vector :math:`\vec{x_i} - \vec{x_j}` between the pair of atoms.  The
+order of the atoms is determined by the neighbor list and the respective
+atom-IDs can be output with :doc:`compute property/local
+<compute_property_local>`.
 
 The value *eng* is the interaction energy for the pair of atoms.
 
 The value *force* is the force acting between the pair of atoms, which
 is positive for a repulsive force and negative for an attractive
-force.  The values *fx*, *fy*, and *fz* are the :math:`(x,y,z)` components of
-*force* on atom I. For pair styles that apply non-central forces,
-such as :doc:`granular pair styles <pair_gran>`, these values only include
-the :math:`(x,y,z)` components of the normal force component.
+force.
+
+The values *fx*, *fy*, and *fz* are the :math:`(x,y,z)` components of
+the force vector on the first atom *i* of a pair in the neighbor list
+due to the second atom *j*.  Mathematically, they are obtained by
+multiplying the value of *force* from above with a unit vector created
+from the *dx*, *dy*, and *dz* components of the distance vector also
+described above.  For pair styles that apply non-central forces, such as
+:doc:`granular pair styles <pair_gran>`, these values only include the
+:math:`(x,y,z)` components of the normal force component.
 
 A pair style may define additional pairwise quantities which can be
 accessed as *p1* to *pN*, where :math:`N` is defined by the pair style.

doc/src/compute_rheo_property_atom.rst

@@ -88,7 +88,7 @@ The *phase* property indicates whether the particle is in a fluid state,
 a value of 0, or a solid state, a value of 1.
 
 The *surface* property indicates the surface designation produced by
-the *interface/reconstruct* option of :doc:`fix rheo <fix_rheo>`. Bulk
+the *surface/detection* option of :doc:`fix rheo <fix_rheo>`. Bulk
 particles have a value of 0, surface particles have a value of 1, and
 splash particles have a value of 2. The *surface/r* property is the
 distance from the surface, up to the kernel cutoff length. Surface particles

doc/src/create_atoms.rst

@@ -28,7 +28,7 @@ Syntax
          region-ID = create atoms within this region, use NULL for entire simulation box
 
 * zero or more keyword/value pairs may be appended
-* keyword = *mol* or *basis* or *ratio* or *subset* or *remap* or *var* or *set* or *radscale* or *meshmode* or *rotate* or *overlap* or *maxtry* or *units*
+* keyword = *mol* or *basis* or *ratio* or *subset* or *group* or *remap* or *var* or *set* or *radscale* or *meshmode* or *rotate* or *overlap* or *maxtry* or *units*
 
   .. parsed-literal::
 
@@ -44,6 +44,7 @@ Syntax
        *subset* values = Nsubset seed
          Nsubset = # of lattice sites to populate randomly
          seed = random # seed (positive integer)
+       *group* value = group name
        *remap* value = *yes* or *no*
        *var* value = name = variable name to evaluate for test of atom creation
        *set* values = dim name
@@ -83,7 +84,7 @@ Examples
 
    create_atoms 3 region regsphere basis 2 3
    create_atoms 3 region regsphere basis 2 3 ratio 0.5 74637
-   create_atoms 3 single 0 0 5
+   create_atoms 3 single 0 0 5 group newatom
    create_atoms 1 box var v set x xpos set y ypos
    create_atoms 2 random 50 12345 NULL overlap 2.0 maxtry 50
    create_atoms 1 mesh open_box.stl meshmode qrand 0.1 units box
@@ -395,6 +396,14 @@ correct number of particles are inserted, in a perfectly random
 fashion.  Which lattice sites are selected will change with the number
 of processors used.
 
+.. versionadded:: 12Jun2025
+
+The *group* keyword adds the newly created atoms to the named
+:doc:`group <group>`.  If the group does not yet exist it will be
+created.  There can be only one such group, thus if the *group* keyword
+is used multiple times, only the last one will be used.  All created
+atoms are always added to the group "all".
+
 The *remap* keyword only applies to the *single* style.  If it is set
 to *yes*, then if the specified position is outside the simulation
 box, it will mapped back into the box, assuming the relevant
@@ -407,24 +416,23 @@ atom, based on its coordinates.  They apply to all styles except
 *single*.  The *name* specified for the *var* keyword is the name of
 an :doc:`equal-style variable <variable>` that should evaluate to a
 zero or non-zero value based on one or two or three variables that
-will store the *x*, *y*, or *z* coordinates of an atom (one variable per
-coordinate).  If used, these other variables must be
-:doc:`internal-style variables <variable>` defined in the input
-script; their initial numeric value can be anything.  They must be
-internal-style variables, because this command resets their values
-directly.  The *set* keyword is used to identify the names of these
-other variables, one variable for the *x*-coordinate of a created atom,
-one for *y*, and one for *z*.
+will store the *x*, *y*, or *z* coordinates of an atom (one variable
+per coordinate).  If used, these other variables must be specified by
+the *set* keyword.  They are internal-style variable, because this
+command resets their values directly.  The internal-style variables do
+not need to be defined in the input script (though they can be); if
+one (or more) is not defined, then the *set* option creates an
+:doc:`internal-style variable <variable>` with the specified name.
 
 .. figure:: img/sinusoid.jpg
             :figwidth: 50%
             :align: right
             :target: _images/sinusoid.jpg
 
-When an atom is created, its :math:`(x,y,z)` coordinates become the values for
-any *set* variable that is defined.  The *var* variable is then
-evaluated.  If the returned value is 0.0, the atom is not created.  If
-it is non-zero, the atom is created.
+When an atom is about to be created, its :math:`(x,y,z)` coordinates
+become the values for any *set* variable that is defined.  The *var*
+variable is then evaluated.  If the returned value is 0.0, the atom is
+not created.  If it is non-zero, the atom is created.
 
 As an example, these commands can be used in a 2d simulation, to
 create a sinusoidal surface.  Note that the surface is "rough" due to
@@ -447,8 +455,6 @@ converts lattice spacings to distance.
    region      box block 0 $x 0 $y -0.5 0.5
    create_box  1 box
 
-   variable    xx internal 0.0
-   variable    yy internal 0.0
    variable    v equal "(0.2*v_y*ylat * cos(v_xx/xlat * 2.0*PI*4.0/v_x) + 0.5*v_y*ylat - v_yy) > 0.0"
    create_atoms  1 box var v set x xx set y yy
    write_dump  all atom sinusoid.lammpstrj

doc/src/dihedral_multi_harmonic.rst

@@ -1,4 +1,5 @@
 .. index:: dihedral_style multi/harmonic
+.. index:: dihedral_style multi/harmonic/kk
 .. index:: dihedral_style multi/harmonic/omp
 
 dihedral_style multi/harmonic command

doc/src/fix.rst

@@ -208,6 +208,7 @@ accelerated styles exist.
 * :doc:`ave/grid <fix_ave_grid>` - compute per-grid time-averaged quantities
 * :doc:`ave/histo <fix_ave_histo>` - compute/output time-averaged histograms
 * :doc:`ave/histo/weight <fix_ave_histo>` - weighted version of fix ave/histo
+* :doc:`ave/moments <fix_ave_moments>` - compute moments of scalar quantities
 * :doc:`ave/time <fix_ave_time>` - compute/output global time-averaged quantities
 * :doc:`aveforce <fix_aveforce>` - add an averaged force to each atom
 * :doc:`balance <fix_balance>` - perform dynamic load-balancing
@@ -256,6 +257,7 @@ accelerated styles exist.
 * :doc:`flow/gauss <fix_flow_gauss>` - Gaussian dynamics for constant mass flux
 * :doc:`freeze <fix_freeze>` - freeze atoms in a granular simulation
 * :doc:`gcmc <fix_gcmc>` - grand canonical insertions/deletions
+* :doc:`gjf <fix_gjf>` - statistically correct Langevin temperature control using the GJ methods
 * :doc:`gld <fix_gld>` - generalized Langevin dynamics integrator
 * :doc:`gle <fix_gle>` - generalized Langevin equation thermostat
 * :doc:`gravity <fix_gravity>` - add gravity to atoms in a granular simulation
@@ -395,6 +397,7 @@ accelerated styles exist.
 * :doc:`rigid/small <fix_rigid>` - constrain many small clusters of atoms to move as a rigid body with NVE integration
 * :doc:`rx <fix_rx>` - solve reaction kinetic ODEs for a defined reaction set
 * :doc:`saed/vtk <fix_saed_vtk>` - time-average the intensities from :doc:`compute saed <compute_saed>`
+* :doc:`set <fix_set>` - reset an atom property via an atom-style variable every N steps
 * :doc:`setforce <fix_setforce>` - set the force on each atom
 * :doc:`setforce/spin <fix_setforce>` - set magnetic precession vectors on each atom
 * :doc:`sgcmc <fix_sgcmc>` - fix for hybrid semi-grand canonical MD/MC simulations

doc/src/fix_adapt.rst

@@ -14,7 +14,7 @@ Syntax
 * adapt = style name of this fix command
 * N = adapt simulation settings every this many timesteps
 * one or more attribute/arg pairs may be appended
-* attribute = *pair* or *bond* or *angle* or *improper* or *kspace* or *atom*
+* attribute = *pair* or *bond* or *angle* or *dihedral* or *improper* or *kspace* or *atom*
 
   .. parsed-literal::
 
@@ -33,6 +33,11 @@ Syntax
          aparam = parameter to adapt over time
          I = type angle to set parameter for (integer or type label)
          v_name = variable with name that calculates value of aparam
+       *dihedral* args = dstyle dparam I v_name
+         dstyle = dihedral style name (e.g., quadratic)
+         dparam = parameter to adapt over time
+         I = type dihedral to set parameter for (integer or type label)
+         v_name = variable with name that calculates value of iparam
        *improper* args = istyle iparam I v_name
          istyle = improper style name (e.g., cvff)
          iparam = parameter to adapt over time
@@ -209,6 +214,8 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lj/mdf <pair_mdf>`                                                     | epsilon,sigma                                    | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
+| :doc:`lj/pirani <pair_lj_pirani>`                                            | alpha, beta, gamma, rm, epsilon                  | type pairs  |
++------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lj/sf/dipole/sf <pair_dipole>`                                         | epsilon,sigma,scale                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`lubricate <pair_lubricate>`                                            | mu                                               | global      |
@@ -433,6 +440,48 @@ this fix uses to reset theta0 needs to generate values in radians.
 
 ----------
 
+.. versionadded:: 12Jun2025
+
+The *dihedral* keyword uses the specified variable to change the value of
+a dihedral coefficient over time, very similar to how the *angle* keyword
+operates. The only difference is that now a dihedral coefficient for a
+given dihedral type is adapted.
+
+A wild-card asterisk can be used in place of or in conjunction with the
+dihedral type argument to set the coefficients for multiple dihedral types.
+This takes the form "\*" or "\*n" or "m\*" or "m\*n".  If :math:`N` is
+the number of dihedral types, then an asterisk with no numeric values means
+all types from 1 to :math:`N`.  A leading asterisk means all types from
+1 to n (inclusive).  A trailing asterisk means all types from m to
+:math:`N` (inclusive).  A middle asterisk means all types from m to n
+(inclusive).
+
+If :doc:`dihedral_style hybrid <dihedral_hybrid>` is used, *dstyle* should be a
+sub-style name. The dihedral styles that currently work with fix adapt are:
+
++------------------------------------------------------------------------+-------------------------+----------------+
+| :doc:`charmm  <dihedral_charmm>`                                       | k,n,d                   | type dihedrals |
++------------------------------------------------------------------------+-------------------------+----------------+
+| :doc:`charmmfsw <dihedral_charmm>`                                     | k,n,d                   | type dihedrals |
++------------------------------------------------------------------------+-------------------------+----------------+
+| :doc:`class2 <dihedral_class2>`                                        | k1,k2,k3,phi1,phi2,phi3 | type dihedrals |
++------------------------------------------------------------------------+-------------------------+----------------+
+| :doc:`cosine/squared/restricted <dihedral_cosine_squared_restricted>`  | k,phi0                  | type dihedrals |
++------------------------------------------------------------------------+-------------------------+----------------+
+| :doc:`helix <dihedral_helix>`                                          | a,b,c                   | type dihedrals |
++------------------------------------------------------------------------+-------------------------+----------------+
+| :doc:`multi/harmonic <dihedral_multi_harmonic>`                        | a1,a2,a3,a4,a5          | type dihedrals |
++------------------------------------------------------------------------+-------------------------+----------------+
+| :doc:`opls <dihedral_opls>`                                            | k1,k2,k3,k4             | type dihedrals |
++------------------------------------------------------------------------+-------------------------+----------------+
+| :doc:`quadratic <dihedral_quadratic>`                                  | k,phi0                  | type dihedrals |
++------------------------------------------------------------------------+-------------------------+----------------+
+
+Note that internally, phi0 is stored in radians, so the variable
+this fix use to reset phi0 needs to generate values in radians.
+
+----------
+
 .. versionadded:: 2Apr2025
 
 The *improper* keyword uses the specified variable to change the value of

doc/src/fix_ave_correlate_long.rst

@@ -82,10 +82,9 @@ specified values may represent calculations performed by computes and
 fixes which store their own "group" definitions.
 
 Each listed value can be the result of a compute or fix or the
-evaluation of an equal-style or vector-style variable.  For
-vector-style variables, the specified indices can include a wildcard
-character.  See the :doc:`fix ave/correlate <fix_ave_correlate>` page
-for details.
+evaluation of an equal-style or vector-style variable.  The specified
+indices can include a wildcard string.  See the
+:doc:`fix ave/correlate <fix_ave_correlate>` page for details on that.
 
 The *Nevery* and *Nfreq* arguments specify on what time steps the input
 values will be used to calculate correlation data and the frequency

doc/src/fix_ave_moments.rst

@@ -0,0 +1,296 @@
+.. index:: fix ave/moments
+
+fix ave/moments command
+=======================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   fix ID group-ID ave/moments Nevery Nrepeat Nfreq value1 value2 ... moment1 moment2 ... keyword args ...
+
+* ID, group-ID are documented in :doc:`fix <fix>` command
+* ave/moments = style name of this fix command
+* Nevery = use input values every this many time steps
+* Nrepeat = # of times to use input values for calculating averages
+* Nfreq = calculate averages every this many time steps
+* one or more input variables can be listed
+* value = v_name
+
+  .. parsed-literal::
+
+       c_ID = global scalar calculated by a compute with ID
+       c_ID[I] = Ith component of global vector calculated by a compute with ID, I can include wildcard (see below)
+       f_ID = global scalar calculated by a fix with ID
+       f_ID[I] = Ith component of global vector calculated by a fix with ID, I can include wildcard (see below)
+       v_name = value calculated by an equal-style variable with name
+       v_name[I] = value calculated by a vector-style variable with name, I can include wildcard (see below)
+
+* one or more moments to compute can be listed
+* moment = *mean* or *stddev* or *variance* or *skew* or *kurtosis*, see exact definitions below.
+* zero or more keyword/arg pairs may be appended
+* keyword = *start* or *history*
+
+  .. parsed-literal::
+
+       *start* args = Nstart
+         Nstart = invoke first after this time step
+       *history* args = Nrecent
+         Nrecent = keep a history of up to Nrecent outputs
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix 1 all ave/moments 1 1000 100 v_volume mean stddev
+   fix 1 all ave/moments 1 200 1000 v_volume variance kurtosis history 10
+
+Description
+"""""""""""
+
+.. versionadded:: 12Jun2025
+
+Using one or more values as input, calculate the moments of the underlying
+(population) distributions based on samples collected every few time
+steps over a time step window. The definitions of the moments calculated
+are given below.
+
+The group specified with this command is ignored.  However, note that
+specified values may represent calculations performed by computes and
+fixes which store their own "group" definitions.
+
+Each listed value can be the result of a :doc:`compute <compute>` or
+:doc:`fix <fix>` or the evaluation of an equal-style or vector-style
+:doc:`variable <variable>`.  In each case, the compute, fix, or variable
+must produce a global quantity, not a per-atom or local quantity.
+If you wish to spatial- or time-average or histogram per-atom
+quantities from a compute, fix, or variable, then see the :doc:`fix
+ave/chunk <fix_ave_chunk>`, :doc:`fix ave/atom <fix_ave_atom>`, or
+:doc:`fix ave/histo <fix_ave_histo>` commands.  If you wish to sum a
+per-atom quantity into a single global quantity, see the :doc:`compute
+reduce <compute_reduce>` command.
+
+Many :doc:`computes <compute>` and :doc:`fixes <fix>` produce global
+quantities.  See their doc pages for details. :doc:`Variables <variable>`
+of style *equal* and *vector* are the only ones that can be used with
+this fix.  Variables of style *atom* cannot be used, since they produce
+per-atom values.
+
+The input values must all be scalars or vectors with a bracketed term
+appended, indicating the :math:`I^\text{th}` value of the vector is
+used.
+
+The result of this fix can be accessed as a vector, containing the
+interleaved moments of each input in order.  If M moments are requested,
+then the moments of input 1 will be the first M values in the vector
+output by this fix. The moments of input 2 will the next M values, etc.
+If there are N values, the vector length will be N*M.
+
+----------
+
+For input values from a compute or fix or variable, the bracketed index
+I can be specified using a wildcard asterisk with the index to
+effectively specify multiple values.  This takes the form "\*" or "\*n"
+or "m\*" or "m\*n".  If :math:`N` is the size of the vector, then an
+asterisk with no numeric values means all indices from 1 to :math:`N`.
+A leading asterisk means all indices from 1 to n (inclusive).  A
+trailing asterisk means all indices from n to :math:`N` (inclusive).  A
+middle asterisk means all indices from m to n (inclusive).
+
+Using a wildcard is the same as if the individual elements of the vector
+or cells of the array had been listed one by one.  For examples, see the
+description of this capability in :doc:`fix ave/time <fix_ave_time>`.
+
+----------
+
+The :math:`N_\text{every}`, :math:`N_\text{repeat}`, and
+:math:`N_\text{freq}` arguments specify on what time steps the input
+values will be used in order to contribute to the average.  The final
+statistics are generated on time steps that are a multiple of
+:math:`N_\text{freq}`\ .  The average is over a window of up to
+:math:`N_\text{repeat}` quantities, computed in the preceding portion of
+the simulation once every :math:`N_\text{every}` time steps.
+
+.. note::
+
+    Contrary to most fix ave/* commands, it is not required that Nevery *
+    Nrepeat <= Nfreq.  This is to allow the user to choose the time
+    window and number of samples contributing to the output at each
+    Nfreq interval.
+
+For example, if :math:`N_\text{freq}=100` and :math:`N_\text{repeat}=5`
+(and :math:`N_\text{every}=1`), then on step 100 values from time steps
+96, 97, 98, 99, and 100 will be used. The fix does not compute its
+inputs on steps that are not required.  If :math:`N_\text{freq}=5`,
+:math:`N_\text{repeat}=8` and :math:`N_\text{every}=1`, then values
+will first be calculated on step 5 from steps 1-5, on step 10 from 3-10,
+on step 15 from 8-15 and so on, forming a rolling average over
+timesteps that span a time window larger than Nfreq.
+
+----------
+
+If a value begins with "c\_", a compute ID must follow which has been
+previously defined in the input script.  If no bracketed term is
+appended, the global scalar calculated by the compute is used.  If a
+bracketed term is appended, the Ith element of the global vector
+calculated by the compute is used.  See the discussion above for how I
+can be specified with a wildcard asterisk to effectively specify
+multiple values.
+
+If a value begins with "f\_", a fix ID must follow which has been
+previously defined in the input script.  If no bracketed term is
+appended, the global scalar calculated by the fix is used.  If a
+bracketed term is appended, the Ith element of the global vector
+calculated by the fix is used.  See the discussion above for how I can
+be specified with a wildcard asterisk to effectively specify multiple
+values.
+
+Note that some fixes only produce their values on certain time steps,
+which must be compatible with *Nevery*, else an error will result.
+Users can also write code for their own fix styles and :doc:`add them to
+LAMMPS <Modify>`.
+
+If a value begins with "v\_", a variable name must follow which has been
+previously defined in the input script. Only equal-style or vector-style
+variables can be used, which both produce global values.  Vector-style
+variables require a bracketed term to specify the Ith element of the
+vector calculated by the variable.
+
+Note that variables of style *equal* and *vector* define a formula which
+can reference individual atom properties or thermodynamic keywords, or
+they can invoke other computes, fixes, or variables when they are
+evaluated, so this is a very general means of specifying quantities to
+time average.
+
+----------
+
+The moments are output in the order requested in the arguments following
+the last input.  Any number and order of moments can be specified,
+although it does not make much sense to specify the same moment multiple
+times.  All moments are computed using a correction of the sample estimators
+used to obtain unbiased cumulants :math:`k_{1..4}` (see :ref:`(Cramer)
+<Cramer1>`). The correction for variance is the standard Bessel
+correction. For other moments, see :ref:`(Joanes)<Joanes1>`.
+
+For *mean*, the arithmetic mean :math:`\bar{x} = \frac{1}{n}
+\sum_{i=1}^{n} x_i` is calculated.
+
+For *variance*, the Bessel-corrected sample variance :math:`var = k_2 =
+\frac{1}{n - 1} \sum_{i=1}^{n} (x_i - \bar{x})^2` is calculated.
+
+For *stddev*, the Bessel-corrected sample standard deviation
+:math:`stddev = \sqrt{k_2}` is calculated.
+
+For *skew*, the adjusted Fisher--Pearson standardized moment :math:`G_1
+= \frac{k_3}{k_2^{3/2}} = \frac{k_3}{stddev^3}` is calculated.
+
+For *kurtosis*, the adjusted Fisher--Pearson standardized moment
+:math:`G_2 = \frac{k_4}{k_2^2}` is calculated.
+
+----------
+
+Fix invocation and output can be modified by optional keywords.
+
+The *start* keyword specifies that the first computation should be no
+earlier than the step number given (but will still occur on a multiple
+of *Nfreq*).  The default is step 0.  Often input values can be 0.0 at
+time 0, so setting *start* to a larger value can avoid including a 0.0
+in a longer series.
+
+The *history* keyword stores the Nrecent most recent outputs on Nfreq
+timesteps, so they can be accessed as global outputs of the fix.  Nrecent
+must be >= 1. The default is 1, meaning only the most recent output is
+accessible. For example, if history 10 is specified and Nfreq = 1000,
+then on timestep 20000, the Nfreq outputs from steps 20000, 19000, ...
+11000 are available for access.  See below for details on how to access
+the history values.
+
+For example, this will store the outputs of the previous 10 Nfreq
+time steps, i.e. a window of 10000 time steps:
+
+.. code-block:: LAMMPS
+
+   fix 1 all ave/moments 1 200 1000 v_volume mean history 10
+
+The previous results can be accessed as values in a global array output
+by this fix. Each column of the array is the vector output of the N-th
+preceding Nfreq timestep.  For example, assuming a single moment is
+calculated, the most recent result corresponding to the third input
+value would be accessed as "f_name[3][1]", "f_name[3][4]" is the 4th
+most recent and so on.  The current vector output is always the first
+column of the array, corresponding to the most recent result.
+
+To illustrate the utility of keeping output history, consider using
+this fix in conjunction with :doc:`fix halt <fix_halt>` to stop a run
+automatically if a quantity is converged to within some desired tolerance:
+
+.. code-block:: LAMMPS
+
+   variable target equal etot
+   fix aveg all ave/moments 1 200 1000 v_target mean stddev history 10
+   variable stopcond equal "abs(f_aveg[1]-f_aveg[1][10])<f_aveg[2]"
+   fix fhalt all halt 1000 v_stopcond == 1
+
+In this example, every 1000 time steps, the average and standard
+deviation of the total energy over the previous 200 time steps are
+calculated.  If the difference between the most recent and 10-th most
+recent average is lower than the most recent standard deviation, the run
+is stopped.
+
+----------
+
+Restart, fix_modify, output, run start/stop, minimize info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+No information about this fix is written to :doc:`binary restart files
+<restart>`.
+
+This fix produces a global vector and global array which can be accessed
+by various :doc:`output commands <Howto_output>`.  The values can be
+accessed on any time step, but may not be current.
+
+A global vector is produced with the # of elements = number of moments *
+number of inputs.  The moments are output in the order given in the fix
+definition.  An array is produced having # of rows = length of vector
+output (with an ordering which matches the vector) and # of columns =
+value of *history*. There is always at least one column.
+
+Each element of the global vector or array can be either "intensive" or
+"extensive", depending on whether the values contributing to the element
+are "intensive" or "extensive".  If a compute or fix provides the value
+being time averaged, then the compute or fix determines whether the value
+is intensive or extensive; see the page for that compute or fix for
+further info.  Values produced by a variable are treated as intensive.
+
+No parameter of this fix can be used with the *start/stop* keywords of
+the :doc:`run <run>` command.  This fix is not invoked during
+:doc:`energy minimization <minimize>`.
+
+Restrictions
+""""""""""""
+
+This compute is part of the EXTRA-FIX package.  It is only enabled if
+LAMMPS was built with that package.  See the :doc:`Build package
+<Build_package>` page for more info.
+
+Related commands
+""""""""""""""""
+
+:doc:`fix ave/time <fix_ave_time>`,
+
+Default
+"""""""
+
+The option defaults are history = 1, start = 0.
+
+----------
+
+.. _Cramer1:
+
+**(Cramer)** Cramer, Mathematical Methods of Statistics, Princeton University Press (1946).
+
+.. _Joanes1:
+
+**(Joanes)** Joanes, Gill, The Statistician, 47, 183--189 (1998).

doc/src/fix_controller.rst

@@ -98,52 +98,53 @@ the following dynamic equation:
 
    \frac{dc}{dt}  = -\alpha (K_p e + K_i \int_0^t e \, dt + K_d \frac{de}{dt} )
 
-where *c* is the continuous time analog of the control variable,
-*e* =\ *pvar*\ -\ *setpoint* is the error in the process variable, and
-:math:`\alpha`, :math:`K_p`, :math:`K_i` , and :math:`K_d` are constants
-set by the corresponding
-keywords described above. The discretized version of this equation is:
+where *c* is the continuous time analog of the control variable, *e*
+=\ *pvar*\ -\ *setpoint* is the error in the process variable, and
+:math:`\alpha`, :math:`K_p`, :math:`K_i` , and :math:`K_d` are
+constants set by the corresponding keywords described above. The
+discretized version of this equation is:
 
 .. math::
 
    c_n  = c_{n-1} -\alpha \left( K_p \tau e_n + K_i \tau^2 \sum_{i=1}^n e_i + K_d (e_n - e_{n-1}) \right)
 
-where :math:`\tau = \mathtt{Nevery} \cdot \mathtt{timestep}` is the time
-interval between updates,
-and the subscripted variables indicate the values of *c* and *e* at
-successive updates.
+where :math:`\tau = \mathtt{Nevery} \cdot \mathtt{timestep}` is the
+time interval between updates, and the subscripted variables indicate
+the values of *c* and *e* at successive updates.
 
 From the first equation, it is clear that if the three gain values
 :math:`K_p`, :math:`K_i`, :math:`K_d` are dimensionless constants,
-then :math:`\alpha` must have
-units of [unit *cvar*\ ]/[unit *pvar*\ ]/[unit time] e.g. [ eV/K/ps
-]. The advantage of this unit scheme is that the value of the
-constants should be invariant under a change of either the MD timestep
-size or the value of *Nevery*\ . Similarly, if the LAMMPS :doc:`unit style <units>` is changed, it should only be necessary to change
-the value of :math:`\alpha` to reflect this, while leaving :math:`K_p`,
-:math:`K_i`, and :math:`K_d` unaltered.
+then :math:`\alpha` must have units of [unit *cvar*\ ]/[unit *pvar*\
+]/[unit time] e.g. [ eV/K/ps ]. The advantage of this unit scheme is
+that the value of the constants should be invariant under a change of
+either the MD timestep size or the value of *Nevery*\ . Similarly, if
+the LAMMPS :doc:`unit style <units>` is changed, it should only be
+necessary to change the value of :math:`\alpha` to reflect this, while
+leaving :math:`K_p`, :math:`K_i`, and :math:`K_d` unaltered.
 
 When choosing the values of the four constants, it is best to first
 pick a value and sign for :math:`\alpha` that is consistent with the
-magnitudes and signs of *pvar* and *cvar*\ .  The magnitude of :math:`K_p`
-should then be tested over a large positive range keeping :math:`K_i = K_d =0`.
-A good value for :math:`K_p` will produce a fast response in *pvar*,
-without overshooting the *setpoint*\ .  For many applications, proportional
-feedback is sufficient, and so :math:`K_i = K_d =0` can be used. In cases
-where there is a substantial lag time in the response of *pvar* to a change
-in *cvar*, this can be counteracted by increasing :math:`K_d`. In situations
+magnitudes and signs of *pvar* and *cvar*\ .  The magnitude of
+:math:`K_p` should then be tested over a large positive range keeping
+:math:`K_i = K_d =0`.  A good value for :math:`K_p` will produce a
+fast response in *pvar*, without overshooting the *setpoint*\ .  For
+many applications, proportional feedback is sufficient, and so
+:math:`K_i = K_d =0` can be used. In cases where there is a
+substantial lag time in the response of *pvar* to a change in *cvar*,
+this can be counteracted by increasing :math:`K_d`. In situations
 where *pvar* plateaus without reaching *setpoint*, this can be
-counteracted by increasing :math:`K_i`.  In the language of Charles Dickens,
-:math:`K_p` represents the error of the present, :math:`K_i` the error of
-the past, and :math:`K_d` the error yet to come.
+counteracted by increasing :math:`K_i`.  In the language of Charles
+Dickens, :math:`K_p` represents the error of the present, :math:`K_i`
+the error of the past, and :math:`K_d` the error yet to come.
 
 Because this fix updates *cvar*, but does not initialize its value,
-the initial value :math:`c_0` is that assigned by the user in the input script via
-the :doc:`internal-style variable <variable>` command.  This value is
-used (by every other LAMMPS command that uses the variable) until this
-fix performs its first update of *cvar* after *Nevery* timesteps.  On
-the first update, the value of the derivative term is set to zero,
-because the value of :math:`e_{n-1}` is not yet defined.
+the initial value :math:`c_0` is that assigned by the user in the
+input script via the :doc:`internal-style variable <variable>`
+command.  This value is used (by every other LAMMPS command that uses
+the variable) until this fix performs its first update of *cvar* after
+*Nevery* timesteps.  On the first update, the value of the derivative
+term is set to zero, because the value of :math:`e_{n-1}` is not yet
+defined.
 
 ----------
 
@@ -154,21 +155,23 @@ must produce a global quantity, not a per-atom or local quantity.
 
 If *pvar* begins with "c\_", a compute ID must follow which has been
 previously defined in the input script and which generates a global
-scalar or vector.  See the individual :doc:`compute <compute>` doc page
-for details.  If no bracketed integer is appended, the scalar
+scalar or vector.  See the individual :doc:`compute <compute>` doc
+page for details.  If no bracketed integer is appended, the scalar
 calculated by the compute is used.  If a bracketed integer is
 appended, the Ith value of the vector calculated by the compute is
-used.  Users can also write code for their own compute styles and :doc:`add them to LAMMPS <Modify>`.
+used.  Users can also write code for their own compute styles and
+:doc:`add them to LAMMPS <Modify>`.
 
 If *pvar* begins with "f\_", a fix ID must follow which has been
 previously defined in the input script and which generates a global
 scalar or vector.  See the individual :doc:`fix <fix>` page for
 details.  Note that some fixes only produce their values on certain
 timesteps, which must be compatible with when fix controller
-references the values, or else an error results.  If no bracketed integer
-is appended, the scalar calculated by the fix is used.  If a bracketed
-integer is appended, the Ith value of the vector calculated by the fix
-is used.  Users can also write code for their own fix style and :doc:`add them to LAMMPS <Modify>`.
+references the values, or else an error results.  If no bracketed
+integer is appended, the scalar calculated by the fix is used.  If a
+bracketed integer is appended, the Ith value of the vector calculated
+by the fix is used.  Users can also write code for their own fix style
+and :doc:`add them to LAMMPS <Modify>`.
 
 If *pvar* begins with "v\_", a variable name must follow which has been
 previously defined in the input script.  Only equal-style variables
@@ -182,19 +185,21 @@ variable.
 The target value *setpoint* for the process variable must be a numeric
 value, in whatever units *pvar* is defined for.
 
-The control variable *cvar* must be the name of an :doc:`internal-style variable <variable>` previously defined in the input script.  Note
-that it is not specified with a "v\_" prefix, just the name of the
-variable.  It must be an internal-style variable, because this fix
-updates its value directly.  Note that other commands can use an
-equal-style versus internal-style variable interchangeably.
+The control variable *cvar* must be the name of an
+:doc:`internal-style variable <variable>` previously defined in the
+input script.  Note that it is not specified with a "v\_" prefix, just
+the name of the variable.  It must be an internal-style variable,
+because this fix updates its value directly.  Note that other commands
+can use an equal-style versus internal-style variable interchangeably.
 
 ----------
 
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-Currently, 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.
+Currently, no information about this fix is written to :doc:`binary
+restart files <restart>`.  None of the :doc:`fix_modify <fix_modify>`
+options are relevant to this fix.
 
 This fix produces a global vector with 3 values which can be accessed
 by various :doc:`output commands <Howto_output>`.  The values can be
@@ -211,7 +216,8 @@ variable is in.  The vector values calculated by this fix are
 "extensive".
 
 No parameter of this fix can be used with the *start/stop* keywords of
-the :doc:`run <run>` command.  This fix is not invoked during :doc:`energy minimization <minimize>`.
+the :doc:`run <run>` command.  This fix is not invoked during
+:doc:`energy minimization <minimize>`.
 
 Restrictions
 """"""""""""

doc/src/fix_deposit.rst

@@ -225,22 +225,25 @@ rotated configuration of the molecule.
 
 .. versionadded:: 21Nov2023
 
-The *var* and *set* keywords can be used together to provide a criterion
-for accepting or rejecting the addition of an individual atom, based on its
-coordinates.  The *name* specified for the *var* keyword is the name of an
-:doc:`equal-style variable <variable>` that should evaluate to a zero or
-non-zero value based on one or two or three variables that will store the
-*x*, *y*, or *z* coordinates of an atom (one variable per coordinate).  If
-used, these other variables must be :doc:`internal-style variables
-<variable>` defined in the input script; their initial numeric value can be
-anything. They must be internal-style variables, because this command
-resets their values directly.  The *set* keyword is used to identify the
-names of these other variables, one variable for the *x*-coordinate of a
-created atom, one for *y*, and one for *z*.  When an atom is created, its
-:math:`(x,y,z)` coordinates become the values for any *set* variable that
-is defined.  The *var* variable is then evaluated.  If the returned value
-is 0.0, the atom is not created.  If it is non-zero, the atom is created.
-For an example of how to use these keywords, see the
+The *var* and *set* keywords can be used together to provide a
+criterion for accepting or rejecting the addition of an individual
+atom, based on its coordinates.  The *name* specified for the *var*
+keyword is the name of an :doc:`equal-style variable <variable>` that
+should evaluate to a zero or non-zero value based on one or two or
+three variables that will store the *x*, *y*, or *z* coordinates of an
+atom (one variable per coordinate).  If used, these other variables
+must be :doc:`internal-style variables <variable>` specified by the
+*set* keyword.  They must be internal-style variables, because this
+command resets their values directly.  The internal-style variables do
+not need to be defined in the input script (though they can be); if
+one (or more) is not defined, then the *set* option creates an
+:doc:`internal-style variable <variable>` with the specified name.
+
+When an atom is about to be created, its :math:`(x,y,z)` coordinates
+become the values for any *set* variable that is defined.  The *var*
+variable is then evaluated.  If the returned value is 0.0, the atom is
+not created.  If it is non-zero, the atom is created.  For an example
+of how to use the set/var keywords in a similar context, see the
 :doc:`create_atoms <create_atoms>` command.
 
 The *rate* option moves the insertion volume in the z direction (3d)
@@ -304,12 +307,13 @@ units of distance or velocity.
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-This fix writes the state of the deposition to :doc:`binary restart files <restart>`.  This includes information about how many
-particles have been deposited, the random number generator seed, the
-next timestep for deposition, etc.  See the
-:doc:`read_restart <read_restart>` command for info on how to re-specify
-a fix in an input script that reads a restart file, so that the
-operation of the fix continues in an uninterrupted fashion.
+This fix writes the state of the deposition to :doc:`binary restart
+files <restart>`.  This includes information about how many particles
+have been deposited, the random number generator seed, the next
+timestep for deposition, etc.  See the :doc:`read_restart
+<read_restart>` command for info on how to re-specify a fix in an
+input script that reads a restart file, so that the operation of the
+fix continues in an uninterrupted fashion.
 
 .. note::
 

doc/src/fix_gjf.rst

@@ -0,0 +1,208 @@
+.. index:: fix gjf
+
+fix gjf command
+========================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   fix ID group-ID gjf Tstart Tstop damp seed keyword values ...
+
+* ID, group-ID are documented in :doc:`fix <fix>` command
+* gjf = style name of this fix command
+* Tstart,Tstop = desired temperature at start/end of run (temperature units)
+* Tstart can be a variable (see below)
+* damp = damping parameter (time units)
+* seed = random number seed to use for white noise (positive integer)
+* zero or more keyword/value pairs may be appended
+* keyword = *vel* or *method*
+
+  .. parsed-literal::
+
+       *vel* value = *vfull* or *vhalf*
+         *vfull* = use on-site velocity
+         *vhalf* = use half-step velocity
+       *method* value = *1-8*
+         *1-8* = choose one of the many GJ formulations
+         *7*   = requires input of additional scalar between 0 and 1
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix 3 boundary gjf 10.0 10.0 1.0 699483
+   fix 1 all gjf 10.0 100.0 100.0 48279 vel vfull method 4
+   fix 2 all gjf 10.0 10.0 1.0 26488 method 7 0.95
+
+Description
+"""""""""""
+.. versionadded:: 12Jun2025
+
+Apply a Langevin thermostat as described in :ref:`(Gronbech-Jensen-2020) <Gronbech-Jensen-2020>`
+to a group of atoms which models an interaction with a background
+implicit solvent.  As described in the papers cited below, the GJ methods
+provide exact diffusion, drift, and Boltzmann sampling for linear systems for
+any time step within the stability limit. The purpose of this set of methods
+is therefore to significantly improve statistical accuracy at longer time steps
+compared to other thermostats.
+
+The current implementation provides the user with the option to output
+the velocity in one of two forms: *vfull* or *vhalf*. The option *vhalf*
+outputs the 2GJ half-step velocity given in :ref:`Gronbech Jensen/Gronbech-Jensen
+<Gronbech-Jensen-2019>`; for linear systems, this velocity is shown to not
+have any statistical errors for any stable time step. The option *vfull*
+outputs the on-site velocity given in :ref:`Gronbech-Jensen/Farago
+<Gronbech-Jensen-Farago>`; this velocity is shown to be systematically lower
+than the target temperature by a small amount, which grows
+quadratically with the timestep. An overview of statistically correct Boltzmann
+and Maxwell-Boltzmann sampling of true on-site and true half-step velocities is
+given in :ref:`Gronbech-Jensen-2020 <Gronbech-Jensen-2020>`.
+
+This fix allows the use of several GJ methods as listed in :ref:`Gronbech-Jensen-2020 <Gronbech-Jensen-2020>`.
+The GJ-VII method is described in :ref:`Finkelstein <Finkelstein>` and GJ-VIII
+is described in :ref:`Gronbech-Jensen-2024 <Gronbech-Jensen-2024>`.
+The implementation follows the splitting form provided in Eqs. (24) and (25)
+in :ref:`Gronbech-Jensen-2024 <Gronbech-Jensen-2024>`, including the application
+of Gaussian noise values, per the description in
+:ref:`Gronbech-Jensen-2023 <Gronbech-Jensen-2023>`.
+
+
+.. note::
+
+   Unlike the :doc:`fix langevin <fix_langevin>` command which performs force
+   modifications only, this fix performs thermostatting and time integration.
+   Thus you no longer need a separate time integration fix, like :doc:`fix nve <fix_nve>`.
+
+See the :doc:`Howto thermostat <Howto_thermostat>` page for
+a discussion of different ways to compute temperature and perform
+thermostatting.
+
+The desired temperature at each timestep is a ramped value during the
+run from *Tstart* to *Tstop*\ .
+
+*Tstart* can be specified as an equal-style or atom-style
+:doc:`variable <variable>`.  In this case, the *Tstop* setting is
+ignored.  If the value is a variable, it should be specified as
+v_name, where name is the variable name.  In this case, the variable
+will be evaluated each timestep, and its value used to determine the
+target temperature.
+
+Equal-style variables can specify formulas with various mathematical
+functions, and include :doc:`thermo_style <thermo_style>` command
+keywords for the simulation box parameters and timestep and elapsed
+time.  Thus it is easy to specify a time-dependent temperature.
+
+Atom-style variables can specify the same formulas as equal-style
+variables but can also include per-atom values, such as atom
+coordinates.  Thus it is easy to specify a spatially-dependent
+temperature with optional time-dependence as well.
+
+Like other fixes that perform thermostatting, this fix can be used
+with :doc:`compute commands <compute>` that remove a "bias" from the
+atom velocities.  E.g. to apply the thermostat only to atoms within a
+spatial :doc:`region <region>`, or to remove the center-of-mass
+velocity from a group of atoms, or to remove the x-component of
+velocity from the calculation.
+
+This is not done by default, but only if the :doc:`fix_modify
+<fix_modify>` command is used to assign a temperature compute to this
+fix that includes such a bias term.  See the doc pages for individual
+:doc:`compute temp commands <compute>` to determine which ones include
+a bias.
+
+The *damp* parameter is specified in time units and determines how
+rapidly the temperature is relaxed.  For example, a value of 100.0 means
+to relax the temperature in a timespan of (roughly) 100 time units
+(:math:`\tau` or fs or ps - see the :doc:`units <units>` command).  The
+damp factor can be thought of as inversely related to the viscosity of
+the solvent.  I.e. a small relaxation time implies a high-viscosity
+solvent and vice versa.  See the discussion about :math:`\gamma` and
+viscosity in the documentation for the :doc:`fix viscous <fix_viscous>`
+command for more details.
+
+The random # *seed* must be a positive integer.  A Marsaglia random
+number generator is used.  Each processor uses the input seed to
+generate its own unique seed and its own stream of random numbers.
+Thus the dynamics of the system will not be identical on two runs on
+different numbers of processors.
+
+----------
+
+The keyword/value option pairs are used in the following ways.
+
+The keyword *vel* determines which velocity is used to determine
+quantities of interest in the simulation.
+
+The keyword *method* selects one of the eight GJ-methods implemented in LAMMPS.
+
+----------
+
+Restart, fix_modify, output, run start/stop, minimize info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+No information about this fix is written to :doc:`binary restart files <restart>`.
+Because the state of the random number generator is not saved in restart files,
+this means you cannot do "exact" restarts with this fix, where the simulation
+continues on the same as if no restart had taken place.  However, in a
+statistical sense, a restarted simulation should produce the same behavior.
+Additionally, the GJ methods implement noise exclusively within each time step
+(unlike the BBK thermostat of the fix-langevin). The restart is done with
+either vfull or vhalf velocity output for as long as the choice of vfull/vhalf
+is the same for the simulation as it is in the restart file.
+
+The :doc:`fix_modify <fix_modify>` *temp* option is supported by this
+fix.  You can use it to assign a temperature :doc:`compute <compute>`
+you have defined to this fix which will be used in its thermostatting
+procedure, as described above.  For consistency, the group used by
+this fix and by the compute should be the same.
+
+This fix can ramp its target temperature over multiple runs, using the
+*start* and *stop* keywords of the :doc:`run <run>` command.  See the
+:doc:`run <run>` command for details of how to do this.
+
+This fix is not invoked during :doc:`energy minimization <minimize>`.
+
+Restrictions
+""""""""""""
+
+This fix is not compatible with run_style respa. It is not compatible with
+accelerated packages such as KOKKOS.
+
+Related commands
+""""""""""""""""
+
+:doc:`fix langevin <fix_langevin>`, :doc:`fix nvt <fix_nh>`
+
+Default
+"""""""
+
+The option defaults are vel = vhalf, method = 1.
+
+----------
+
+.. _Gronbech-Jensen-2020:
+
+**(Gronbech-Jensen-2020)** Gronbech-Jensen, Mol Phys 118, e1662506 (2020).
+
+.. _Gronbech-Jensen-2019:
+
+**(Gronbech Jensen/Gronbech-Jensen)** Gronbech Jensen and Gronbech-Jensen, Mol Phys, 117, 2511 (2019)
+
+.. _Gronbech-Jensen-Farago:
+
+**(Gronbech-Jensen/Farago)** Gronbech-Jensen and Farago, Mol Phys, 111, 983 (2013).
+
+.. _Finkelstein:
+
+**(Finkelstein)** Finkelstein, Cheng, Florin, Seibold, Gronbech-Jensen, J. Chem. Phys., 155, 18 (2021)
+
+.. _Gronbech-Jensen-2024:
+
+**(Gronbech-Jensen-2024)** Gronbech-Jensen, J. Stat. Phys. 191, 137 (2024).
+
+.. _Gronbech-Jensen-2023:
+
+**(Gronbech-Jensen-2023)** Gronbech-Jensen, J. Stat. Phys. 190, 96 (2023).

doc/src/fix_langevin.rst

@@ -56,7 +56,7 @@ Examples
 Description
 """""""""""
 
-Apply a Langevin thermostat as described in :ref:`(Schneider) <Schneider1>`
+Apply a Langevin thermostat as described in :ref:`(Bruenger) <Bruenger1>`
 to a group of atoms which models an interaction with a background
 implicit solvent.  Used with :doc:`fix nve <fix_nve>`, this command
 performs Brownian dynamics (BD), since the total force on each atom
@@ -241,6 +241,13 @@ to zero by subtracting off an equal part of it from each atom in the
 group.  As a result, the center-of-mass of a system with zero initial
 momentum will not drift over time.
 
+.. deprecated:: TDB
+
+The *gjf* keyword in fix langevin is deprecated and will be removed
+soon.  The GJF functionality has been moved to its own fix style
+:doc:`fix gjf <fix_gjf>` and it is strongly recommended to use that
+fix instead.
+
 The keyword *gjf* can be used to run the :ref:`Gronbech-Jensen/Farago
 <Gronbech-Jensen>` time-discretization of the Langevin model.  As
 described in the papers cited below, the purpose of this method is to
@@ -324,14 +331,16 @@ types, tally = no, zero = no, gjf = no.
 
 ----------
 
+.. _Bruenger1:
+
+**(Bruenger)** Bruenger, Brooks, and Karplus, Chem. Phys. Lett. 105, 495 (1982).
+[Previously attributed to Schneider and Stoll, Phys. Rev. B 17, 1302 (1978).
+Implementation remains unchanged.]
+
 .. _Dunweg1:
 
 **(Dunweg)** Dunweg and Paul, Int J of Modern Physics C, 2, 817-27 (1991).
 
-.. _Schneider1:
-
-**(Schneider)** Schneider and Stoll, Phys Rev B, 17, 1302 (1978).
-
 .. _Gronbech-Jensen:
 
 **(Gronbech-Jensen)** Gronbech-Jensen and Farago, Mol Phys, 111, 983

doc/src/fix_qeq_rel_reaxff.rst

@@ -37,18 +37,18 @@ Examples
 Description
 """""""""""
 
-.. versionadded:: 19Nov2024
+.. versionadded:: 2Apr2025
 
-This fix implements the QEqR method for charge equilibration, which
-differs from the QEq charge equilibration method :ref:`(Rappe and
-Goddard) <Rappe4>` only in how external electric fields are accounted
-for.  This fix therefore raises a warning when used without :doc:`fix
-efield <fix_efield>` since :doc:`fix qeq/reaxff <fix_qeq_reaxff>` should
-be used without an external electric field.  Charges are computed with
-the QEqR method by minimizing the electrostatic energy of the system in
-the same way as the QEq method but where the absolute electronegativity,
-:math:`\chi_i`, of each atom in the QEq method is replaced with an
-effective electronegativity given by
+This fix implements the QEqR method :ref:`(Lalli) <lalli2>` for charge
+equilibration, which differs from the QEq charge equilibration method
+:ref:`(Rappe and Goddard) <Rappe4>` only in how external electric fields
+are accounted for. This fix therefore raises a warning when used without
+:doc:`fix efield <fix_efield>` since :doc:`fix qeq/reaxff <fix_qeq_reaxff>`
+should be used when no external electric field is present.  Charges are
+computed with the QEqR method by minimizing the electrostatic energy of
+the system in the same way as the QEq method but where the absolute
+electronegativity, :math:`\chi_i`, of each atom in the QEq method is
+replaced with an effective electronegativity given by
 
 .. math::
    \chi_{\mathrm{r}i} = \chi_i + \frac{\sum_{j=1}^{N} \beta(\phi_i - \phi_j) S_{ij}}
@@ -61,8 +61,9 @@ external electric field and :math:`S_{ij}` is the overlap integral
 between atoms :math:`i` and :math:`j`.  This formulation is advantageous
 over the method used by :doc:`fix qeq/reaxff <fix_qeq_reaxff>` to
 account for an external electric field in that it permits periodic
-boundaries in the direction of an external electric field and in that it
-does not worsen long-range charge transfer seen with QEq.
+boundaries in the direction of an external electric field and in
+that it does not worsen long-range charge transfer seen with
+QEq. See :ref:`Lalli <lalli2>` for further details.
 
 This fix is typically used in conjunction with the ReaxFF force field
 model as implemented in the :doc:`pair_style reaxff <pair_reaxff>`
@@ -184,6 +185,10 @@ scale = 1.0 and maxiter = 200
 
 ----------
 
+.. _lalli2:
+
+**(Lalli)** Lalli and Giusti, Journal of Chemical Physics, 162, 174311 (2025).
+
 .. _Rappe4:
 
 **(Rappe)** Rappe and Goddard III, Journal of Physical Chemistry, 95,

doc/src/fix_qtpie_reaxff.rst

@@ -59,8 +59,7 @@ and atom :math:`j`.
 The effect of an external electric field can be incorporated into the QTPIE
 method by modifying the absolute or effective electronegativities of each
 atom :ref:`(Chen) <qtpie-Chen>`. This fix models the effect of an external
-electric field by using the effective electronegativity given in
-:ref:`(Gergs) <Gergs>`:
+electric field by using the effective electronegativity :ref:`(Lalli) <lalli>`
 
 .. math::
    \tilde{\chi}_{\mathrm{r}i} = \frac{\sum_{j=1}^{N} (\chi_i - \chi_j + \beta(\phi_i - \phi_j)) S_{ij}}
@@ -68,7 +67,8 @@ electric field by using the effective electronegativity given in
 
 where :math:`\beta` is a scaling factor and :math:`\phi_i` and :math:`\phi_j`
 are the electric potentials at the positions of atoms :math:`i` and :math:`j`
-due to the external electric field.
+due to the external electric field. Additional details regarding the
+implementation and performance of this fix are provided in :ref:`Lalli <lalli>`.
 
 This fix is typically used in conjunction with the ReaxFF force
 field model as implemented in the :doc:`pair_style reaxff <pair_reaxff>`
@@ -206,10 +206,9 @@ scale = 1.0 and maxiter = 200
 **(Chen)** Chen, Jiahao. Theory and applications of fluctuating-charge models.
 University of Illinois at Urbana-Champaign, 2009.
 
-.. _Gergs:
+.. _lalli:
 
-**(Gergs)** Gergs, Dirkmann and Mussenbrock.
-Journal of Applied Physics 123.24 (2018).
+**(Lalli)** Lalli and Giusti, Journal of Chemical Physics, 162, 174311 (2025).
 
 .. _qeq-Aktulga2:
 

doc/src/fix_set.rst

@@ -0,0 +1,175 @@
+.. index:: fix set
+
+fix set command
+===============
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   fix ID group-ID set Nfreq rnflag set-args
+
+* ID, group-ID are documented in :doc:`fix <fix>` command
+* set = style name of this fix command
+* Nfreq = reset per-atom properties every this many timesteps
+* rnflag = 1 to reneighbor on next timestep, 0 to not
+* set-args = identical to args for the :doc:`set <set>` command
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix 10 all set 1 0 group all i_dump v_new
+   fix 10 all set 1 0 group all i_dump v_turnoff
+
+Description
+"""""""""""
+
+.. versionadded:: 12Jun2025
+
+Reset one or more properties of one or more atoms once every *Nfreq*
+steps during a simulation.
+
+If the *rnflag* for reneighboring is set to 1, then a reneighboring
+will be triggered on the next timestep (since the fix set operation
+occurs at the end of the current timestep).  This is important to do
+if this command changes per-atom properties that need to be
+communicated to ghost atoms.  If this is not the case, an *rnflag*
+setting of 0 can be used; reneighboring will only be triggered on
+subsequent timesteps by the usual neighbor list criteria; see the
+:doc:`neigh_modify command <neigh_modify>`.
+
+Here are two examples where an *rnflag* setting of 1 are needed.  If a
+custom per-atom property is changed and the :doc:`fix property/atom
+<fix_property_atom>` command to create the property used the *ghost
+yes* keyword.  Or if per-atom charges are changed, all pair styles
+which compute Coulombic interactions require charge values for ghost
+atoms.  In both these examples, the re-neighboring will trigger the
+changes in the owned atom properties to be immediately communicated to
+ghost atoms.
+
+The arguments following *Nfreq* and *rnflag* are identical to those
+allowed for the :doc:`set <set>` command, as in the examples above and
+below.
+
+Note that the group-ID setting for this command is ignored.  The
+syntax for the :doc:`set <set>` arguments allows selection of which
+atoms have their properties reset.
+
+This command can only be used to reset an atom property using a
+per-atom variable.  This option in allowed by many, but not all, of
+the keyword/value pairs supported by the :doc:`set <set>` command.
+The reason for this restriction is that if a per-atom variable is not
+used, this command will typically not change atom properties during
+the simulation.
+
+The :doc:`set <set>` command can be used with similar syntax to this
+command to reset atom properties once before or between simulations.
+
+----------
+
+Here is an example of input script commands which will output atoms
+into a dump file only when their x-velocity crosses a threshold value
+*vthresh* for the first time.  Their position and x-velocity will then
+be output every step for *twindow* timesteps.
+
+.. code-block:: LAMMPS
+
+   variable        vthresh equal 2             # threshold velocity
+   variable        twindow equal 10            # dump for this many steps
+   #
+   # define custom property i_dump to store timestep threshold is crossed
+   #
+   fix             2 all property/atom i_dump
+   set             group all i_dump -1
+   #
+   # fix set command checks for threshold crossings every step
+   # resets i_dump from -1 to current timestep when crossing occurs
+   #
+   variable        start atom "vx > v_vthresh && i_dump == -1"
+   variable        new atom ternary(v_start,step,i_dump)
+   fix             3 all set 1 0 group all i_dump v_new
+   #
+   # dump command with thresh which enforces twindow
+   #
+   dump            1 all custom 1 tmp.dump id x y vx i_dump
+   variable        dumpflag atom "i_dump >= 0 && (step-i_dump) < v_twindow"
+   dump_modify     1 thresh v_dumpflag == 1
+   #
+   # run the simulation
+   # final dump with all atom IDs which crossed threshold on which timestep
+   #
+   run             1000
+   write_dump      all custom tmp.dump.final id i_dump modify thresh i_dump >= 0
+
+The tmp.dump.final file lists which atoms crossed the velocity
+threshold.  This command will print the *twindow* timesteps when a
+specific atom ID (104 in this case) was output in the tmp.dump file:
+
+.. code-block:: LAMMPS
+
+   % grep "^104 " tmp.dump
+
+If these commands are used instead of the above, then an atom can
+cross the velocity threshold multiple times, and will be output for
+*twindow* timesteps each time.  However the write_dump command is no
+longer useful.
+
+.. code-block:: LAMMPS
+
+   variable        vthresh equal 2             # threshold velocity
+   variable        twindow equal 10            # dump for this many steps
+   #
+   # define custom property i_dump to store timestep threshold is crossed
+   #
+   fix             2 all property/atom i_dump
+   set             group all i_dump -1
+   #
+   # fix set command checks for threshold crossings every step
+   # resets i_dump from -1 to current timestep when crossing occurs
+   #
+   variable        start atom "vx > v_vthresh && i_dump == -1"
+   variable        turnon atom ternary(v_start,step,i_dump)
+   variable        stop atom "v_turnon >= 0 && (step-v_turnon) < v_twindow"
+   variable        turnoff atom ternary(v_stop,v_turnon,-1)
+   fix             3 all set 1 0 group all i_dump v_turnoff
+   #
+   # dump command with thresh which enforces twindow
+   #
+   dump            1 all custom 1 tmp.dump id x y vx i_dump
+   variable        dumpflag atom "i_dump >= 0 && (step-i_dump) < v_twindow"
+   dump_modify     1 thresh v_dumpflag == 1
+   #
+   # run the simulation
+   #
+   run             1000
+
+----------
+
+Restart, fix_modify, output, run start/stop, minimize info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+No information about this fix is written to :doc:`binary restart files
+<restart>`.  None of the :doc:`fix_modify <fix_modify>` options are
+relevant to this fix.  No global or per-atom quantities are stored by
+this fix for access by various :doc:`output commands <Howto_output>`.
+No parameter of this fix can be used with the *start/stop* keywords of
+the :doc:`run <run>` command.  This fix is not invoked during
+:doc:`energy minimization <minimize>`.
+
+Restrictions
+""""""""""""
+
+none
+
+Related commands
+""""""""""""""""
+
+:doc:`set <set>`
+
+Default
+"""""""
+
+none

doc/src/fix_sgcmc.rst

@@ -30,7 +30,9 @@ Syntax
          N = number of times sampling window is moved during one MC cycle
        *window_size* frac
          frac = size of sampling window (must be between 0.5 and 1.0)
-
+       *atomic/energy* yes/no
+         yes = use the atomic energy method to calculate energy changes
+         no = use the default method to calculate energy changes
 
 Examples
 """"""""
@@ -127,6 +129,14 @@ The number of times the window is moved during a MC cycle is set using
 the parameter *window_moves* (see Sect. III.B in :ref:`Sadigh1
 <Sadigh1>` for details).
 
+The *atomic/energy* keyword controls which method is used for calculating
+the energy change when atom types are swapped. A value of *no*
+uses the default method, see discussion below in Restrictions section.
+A value of *yes* uses the atomic energy method,
+if the method has been implemented for the LAMMPS energy model,
+otherwise LAMMPS will exit with an error message.
+So far this has only been implemented for EAM type potentials.
+
 ------------
 
 Restart, fix_modify, output, run start/stop, minimize info
@@ -159,16 +169,26 @@ page for more info.
 This fix style requires an :doc:`atom style <atom_style>` with per atom
 type masses.
 
-At present the fix provides optimized subroutines for EAM type
-potentials (see above) that calculate potential energy changes due to
-*local* atom type swaps very efficiently.  Other potentials are
-supported by using the generic potential functions. This, however, will
-lead to exceedingly slow simulations since it implies that the
-energy of the *entire* system is recomputed at each MC trial step.  If
-other potentials are to be used it is strongly recommended to modify and
-optimize the existing generic potential functions for this purpose.
-Also, the generic energy calculation can not be used for parallel
-execution i.e. it only works with a single MPI process.
+The fix provides three methods for calculating the potential energy
+change due to atom type swaps. For EAM type potentials, the default
+method is a carefully optimized local energy change calculation that
+is part of the source code for this fix. It takes advantage of the
+specific computational and communication requirements of EAM. Customizing
+the local method to handle other energy models such as Tersoff has been done,
+but these cases are not supported in the public LAMMPS code.
+For all other LAMMPS energy models, the default method calculates
+the *total* potential energy of the system before and after each
+atom type swap.  This method does not depend on the details of the
+energy model and so is guaranteed to be correct.  It is also
+orders of magnitude slower than the custom EAM calculation.
+In addition, it can not be used with parallel execution i.e. only
+a single MPI process is allowed.
+The third method uses the *atomic/energy* keyword described above.
+This allows parallel execution and it is also a local calculation,
+making it only a bit slower than a fully-optimized local calculation.
+So far, this has been implemented for EAM type potentials.
+It is straightforward to extend this to other potentials,
+requiring adding an atomic energy method to the pair style.
 
 ------------
 
@@ -180,6 +200,7 @@ The optional parameters default to the following values:
 * *randseed* = 324234
 * *window_moves* = 8
 * *window_size* = automatic
+* *atomic/energy* = no
 
 ------------
 

doc/src/geturl.rst

@@ -58,6 +58,32 @@ behave as expected.  If the argument is *no*, geturl will operate silently
 and only report the error status number provided by libcurl, in case of a
 failure.
 
+.. _geturl_proxy:
+
+.. admonition:: Using *geturl* with proxies for http or https
+   :class: note
+
+   The `libcurl library <https:://curl.se/libcurl/>`_ supports `routing
+   traffic through proxies
+   <https://everything.curl.dev/usingcurl/proxies/env.html>`_ by setting
+   suitable environment variables (e.g. ``http_proxy`` or
+   ``https_proxy``) as required by some institutional or corporate
+   security protocols.  In that case you probably also want to use the
+   *verify* *no* setting.
+
+   Using a proxy may also be needed if you are running on an HPC cluster
+   where only the login or head nodes have access to the internet, but
+   not the compute nodes.  In this case the following input can be adapted
+   and used for your local HPC environment:
+
+   .. code-block:: LAMMPS
+
+      variable headnode getenv PBS_O_HOST     # use SLURM_SUBMIT_HOST when using SLURM instead of Torque/PBS
+      shell ssh -N -f -D 8001 ${headnode}     # start SOCKS5 proxy with backgrounded ssh connection to cluster head node
+      shell putenv http_proxy=socks5://localhost:8001 https_proxy=socks5://localhost:8001
+      geturl https://download.lammps.org/tars/SHA256SUMS # download a file using proxy
+      shell head SHA256SUMS                # check if the download was successful
+
 ----------
 
 Restrictions

doc/src/kspace_style.rst

@@ -32,6 +32,7 @@
 .. index:: kspace_style msm/cg/omp
 .. index:: kspace_style msm/dielectric
 .. index:: kspace_style scafacos
+.. index:: kspace_style zero
 
 kspace_style command
 ====================
@@ -43,7 +44,7 @@ Syntax
 
    kspace_style style value
 
-* style = *none* or *ewald* or *ewald/dipole* or *ewald/dipole/spin* or *ewald/disp* or *ewald/disp/dipole* or *ewald/omp* or *ewald/electrode* or *pppm* or *pppm/cg* or *pppm/disp* or *pppm/tip4p* or *pppm/stagger* or *pppm/disp/tip4p* or *pppm/gpu* or *pppm/intel* or *pppm/disp/intel* or *pppm/kk* or *pppm/omp* or *pppm/cg/omp* or *pppm/disp/tip4p/omp* or *pppm/tip4p/omp* or *pppm/dielectic* or *pppm/disp/dielectric* or *pppm/electrode* or *pppm/electrode/intel* or *msm* or *msm/cg* or *msm/omp* or *msm/cg/omp* or *msm/dielectric* or *scafacos*
+* style = *none* or *ewald* or *ewald/dipole* or *ewald/dipole/spin* or *ewald/disp* or *ewald/disp/dipole* or *ewald/omp* or *ewald/electrode* or *pppm* or *pppm/cg* or *pppm/disp* or *pppm/tip4p* or *pppm/stagger* or *pppm/disp/tip4p* or *pppm/gpu* or *pppm/intel* or *pppm/disp/intel* or *pppm/kk* or *pppm/omp* or *pppm/cg/omp* or *pppm/disp/tip4p/omp* or *pppm/tip4p/omp* or *pppm/dielectic* or *pppm/disp/dielectric* or *pppm/electrode* or *pppm/electrode/intel* or *msm* or *msm/cg* or *msm/omp* or *msm/cg/omp* or *msm/dielectric* or *scafacos* or *zero*
 
   .. parsed-literal::
 
@@ -121,6 +122,7 @@ Syntax
        *scafacos* values = method accuracy
          method = fmm or p2nfft or p3m or ewald or direct
          accuracy = desired relative error in forces
+       *zero* value = none
 
 Examples
 """"""""
@@ -132,6 +134,7 @@ Examples
    kspace_style msm 1.0e-4
    kspace_style scafacos fmm 1.0e-4
    kspace_style none
+   kspace_style zero
 
 Used in input scripts:
 
@@ -375,6 +378,13 @@ other ScaFaCoS options currently exposed to LAMMPS.
 
 ----------
 
+.. versionadded:: 12Jun2025
+
+The *zero* style does not do any calculations, but is compatible
+with all pair styles that require some version of a kspace style.
+
+----------
+
 The specified *accuracy* determines the relative RMS error in per-atom
 forces calculated by the long-range solver.  It is set as a
 dimensionless number, relative to the force that two unit point

doc/src/molecule.rst

@@ -34,7 +34,7 @@ Syntax
        *ioff* value = Ioff
          Ioff = offset to add to improper types
        *scale* value = sfactor
-         sfactor = scale factor to apply to the size and mass of the molecule
+         sfactor = scale factor to apply to the size, mass, and dipole of the molecule
 
 Examples
 """"""""
@@ -42,6 +42,7 @@ Examples
 .. code-block:: LAMMPS
 
    molecule 1 mymol.txt
+   molecule water tip3p.json
    molecule 1 co2.txt h2o.txt
    molecule CO2 co2.txt boff 3 aoff 2
    molecule 1 mymol.txt offset 6 9 18 23 14
@@ -65,7 +66,7 @@ templates include:
 * :doc:`atom_style template <atom_style>`
 
 The ID of a molecule template can only contain alphanumeric characters
-and underscores.
+and underscores, same as other IDs in LAMMPS.
 
 A single template can contain multiple molecules, listed one per file.
 Some of the commands listed above currently use only the first
@@ -74,6 +75,11 @@ contains multiple molecules.  The :doc:`atom_style template
 <atom_style>` command allows multiple-molecule templates to define a
 system with more than one templated molecule.
 
+The molecule file can be either in a *native* format or in `JSON format
+<https://www.json.org/>`_.  The details of the two formats are described
+below.  When referencing multiple molecule files in a single *molecule*
+command, each of those files may be either format.
+
 Each filename can be followed by optional keywords which are applied
 only to the molecule in the file as used in this template.  This is to
 make it easy to use the same molecule file in different molecule
@@ -95,40 +101,45 @@ use that attribute (e.g. no bonds).
    labels will determine the actual types directly depending on the
    current :doc:`labelmap <labelmap>` settings.
 
-The *scale* keyword scales the size of the molecule.  This can be
-useful for modeling polydisperse granular rigid bodies.  The scale
-factor is applied to each of these properties in the molecule file, if
-they are defined: the individual particle coordinates (Coords
-section), the individual mass of each particle (Masses section), the
-individual diameters of each particle (Diameters section), the total
-mass of the molecule (header keyword = mass), the center-of-mass of
-the molecule (header keyword = com), and the moments of inertia of the
-molecule (header keyword = inertia).
+The *scale* keyword scales the size of the molecule.  This can be useful
+for modeling polydisperse granular rigid bodies.  The scale factor is
+applied to each of these properties in the molecule file, if they are
+defined: the individual particle coordinates (Coords or "coords"
+section), the individual mass of each particle (Masses or "masses"
+section), the individual diameters of each particle (Diameters or
+"diameters" section), the per-atom dipoles (Dipoles or "dipoles"
+section) the total mass of the molecule (header keyword = mass), the
+center-of-mass of the molecule (header keyword = com), and the moments
+of inertia of the molecule (header keyword = inertia).
 
 .. note::
 
    The molecule command can be used to define molecules with bonds,
-   angles, dihedrals, impropers, or special bond lists of neighbors
+   angles, dihedrals, impropers, and special bond lists of neighbors
    within a molecular topology, so that you can later add the molecules
    to your simulation, via one or more of the commands listed above.
-   Since this topology-related information requires that suitable storage
-   is reserved when LAMMPS creates the simulation box (e.g. when using
-   the :doc:`create_box <create_box>` command or the
-   :doc:`read_data <read_data>` command) suitable space has to be reserved
-   so you do not overflow those pre-allocated data structures when adding
-   molecules later.  Both the :doc:`create_box <create_box>` command and
-   the :doc:`read_data <read_data>` command have "extra" options which
-   ensure space is allocated for storing topology info for molecules that
-   are added later.
+   Since this topology-related information requires that suitable
+   storage is reserved when LAMMPS creates the simulation box (e.g. when
+   using the :doc:`create_box <create_box>` command or the
+   :doc:`read_data <read_data>` command) suitable space has to be
+   reserved at that step so you do not overflow those pre-allocated data
+   structures when adding molecules later.  Both the :doc:`create_box
+   <create_box>` command and the :doc:`read_data <read_data>` command
+   have "extra" options which ensure extra space is allocated for
+   storing topology info for molecules that are added later.  This
+   feature is *not* available for the :doc:`read_restart command
+   <read_restart>`, thus binary restart files need to be converted
+   to data files first.
 
 ----------
 
-Format of a molecule file
-"""""""""""""""""""""""""
+Format of a native molecule file
+""""""""""""""""""""""""""""""""
 
-The format of an individual molecule file looks similar but is
-different than that of a data file read by the :doc:`read_data <read_data>`
-commands.  Here is a simple example for a TIP3P water molecule:
+The format of an "native" individual molecule file looks similar but is
+*different* from that of a data file read by the :doc:`read_data
+<read_data>` commands.  Here is a simple example for a TIP3P water
+molecule:
 
 .. code-block::
 
@@ -669,6 +680,191 @@ the file format.
 
 ----------
 
+Format of a JSON molecule file
+""""""""""""""""""""""""""""""
+
+.. versionadded:: 12Jun2025
+
+The format of a JSON format individual molecule file must follow the
+`JSON format <https://www.json.org/>`_, which evolved from the
+JavaScript programming language as a programming-language-neutral data
+interchange language.  The JSON syntax is independent of its content,
+and thus the data in the file must follow suitable conventions to be
+correctly processed.  LAMMPS provides a `JSON schema file
+<https://json-schema.org/>`_ for JSON format molecule files in the
+:ref:`tools/json folder <json>` to represent those conventions.  Using
+the schema file any JSON format molecule files can be validated.
+Validating a particular JSON format molecule file against this schema
+ensures that both, the JSON syntax requirement *and* the LAMMPS
+conventions for molecule templates are followed.  This is a formal check
+only and thus it **cannot** check whether the file contents are
+physically meaningful.
+
+Here is a simple example for the same TIP3P water molecule from above in
+JSON format and also using :doc:`type labels <labelmap>` instead of
+numeric types:
+
+.. code-block:: json
+
+   {
+       "application": "LAMMPS",
+       "format": "molecule",
+       "revision": 1,
+       "title": "Water molecule. TIP3P geometry",
+       "schema": "https://download.lammps.org/json/molecule-schema.json",
+       "units": "real",
+       "coords": {
+           "format": ["atom-id", "x", "y", "z"],
+           "data": [
+               [1,  0.00000, -0.06556,  0.00000],
+               [2,  0.75695,  0.52032,  0.00000],
+               [3, -0.75695,  0.52032,  0.00000]
+           ]
+       },
+       "types": {
+           "format": ["atom-id", "type"],
+           "data": [
+               [1,  "OW"],
+               [2,  "HO1"],
+               [3,  "HO1"]
+           ]
+       },
+       "charges": {
+           "format": ["atom-id", "charge"],
+           "data": [
+               [1, -0.834],
+               [2,  0.417],
+               [3,  0.417]
+           ]
+       },
+       "bonds": {
+           "format": ["bond-type", "atom1", "atom2"],
+           "data": [
+               ["OW-HO1",  1,  2],
+               ["OW-HO1",  1,  3]
+           ]
+       },
+       "angles": {
+           "format": ["angle-type", "atom1", "atom2", "atom3"],
+           "data": [
+               ["HO1-OW-HO1",  2,  1,  3]
+           ]
+       }
+   }
+
+Unlike with the native molecule file format, there are no header or body
+sections, just a list of keywords with associated data.  JSON format
+data is read, parsed, and stored in an internal dictionary data
+structure in one step and thus the order of keywords is not relevant.
+
+Data for keywords is either provided directly following the keyword or
+as a *data block*.  A *data block* is a list that has to include two
+keywords, "format" and "data", where the former lists keywords of the
+properties that are stored in the columns of the "data" lists.  The
+names and order of entries in the "format" list (and thus how the data
+is interpreted) are currently fixed.
+
+Since the length of the various lists can be easily obtained from the
+internal data structure, several header keywords of the "native" molecule
+file are not needed.  On the other hand, some additional keywords are
+required to identify the conventions applied to the generic JSON file
+format.  The structure of the data itself mostly follows what is used
+for the "native" molecule file format.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Keyword
+     - Argument(s)
+     - Required
+     - Description
+   * - application
+     - "LAMMPS"
+     - yes
+     - indicates a LAMMPS JSON file; files from other applications may be accepted in the future
+   * - format
+     - "molecule"
+     - yes
+     - indicates a molecule template file
+   * - revision
+     - an integer
+     - yes
+     - currently 1, to facility backward compatibility on changes to the conventions
+   * - title
+     - a string
+     - no
+     - information about the template which will echoed to the screen and log
+   * - schema
+     - URL as string
+     - no
+     - location of a JSON schema file for validating the molecule file format
+   * - units
+     - a string
+     - no
+     - indicates :doc:`units settings <units>` for this molecule template
+   * - com
+     - list with 3 doubles
+     - no
+     - overrides the auto-computed center-of-mass for the template
+   * - masstotal
+     - double
+     - no
+     - overrides the auto-computed total mass for the template
+   * - inertia
+     - list with 6 doubles
+     - no
+     - overrides the auto-computed moments of inertia
+   * - coords
+     - a data block
+     - no
+     - contains atom positions with the format "atom-id", "x", "y", "z" (same as Coords)
+   * - types
+     - a data block
+     - yes
+     - assigns atom types to atoms with the format "atom-id", "type" (same as Types)
+   * - molecule
+     - a data block
+     - no
+     - assigns molecule-IDs to atoms with the format "atom-id", "molecule-id" (same as Molecules)
+   * - fragments
+     - a data block
+     - no
+     - assigns atom-ids to fragment-IDs with the format "fragment-id", "atom-id-list" (same as Fragments)
+   * - charges
+     - a data block
+     - no
+     - assigns charges to atoms with the format "atom-id", "charge" (same as Charges)
+   * - dipoles
+     - a data block
+     - no
+     - assigns point dipoles to atoms with the format "atom-id", "mux", "muy", "muz" (same as Dipoles)
+   * - diameters
+     - a data block
+     - no
+     - assigns diameters to atoms with the format "atom-id", "diameter" (same as Diameters)
+   * - masses
+     - a data block
+     - no
+     - assigns per-atom masses to atoms with the format "atom-id", "mass" (same as Masses)
+   * - bonds
+     - a data block
+     - no
+     - defines bonds in the molecule template with the format "bond-type", "atom1", "atom2" (same as Bonds without bond-ID)
+   * - angles
+     - a data block
+     - no
+     - defines angles in the molecule template with the format "angle-type", "atom1", "atom2", "atom3" (same as Angles without angle-ID)
+   * - dihedrals
+     - a data block
+     - no
+     - defines dihedrals in the molecule template with the format "dihedral-type", "atom1", "atom2", "atom3", "atom4" (same as Dihedrals without dihedral-ID)
+   * - impropers
+     - a data block
+     - no
+     - defines impropers in the molecule template with the format "improper-type", "atom1", "atom2", "atom3", "atom4" (same as Impropers without improper-ID)
+
+----------
+
 Restrictions
 """"""""""""
 

doc/src/pair_granular.rst

@@ -44,7 +44,7 @@ Examples
    pair_coeff * * hertz 1000.0 50.0 tangential mindlin 1000.0 1.0 0.4 heat area 0.1
 
    pair_style granular
-   pair_coeff * * mdr 5e6 0.4 1.9e5 2.0 0.5 0.5 tangential linear_history 940.0 0.0 0.7 rolling sds 2.7e5 0.0 0.6 damping none
+   pair_coeff * * mdr 5e6 0.4 1.9e5 2.0 0.5 0.5 tangential linear_history 940.0 1.0 0.7 rolling sds 2.7e5 0.0 0.6 damping mdr 1
 
 Description
 """""""""""
@@ -88,7 +88,8 @@ and their required arguments are:
 3. *hertz/material* : E, :math:`\eta_{n0}` (or :math:`e`), :math:`\nu`
 4. *dmt* : E, :math:`\eta_{n0}` (or :math:`e`), :math:`\nu`, :math:`\gamma`
 5. *jkr* : E, :math:`\eta_{n0}` (or :math:`e`), :math:`\nu`, :math:`\gamma`
-6. *mdr* : :math:`E`, :math:`\nu`, :math:`Y`, :math:`\Delta\gamma`, :math:`\psi_b`, :math:`e`
+6. *mdr* : :math:`E`, :math:`\nu`, :math:`Y`, :math:`\Delta\gamma`,
+   :math:`\psi_b`, :math:`\eta_{n0}`
 
 Here, :math:`k_n` is spring stiffness (with units that depend on model
 choice, see below); :math:`\eta_{n0}` is a damping prefactor (or, in its
@@ -177,6 +178,8 @@ two-part series :ref:`Zunker and Kamrin Part I <Zunker2024I>` and
 :ref:`Zunker and Kamrin Part II <Zunker2024II>`. Further development
 and demonstrations of its application to industrially relevant powder
 compaction processes are presented in :ref:`Zunker et al. <Zunker2025>`.
+If you use the *mdr* normal model the only supported damping option is
+the *mdr* damping class described below.
 
 The model requires the following inputs:
 
@@ -200,8 +203,8 @@ The model requires the following inputs:
    triggered. Lower values of :math:`\psi_b` delay the onset of the bulk elastic
    response.
 
-   6. *Coefficient of restitution* :math:`0 \le e \le 1` : The coefficient of
-   restitution is a tunable parameter that controls damping in the normal direction.
+   6. *Damping coefficent* :math:`\eta_{n0} \ge 0` : The damping coefficient
+   is a tunable parameter that controls damping in the normal direction.
 
 .. note::
 
@@ -213,18 +216,12 @@ The *mdr* model produces a nonlinear force-displacement response, therefore the
 critical timestep :math:`\Delta t` depends on the inputs and level of
 deformation. As a conservative starting point the timestep can be assumed to be
 dictated by the bulk elastic response such that
-:math:`\Delta t = 0.35\sqrt{m/k_\textrm{bulk}}`, where :math:`m` is the mass of
+:math:`\Delta t = 0.08\sqrt{m/k_\textrm{bulk}}`, where :math:`m` is the mass of
 the smallest particle and :math:`k_\textrm{bulk} = \kappa R_\textrm{min}` is an
 effective stiffness related to the bulk elastic response.
 Here, :math:`\kappa = E/(3(1-2\nu))` is the bulk modulus and
 :math:`R_\textrm{min}` is the radius of the smallest particle.
 
-.. note::
-
-   The *mdr* model requires some specific settings to function properly,
-   please read the following text carefully to ensure all requirements are
-   followed.
-
 The *atom_style* must be set to *sphere 1* to enable dynamic particle
 radii. The *mdr* model is designed to respect the incompressibility of
 plastic deformation and inherently tracks free surface displacements
@@ -253,13 +250,6 @@ algorithm see :ref:`Zunker et al. <Zunker2025>`.
 
    newton off
 
-The damping model must be set to *none*. The *mdr* model already has a built
-in damping model.
-
-.. code-block:: LAMMPS
-
-   pair_coeff * * mdr 5e6 0.4 1.9e5 2 0.5 0.5 damping none
-
 The definition of multiple *mdr* models in the *pair_style* is currently not
 supported. Similarly, the *mdr* model cannot be combined with a different normal
 model in the *pair_style*. Physically this means that only one homogeneous
@@ -270,7 +260,7 @@ The *mdr* model currently only supports *fix wall/gran/region*, not
 any *fix wall/gran/region* commands must also use the *mdr* model.
 Additionally, the following *mdr* inputs must match between the
 *pair_style* and *fix wall/gran/region* definitions: :math:`E`,
-:math:`\nu`, :math:`Y`, :math:`\psi_b`, and :math:`e`. The exception
+:math:`\nu`, :math:`Y`, :math:`\psi_b`, and :math:`\eta_{n0}`. The exception
 is :math:`\Delta\gamma`, which may vary, permitting different
 adhesive behaviors between particle-particle and particle-wall interactions.
 
@@ -336,6 +326,7 @@ for the damping model currently supported are:
 3. *viscoelastic*
 4. *tsuji*
 5. *coeff_restitution*
+6. *mdr* (class) : :math:`d_{type}`
 
 If the *damping* keyword is not specified, the *viscoelastic* model is
 used by default.
@@ -425,6 +416,37 @@ the damping coefficient, it accurately reproduces the specified coefficient of
 restitution for both monodisperse and polydisperse particle pairs.  This damping
 model is not compatible with cohesive normal models such as *JKR* or *DMT*.
 
+The *mdr* damping class contains multiple damping models that can be toggled between
+by specifying different integer values for the :math:`d_{type}` input parameter. This
+damping option is only compatible with the normal *mdr* contact model.
+
+Setting :math:`d_{type} = 1` is the suggested damping option. This specifies a damping
+model that takes into account the contact stiffness :math:`k_{mdr}` calculated
+by the normal *mdr* contact model to determine the damping coefficient:
+
+.. math::
+
+   \eta_n = \eta_{n0} (m_{eff}k_{mdr})^{1/2},
+
+where :math:`k_{mdr}` is proportional to contact radius :math:`a_{mdr}` tracked by the
+normal *mdr* contact model:
+
+.. math::
+
+   k_{mdr} = 2 E_{eff} a_{mdr}.
+
+In this case, :math:`\eta_{n0}` is simply a dimensionless coefficient that scales the
+the overall damping coefficient.
+
+The other supported option is :math:`d_{type} = 2`, which defines a simple damping model
+similar to the *velocity* option
+
+.. math::
+
+   \eta_n = \eta_{n0},
+
+but has additional checks to avoid non-physical damping after plastic deformation.
+
 The total normal force is computed as the sum of the elastic and
 damping components:
 
@@ -1068,8 +1090,8 @@ a bulk elastic response. Journal of the Mechanics and Physics of Solids,
 
 **(Zunker et al, 2025)** Zunker, W., Dunatunga, S., Thakur, S.,
 Tang, P., & Kamrin, K. (2025). Experimentally validated DEM for large
-deformation powder compaction: mechanically-derived contact model and
-screening of non-physical contacts.
+deformation powder compaction: Mechanically-derived contact model and
+screening of non-physical contacts. Powder Technology, 120972.
 
 .. _Luding2008:
 

doc/src/pair_hybrid.rst

@@ -100,6 +100,56 @@ first is assigned to intra-molecular interactions (i.e. both atoms
 have the same molecule ID), the second to inter-molecular interactions
 (i.e. interacting atoms have different molecule IDs).
 
+.. admonition:: When **NOT** to use a hybrid pair style
+   :class: warning
+
+   Using pair style *hybrid* can be very tempting to use if you need a
+   **many-body potential** supporting a mix of elements for which you
+   cannot find a potential file that covers *all* of them.  Regardless
+   of how this is set up, there will be *errors*.  The major use case
+   where the error is *small*, is when the many-body sub-styles are used
+   on different objects (for example a slab and a liquid, a metal and a
+   nano-machining work piece).  In that case the *mixed* terms
+   **should** be provided by a pair-wise additive potential (like
+   Lennard-Jones or Morse) to avoid unexpected behavior and reduce
+   errors.  LAMMPS cannot easily check for this condition and thus will
+   accept good and bad choices alike.
+
+   Outside of this, we *strongly* recommend *against* using pair style
+   hybrid with many-body potentials for the following reasons:
+
+   1. When trying to combine EAM or MEAM potentials, there is a *large*
+      error in the embedding term, since it is computed separately for
+      each sub-style only.
+
+   2. When trying to combine many-body potentials like Stillinger-Weber,
+      Tersoff, AIREBO, Vashishta, or similar, you have to understand
+      that the potential of a sub-style cannot be applied in a pair-wise
+      fashion but will need to be applied to multiples of atoms
+      (e.g. a Tersoff potential of elements A and B includes the
+      interactions A-A, B-B, A-B, A-A-A, A-A-B, A-B-B, A-B-A, B-A-A,
+      B-A-B, B-B-A, B-B-B; AIREBO also considers all quadruples of
+      atom elements).
+
+   3. When one of the sub-styles uses charge-equilibration (= QEq; like
+      in ReaxFF or COMB) you have inconsistent QEq behavior because
+      either you try to apply QEq to *all* atoms but then you are
+      missing the QEq parameters for the non-QEq pair style (and it
+      would be inconsistent to apply QEq for pair styles that are not
+      parameterized for QEq) or else you would have either no charges or
+      fixed charges interacting with the QEq which also leads to
+      inconsistent behavior between two sub-styles.  When attempting to
+      use multiple ReaxFF instances to combine different potential
+      files, you might be able to work around the QEq limitations, but
+      point 2. still applies.
+
+   We understand that it is frustrating to not be able to run simulations
+   due to lack of available potential files, but that does not justify
+   combining potentials in a broken way via pair style hybrid.  This is
+   not what the hybrid pair styles are designed for.
+
+----------
+
 Here are two examples of hybrid simulations.  The *hybrid* style could
 be used for a simulation of a metal droplet on a LJ surface.  The metal
 atoms interact with each other via an *eam* potential, the surface atoms
@@ -374,12 +424,11 @@ selected sub-style.
 
 ----------
 
-.. note::
-
-   Several of the potentials defined via the pair_style command in
-   LAMMPS are really many-body potentials, such as Tersoff, AIREBO, MEAM,
-   ReaxFF, etc.  The way to think about using these potentials in a
-   hybrid setting is as follows.
+Even though the command name "pair_style" would suggest that these are
+pair-wise interactions, several of the potentials defined via the
+pair_style command in LAMMPS are really many-body potentials, such as
+Tersoff, AIREBO, MEAM, ReaxFF, etc.  The way to think about using these
+potentials in a hybrid setting is as follows.
 
 A subset of atom types is assigned to the many-body potential with a
 single :doc:`pair_coeff <pair_coeff>` command, using "\* \*" to include

doc/src/pair_lj_pirani.rst

@@ -0,0 +1,163 @@
+.. index:: pair_style lj/pirani
+.. index:: pair_style lj/pirani/omp
+
+pair_style lj/pirani command
+============================
+
+Accelerator Variants: *lj/pirani/omp*
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   pair_style lj/pirani cutoff
+
+* lj/pirani = name of the pair style
+* cutoff = global cutoff (distance units)
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   pair_style lj/pirani 10.0
+   pair_coeff 1 1 4.0 7.0 6.0 3.5 0.0045
+
+Description
+"""""""""""
+
+.. versionadded:: 12Jun2025
+
+Pair style *lj/pirani* computes pairwise interactions from an Improved
+Lennard-Jones (ILJ) potential according to :ref:`(Pirani) <Pirani>`.
+The ILJ force field is adequate to model both equilibrium and
+non-equilibrium properties of matter, in gaseous and condensed phases,
+and at gas-surface interfaces. In particular, its use improves the
+description of elementary process dynamics where the traditional
+Lennard-Jones (LJ) formulation is usually applied.
+
+
+.. math::
+
+   x = r/R_m   \\
+   n_x = \alpha*x^2 + \beta   \\
+   \gamma \equiv m  \\
+
+  V(x) = \varepsilon \cdot \left( \frac{\gamma}{ n_x - \gamma}  \left(\frac{1}{x} \right)^{n_x}
+          -  \frac{n_x}{n_x - \gamma}  \left(\frac{1}{x} \right)^{\gamma} \right) \qquad r < r_c
+
+:math:`r_c` is the cutoff.
+
+
+An additional parameter, :math:`\alpha`, has been introduced in order to
+be able to recover the traditional Lennard-Jones 12-6 with a specific
+choice of parameters. With :math:`R_m \equiv r_0 = \sigma \cdot 2^{1 /
+6}`, :math:`\alpha = 0`, :math:`\beta = 12` and :math:`\gamma = 6` it is
+straightforward to prove that LJ 12-6 is obtained. Also, it can be
+verified that using :math:`\alpha= 4`, :math:`\beta= 8` and
+:math:`\gamma = 6`, at the equilibrium distance, the first and second
+derivatives of ILJ match those of LJ 12-6. The parameter :math:`R_m`
+corresponds to the equilibrium distance and :math:`\epsilon` to the well
+depth.
+
+
+This potential provides some advantages with respect to the standard LJ
+potential, as explained in :ref:`(Pirani) <Pirani>`: it provides a more
+realistic description of the long range behavior and an attenuation of
+the hardness of the repulsive wall.
+
+This force field can be used for neutral-neutral (:math:`\gamma = 6`),
+ion-neutral (:math:`\gamma = 4`) or ion-ion systems (:math:`\gamma =
+1`).  Notice that this implementation does not include explicit
+electrostatic interactions.  If these are desired, this pair style
+should be used along with a Coulomb pair style like
+:doc:`pair styles coul/cut or coul/long <pair_coul>` by using
+:doc:`pair style hybrid/overlay <pair_hybrid>` and a suitable
+:doc:`kspace style <kspace_style>`, if needed.
+
+As discussed in :ref:`(Pirani) <Pirani>`, analysis of a variety of
+systems showed that :math:`\alpha= 4` generally works very well.  In
+some special cases (e.g. those involving very small multiple charged
+ions) this factor may take a slightly different value. The parameter
+:math:`\beta` codifies the hardness (polarizability) of the interacting
+partners, and for neutral-neutral systems it usually ranges from 6
+to 11.  Moreover, the modulation of :math:`\beta` can model additional
+interaction effects, such as charge transfer in the perturbative limit,
+and can mitigate the effect of some uncertainty in the data used to
+build up the potential function.
+
+The following coefficients must be defined for each pair of atoms
+types via the :doc:`pair_coeff <pair_coeff>` command as in the examples
+above, or in the data file or restart files read by the
+:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
+commands:
+
+* :math:`\alpha` (dimensionless)
+* :math:`\beta` (dimensionless)
+* :math:`\gamma` (dimensionless)
+* :math:`R_m` (distance units)
+* :math:`\epsilon` (energy units)
+* cutoff (distance units)
+
+The last coefficient is optional. If not specified, the global cutoff is used.
+
+----------
+
+.. include:: accel_styles.rst
+
+----------
+
+Mixing, shift, table, tail correction, restart, rRESPA info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This pair style does not support mixing.  Thus, coefficients for all I,J
+pairs must be specified explicitly.
+
+This pair style supports the :doc:`pair_modify <pair_modify>` shift
+option for the energy of the pair interaction.
+
+The :doc:`pair_modify <pair_modify>` table options are not relevant for
+this pair style.
+
+This pair style does not support the :doc:`pair_modify <pair_modify>`
+tail option for adding long-range tail corrections to energy and
+pressure.
+
+This pair style writes its information to :doc:`binary restart files
+<restart>`, so pair_style and pair_coeff commands do not need to be
+specified in an input script that reads a restart file.
+
+This pair style supports the use of the *inner*, *middle*, and
+*outer* keywords of the :doc:`run_style respa <run_style>` command,
+meaning the pairwise forces can be partitioned by distance at different
+levels of the rRESPA hierarchy. See the :doc:`run_style <run_style>`
+command for details.
+
+
+----------
+
+Restrictions
+""""""""""""
+
+This pair style is only enabled if LAMMPS was built with the EXTRA-PAIR
+package.  See the :doc:`Build package <Build_package>` page for more
+info.
+
+Related commands
+""""""""""""""""
+
+* :doc:`pair_coeff <pair_coeff>`
+* :doc:`pair_style lj/cut <pair_lj>`
+
+Default
+"""""""
+
+none
+
+--------------
+
+.. _Pirani:
+
+**(Pirani)** F. Pirani, S. Brizi, L. Roncaratti, P. Casavecchia, D. Cappelletti and F. Vecchiocattivi,
+Phys. Chem. Chem. Phys., 2008, 10, 5489-5503.

doc/src/pair_lj_smooth.rst

@@ -48,13 +48,19 @@ At the inner cutoff the force and its first derivative
 will match the non-smoothed LJ formula.  At the outer cutoff the force
 and its first derivative will be 0.0.  The inner cutoff cannot be 0.0.
 
+Explicit expressions for the coefficients C1, C2, C3, C4, as well as the
+energy discontinuity at the cutoff can be found here :ref:`(Leoni_1) <Leoni_1>`
+and here :ref:`(Leoni_2) <Leoni_2>`
+
 .. note::
 
    this force smoothing causes the energy to be discontinuous both
    in its values and first derivative.  This can lead to poor energy
-   conservation and may require the use of a thermostat.  Plot the energy
-   and force resulting from this formula via the
-   :doc:`pair_write <pair_write>` command to see the effect.
+   conservation and may require the use of a thermostat.  The energy
+   value discontinuity can be eliminated by shifting the potential
+   energy to be zero at the outer cutoff using the pair_modify shift
+   option. With or without shifting, you can plot the resulting energy
+   and force via the :doc:`pair_write <pair_write>` command to see the effect.
 
 The following coefficients must be defined for each pair of atoms
 types via the :doc:`pair_coeff <pair_coeff>` command as in the examples
@@ -122,3 +128,14 @@ Default
 """""""
 
 none
+
+----------
+
+.. _Leoni_1:
+
+**(Leoni_1)** F. Leoni et al., Phys Rev Lett, 134, 128201 (2025).
+
+.. _Leoni_2:
+
+**(Leoni_2)** F. Leoni et al., Phys Rev Lett, 134, Supplementary Material (2025).
+

doc/src/pair_style.rst

@@ -272,6 +272,7 @@ accelerated styles exist.
 * :doc:`lj/long/dipole/long <pair_dipole>` - long-range LJ and long-range point dipoles
 * :doc:`lj/long/tip4p/long <pair_lj_long>` - long-range LJ and long-range Coulomb for TIP4P water
 * :doc:`lj/mdf <pair_mdf>` - LJ potential with a taper function
+* :doc:`lj/pirani <pair_lj_pirani>` - Improved LJ potential
 * :doc:`lj/relres <pair_lj_relres>` - LJ using multiscale Relative Resolution (RelRes) methodology :ref:`(Chaimovich) <Chaimovich2>`.
 * :doc:`lj/spica <pair_spica>` - LJ for SPICA coarse-graining
 * :doc:`lj/spica/coul/long <pair_spica>` - LJ for SPICA coarse-graining with long-range Coulomb

doc/src/plugin.rst

@@ -10,16 +10,17 @@ Syntax
 
    plugin command args
 
-* command = *load* or *unload* or *list* or *clear*
+* command = *load* or *unload* or *list* or *clear* or *restore*
 * args = list of arguments for a particular plugin command
 
   .. parsed-literal::
 
      *load* file = load plugin(s) from shared object in *file*
      *unload* style name = unload plugin *name* of style *style*
-         *style* = *pair* or *bond* or *angle* or *dihedral* or *improper* or *kspace* or *compute* or *fix* or *region* or *command*
+         *style* = *pair* or *bond* or *angle* or *dihedral* or *improper* or *kspace* or *compute* or *fix* or *region* or *command* or *run* or *min*
      *list* = print a list of currently loaded plugins
      *clear* = unload all currently loaded plugins
+     *restore* = restore all loaded plugins
 
 Examples
 """"""""
@@ -31,6 +32,7 @@ Examples
    plugin unload command hello
    plugin list
    plugin clear
+   plugin restore
 
 Description
 """""""""""
@@ -40,22 +42,46 @@ commands into a LAMMPS binary from so-called dynamic shared object (DSO)
 files.  This enables to add new functionality to an existing LAMMPS
 binary without having to recompile and link the entire executable.
 
+.. admonition:: Plugins are a global, per-executable property
+   :class: Hint
+
+   Unlike most settings in LAMMPS, plugins are a per-executable global
+   property.  Loading a plugin means that it is not only available for
+   the current LAMMPS instance but for all *future* LAMMPS instances.
+
+   After a :doc:`clear <clear>` command, all currently loaded plugins
+   will be restored and do not need to be loaded again.
+
+   When using the library interface or the Python or Fortran module
+   to create multiple concurrent LAMMPS instances, all plugins should
+   be loaded by the first created LAMMPS instance as all future instances
+   will inherit them.  To import plugins that were loaded by a different
+   LAMMPS instance, use the *restore* command.
+
+
 The *load* command will load and initialize all plugins contained in the
-plugin DSO with the given filename.  A message with information the
-plugin style and name and more will be printed.  Individual DSO files
-may contain multiple plugins.  More details about how to write and
+plugin DSO with the given filename.  A message with information about
+the plugin style and name and more will be printed.  Individual DSO
+files may contain multiple plugins.  If a plugin is already loaded
+it will be skipped.  More details about how to write and
 compile the plugin DSO is given in programmer's guide part of the manual
 under :doc:`Developer_plugins`.
 
 The *unload* command will remove the given style or the given name from
 the list of available styles.  If the plugin style is currently in use,
-that style instance will be deleted.
+that style instance will be deleted and replaced by the default setting
+for that style.
 
 The *list* command will print a list of the loaded plugins and their
 styles and names.
 
 The *clear* command will unload all currently loaded plugins.
 
+.. versionadded:: 12Jun2025
+
+The *restore* command will restore all currently loaded plugins.
+This allows to "import" plugins into a different LAMMPS instance.
+
 .. admonition:: Automatic loading of plugins
    :class: note
 
@@ -79,7 +105,7 @@ If plugins access functions or classes from a package,
 LAMMPS must have been compiled with that package included.
 
 Plugins are dependent on the LAMMPS binary interface (ABI)
-and particularly the MPI library used. So they are not guaranteed
+and particularly the MPI library used.  So they are not guaranteed
 to work when the plugin was compiled with a different MPI library
 or different compilation settings or a different LAMMPS version.
 There are no checks, so if there is a mismatch the plugin object

doc/src/python.rst

@@ -10,7 +10,7 @@ Syntax
 
    python mode keyword args ...
 
-* mode = *source* or name of Python function
+* mode = *source* or *name* of Python function
 
   if mode is *source*:
 
@@ -18,35 +18,39 @@ Syntax
 
      keyword = *here* or name of a *Python file*
        *here* arg = inline
-         inline = one or more lines of Python code which defines func
+         inline = one or more lines of Python code which will be executed immediately
                   must be a single argument, typically enclosed between triple quotes
        *Python file* = name of a file with Python code which will be executed immediately
 
-* if *mode* is the name of a Python function, one or more keywords with/without arguments must be appended
+* if *mode* is *name* of a Python function:
 
   .. parsed-literal::
 
+     one or more keywords with/without arguments must be appended
      keyword = *invoke* or *input* or *return* or *format* or *length* or *file* or *here* or *exists*
-       *invoke* arg = none = invoke the previously defined Python function
+       *invoke* arg = logreturn (optional)
+         invoke the previously-defined Python function
+         if logreturn is specified, print the return value of the invoked function to the screen and logfile
        *input* args = N i1 i2 ... iN
          N = # of inputs to function
          i1,...,iN = value, SELF, or LAMMPS variable name
            value = integer number, floating point number, or string
-           SELF = reference to LAMMPS itself which can be accessed by Python function
-           variable = v_name, where name = name of LAMMPS variable, e.g. v_abc
+           SELF = reference to LAMMPS itself which can then be accessed by Python function
+           variable = v_name, where name = name of a LAMMPS variable, e.g. v_abc
+           internal variable = iv_name, where name = name of a LAMMPS internal-style variable, e.g. iv_xyz
        *return* arg = varReturn
          varReturn = v_name  = LAMMPS variable name which the return value of the Python function will be assigned to
        *format* arg = fstring with M characters
          M = N if no return value, where N = # of inputs
          M = N+1 if there is a return value
-         fstring = each character (i,f,s,p) corresponds in order to an input or return value
-         'i' = integer, 'f' = floating point, 's' = string, 'p' = SELF
+         fstring = each character (i,f,s,p) corresponds (in order) to an input or return value
+           'i' = integer, 'f' = floating point, 's' = string, 'p' = SELF
        *length* arg = Nlen
          Nlen = max length of string returned from Python function
        *file* arg = filename
-         filename = file of Python code, which defines func
+         filename = file of Python code, which defines the Python function
        *here* arg = inline
-         inline = one or more lines of Python code which defines func
+         inline = one or more lines of Python code which defines the Python function
                   must be a single argument, typically enclosed between triple quotes
        *exists* arg = none = Python code has been loaded by previous python command
 
@@ -56,7 +60,7 @@ Examples
 .. code-block:: LAMMPS
 
    python pForce input 2 v_x 20.0 return v_f format fff file force.py
-   python pForce invoke
+   python pForce invoke logreturn
 
    python factorial input 1 myN return v_fac format ii here """
    def factorial(n):
@@ -87,75 +91,149 @@ Examples
 Description
 """""""""""
 
-The *python* command allows interfacing LAMMPS with an embedded Python
-interpreter and enables either executing arbitrary python code in that
-interpreter, registering a Python function for future execution (as a
-python style variable, from a fix interfaced with python, or for direct
-invocation), or invoking such a previously registered function.
+The *python* command interfaces LAMMPS with an embedded Python
+interpreter and enables executing arbitrary python code in that
+interpreter.  This can be done immediately, by using *mode* = *source*.
+Or execution can be deferred, by registering a Python function for later
+execution, by using *mode* = *name* of a Python function.
 
-Arguments, including LAMMPS variables, can be passed to the function
-from the LAMMPS input script and a value returned by the Python function
-assigned to a LAMMPS variable.  The Python code for the function can be included
-directly in the input script or in a separate Python file.  The function
-can be standard Python code or it can make "callbacks" to LAMMPS through
-its library interface to query or set internal values within LAMMPS.
-This is a powerful mechanism for performing complex operations in a
-LAMMPS input script that are not possible with the simple input script
-and variable syntax which LAMMPS defines.  Thus your input script can
-operate more like a true programming language.
+Later execution can be triggered in one of two ways.  One is to use the
+python command again with its *invoke* keyword.  The other is to trigger
+the evaluation of a python-style, equal-style, vector-style, or
+atom-style variable.  A python-style variable invokes its associated
+Python function; its return value becomes the value of the python-style
+variable.  Equal-, vector-, and atom-style variables can use a Python
+function wrapper in their formulas which encodes the python-style
+variable name, and specifies arguments (which themselves can be numeric
+formulas) to pass to the Python function associated with the
+python-style variable.
+
+As explained on the :doc:`variable <variable>` doc page, the definition
+of a python-style variable associates a Python function name with the
+variable.  Its specification must match the *mode* argument of the
+*python* command for the Python function name.  For example these two
+commands would be consistent:
+
+.. code-block:: LAMMPS
+
+   variable foo python myMultiply
+   python myMultiply return v_foo format f file funcs.py
+
+The two commands can appear in either order in the input script so long
+as both are specified before the Python function is invoked for the
+first time.
+
+Note that python-style, equal-style, vector-style, and atom-style
+variables can be used in many different ways within LAMMPS.  They can be
+evaluated directly in an input script, effectively replacing the
+variable with its value.  Or they can be passed to various commands as
+arguments, so that the variable is evaluated multiple times during a
+simulation run.  See the :doc:`variable <variable>` command doc page for
+more details on variable styles which enable Python function evaluation.
+
+The Python code for a Python function can be included directly in the
+input script or in a separate Python file.  The function can be standard
+Python code or it can make "callbacks" to LAMMPS through its library
+interface to query or set internal values within LAMMPS.  This is a
+powerful mechanism for performing complex operations in a LAMMPS input
+script that are not possible with the simple input script and variable
+syntax which LAMMPS defines.  Thus your input script can operate more
+like a true programming language.
 
 Use of this command requires building LAMMPS with the PYTHON package
 which links to the Python library so that the Python interpreter is
 embedded in LAMMPS.  More details about this process are given below.
 
-There are two ways to invoke a Python function once it has been
-registered.  One is using the *invoke* keyword.  The other is to assign
-the function to a :doc:`python-style variable <variable>` defined in
-your input script.  Whenever the variable is evaluated, it will execute
-the Python function to assign a value to the variable.  Note that
-variables can be evaluated in many different ways within LAMMPS.  They
-can be substituted with their result directly in an input script, or
-they can be passed to various commands as arguments, so that the
-variable is evaluated during a simulation run.
-
 A broader overview of how Python can be used with LAMMPS is given in the
 :doc:`Use Python with LAMMPS <Python_head>` section of the
-documentation.  There also is an ``examples/python`` directory which
+documentation.  There is also an ``examples/python`` directory which
 illustrates use of the python command.
 
 ----------
 
-The first argument of the *python* command is either the *source*
-keyword or the name of a Python function.  This defines the mode
-of the python command.
+The first argument to the *python* command is the *mode* setting, which
+is either *source* or the *name* of a Python function.
 
 .. versionchanged:: 22Dec2022
 
-If the *source* keyword is used, it is followed by either a file name or
-the *here* keyword.  No other keywords can be used.  The *here* keyword
-is followed by a string with python commands, either on a single line
-enclosed in quotes, or as multiple lines enclosed in triple quotes.
-These Python commands will be passed to the python interpreter and
-executed immediately without registering a Python function for future
-execution.  The code will be loaded into and run in the "main" module of
-the Python interpreter.  This allows running arbitrary Python code at
-any time while processing the LAMMPS input file.  This can be used to
-pre-load Python modules, initialize global variables, define functions
-or classes, or perform operations using the python programming language.
-The Python code will be executed in parallel on all MPI processes.  No
-arguments can be passed.
+If *source* is used, it is followed by either the *here* keyword or a
+file name containing Python code.  The *here* keyword is followed by a
+single *inline* argument which is a string containing one or more python
+commands.  The string can either be on the same line as the *python*
+command, enclosed in quotes, or it can be multiple lines enclosed in
+triple quotes.
 
-In all other cases, the first argument is the name of a Python function
-that will be registered with LAMMPS for future execution.  The function
-may already be defined (see *exists* keyword) or must be defined using
-the *file* or *here* keywords as explained below.
+In either case, the in-line code or the file contents are passed to the
+python interpreter and executed immediately.  The code will be loaded
+into and run in the "main" module of the Python interpreter.  This
+allows running arbitrary Python code at any time while processing the
+LAMMPS input file.  This can be used to pre-load Python modules,
+initialize global variables, define functions or classes, or perform
+operations using the Python programming language.  The Python code will
+be executed in parallel on all the MPI processes being used to run
+LAMMPS.  Note that no arguments can be passed to the executed Python
+code.
 
-If the *invoke* keyword is used, no other keywords can be used, and a
+If the *mode* setting is the *name* of a Python function, then it will
+be registered with LAMMPS for future execution (or can already be
+defined, see the *exists* keyword).  One or more keywords must follow
+the *mode* function name.  One of the keywords must be *invoke*, *file*,
+*here*, or *exists*, which specifies what Python code to load into the
+Python interpreter.  Note that only one of those 4 keywords is allowed
+since their operations are mutually exclusive.
+
+----------
+
+If the *invoke* keyword is used, no other keywords can be used.  A
 previous *python* command must have registered the Python function
-referenced by this command.  This invokes the Python function with the
-previously defined arguments and the return value is processed as
-explained below.  You can invoke the function as many times as you wish
-in your input script.
+referenced by this command, which can then be invoked multiple times in
+an input script via the *invoke* keyword.  Each invocation passes
+current values for arguments to the Python function.  A return value of
+the Python function will be ignored unless the Python function is linked
+to a :doc:`python style variable <variable>` with the *return* keyword.
+This return value can be logged to the screen and logfile by adding the
+optional *logreturn* argument to the *invoke* keyword.  In that case a
+message with the name of the python command and the return value is
+printed.  Note that return values of python functions are otherwise
+*only* accessible when the function is invoked indirectly by evaluating
+its associated :doc:`python style variable <variable>`, as described
+below.
+
+The *file* keyword gives the name of a file containing Python code,
+which should end with a ".py" suffix.  The code will be immediately
+loaded into and run in the "main" module of the Python interpreter.  The
+Python code will be executed in parallel on all MPI processes.  Note
+that Python code which contains a function definition does NOT "execute"
+the function when it is run; it simply defines the function so that it
+can be invoked later.
+
+The *here* keyword does the same thing, except that the Python code
+follows as a single argument to the *here* keyword.  This can be done
+using triple quotes as delimiters, as in the examples above and below.
+This allows Python code to be listed verbatim in your input script, with
+proper indentation, blank lines, and comments, as desired.  See the
+:doc:`Commands parse <Commands_parse>` doc page, for an explanation of
+how triple quotes can be used as part of input script syntax.
+
+The *exists* keyword takes no argument.  It simply means that Python
+code containing the needed Python function has already been loaded into
+the LAMMPS Python interpreter, for example by previous *python source*
+command or in a file that was loaded previously with the *file*
+keyword. This allows use of a single file of Python code which contains
+multiple functions, any of which can be used in the same (or different)
+input scripts (see below).
+
+Note that the Python code that is loaded and run by the *file* or *here*
+keyword must contain a function with the specified function *name*.  To
+operate properly when the function is later invoked, the code for the
+function must match the *input* and *return* and *format* keywords
+specified by the python command.  Otherwise Python will generate an
+error.
+
+----------
+
+The other keywords which can be used with the *python* command are
+*input*, *return*, *format*, and *length*.
 
 The *input* keyword defines how many arguments *N* the Python function
 expects.  If it takes no arguments, then the *input* keyword should not
@@ -169,35 +247,63 @@ itself using the :doc:`LAMMPS Python module <Python_module>`.  This
 enables the function to call back to LAMMPS through its library
 interface as explained below.  This allows the Python function to query
 or set values internal to LAMMPS which can affect the subsequent
-execution of the input script.  A LAMMPS variable can also be used as an
-argument, specified as v_name, where "name" is the name of the variable.
-Any style of LAMMPS variable returning a scalar or a string can be used,
-as defined by the :doc:`variable <variable>` command.  The *format*
-keyword must be used to set the type of data that is passed to Python.
-Each time the Python function is invoked, the LAMMPS variable is
-evaluated and its value is passed to the Python function.
+execution of the input script.
+
+A LAMMPS variable can also be used as an *input* argument, specified as
+v_name, where "name" is the name of the variable defined in the input
+script.  Any style of LAMMPS variable returning a scalar or a string can
+be used, as defined by the :doc:`variable <variable>` command.  The
+style of variable must be consistent with the *format* keyword
+specification for the type of data that is passed to Python.  Each time
+the Python function is invoked, the LAMMPS variable is evaluated and its
+value is passed as an argument to the Python function.  Note that a
+python-style variable can be used as an argument, which means that the a
+Python function can use arguments which invoke other Python functions.
+
+A LAMMPS internal-style variable can also be used as an *input*
+argument, specified as iv_name, where "name" is the name of the
+internal-style variable.  The internal-style variable does not have to
+be defined in the input script (though it can be); if it is not defined,
+this command creates an :doc:`internal-style variable <variable>` with
+the specified name.
+
+An internal-style variable must be used when an equal-style,
+vector-style, or atom-style variable triggers the invocation of the
+Python function defined by this command, by including a Python function
+wrapper with arguments in its formula.  Each of the arguments must be
+specified as an internal-style variable via the *input* keyword.
+
+In brief, the syntax for a Python function wrapper in a variable formula
+is ``py_varname(arg1,arg2,...argN)``, where "varname" is the name of a
+python-style variable associated with a Python function defined by this
+command.  One or more arguments to the function wrapper can themselves
+be sub-formulas which the variable command will evaluate and pass as
+arguments to the Python function.  This is done by assigning the numeric
+result for each argument to an internal-style variable; thus the *input*
+keyword must specify the arguments as internal-style variables and their
+format (see below) as "f" for floating point.  This is because LAMMPS
+variable formulas are calculated with floating point arithmetic (any
+integer values are converted to floating point).  Note that the Python
+function can also have additional inputs, also specified by the *input*
+keyword, which are NOT arguments in the Python function wrapper.  See
+the example below for the ``mixedargs`` Python function.
+
+See the :doc:`variable <variable>` command doc page for full details on
+formula syntax including for Python function wrappers.  Examples using
+Python function wrappers are shown below.  Note that as explained above
+with python-style variables, Python function wrappers can be nested; a
+sub-formula for an argument can contain its own Python function wrapper
+which invokes another Python function.
 
 The *return* keyword is only needed if the Python function returns a
-value.  The specified *varReturn* must be of the form v_name, where
-"name" is the name of a python-style LAMMPS variable, defined by the
+value.  The specified *varReturn* is of the form v_name, where "name" is
+the name of a python-style LAMMPS variable, defined by the
 :doc:`variable <variable>` command.  The Python function can return a
-numeric or string value, as specified by the *format* keyword.
-
-As explained on the :doc:`variable <variable>` doc page, the definition
-of a python-style variable associates a Python function name with the
-variable.  This must match the *Python function name* first argument of
-the *python* command.  For example these two commands would be
-consistent:
-
-.. code-block:: LAMMPS
-
-   variable foo python myMultiply
-   python myMultiply return v_foo format f file funcs.py
-
-The two commands can appear in either order in the input script so
-long as both are specified before the Python function is invoked for
-the first time.  Afterwards, the variable 'foo' is associated with
-the Python function 'myMultiply'.
+numeric or string value, as specified by the *format* keyword.  This
+return value is *only* accessible when its associated python-style
+variable is evaluated.  When the *invoke* keyword is used, the return
+value of the python function is ignored unless the optional *logreturn*
+argument is specified.
 
 The *format* keyword must be used if the *input* or *return* keywords
 are used.  It defines an *fstring* with M characters, where M = sum of
@@ -214,47 +320,16 @@ but only if the output of the Python function is flagged as a numeric
 value ("i" or "f") via the *format* keyword.
 
 If the *return* keyword is used and the *format* keyword specifies the
-output as a string, then the default maximum length of that string is
-63 characters (64-1 for the string terminator).  If you want to return
-a longer string, the *length* keyword can be specified with its *Nlen*
-value set to a larger number (the code allocates space for Nlen+1 to
-include the string terminator).  If the Python function generates a
+output as a string, then the default maximum length of that string is 63
+characters (64-1 for the string terminator).  If you want to return a
+longer string, the *length* keyword can be specified with its *Nlen*
+value set to a larger number.  LAMMPS will then allocate Nlen+1 space to
+include the string terminator.  If the Python function generates a
 string longer than the default 63 or the specified *Nlen*, it will be
 truncated.
 
 ----------
 
-Either the *file*, *here*, or *exists* keyword must be used, but only
-one of them.  These keywords specify what Python code to load into the
-Python interpreter.  The *file* keyword gives the name of a file
-containing Python code, which should end with a ".py" suffix.  The code
-will be immediately loaded into and run in the "main" module of the
-Python interpreter.  The Python code will be executed in parallel on all
-MPI processes.  Note that Python code which contains a function
-definition does not "execute" the function when it is run; it simply
-defines the function so that it can be invoked later.
-
-The *here* keyword does the same thing, except that the Python code
-follows as a single argument to the *here* keyword.  This can be done
-using triple quotes as delimiters, as in the examples above.  This
-allows Python code to be listed verbatim in your input script, with
-proper indentation, blank lines, and comments, as desired.  See the
-:doc:`Commands parse <Commands_parse>` doc page, for an explanation of
-how triple quotes can be used as part of input script syntax.
-
-The *exists* keyword takes no argument.  It means that Python code
-containing the required Python function with the given name has already
-been executed, for example by a *python source* command or in the same
-file that was used previously with the *file* keyword.
-
-Note that the Python code that is loaded and run must contain a function
-with the specified function name.  To operate properly when later
-invoked, the function code must match the *input* and *return* and
-*format* keywords specified by the python command.  Otherwise Python
-will generate an error.
-
-----------
-
 This section describes how Python code can be written to work with
 LAMMPS.
 
@@ -275,16 +350,16 @@ keyword once to load several functions, and the *exists* keyword
 thereafter in subsequent python commands to register the other functions
 that were previously loaded with LAMMPS.
 
-A Python function you define (or more generally, the code you load)
-can import other Python modules or classes, it can make calls to other
+A Python function you define (or more generally, the code you load) can
+import other Python modules or classes, it can make calls to other
 system functions or functions you define, and it can access or modify
 global variables (in the "main" module) which will persist between
 successive function calls.  The latter can be useful, for example, to
 prevent a function from being invoke multiple times per timestep by
 different commands in a LAMMPS input script that access the returned
 python-style variable associated with the function.  For example,
-consider this function loaded with two global variables defined
-outside the function:
+consider this function loaded with two global variables defined outside
+the function:
 
 .. code-block:: python
 
@@ -308,32 +383,33 @@ previous value is simply returned, without re-computing it.  The
 "global" statement inside the Python function allows it to overwrite the
 global variables from within the local context of the function.
 
-Note that if you load Python code multiple times (via multiple python
-commands), you can overwrite previously loaded variables and functions
-if you are not careful.  E.g. if the code above were loaded twice, the
-global variables would be re-initialized, which might not be what you
-want.  Likewise, if a function with the same name exists in two chunks
-of Python code you load, the function loaded second will override the
-function loaded first.
+Also note that if you load Python code multiple times (via multiple
+python commands), you can overwrite previously loaded variables and
+functions if you are not careful.  E.g. if the code above were loaded
+twice, the global variables would be re-initialized, which might not be
+what you want.  Likewise, if a function with the same name exists in two
+chunks of Python code you load, the function loaded second will override
+the function loaded first.
 
 It's important to realize that if you are running LAMMPS in parallel,
-each MPI task will load the Python interpreter and execute a local
-copy of the Python function(s) you define.  There is no connection
-between the Python interpreters running on different processors.
-This implies three important things.
+each MPI task will load the Python interpreter and execute a local copy
+of the Python function(s) you define.  There is no connection between
+the Python interpreters running on different processors.  This implies
+three important things.
 
 First, if you put a print or other statement creating output to the
 screen in your Python function, you will see P copies of the output,
 when running on P processors.  If the prints occur at (nearly) the same
-time, the P copies of the output may be mixed together.  When loading
-the LAMMPS Python module into the embedded Python interpreter, it is
-possible to pass the pointer to the current LAMMPS class instance and
-via the Python interface to the LAMMPS library interface, it is possible
-to determine the MPI rank of the current process and thus adapt the
-Python code so that output will only appear on MPI rank 0.  The
-following LAMMPS input demonstrates how this could be done. The text
-'Hello, LAMMPS!' should be printed only once, even when running LAMMPS
-in parallel.
+time, the P copies of the output may be mixed together.
+
+It is possible to avoid this issue, by passing the pointer to the
+current LAMMPS class instance to the Python function via the {input}
+SELF argument described above.  The Python function can then use the
+Python interface to the LAMMPS library interface, and determine the MPI
+rank of the current process.  The Python code can then ensure output
+will only appear on MPI rank 0.  The following LAMMPS input demonstrates
+how this could be done. The text 'Hello, LAMPS!' should be printed only
+once, even when running LAMMPS in parallel.
 
 .. code-block:: LAMMPS
 
@@ -348,27 +424,26 @@ in parallel.
 
    python python_hello invoke
 
-If your Python code loads Python modules that are not pre-loaded by the
-Python library, then it will load the module from disk.  This may be a
-bottleneck if 1000s of processors try to load a module at the same time.
-On some large supercomputers, loading of modules from disk by Python may
-be disabled.  In this case you would need to pre-build a Python library
-that has the required modules pre-loaded and link LAMMPS with that
-library.
+Second, if your Python code loads Python modules that are not pre-loaded
+by the Python library, then it will load the module from disk.  This may
+be a bottleneck if 1000s of processors try to load a module at the same
+time.  On some large supercomputers, loading of modules from disk by
+Python may be disabled.  In this case you would need to pre-build a
+Python library that has the required modules pre-loaded and link LAMMPS
+with that library.
 
-Third, if your Python code calls back to LAMMPS (discussed in the
-next section) and causes LAMMPS to perform an MPI operation requires
-global communication (e.g. via MPI_Allreduce), such as computing the
-global temperature of the system, then you must ensure all your Python
+Third, if your Python code calls back to LAMMPS (discussed in the next
+section) and causes LAMMPS to perform an MPI operation requires global
+communication (e.g. via MPI_Allreduce), such as computing the global
+temperature of the system, then you must ensure all your Python
 functions (running independently on different processors) call back to
 LAMMPS.  Otherwise the code may hang.
 
 ----------
 
-Your Python function can "call back" to LAMMPS through its
-library interface, if you use the SELF input to pass Python
-a pointer to LAMMPS.  The mechanism for doing this in your
-Python function is as follows:
+As mentioned above, a Python function can "call back" to LAMMPS through
+its library interface, if the SELF input is used to pass Python a
+pointer to LAMMPS.  The mechanism for doing this is as follows:
 
 .. code-block:: python
 
@@ -393,15 +468,15 @@ appeared in your input script.  In this case, LAMMPS should output
    Hello from inside Python
 
 to the screen and log file.  Note that since the LAMMPS print command
-itself takes a string in quotes as its argument, the Python string
-must be delimited with a different style of quotes.
+itself takes a string in quotes as its argument, the Python string must
+be delimited with a different style of quotes.
 
-The :doc:`Python_head` page describes the syntax
-for how Python wraps the various functions included in the LAMMPS
-library interface.
+The :doc:`Python_head` page describes the syntax for how Python wraps
+the various functions included in the LAMMPS library interface.
 
-A more interesting example is in the ``examples/python/in.python`` script
-which loads and runs the following function from ``examples/python/funcs.py``:
+A more interesting example is in the ``examples/python/in.python``
+script which loads and runs the following function from
+``examples/python/funcs.py``:
 
 .. code-block:: python
 
@@ -416,7 +491,7 @@ which loads and runs the following function from ``examples/python/funcs.py``:
 
        lmp.set_variable("cut",cut)                 # set a variable in LAMMPS
        lmp.command("pair_style lj/cut ${cut}")     # LAMMPS command
-       #lmp.command("pair_style lj/cut %d" % cut)  # LAMMPS command option
+       #lmp.command("pair_style lj/cut %d" % cut)  # alternate form of LAMMPS command
 
        lmp.command("pair_coeff * * 1.0 1.0")       # ditto
        lmp.command("run 10")                       # ditto
@@ -432,51 +507,160 @@ with these input script commands:
    python          loop invoke
 
 This has the effect of looping over a series of 10 short runs (10
-timesteps each) where the pair style cutoff is increased from a value
-of 1.0 in distance units, in increments of 0.1.  The looping stops
-when the per-atom potential energy falls below a threshold of -4.0 in
-energy units.  More generally, Python can be used to implement a loop
-with complex logic, much more so than can be created using the LAMMPS
+timesteps each) where the pair style cutoff is increased from a value of
+1.0 in distance units, in increments of 0.1.  The looping stops when the
+per-atom potential energy falls below a threshold of -4.0 in energy
+units.  More generally, Python can be used to implement a loop with
+complex logic, much more so than can be created using the LAMMPS
 :doc:`jump <jump>` and :doc:`if <if>` commands.
 
 Several LAMMPS library functions are called from the loop function.
 Get_natoms() returns the number of atoms in the simulation, so that it
 can be used to normalize the potential energy that is returned by
-extract_compute() for the "thermo_pe" compute that is defined by
-default for LAMMPS thermodynamic output.  Set_variable() sets the
-value of a string variable defined in LAMMPS.  This library function
-is a useful way for a Python function to return multiple values to
-LAMMPS, more than the single value that can be passed back via a
-return statement.  This cutoff value in the "cut" variable is then
-substituted (by LAMMPS) in the pair_style command that is executed
-next.  Alternatively, the "LAMMPS command option" line could be used
-in place of the 2 preceding lines, to have Python insert the value
-into the LAMMPS command string.
+extract_compute() for the "thermo_pe" compute that is defined by default
+for LAMMPS thermodynamic output.  Set_variable() sets the value of a
+string variable defined in LAMMPS.  This library function is a useful
+way for a Python function to return multiple values to LAMMPS, more than
+the single value that can be passed back via a return statement.  This
+cutoff value in the "cut" variable is then substituted (by LAMMPS) in
+the pair_style command that is executed next.  Alternatively, the
+"alternate form of LAMMPS command" line could be used in place of the 2
+preceding lines, to have Python insert the value into the LAMMPS command
+string.
 
 .. note::
 
    When using the callback mechanism just described, recognize that
-   there are some operations you should not attempt because LAMMPS cannot
-   execute them correctly.  If the Python function is invoked between
-   runs in the LAMMPS input script, then it should be OK to invoke any
-   LAMMPS input script command via the library interface command() or
-   file() functions, so long as the command would work if it were
-   executed in the LAMMPS input script directly at the same point.
+   there are some operations you should not attempt because LAMMPS
+   cannot execute them correctly.  If the Python function is invoked
+   between runs in the LAMMPS input script, then it should be OK to
+   invoke any LAMMPS input script command via the library interface
+   command() or file() functions, so long as the command would work if
+   it were executed in the LAMMPS input script directly at the same
+   point.
 
-However, a Python function can also be invoked during a run, whenever
-an associated LAMMPS variable it is assigned to is evaluated.  If the
-variable is an input argument to another LAMMPS command (e.g. :doc:`fix setforce <fix_setforce>`), then the Python function will be invoked
-inside the class for that command, in one of its methods that is
-invoked in the middle of a timestep.  You cannot execute arbitrary
-input script commands from the Python function (again, via the
-command() or file() functions) at that point in the run and expect it
-to work.  Other library functions such as those that invoke computes
-or other variables may have hidden side effects as well.  In these
-cases, LAMMPS has no simple way to check that something illogical is
-being attempted.
 
-The same applies to Python functions called during a simulation run at
-each time step using :doc:`fix python/invoke <fix_python_invoke>`.
+----------
+
+As noted above, a Python function can be invoked during a run, whenever
+an associated python-style variable it is assigned to is evaluated.
+
+If the variable is an input argument to another LAMMPS command
+(e.g. :doc:`fix setforce <fix_setforce>`), then the Python function will
+be invoked inside the class for that command, possibly in one of its
+methods that is invoked in the middle of a timestep.  You cannot execute
+arbitrary input script commands from the Python function (again, via the
+command() or file() functions) at that point in the run and expect it to
+work.  Other library functions such as those that invoke computes or
+other variables may have hidden side effects as well.  In these cases,
+LAMMPS has no simple way to check that something illogical is being
+attempted.
+
+The same constraints apply to Python functions called during a
+simulation run at each time step using the :doc:`fix python/invoke
+<fix_python_invoke>` command.
+
+----------
+
+As noted above, a Python function can also be invoked within the formula
+for an equal-style, vector-style, or atom-style variable.  This means
+the Python function will be invoked whenever that variable is invoked.
+In the case of a vector-style variable, the Python function can be
+invoked once per element of the global vector.  In the case of an
+atom-style variable, the Python function can be invoked once per atom.
+
+Here are three simple examples using equal-, vector-, and atom-style
+variables to trigger execution of a Python function:
+
+.. code-block:: LAMMPS
+
+   variable        foo python truncate
+   python          truncate return v_foo input 1 iv_arg format fi here """
+   def truncate(x):
+     return int(x)
+   """
+   variable        ptrunc equal py_foo(press)
+   print           "TRUNCATED pressure = ${ptrunc}"
+
+The Python ``truncate`` function simply converts a floating-point value
+to an integer value.  When the LAMMPS print command evaluates the
+equal-style ``ptrunc`` variable, the current thermodynamic pressure is
+passed to the Python function.  The truncated value is output to the
+screen and logfile by the print command.  Note that the *input* keyword
+for the *python* command, specifies an internal-style variable named
+"arg" as iv_arg which is required to invoke the Python function from a
+Python function wrapper.
+
+The last 2 lines can be replaced by these to define a vector-style
+variable which invokes the same Python ``truncate`` function:
+
+.. code-block:: LAMMPS
+
+  compute         ke all temp
+  variable        ke vector c_ke
+  variable        ketrunc vector py_foo(v_ke)
+  thermo_style    custom step temp epair v_ketrunc[*6]
+
+The vector-style variable ``ketrunc`` invokes the Python ``truncate``
+function on each of the 6 components of the global kinetic energy tensor
+calculated by the :doc:`compute ke <compute_ke>` command.  The 6
+truncated values will be printed with thermo output to the screen and
+log file.
+
+Or the last 2 lines of the equal-style variable example can be replaced
+by these to define atom-style variables which invoke the same Python
+``truncate`` function:
+
+.. code-block:: LAMMPS
+
+   variable        xtrunc atom py_foo(x)
+   variable        ytrunc atom py_foo(y)
+   variable        ztrunc atom py_foo(z)
+   dump            1 all custom 100 tmp.dump id x y z v_xtrunc v_ytrunc v_ztrunc
+
+When the dump command invokes the 3 atom-style variables, their
+arguments x,y,z to the Python function wrapper are the current per-atom
+coordinates of each atom.  The Python ``truncate`` function is thus
+invoked 3 times for each atom, and the truncated coordinate values for
+each atom are written to the dump file.
+
+Note that when using a Python function wrapper in a variable, arguments
+can be passed to the Python function either from the variable formula or
+by *input* keyword to the :doc:`python command <python>`.  For example,
+consider these (made up) commands:
+
+.. code-block:: LAMMPS
+
+   variable        foo python mixedargs
+   python          mixedargs return v_foo input 6 7.5 v_myValue iv_arg1 iv_argy iv_argz v_flag &
+                   format fffffsf here """
+   def mixedargs(a,b,x,y,z,flag):
+     ...
+     return result
+   """
+   variable        flag string optionABC
+   variable        myValue equal "2.0*temp*c_pe"
+   compute         pe all pe
+   compute         peatom all pe/atom
+   variable        field atom py_foo(x+3.0,sqrt(y),(z-zlo)*c_peatom)
+
+They define a Python ``mixedargs`` function with 6 arguments.  Three of
+them are internal-style variables, which the variable formula calculates
+as numeric values for each atom and passes to the function.  In this
+example, these arguments are themselves small formulas containing the
+x,y,z coordinates of each atom as well as a per-atom compute (c_peratom)
+and thermodynamic keyword (zlo).
+
+The other three arguments ``(7.5,v_myValue,v_flag)`` are defined by the
+*python* command.  The first and last are constant values ("7.5" and the
+``optionABC`` string).  The second argument (``myValue``) is the result
+of an equal-style variable formula which accesses the system temperature
+and potential energy.
+
+The "result" returned by each invocation of the Python ``mixedargs``
+function becomes the per-atom value in the atom-style "field" variable,
+which could be output to a dump file or used elsewhere in the input
+script.
 
 ----------
 
@@ -485,12 +669,11 @@ interactively or by using Python to launch a Python script stored in a
 file, and your code has an error, you will typically see informative
 error messages.  That is not the case when you run Python code from
 LAMMPS using an embedded Python interpreter.  The code will typically
-fail silently.  LAMMPS will catch some errors but cannot tell you
-where in the Python code the problem occurred.  For example, if the
-Python code cannot be loaded and run because it has syntax or other
-logic errors, you may get an error from Python pointing to the
-offending line, or you may get one of these generic errors from
-LAMMPS:
+fail silently.  LAMMPS will catch some errors but cannot tell you where
+in the Python code the problem occurred.  For example, if the Python
+code cannot be loaded and run because it has syntax or other logic
+errors, you may get an error from Python pointing to the offending line,
+or you may get one of these generic errors from LAMMPS:
 
 .. parsed-literal::
 
@@ -504,16 +687,16 @@ you will typically get this generic error from LAMMPS:
 
    Python function evaluation failed
 
-Here are three suggestions for debugging your Python code while
-running it under LAMMPS.
+Here are three suggestions for debugging your Python code while running
+it under LAMMPS.
 
 First, don't run it under LAMMPS, at least to start with!  Debug it
 using plain Python.  Load and invoke your function, pass it arguments,
 check return values, etc.
 
-Second, add Python print statements to the function to check how far
-it gets and intermediate values it calculates.  See the discussion
-above about printing from Python when running in parallel.
+Second, add Python print statements to the function to check how far it
+gets and intermediate values it calculates.  See the discussion above
+about printing from Python when running in parallel.
 
 Third, use Python exception handling.  For example, say this statement
 in your Python function is failing, because you have not initialized the
@@ -523,8 +706,7 @@ variable foo:
 
    foo += 1
 
-If you put one (or more) statements inside a "try" statement,
-like this:
+If you put one (or more) statements inside a "try" statement, like this:
 
 .. code-block:: python
 
@@ -563,13 +745,15 @@ If you use Python code which calls back to LAMMPS, via the SELF input
 argument explained above, there is an extra step required when building
 LAMMPS.  LAMMPS must also be built as a shared library and your Python
 function must be able to load the :doc:`"lammps" Python module
-<Python_module>` that wraps the LAMMPS library interface.  These are the
-same steps required to use Python by itself to wrap LAMMPS.  Details on
-these steps are explained on the :doc:`Python <Python_head>` doc page.
-Note that it is important that the stand-alone LAMMPS executable and the
-LAMMPS shared library be consistent (built from the same source code
-files) in order for this to work.  If the two have been built at
-different times using different source files, problems may occur.
+<Python_module>` that wraps the LAMMPS library interface.
+
+These are the same steps required to use Python by itself to wrap
+LAMMPS.  Details on these steps are explained on the :doc:`Python
+<Python_head>` doc page.  Note that it is important that the stand-alone
+LAMMPS executable and the LAMMPS shared library be consistent (built
+from the same source code files) in order for this to work.  If the two
+have been built at different times using different source files,
+problems may occur.
 
 Another limitation of calling back to Python from the LAMMPS module
 using the *python* command in a LAMMPS input is that both, the Python
@@ -583,7 +767,8 @@ global variables will become invisible.
 Related commands
 """"""""""""""""
 
-:doc:`shell <shell>`, :doc:`variable <variable>`, :doc:`fix python/invoke <fix_python_invoke>`
+:doc:`shell <shell>`, :doc:`variable <variable>`,
+:doc:`fix python/invoke <fix_python_invoke>`
 
 Default
 """""""

doc/src/run.rst

@@ -103,14 +103,16 @@ must be done.
 
 .. note::
 
-   If your input script changes the system between 2 runs, then the
-   initial setup must be performed to ensure the change is recognized by
-   all parts of the code that are affected.  Examples are adding a
-   :doc:`fix <fix>` or :doc:`dump <dump>` or :doc:`compute <compute>`, changing
-   a :doc:`neighbor <neigh_modify>` list parameter, or writing restart file
-   which can migrate atoms between processors.  LAMMPS has no easy way to
-   check if this has happened, but it is an error to use the *pre no*
-   option in this case.
+   If your input script "changes" the system between 2 runs, then the
+   initial setup typically needs to be performed to ensure the change
+   is recognized by all parts of the code that are affected.  Examples
+   are adding a :doc:`fix <fix>` or :doc:`dump <dump>` or
+   :doc:`compute <compute>`, changing a :doc:`neighbor <neigh_modify>`
+   list parameter, using the :doc:`set <set>` command, or writing a
+   restart file via the :doc:`write_restart <write_restart>` command,
+   which can migrate atoms between processors.  LAMMPS has no easy way
+   to check if this has happened, but it is an error to use the *pre
+   no* option in these cases.
 
 If *post* is specified as "no", the full timing summary is skipped;
 only a one-line summary timing is printed.

doc/src/set.rst

@@ -22,21 +22,110 @@ Syntax
        for style = *region*, ID = a region ID
 
 * one or more keyword/value pairs may be appended
-* keyword = *type* or *type/fraction* or *type/ratio* or *type/subset*
-  or *mol* or *x* or *y* or *z* or *vx* or *vy* or *vz* or *charge* or
-  *dipole* or *dipole/random* or *quat* or *spin/atom* or *spin/atom/random* or
-  *spin/electron* or *radius/electron* or
-  *quat* or *quat/random* or *diameter* or *shape* or *length* or *tri* or
-  *theta* or *theta/random* or *angmom* or *omega* or
-  *mass* or *density* or *density/disc* or *temperature* or
-  *volume* or *image* or *bond* or *angle* or *dihedral* or
-  *improper* or *sph/e* or *sph/cv* or *sph/rho* or
-  *smd/contact/radius* or *smd/mass/density* or *dpd/theta* or
-  *edpd/temp* or *edpd/cv* or *cc* or *epsilon* or
-  *i_name* or *d_name* or *i2_name* or *d2_name*
+
+* keyword = *angle* or *angmom* or *bond* or *cc* or *charge* or
+  *density* or *density/disc* or *diameter* or *dihedral* or *dipole*
+  or *dipole/random* or *dpd/theta* or *edpd/cv* or *edpd/temp* or
+  *epsilon* or *image* or *improper* or *length* or *mass* or *mol* or
+  *omega* or *quat* or *quat/random* or *radius/electron* or *shape* or
+  *smd/contact/radius* or *smd/mass/density* or *sph/cv* or *sph/e* or
+  *sph/rho* or *spin/atom* or *spin/atom/random* or *spin/electron* or
+  *temperature* or *theta* or *theta/random* or *tri* or *type* or
+  *type/fraction* or *type/ratio* or *type/subset* or *volume* or *vx*
+  or *vy* or *vz* or *x* or *y* or *z* or *i_name* or *d_name* or
+  *i2_name* or *d2_name*
 
   .. parsed-literal::
 
+       *angle* value = numeric angle type or angle type label, for all angles between selected atoms
+       *angmom* values = Lx Ly Lz
+         Lx,Ly,Lz = components of angular momentum vector (distance-mass-velocity units)
+         any of Lx,Ly,Lz can be an atom-style variable (see below)
+       *bond* value = numeric bond type or bond type label, for all bonds between selected atoms
+       *cc* values = index cc
+         index = index of a chemical species (1 to Nspecies)
+         cc = chemical concentration of tDPD particles for a species (mole/volume units)
+         cc can be an atom-style variable (see below)
+       *charge* value = atomic charge (charge units)
+         value can be an atom-style variable (see below)
+       *density* value = particle density for a sphere or ellipsoid (mass/distance\^3 units), or for a triangle (mass/distance\^2 units) or line (mass/distance units) particle
+         value can be an atom-style variable (see below)
+       *density/disc* value = particle density for a 2d disc or ellipse (mass/distance\^2 units)
+         value can be an atom-style variable (see below)
+       *diameter* value = diameter of spherical particle (distance units)
+         value can be an atom-style variable (see below)
+       *dihedral* value = numeric dihedral type or dihedral type label, for all dihedrals between selected atoms
+       *dipole* values = x y z
+         x,y,z = orientation of dipole moment vector
+         any of x,y,z can be an atom-style variable (see below)
+       *dipole/random* values = seed Dlen
+         seed = random # seed (positive integer) for dipole moment orientations
+         Dlen = magnitude of dipole moment (dipole units)
+       *dpd/theta* value = internal temperature of DPD particles (temperature units)
+         value can be an atom-style variable (see below)
+         value can be NULL which sets internal temp of each particle to KE temp
+       *edpd/cv* value = volumetric heat capacity of eDPD particles (energy/temperature/volume units)
+         value can be an atom-style variable (see below)
+       *edpd/temp* value = temperature of eDPD particles (temperature units)
+         value can be an atom-style variable (see below)
+       *epsilon* value = dielectric constant of the medium where the atoms reside
+         value can be an atom-style variable (see below)
+       *image* values = nx ny nz
+         nx,ny,nz = which periodic image of the simulation box the atom is in
+         any of nx,ny,nz can be an atom-style variable (see below)
+       *improper* value = numeric improper type or improper type label, for all impropers between selected atoms
+       *length* value = len
+         len = length of line segment (distance units)
+         len can be an atom-style variable (see below)
+       *mass* value = per-atom mass (mass units)
+         value can be an atom-style variable (see below)
+       *mol* value = molecule ID
+         the moleclue ID can be an atom-style variable (see below)
+       *omega* values = Wx Wy Wz
+         Wx,Wy,Wz = components of angular velocity vector (radians/time units)
+         any of Wx,Wy,Wz can be an atom-style variable (see below)
+       *quat* values = a b c theta
+         a,b,c = unit vector to rotate particle around via right-hand rule
+         theta = rotation angle (degrees)
+         any of a,b,c,theta values can be an atom-style variable (see below)
+       *quat/random* value = seed
+         seed = random # seed (positive integer) for quaternion orientations
+       *radius/electron* value = eradius
+         eradius = electron radius (or fixed-core radius) (distance units)
+         value can be an atom-style variable (see below)
+       *shape* values = Sx Sy Sz
+         Sx,Sy,Sz = 3 diameters of ellipsoid (distance units)
+         any of Sx,Sy,Sz can be an atom-style variable (see below)
+       *smd/contact/radius* value = radius for short range interactions, i.e. contact and friction
+         value can be an atom-style variable (see below)
+       *smd/mass/density* value = set particle mass based on volume by providing a mass density
+         value can be an atom-style variable (see below)
+       *sph/cv* value = heat capacity of SPH particles (need units)
+         value can be an atom-style variable (see below)
+       *sph/e* value = energy of SPH particles (need units)
+         value can be an atom-style variable (see below)
+       *sph/rho* value = density of SPH particles (need units)
+         value can be an atom-style variable (see below)
+       *spin/atom* values = g x y z
+         g = magnitude of magnetic spin vector (in Bohr magneton's unit)
+         x,y,z = orientation of magnetic spin vector
+         any of x,y,z can be an atom-style variable (see below)
+       *spin/atom/random* values = seed Dlen
+         seed = random # seed (positive integer) for magnetic spin orientations
+         Dlen = magnitude of magnetic spin vector (in Bohr magneton's unit)
+       *spin/electron* value = espin
+         espin = electron spin (+1/-1), 0 = nuclei, 2 = fixed-core, 3 = pseudo-cores (i.e. ECP)
+         value can be an atom-style variable (see below)
+       *temperature* value = temperature for finite-size particles (temperature units)
+         value can be an atom-style variable (see below)
+       *theta* value = angle (degrees)
+         angle = orientation of line segment with respect to x-axis
+         value can be an atom-style variable (see below)
+       *theta/random* value = seed
+         seed = random # seed (positive integer) for line segment orienations
+       *tri* value = side
+         side = side length of equilateral triangle (distance units)
+         value can be an atom-style variable (see below)
        *type* value = numeric atom type or type label
          value can be an atom-style variable (see below)
        *type/fraction* values = type fraction seed
@@ -51,104 +140,22 @@ Syntax
          type = numeric atom type or type label
          Nsubset = exact number of selected atoms to set to new atom type
          seed = random # seed (positive integer)
-       *mol* value = molecule ID
-       value can be an atom-style variable (see below)
-       *x*,\ *y*,\ *z* value = atom coordinate (distance units)
+       *volume* value = particle volume for Peridynamic particle (distance\^3 units)
          value can be an atom-style variable (see below)
        *vx*,\ *vy*,\ *vz* value = atom velocity (velocity units)
          value can be an atom-style variable (see below)
-       *charge* value = atomic charge (charge units)
+       *x*,\ *y*,\ *z* value = atom coordinate (distance units)
          value can be an atom-style variable (see below)
-       *dipole* values = x y z
-         x,y,z = orientation of dipole moment vector
-         any of x,y,z can be an atom-style variable (see below)
-       *dipole/random* value = seed Dlen
-         seed = random # seed (positive integer) for dipole moment orientations
-         Dlen = magnitude of dipole moment (dipole units)
-       *spin/atom* values = g x y z
-         g = magnitude of magnetic spin vector (in Bohr magneton's unit)
-         x,y,z = orientation of magnetic spin vector
-         any of x,y,z can be an atom-style variable (see below)
-       *spin/atom/random* value = seed Dlen
-         seed = random # seed (positive integer) for magnetic spin orientations
-         Dlen = magnitude of magnetic spin vector (in Bohr magneton's unit)
-       *radius/electron* values = eradius
-         eradius = electron radius (or fixed-core radius) (distance units)
-       *spin/electron* value = espin
-         espin = electron spin (+1/-1), 0 = nuclei, 2 = fixed-core, 3 = pseudo-cores (i.e. ECP)
-       *quat* values = a b c theta
-         a,b,c = unit vector to rotate particle around via right-hand rule
-         theta = rotation angle (degrees)
-         any of a,b,c,theta can be an atom-style variable (see below)
-       *quat/random* value = seed
-         seed = random # seed (positive integer) for quaternion orientations
-       *diameter* value = diameter of spherical particle (distance units)
-         value can be an atom-style variable (see below)
-       *shape* value = Sx Sy Sz
-         Sx,Sy,Sz = 3 diameters of ellipsoid (distance units)
-       *length* value = len
-         len = length of line segment (distance units)
-         len can be an atom-style variable (see below)
-       *tri* value = side
-         side = side length of equilateral triangle (distance units)
-         side can be an atom-style variable (see below)
-       *theta* value = angle (degrees)
-         angle = orientation of line segment with respect to x-axis
-         angle can be an atom-style variable (see below)
-       *theta/random* value = seed
-         seed = random # seed (positive integer) for line segment orienations
-       *angmom* values = Lx Ly Lz
-         Lx,Ly,Lz = components of angular momentum vector (distance-mass-velocity units)
-         any of Lx,Ly,Lz can be an atom-style variable (see below)
-       *omega* values = Wx Wy Wz
-         Wx,Wy,Wz = components of angular velocity vector (radians/time units)
-         any of wx,wy,wz can be an atom-style variable (see below)
-       *mass* value = per-atom mass (mass units)
-         value can be an atom-style variable (see below)
-       *density* value = particle density for a sphere or ellipsoid (mass/distance\^3 units), or for a triangle (mass/distance\^2 units) or line (mass/distance units) particle
-         value can be an atom-style variable (see below)
-       *density/disc* value = particle density for a 2d disc or ellipse (mass/distance\^2 units)
-         value can be an atom-style variable (see below)
-       *temperature* value = temperature for finite-size particles (temperature units)
-         value can be an atom-style variable (see below)
-       *volume* value = particle volume for Peridynamic particle (distance\^3 units)
-         value can be an atom-style variable (see below)
-       *image* nx ny nz
-         nx,ny,nz = which periodic image of the simulation box the atom is in
-         any of nx,ny,nz can be an atom-style variable (see below)
-       *bond* value = numeric bond type or bond type label, for all bonds between selected atoms
-       *angle* value = numeric angle type or angle type label, for all angles between selected atoms
-       *dihedral* value = numeric dihedral type or dihedral type label, for all dihedrals between selected atoms
-       *improper* value = numeric improper type or improper type label, for all impropers between selected atoms
-       *rheo/rho* value = density of RHEO particles (mass/distance\^3)
-       *rheo/status* value = status or phase of RHEO particles (unitless)
-       *sph/e* value = energy of SPH particles (need units)
-         value can be an atom-style variable (see below)
-       *sph/cv* value = heat capacity of SPH particles (need units)
-         value can be an atom-style variable (see below)
-       *sph/rho* value = density of SPH particles (need units)
-         value can be an atom-style variable (see below)
-       *smd/contact/radius* = radius for short range interactions, i.e. contact and friction
-         value can be an atom-style variable (see below)
-       *smd/mass/density* = set particle mass based on volume by providing a mass density
-         value can be an atom-style variable (see below)
-       *dpd/theta* value = internal temperature of DPD particles (temperature units)
-         value can be an atom-style variable (see below)
-         value can be NULL which sets internal temp of each particle to KE temp
-       *edpd/temp* value = temperature of eDPD particles (temperature units)
-         value can be an atom-style variable (see below)
-       *edpd/cv* value = volumetric heat capacity of eDPD particles (energy/temperature/volume units)
-         value can be an atom-style variable (see below)
-       *cc* values = index cc
-         index = index of a chemical species (1 to Nspecies)
-         cc = chemical concentration of tDPD particles for a species (mole/volume units)
-       *epsilon* value = dielectric constant of the medium where the atoms reside
        *i_name* value = custom integer vector with name
+         value can be an atom-style variable (see below)
        *d_name* value = custom floating-point vector with name
-       *i2_name* value = column of a custom integer array with name
+         value can be an atom-style variable (see below)
+       *i2_name* value = custom integer array with name
                          column specified as i2_name[N] where N is 1 to Ncol
-       *d2_name* value = column of a custom floating-point array with name
+         value can be an atom-style variable (see below)
+       *d2_name* value = custom floating-point array with name
                          column specified as d2_name[N] where N is 1 to Ncol
+         value can be an atom-style variable (see below)
 
 Examples
 """"""""
@@ -177,22 +184,26 @@ Description
 
 Set one or more properties of one or more atoms.  Since atom
 properties are initially assigned by the :doc:`read_data <read_data>`,
-:doc:`read_restart <read_restart>` or :doc:`create_atoms <create_atoms>`
-commands, this command changes those assignments.  This can be useful
-for overriding the default values assigned by the
-:doc:`create_atoms <create_atoms>` command (e.g. charge = 0.0).  It can
-be useful for altering pairwise and molecular force interactions,
+:doc:`read_restart <read_restart>` or :doc:`create_atoms
+<create_atoms>` commands, this command changes those assignments.
+This can be useful for overriding the default values assigned by the
+:doc:`create_atoms <create_atoms>` command (e.g. charge = 0.0).  It
+can be useful for altering pairwise and molecular force interactions,
 since force-field coefficients are defined in terms of types.  It can
 be used to change the labeling of atoms by atom type or molecule ID
-when they are output in :doc:`dump <dump>` files.  It can also be useful
-for debugging purposes; i.e. positioning an atom at a precise location
-to compute subsequent forces or energy.
+when they are output in :doc:`dump <dump>` files.  It can also be
+useful for debugging purposes; i.e. positioning an atom at a precise
+location to compute subsequent forces or energy.
 
 Note that the *style* and *ID* arguments determine which atoms have
 their properties reset.  The remaining keywords specify which
 properties to reset and what the new values are.  Some strings like
 *type* or *mol* can be used as a style and/or a keyword.
 
+The :doc:`fix set <fix_set>` command can be used with similar syntax
+to this command to reset atom properties once every *N* steps during a
+simulation using via atom-style variables.
+
 ----------
 
 This section describes how to select which atoms to change
@@ -211,8 +222,8 @@ can be specified, e.g. "C".  The style *mol* selects all the atoms in
 a range of molecule IDs.
 
 In each of the range cases, the range can be specified as a single
-numeric value, or a wildcard asterisk can be used to specify a range
-of values.  This takes the form "\*" or "\*n" or "n\*" or "m\*n".  For
+numeric value, or with a wildcard asterisk to specify a range of
+values.  This takes the form "\*" or "\*n" or "n\*" or "m\*n".  For
 example, for the style *type*, if N = the number of atom types, then
 an asterisk with no numeric values means all types from 1 to N.  A
 leading asterisk means all types from 1 to n (inclusive).  A trailing
@@ -222,25 +233,25 @@ means all types from m to n (inclusive).  For all the styles except
 
 The style *group* selects all the atoms in the specified group.  The
 style *region* selects all the atoms in the specified geometric
-region.  See the :doc:`group <group>` and :doc:`region <region>` commands
-for details of how to specify a group or region.
+region.  See the :doc:`group <group>` and :doc:`region <region>`
+commands for details of how to specify a group or region.
 
 ----------
 
-This section describes the keyword options for which properties to
+The next section describes the keyword options for which properties to
 change, for the selected atoms.
 
 Note that except where explicitly prohibited below, all of the
 keywords allow an :doc:`atom-style or atomfile-style variable
 <variable>` to be used as the specified value(s).  If the value is a
-variable, it should be specified as v_name, where name is the
-variable name.  In this case, the variable will be evaluated, and its
-resulting per-atom value used to determine the value assigned to each
-selected atom.  Note that the per-atom value from the variable will be
-ignored for atoms that are not selected via the *style* and *ID*
-settings explained above.  A simple way to use per-atom values from
-the variable to reset a property for all atoms is to use style *atom*
-with *ID* = "\*"; this selects all atom IDs.
+variable, it should be specified as v_name, where name is the variable
+name.  In this case, the variable will be evaluated, and its resulting
+per-atom value used to determine the value assigned to each selected
+atom.  Note that the per-atom value from the variable will be ignored
+for atoms that are not selected via the *style* and *ID* settings
+explained above.  A simple way to use per-atom values from the
+variable to reset a property for all atoms is to use style *atom* with
+*ID* = "\*"; this selects all atom IDs.
 
 Atom-style variables can specify formulas with various mathematical
 functions, and include :doc:`thermo_style <thermo_style>` command
@@ -256,52 +267,110 @@ from a file.
 .. note::
 
    Atom-style and atomfile-style variables return floating point
-   per-atom values.  If the values are assigned to an integer variable,
-   such as the molecule ID, then the floating point value is truncated to
-   its integer portion, e.g. a value of 2.6 would become 2.
+   per-atom values.  If the values are assigned to an integer
+   variable, such as the molecule ID, then the floating point value is
+   truncated to its integer portion, e.g. a value of 2.6 would
+   become 2.
+
+----------
 
 .. versionchanged:: 28Mar2023
 
-   Support for type labels was added for setting atom, bond, angle,
-   dihedral, and improper types
+   Support for type labels was added for setting angle types
 
-Keyword *type* sets the atom type for all selected atoms.  A specified
-value can be either a numeric atom type or an atom type label. When
-using a numeric type, the specified value must be from 1 to ntypes,
-where ntypes was set by the :doc:`create_box <create_box>` command or
-the *atom types* field in the header of the data file read by the
-:doc:`read_data <read_data>` command.  When using a type label it must
-have been defined previously.  See the :doc:`Howto type labels
-<Howto_type_labels>` doc page for the allowed syntax of type labels
-and a general discussion of how type labels can be used.
+Keyword *angle* sets the angle type of all angles of selected atoms to
+the specified value.  The value can be a numeric type from 1 to
+nangletypes.  Or it can be a angle type label.  See the :doc:`Howto
+type labels <Howto_type_labels>` doc page for the allowed syntax of
+type labels and a general discussion of how type labels can be used.
+All atoms in a particular angle must be selected atoms in order for
+the change to be made.  The value of nangletypes was set by the *angle
+types* field in the header of the data file read by the
+:doc:`read_data <read_data>` command.  This keyword does NOT allow use
+of an atom-style variable.
 
-Keyword *type/fraction* sets the atom type for a fraction of the selected
-atoms.  The actual number of atoms changed is not guaranteed
-to be exactly the specified fraction (0 <= *fraction* <= 1), but
-should be statistically close.  Random numbers are used in such a way
-that a particular atom is changed or not changed, regardless of how
-many processors are being used.  This keyword does not allow use of an
-atom-style variable.
+Keyword *angmom* sets the angular momentum of selected atoms.  The
+particles must be ellipsoids as defined by the :doc:`atom_style
+ellipsoid <atom_style>` command or triangles as defined by the
+:doc:`atom_style tri <atom_style>` command.  The angular momentum
+vector of the particles is set to the 3 specified components.
 
-Keywords *type/ratio* and *type/subset* also set the atom type for a
-fraction of the selected atoms.  The actual number of atoms changed
-will be exactly the requested number.  For *type/ratio* the specified
-fraction (0 <= *fraction* <= 1) determines the number.  For
-*type/subset*, the specified *Nsubset* is the number.  An iterative
-algorithm is used which ensures the correct number of atoms are
-selected, in a perfectly random fashion.  Which atoms are selected
-will change with the number of processors used.  These keywords do not
-allow use of an atom-style variable.
+.. versionchanged:: 28Mar2023
 
-Keyword *mol* sets the molecule ID for all selected atoms.  The
-:doc:`atom style <atom_style>` being used must support the use of
-molecule IDs.
+   Support for type labels was added for setting bond types
 
-Keywords *x*, *y*, *z*, and *charge* set the coordinates or
-charge of all selected atoms.  For *charge*, the :doc:`atom style
-<atom_style>` being used must support the use of atomic
-charge. Keywords *vx*, *vy*, and *vz* set the velocities of all
-selected atoms.
+Keyword *bond* sets the bond type of all bonds of selected atoms to
+the specified value.  The value can be a numeric type from 1 to
+nbondtypes.  Or it can be a bond type label.  See the :doc:`Howto type
+labels <Howto_type_labels>` doc page for the allowed syntax of type
+labels and a general discussion of how type labels can be used.  All
+atoms in a particular bond must be selected atoms in order for the
+change to be made.  The value of nbondtypes was set by the *bond
+types* field in the header of the data file read by the
+:doc:`read_data <read_data>` command.  This keyword does NOT allow use
+of an atom-style variable.
+
+Keyword *cc* sets the chemical concentration of a tDPD particle for a
+specified species as defined by the DPD-MESO package. Currently, only
+:doc:`atom_style tdpd <atom_style>` defines particles with this
+attribute. An integer for "index" selects a chemical species (1 to
+Nspecies) where Nspecies is set by the atom_style command. The value
+for the chemical concentration must be >= 0.0.
+
+Keyword *charge* set the charge of all selected atoms.  The :doc:`atom
+style <atom_style>` being used must support the use of atomic charge.
+
+Keyword *density* or *density/disc* also sets the mass of all selected
+particles, but in a different way.  The particles must have a per-atom
+mass attribute, as defined by the :doc:`atom_style <atom_style>`
+command.  If the atom has a radius attribute (see :doc:`atom_style
+sphere <atom_style>`) and its radius is non-zero, its mass is set from
+the density and particle volume for 3d systems (the input density is
+assumed to be in mass/distance\^3 units).  For 2d, the default is for
+LAMMPS to model particles with a radius attribute as spheres.
+However, if the *density/disc* keyword is used, then they can be
+modeled as 2d discs (circles).  Their mass is set from the density and
+particle area (the input density is assumed to be in mass/distance\^2
+units).
+
+If the atom has a shape attribute (see :doc:`atom_style ellipsoid
+<atom_style>`) and its 3 shape parameters are non-zero, then its mass
+is set from the density and particle volume (the input density is
+assumed to be in mass/distance\^3 units).  The *density/disc* keyword
+has no effect; it does not (yet) treat 3d ellipsoids as 2d ellipses.
+
+If the atom has a length attribute (see :doc:`atom_style line
+<atom_style>`) and its length is non-zero, then its mass is set from
+the density and line segment length (the input density is assumed to
+be in mass/distance units).  If the atom has an area attribute (see
+:doc:`atom_style tri <atom_style>`) and its area is non-zero, then its
+mass is set from the density and triangle area (the input density is
+assumed to be in mass/distance\^2 units).
+
+If none of these cases are valid, then the mass is set to the density
+value directly (the input density is assumed to be in mass units).
+
+Keyword *diameter* sets the size of the selected atoms.  The particles
+must be finite-size spheres as defined by the :doc:`atom_style sphere
+<atom_style>` command.  The diameter of a particle can be set to 0.0,
+which means they will be treated as point particles.  Note that this
+command does not adjust the particle mass, even if it was defined with
+a density, e.g. via the :doc:`read_data <read_data>` command.
+
+.. versionchanged:: 28Mar2023
+
+   Support for type labels was added for setting dihedral types
+
+Keyword *dihedral* sets the dihedral type of all dihedrals of selected
+atoms to the specified value.  The value can be a numeric type from 1
+to ndihedraltypes.  Or it can be a dihedral type label.  See the
+:doc:`Howto type labels <Howto_type_labels>` doc page for the allowed
+syntax of type labels and a general discussion of how type labels can
+be used.  All atoms in a particular dihedral must be selected atoms in
+order for the change to be made.  The value of ndihedraltypes was set
+by the *dihedral types* field in the header of the data file read by
+the :doc:`read_data <read_data>` command.  This keyword does NOT allow
+use of an atom-style variable.
 
 Keyword *dipole* uses the specified x,y,z values as components of a
 vector to set as the orientation of the dipole moment vectors of the
@@ -313,40 +382,106 @@ moment vectors for the selected atoms and sets the magnitude of each
 to the specified *Dlen* value.  For 2d systems, the z component of the
 orientation is set to 0.0.  Random numbers are used in such a way that
 the orientation of a particular atom is the same, regardless of how
-many processors are being used.  This keyword does not allow use of an
+many processors are being used.  This keyword does NOT allow use of an
 atom-style variable.
 
-.. versionchanged:: 15Sep2022
+Keyword *dpd/theta* sets the internal temperature of a DPD particle as
+defined by the DPD-REACT package.  If the specified value is a number
+it must be >= 0.0.  If the specified value is NULL, then the kinetic
+temperature Tkin of each particle is computed as 3/2 k Tkin = KE = 1/2
+m v\^2 = 1/2 m (vx\*vx+vy\*vy+vz\*vz).  Each particle's internal
+temperature is set to Tkin.  If the specified value is an atom-style
+variable, then the variable is evaluated for each particle.  If a
+value >= 0.0, the internal temperature is set to that value.  If it is
+< 0.0, the computation of Tkin is performed and the internal
+temperature is set to that value.
 
-Keyword *spin/atom* uses the specified g value to set the magnitude of the
-magnetic spin vectors, and the x,y,z values as components of a vector
-to set as the orientation of the magnetic spin vectors of the selected
-atoms.  This keyword was previously called *spin*.
+Keywords *edpd/temp* and *edpd/cv* set the temperature and volumetric
+heat capacity of an eDPD particle as defined by the DPD-MESO package.
+Currently, only :doc:`atom_style edpd <atom_style>` defines particles
+with these attributes. The values for the temperature and heat
+capacity must be positive.
 
-.. versionchanged:: 15Sep2022
+Keyword *epsilon* sets the dielectric constant of a particle to be
+that of the medium where the particle resides as defined by the
+DIELECTRIC package. Currently, only :doc:`atom_style dielectric
+<atom_style>` defines particles with this attribute. The value for the
+dielectric constant must be >= 0.0.  Note that the set command with
+this keyword will rescale the particle charge accordingly so that the
+real charge (e.g., as read from a data file) stays intact. To change
+the real charges, one needs to use the set command with the *charge*
+keyword. Care must be taken to ensure that the real and scaled charges
+and the dielectric constants are consistent.
 
-Keyword *spin/atom/random* randomizes the orientation of the magnetic spin
-vectors for the selected atoms and sets the magnitude of each to the
-specified *Dlen* value.  This keyword was previously called *spin/random*.
+Keyword *image* sets which image of the simulation box the atom is
+considered to be in.  An image of 0 means it is inside the box as
+defined.  A value of 2 means add 2 box lengths to get the true value.
+A value of -1 means subtract 1 box length to get the true value.
+LAMMPS updates these flags as atoms cross periodic boundaries during
+the simulation.  The flags can be output with atom snapshots via the
+:doc:`dump <dump>` command.  If a value of NULL is specified for any
+of nx,ny,nz, then the current image value for that dimension is
+unchanged.  For non-periodic dimensions only a value of 0 can be
+specified.  This command can be useful after a system has been
+equilibrated and atoms have diffused one or more box lengths in
+various directions.  This command can then reset the image values for
+atoms so that they are effectively inside the simulation box, e.g if a
+diffusion coefficient is about to be measured via the :doc:`compute
+msd <compute_msd>` command.  Care should be taken not to reset the
+image flags of two atoms in a bond to the same value if the bond
+straddles a periodic boundary (rather they should be different by +/-
+1).  This will not affect the dynamics of a simulation, but may mess
+up analysis of the trajectories if a LAMMPS diagnostic or your own
+analysis relies on the image flags to unwrap a molecule which
+straddles the periodic box.
 
-.. versionadded:: 15Sep2022
+.. versionchanged:: 28Mar2023
 
-Keyword *radius/electron* uses the specified value to set the radius of
-electrons or fixed cores.
+   Support for type labels was added for setting improper types
 
-.. versionadded:: 15Sep2022
+Keyword *improper* sets the improper type of all impropers of selected
+atoms to the specified value.  The value can be a numeric type from 1
+to nimpropertypes.  Or it can be a improper type label.  See the
+:doc:`Howto type labels <Howto_type_labels>` doc page for the allowed
+syntax of type labels and a general discussion of how type labels can
+be used.  All atoms in a particular improper must be selected atoms in
+order for the change to be made.  The value of nimpropertypes was set
+by the *improper types* field in the header of the data file read by
+the :doc:`read_data <read_data>` command.  This keyword does NOT allow
+use of an atom-style variable.
 
-Keyword *spin/electron* sets the spin of an electron (+/- 1) or indicates
-nuclei (=0), fixed-cores (=2), or pseudo-cores (= 3).
+Keyword *length* sets the length of selected atoms.  The particles
+must be line segments as defined by the :doc:`atom_style line
+<atom_style>` command.  If the specified value is non-zero the line
+segment is (re)set to a length = the specified value, centered around
+the particle position, with an orientation along the x-axis.  If the
+specified value is 0.0, the particle will become a point particle.
+Note that this command does not adjust the particle mass, even if it
+was defined with a density, e.g. via the :doc:`read_data <read_data>`
+command.
+
+Keyword *mass* sets the mass of all selected particles.  The particles
+must have a per-atom mass attribute, as defined by the
+:doc:`atom_style <atom_style>` command.  See the "mass" command for
+how to set mass values on a per-type basis.
+
+Keyword *mol* sets the molecule ID for all selected atoms.  The
+:doc:`atom style <atom_style>` being used must support the use of
+molecule IDs.
+
+Keyword *omega* sets the angular velocity of selected atoms.  The
+particles must be spheres as defined by the :doc:`atom_style sphere
+<atom_style>` command.  The angular velocity vector of the particles
+is set to the 3 specified components.
 
 Keyword *quat* uses the specified values to create a quaternion
 (4-vector) that represents the orientation of the selected atoms.  The
 particles must define a quaternion for their orientation
 (e.g. ellipsoids, triangles, body particles) as defined by the
-:doc:`atom_style <atom_style>` command.  Note that particles defined by
-:doc:`atom_style ellipsoid <atom_style>` have 3 shape parameters.  The 3
-values must be non-zero for each particle set by this command.  They
-are used to specify the aspect ratios of an ellipsoidal particle,
+:doc:`atom_style <atom_style>` command.  Note that particles defined
+by :doc:`atom_style ellipsoid <atom_style>` have 3 shape parameters.
+The 3 values must be non-zero for each particle set by this command.
+They are used to specify the aspect ratios of an ellipsoidal particle,
 which is oriented by default with its x-axis along the simulation
 box's x-axis, and similarly for y and z.  If this body is rotated (via
 the right-hand rule) by an angle theta around a unit rotation vector
@@ -360,51 +495,77 @@ ignored, since a rotation vector of (0,0,1) is the only valid choice.
 Keyword *quat/random* randomizes the orientation of the quaternion for
 the selected atoms.  The particles must define a quaternion for their
 orientation (e.g. ellipsoids, triangles, body particles) as defined by
-the :doc:`atom_style <atom_style>` command.  Random numbers are used in
-such a way that the orientation of a particular atom is the same,
+the :doc:`atom_style <atom_style>` command.  Random numbers are used
+in such a way that the orientation of a particular atom is the same,
 regardless of how many processors are being used.  For 2d systems,
 only orientations in the xy plane are generated.  As with keyword
 *quat*, for ellipsoidal particles, the 3 shape values must be non-zero
-for each particle set by this command.  This keyword does not allow
+for each particle set by this command.  This keyword does NOT allow
 use of an atom-style variable.
 
-Keyword *diameter* sets the size of the selected atoms.  The particles
-must be finite-size spheres as defined by the :doc:`atom_style sphere
-<atom_style>` command.  The diameter of a particle can be set to 0.0,
-which means they will be treated as point particles.  Note that this
-command does not adjust the particle mass, even if it was defined with
-a density, e.g. via the :doc:`read_data <read_data>` command.
+.. versionadded:: 15Sep2022
+
+Keyword *radius/electron* uses the specified value to set the radius
+of electrons or fixed cores.
 
 Keyword *shape* sets the size and shape of the selected atoms.  The
 particles must be ellipsoids as defined by the :doc:`atom_style
-ellipsoid <atom_style>` command.  The *Sx*, *Sy*, *Sz* settings
-are the 3 diameters of the ellipsoid in each direction.  All 3 can be
-set to the same value, which means the ellipsoid is effectively a
-sphere.  They can also all be set to 0.0 which means the particle will
-be treated as a point particle.  Note that this command does not
-adjust the particle mass, even if it was defined with a density,
-e.g. via the :doc:`read_data <read_data>` command.
+ellipsoid <atom_style>` command.  The *Sx*, *Sy*, *Sz* settings are
+the 3 diameters of the ellipsoid in each direction.  All 3 can be set
+to the same value, which means the ellipsoid is effectively a sphere.
+They can also all be set to 0.0 which means the particle will be
+treated as a point particle.  Note that this command does not adjust
+the particle mass, even if it was defined with a density, e.g. via the
+:doc:`read_data <read_data>` command.
 
-Keyword *length* sets the length of selected atoms.  The particles
-must be line segments as defined by the :doc:`atom_style line
-<atom_style>` command.  If the specified value is non-zero the line
-segment is (re)set to a length = the specified value, centered around
-the particle position, with an orientation along the x-axis.  If the
-specified value is 0.0, the particle will become a point particle.
-Note that this command does not adjust the particle mass, even if it
-was defined with a density, e.g. via the :doc:`read_data <read_data>`
-command.
+Keyword *smd/contact/radius* only applies to simulations with the
+Smooth Mach Dynamics package MACHDYN.  Itsets an interaction radius
+for computing short-range interactions, e.g. repulsive forces to
+prevent different individual physical bodies from penetrating each
+other. Note that the SPH smoothing kernel diameter used for computing
+long range, nonlocal interactions, is set using the *diameter*
+keyword.
 
-Keyword *tri* sets the size of selected atoms.  The particles must be
-triangles as defined by the :doc:`atom_style tri <atom_style>` command.
-If the specified value is non-zero the triangle is (re)set to be an
-equilateral triangle in the xy plane with side length = the specified
-value, with a centroid at the particle position, with its base
-parallel to the x axis, and the y-axis running from the center of the
-base to the top point of the triangle.  If the specified value is 0.0,
-the particle will become a point particle.  Note that this command
-does not adjust the particle mass, even if it was defined with a
-density, e.g. via the :doc:`read_data <read_data>` command.
+Keyword *smd/mass/density* sets the mass of all selected particles,
+but it is only applicable to the Smooth Mach Dynamics package MACHDYN.
+It assumes that the particle volume has already been correctly set and
+calculates particle mass from the provided mass density value.
+
+Keywords *sph/cv*, *sph/e*, and *sph/rho* set the heat capacity,
+energy, and density of smoothed particle hydrodynamics (SPH)
+particles.  See `this PDF guide <PDF/SPH_LAMMPS_userguide.pdf>`_ to
+using SPH in LAMMPS.
+
+.. note::
+
+   Note that the SPH PDF guide file has not been updated for many
+   years and thus does not reflect the current *syntax* of the SPH
+   package commands. For that, please refer to the LAMMPS manual.
+
+.. versionchanged:: 15Sep2022
+
+Keyword *spin/atom* uses the specified g value to set the magnitude of
+the magnetic spin vectors, and the x,y,z values as components of a
+vector to set as the orientation of the magnetic spin vectors of the
+selected atoms.  This keyword was previously called *spin*.
+
+.. versionchanged:: 15Sep2022
+
+Keyword *spin/atom/random* randomizes the orientation of the magnetic
+spin vectors for the selected atoms and sets the magnitude of each to
+the specified *Dlen* value.  This keyword does NOT allow use of an
+atom-style variable.  This keyword was previously called
+*spin/random*.
+
+.. versionadded:: 15Sep2022
+
+Keyword *spin/electron* sets the spin of an electron (+/- 1) or
+indicates nuclei (=0), fixed-cores (=2), or pseudo-cores (= 3).
+
+Keyword *temperature* sets the temperature of a finite-size particle.
+Currently, only the GRANULAR package supports this attribute. The
+temperature must be added using an instance of :doc:`fix property/atom
+<fix_property_atom>` The values for the temperature must be positive.
 
 Keyword *theta* sets the orientation of selected atoms.  The particles
 must be line segments as defined by the :doc:`atom_style line
@@ -413,169 +574,71 @@ orientation angle of the line segments with respect to the x axis.
 
 Keyword *theta/random* randomizes the orientation of theta for the
 selected atoms.  The particles must be line segments as defined by the
-:doc:`atom_style line <atom_style>` command.  Random numbers are used in
-such a way that the orientation of a particular atom is the same,
+:doc:`atom_style line <atom_style>` command.  Random numbers are used
+in such a way that the orientation of a particular atom is the same,
 regardless of how many processors are being used.  This keyword does
-not allow use of an atom-style variable.
+NOT allow use of an atom-style variable.
 
-Keyword *angmom* sets the angular momentum of selected atoms.  The
-particles must be ellipsoids as defined by the :doc:`atom_style
-ellipsoid <atom_style>` command or triangles as defined by the
-:doc:`atom_style tri <atom_style>` command.  The angular momentum
-vector of the particles is set to the 3 specified components.
+Keyword *tri* sets the size of selected atoms.  The particles must be
+triangles as defined by the :doc:`atom_style tri <atom_style>`
+command.  If the specified value is non-zero the triangle is (re)set
+to be an equilateral triangle in the xy plane with side length = the
+specified value, with a centroid at the particle position, with its
+base parallel to the x axis, and the y-axis running from the center of
+the base to the top point of the triangle.  If the specified value is
+0.0, the particle will become a point particle.  Note that this
+command does not adjust the particle mass, even if it was defined with
+a density, e.g. via the :doc:`read_data <read_data>` command.
 
-Keyword *omega* sets the angular velocity of selected atoms.  The
-particles must be spheres as defined by the :doc:`atom_style sphere
-<atom_style>` command.  The angular velocity vector of the particles is
-set to the 3 specified components.
+.. versionchanged:: 28Mar2023
 
-Keyword *mass* sets the mass of all selected particles.  The particles
-must have a per-atom mass attribute, as defined by the :doc:`atom_style
-<atom_style>` command.  See the "mass" command for how to set mass
-values on a per-type basis.
+   Support for type labels was added for setting atom types
 
-Keyword *density* or *density/disc* also sets the mass of all selected
-particles, but in a different way.  The particles must have a per-atom
-mass attribute, as defined by the :doc:`atom_style <atom_style>`
-command.  If the atom has a radius attribute (see :doc:`atom_style
-sphere <atom_style>`) and its radius is non-zero, its mass is set from
-the density and particle volume for 3d systems (the input density is
-assumed to be in mass/distance\^3 units).  For 2d, the default is for
-LAMMPS to model particles with a radius attribute as spheres.  However,
-if the *density/disc* keyword is used, then they can be modeled as 2d
-discs (circles).  Their mass is set from the density and particle area
-(the input density is assumed to be in mass/distance\^2 units).
-
-If the atom has a shape attribute (see :doc:`atom_style ellipsoid
-<atom_style>`) and its 3 shape parameters are non-zero, then its mass is
-set from the density and particle volume (the input density is assumed
-to be in mass/distance\^3 units).  The *density/disc* keyword has no
-effect; it does not (yet) treat 3d ellipsoids as 2d ellipses.
-
-If the atom has a length attribute (see :doc:`atom_style line
-<atom_style>`) and its length is non-zero, then its mass is set from the
-density and line segment length (the input density is assumed to be in
-mass/distance units).  If the atom has an area attribute (see
-:doc:`atom_style tri <atom_style>`) and its area is non-zero, then its
-mass is set from the density and triangle area (the input density is
-assumed to be in mass/distance\^2 units).
-
-If none of these cases are valid, then the mass is set to the density
-value directly (the input density is assumed to be in mass units).
-
-Keyword *temperature* sets the temperature of a finite-size particle.
-Currently, only the GRANULAR package supports this attribute. The
-temperature must be added using an instance of
-:doc:`fix property/atom <fix_property_atom>` The values for the
-temperature must be positive.
-
-Keyword *volume* sets the volume of all selected particles.  Currently,
-only the :doc:`atom_style peri <atom_style>` command defines particles
-with a volume attribute.  Note that this command does not adjust the
-particle mass.
-
-Keyword *image* sets which image of the simulation box the atom is
-considered to be in.  An image of 0 means it is inside the box as
-defined.  A value of 2 means add 2 box lengths to get the true value.  A
-value of -1 means subtract 1 box length to get the true value.  LAMMPS
-updates these flags as atoms cross periodic boundaries during the
-simulation.  The flags can be output with atom snapshots via the
-:doc:`dump <dump>` command.  If a value of NULL is specified for any of
-nx,ny,nz, then the current image value for that dimension is unchanged.
-For non-periodic dimensions only a value of 0 can be specified.  This
-command can be useful after a system has been equilibrated and atoms
-have diffused one or more box lengths in various directions.  This
-command can then reset the image values for atoms so that they are
-effectively inside the simulation box, e.g if a diffusion coefficient is
-about to be measured via the :doc:`compute msd <compute_msd>` command.
-Care should be taken not to reset the image flags of two atoms in a bond
-to the same value if the bond straddles a periodic boundary (rather they
-should be different by +/- 1).  This will not affect the dynamics of a
-simulation, but may mess up analysis of the trajectories if a LAMMPS
-diagnostic or your own analysis relies on the image flags to unwrap a
-molecule which straddles the periodic box.
-
-Keywords *bond*, *angle*, *dihedral*, and *improper*, set the bond
-type (angle type, etc) of all bonds (angles, etc) of selected atoms to
-the specified value.  The value can be a numeric type from 1 to
-nbondtypes (nangletypes, etc).  Or it can be a type label (bond type
-label, angle type label, etc).  See the :doc:`Howto type labels
+Keyword *type* sets the atom type for all selected atoms.  A specified
+value can be either a numeric atom type or an atom type label. When
+using a numeric type, the specified value must be from 1 to ntypes,
+where ntypes was set by the :doc:`create_box <create_box>` command or
+the *atom types* field in the header of the data file read by the
+:doc:`read_data <read_data>` command.  When using a type label it must
+have been defined previously.  See the :doc:`Howto type labels
 <Howto_type_labels>` doc page for the allowed syntax of type labels
-and a general discussion of how type labels can be used.  All atoms in
-a particular bond (angle, etc) must be selected atoms in order for the
-change to be made.  The value of nbondtypes (nangletypes, etc) was set
-by the *bond types* (\ *angle types*, etc) field in the header of the
-data file read by the :doc:`read_data <read_data>` command.  These
-keywords do not allow use of an atom-style variable.
+and a general discussion of how type labels can be used.
 
-Keywords *rheo/rho* and *rheo/status* set the density and the status of
-rheo particles. In particular, one can only set the phase in the status
-as described by the :doc:`RHEO howto page <Howto_rheo>`.
+Keyword *type/fraction* sets the atom type for a fraction of the
+selected atoms.  The actual number of atoms changed is not guaranteed
+to be exactly the specified fraction (0 <= *fraction* <= 1), but
+should be statistically close.  Random numbers are used in such a way
+that a particular atom is changed or not changed, regardless of how
+many processors are being used.  This keyword does NOT allow use of an
+atom-style variable.
 
-Keywords *sph/e*, *sph/cv*, and *sph/rho* set the energy, heat capacity,
-and density of smoothed particle hydrodynamics (SPH) particles.  See
-`this PDF guide <PDF/SPH_LAMMPS_userguide.pdf>`_ to using SPH in LAMMPS.
+Keywords *type/ratio* and *type/subset* also set the atom type for a
+fraction of the selected atoms.  The actual number of atoms changed
+will be exactly the requested number.  For *type/ratio* the specified
+fraction (0 <= *fraction* <= 1) determines the number.  For
+*type/subset*, the specified *Nsubset* is the number.  An iterative
+algorithm is used which ensures the correct number of atoms are
+selected, in a perfectly random fashion.  Which atoms are selected
+will change with the number of processors used.  These keywords do not
+allow use of an atom-style variable.
 
-.. note::
+Keyword *volume* sets the volume of all selected particles.
+Currently, only the :doc:`atom_style peri <atom_style>` command
+defines particles with a volume attribute.  Note that this command
+does not adjust the particle mass.
 
-   Please note that the SPH PDF guide file has not been updated for
-   many years and thus does not reflect the current *syntax* of the
-   SPH package commands. For that please refer to the LAMMPS manual.
+Keywords *vx*, *vy*, and *vz* set the velocities of all selected
+atoms.
 
-Keyword *smd/mass/density* sets the mass of all selected particles, but
-it is only applicable to the Smooth Mach Dynamics package MACHDYN.  It
-assumes that the particle volume has already been correctly set and
-calculates particle mass from the provided mass density value.
-
-Keyword *smd/contact/radius* only applies to simulations with the Smooth
-Mach Dynamics package MACHDYN.  Itsets an interaction radius for
-computing short-range interactions, e.g. repulsive forces to prevent
-different individual physical bodies from penetrating each other. Note
-that the SPH smoothing kernel diameter used for computing long range,
-nonlocal interactions, is set using the *diameter* keyword.
-
-Keyword *dpd/theta* sets the internal temperature of a DPD particle as
-defined by the DPD-REACT package.  If the specified value is a number it
-must be >= 0.0.  If the specified value is NULL, then the kinetic
-temperature Tkin of each particle is computed as 3/2 k Tkin = KE = 1/2 m
-v\^2 = 1/2 m (vx\*vx+vy\*vy+vz\*vz).  Each particle's internal
-temperature is set to Tkin.  If the specified value is an atom-style
-variable, then the variable is evaluated for each particle.  If a value
->= 0.0, the internal temperature is set to that value.  If it is < 0.0,
-the computation of Tkin is performed and the internal temperature is set
-to that value.
-
-Keywords *edpd/temp* and *edpd/cv* set the temperature and volumetric
-heat capacity of an eDPD particle as defined by the DPD-MESO package.
-Currently, only :doc:`atom_style edpd <atom_style>` defines particles
-with these attributes. The values for the temperature and heat capacity
-must be positive.
-
-Keyword *cc* sets the chemical concentration of a tDPD particle for a
-specified species as defined by the DPD-MESO package. Currently, only
-:doc:`atom_style tdpd <atom_style>` defines particles with this
-attribute. An integer for "index" selects a chemical species (1 to
-Nspecies) where Nspecies is set by the atom_style command. The value for
-the chemical concentration must be >= 0.0.
-
-Keyword *epsilon* sets the dielectric constant of a particle, precisely
-of the medium where the particle resides as defined by the DIELECTRIC
-package. Currently, only :doc:`atom_style dielectric <atom_style>`
-defines particles with this attribute. The value for the dielectric
-constant must be >= 0.0.  Note that the set command with this keyword
-will rescale the particle charge accordingly so that the real charge
-(e.g., as read from a data file) stays intact. To change the real
-charges, one needs to use the set command with the *charge*
-keyword. Care must be taken to ensure that the real and scaled charges,
-and dielectric constants are consistent.
+Keywords *x*, *y*, *z* set the coordinates of all selected atoms.
 
 Keywords *i_name*, *d_name*, *i2_name*, *d2_name* refer to custom
 per-atom integer and floating-point vectors or arrays that have been
 added via the :doc:`fix property/atom <fix_property_atom>` command.
 When that command is used specific names are given to each attribute
 which are the "name" portion of these keywords.  For arrays *i2_name*
-and *d2_name*, the column of the array must also be included following
-the name in brackets: e.g. d2_xyz[2], i2_mySpin[3].
+and *d2_name*, the column of the array to set must also be included
+following the name in brackets: e.g. d2_xyz[2] or i2_mySpin[3].
 
 Restrictions
 """"""""""""
@@ -584,7 +647,7 @@ You cannot set an atom attribute (e.g. *mol* or *q* or *volume*\ ) if
 the :doc:`atom_style <atom_style>` does not have that attribute.
 
 This command requires inter-processor communication to coordinate the
-setting of bond types (angle types, etc).  This means that your system
+setting of bond types (angle types, etc).  This means that the system
 must be ready to perform a simulation before using one of these
 keywords (force fields set, atom mass set, etc).  This is not
 necessary for other keywords.
@@ -599,7 +662,7 @@ Related commands
 """"""""""""""""
 
 :doc:`create_box <create_box>`, :doc:`create_atoms <create_atoms>`,
-:doc:`read_data <read_data>`
+:doc:`read_data <read_data>`, :doc:`fix set <fix_set>`
 
 Default
 """""""

doc/src/variable.rst

@@ -45,7 +45,8 @@ Syntax
        *universe* args = one or more strings
        *world* args = one string for each partition of processors
 
-       *equal* or *vector* or *atom* args = one formula containing numbers, thermo keywords, math operations, built-in functions, atom values and vectors, compute/fix/variable references
+       *equal* or *vector* or *atom* args = one formula containing numbers, thermo keywords,
+           math operations, built-in functions, atom values and vectors, compute/fix/variable references
          numbers = 0.0, 100, -5.4, 2.8e-4, etc
          constants = PI, version, on, off, true, false, yes, no
          thermo keywords = vol, ke, press, etc from :doc:`thermo_style <thermo_style>`
@@ -67,8 +68,12 @@ Syntax
                            bound(group,dir,region), gyration(group,region), ke(group,reigon),
                            angmom(group,dim,region), torque(group,dim,region),
                            inertia(group,dimdim,region), omega(group,dim,region)
-         special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), sort(x), rsort(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label), is_typelabel(kind,label), is_timeout()
-         feature functions = is_available(category,feature), is_active(category,feature), is_defined(category,id)
+         special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), sort(x), rsort(x), \                                  gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name),
+                             extract_setting(name), label2type(kind,label),
+                             is_typelabel(kind,label), is_timeout()
+         feature functions = is_available(category,feature), is_active(category,feature),
+                             is_defined(category,id)
+         python function wrapper = py_varname(x,y,z,...)
          atom value = id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i]
          atom vector = id, mass, type, mol, radius, q, x, y, z, vx, vy, vz, fx, fy, fz
          custom atom property = i_name, d_name, i_name[i], d_name[i], i2_name[i], d2_name[i], i2_name[i][j], d2_name[i][j]
@@ -127,18 +132,21 @@ command), or used as input to an averaging fix (see the :doc:`fix
 ave/time <fix_ave_time>` command).  Variables of style *vector* store
 a formula which produces a vector of such values which can be used as
 input to various averaging fixes, or elements of which can be part of
-thermodynamic output.  Variables of style *atom* store a formula which
-when evaluated produces one numeric value per atom which can be output
-to a dump file (see the :doc:`dump custom <dump>` command) or used as
-input to an averaging fix (see the :doc:`fix ave/chunk
-<fix_ave_chunk>` and :doc:`fix ave/atom <fix_ave_atom>` commands).
-Variables of style *atomfile* can be used anywhere in an input script
-that atom-style variables are used; they get their per-atom values
-from a file rather than from a formula.  Variables of style *python*
-can be hooked to Python functions using code you provide, so that the
-variable gets its value from the evaluation of the Python code.
-Variables of style *internal* are used by a few commands which set
-their value directly.
+thermodynamic output.
+
+Variables of style *atom* store a formula which when evaluated
+produces one numeric value per atom which can be output to a dump file
+(see the :doc:`dump custom <dump>` command) or used as input to an
+averaging fix (see the :doc:`fix ave/chunk <fix_ave_chunk>` and
+:doc:`fix ave/atom <fix_ave_atom>` commands).  Variables of style
+*atomfile* can be used anywhere in an input script that atom-style
+variables are used; they get their per-atom values from a file rather
+than from a formula.
+
+Variables of style *python* can be hooked to Python functions using
+Python code you provide, so that the variable gets its value from the
+evaluation of the Python code.  Variables of style *internal* are used
+by a few commands which set their value directly.
 
 .. note::
 
@@ -166,15 +174,16 @@ simulation.
 
 .. note::
 
-   When an input script line is encountered that defines a variable
-   of style *equal* or *vector* or *atom* or *python* that contains a
-   formula or Python code, the formula is NOT immediately evaluated.  It
-   will be evaluated every time when the variable is **used** instead.  If
-   you simply want to evaluate a formula in place you can use as
-   so-called. See the section below about "Immediate Evaluation of
-   Variables" for more details on the topic.  This is also true of a
-   *format* style variable since it evaluates another variable when it is
-   invoked.
+   When an input script line is encountered that defines a variable of
+   style *equal* or *vector* or *atom* or *python* that contains a
+   formula or links to Python code, the formula or Python code is NOT
+   immediately evaluated.  Instead, it is evaluated each time the
+   variable is **used**.  If you simply want to evaluate a formula in
+   place you can use a so-called immediate variable. as described in
+   the preceding note.  Or see the section below about "Immediate
+   Evaluation of Variables" for more details on the topic.  This is
+   also true of a *format* style variable since it evaluates another
+   variable when it is invoked.
 
 Variables of style *equal* and *vector* and *atom* can be used as
 inputs to various other commands which evaluate their formulas as
@@ -183,12 +192,12 @@ this context, variables of style *timer* or *internal* or *python* can
 be used in place of an equal-style variable, with the following two
 caveats.
 
-First, internal-style variables can be used except by commands that
-set the value stored by the internal variable.  When the LAMMPS
-command evaluates the internal-style variable, it will use the value
-set (internally) by another command.  Second, python-style variables
-can be used so long as the associated Python function, as defined by
-the :doc:`python <python>` command, returns a numeric value.  When the
+First, internal-style variables require their values be set by code
+elsewhere in LAMMPS.  When a LAMMPS input script or command evaluates
+an internal-style variable, it must have a current value set
+(internally) via that mechanism.  Second, python-style variables can
+be used so long as the associated Python function, as defined by the
+:doc:`python <python>` command, returns a numeric value.  When the
 LAMMPS command evaluates the python-style variable, the Python
 function will be executed.
 
@@ -388,13 +397,24 @@ using the :doc:`command-line switch -var <Run_options>`.
 
 For the *internal* style a numeric value is provided.  This value will
 be assigned to the variable until a LAMMPS command sets it to a new
-value.  There are currently only two LAMMPS commands that require
-*internal* variables as inputs, because they reset them:
-:doc:`create_atoms <create_atoms>` and :doc:`fix controller
-<fix_controller>`.  As mentioned above, an internal-style variable can
-be used in place of an equal-style variable anywhere else in an input
-script, e.g. as an argument to another command that allows for
-equal-style variables.
+value.
+
+Note however, that most commands which use internal-style variables do
+not require them to be defined in the input script.  They create one or
+more internal-style variables if they do not already exist.  Examples
+are these commands:
+
+* :doc:`create_atoms <create_atoms>`
+* :doc:`fix deposit <fix_deposit>`
+* :doc:`compute bond/local <compute_bond_local>`
+* :doc:`compute angle/local <compute_angle_local>`
+* :doc:`compute dihedral/local <compute_dihedral_local>`
+* :doc:`python <python>` command in conjunction with Python function wrappers used in equal- and atom-style variable formulas
+
+A command which does require an internal-style variable to be defined in
+the input script is the :doc:`fix controller <fix_controller>` command,
+because another (arbitrary) command typically also references the
+variable.
 
 ----------
 
@@ -439,6 +459,15 @@ python-style variable can be used in place of an equal-style variable
 anywhere in an input script, e.g. as an argument to another command
 that allows for equal-style variables.
 
+A python-style variable can also be used within the formula for an
+equal-style or atom-style formula in a Python function wrapper, as
+explained below for variable formulas.  In this context, the usage
+syntax is py_varname(arg1,arg2,...), where varname is the name of the
+python-style variable.  When a Python wrapper function is used in an
+atom-style formula, it can be invoked once per atom using arguments
+specific to each atom.  The resulting values in the atom-style
+variable can thus be calculated by Python code.
+
 ----------
 
 For the *string* style, a single string is assigned to the variable.
@@ -528,9 +557,9 @@ is a valid (though strange) variable formula:
 
 Specifically, a formula can contain numbers, constants, thermo
 keywords, math operators, math functions, group functions, region
-functions, special functions, feature functions, atom values, atom
-vectors, custom atom properties, compute references, fix references, and references to other
-variables.
+functions, special functions, feature functions, Python function
+wrappers, atom values, atom vectors, custom atom properties, compute
+references, fix references, and references to other variables.
 
 +------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Number                 | 0.2, 100, 1.0e20, -15.4, etc                                                                                                                                                                                                                                                                                                                               |
@@ -551,6 +580,8 @@ variables.
 +------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Feature functions      | is_available(category,feature), is_active(category,feature), is_defined(category,id)                                                                                                                                                                                                                                                                       |
 +------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Python func wrapper    | py_varname(x,y,z,...)                                                                                                                                                                                                                                                                                                                                      |
++------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Atom values            | id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i]                                                                                                                                                                                                                                                          |
 +------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Atom vectors           | id, mass, type, mol, x, y, z, vx, vy, vz, fx, fy, fz, q                                                                                                                                                                                                                                                                                                    |
@@ -1161,6 +1192,84 @@ variable name.
 
 ----------
 
+Python Function wrapper
+------------------------
+
+A Python function wrapper enables the formula for an equal-style or
+atom-style variable to invoke functions coded in Python.  In the case
+of an equal-style variable, the Python-coded function will be invoked
+once.  In the case of an atom-style variable, it can be invoked once
+per atom, if one or more of its arguments include a per-atom quantity,
+e.g. the position of an atom.  As illustrated below, the reason to use
+a Python function wrapper is to make it easy to pass LAMMPS-related
+arguments to the Python-coded function associated with a python-style
+variable.
+
+The syntax for defining a Python function wrapper is
+
+.. code-block:: LAMMPS
+
+   py_varname(arg1,arg2,...argN)
+
+where *varname* is the name of a python-style variable which couples
+to a Python-coded function.  The function will be passed the zero or
+more arguments listed in parentheses: *arg1*, *arg2*, ... *argN*.  As
+with Math Functions, each argument can itself be an arbitrarily
+complex formula.
+
+A Python function wrapper can be used in the following manner by an
+input script:
+
+.. code-block:: LAMMPS
+
+   variable        foo python truncate
+   python          truncate return v_foo input 1 v_arg format fi here """
+   def truncate(x):
+    return int(x)
+   """
+   variable        xtrunc atom py_foo(x)
+   variable        ytrunc atom py_foo(y)
+   variable        ztrunc atom py_foo(z)
+   dump            1 all custom 100 tmp.dump id x y z v_xtrunc v_ytrunc v_ztrunc
+
+The first two commands define a python-style variable *foo* and couple
+it to the Python-coded function *truncate()* which takes a single
+floating point argument, and returns its truncated integer value.  In
+this case, the Python code for truncate() is included in the *python*
+command; it could also be contained in a file.  See the :doc:`python
+<python>` command doc page for details.
+
+The next three commands define atom-style variables *xtrunc*,
+*ytrunc*, and *ztrunc*.  Each of them include the same Python function
+wrapper in their formula, with a different argument.  The atom-style
+variable *xtrunc* will invoke the python-style variable *foo*, which
+will in turn invoke the Python-coded *truncate()* method.  Because
+*xtrunc* is an atom-style variable, and the argument *x* in the Python
+function wrapper is a per-atom quantity (the x-coord of each atom),
+each processor will invoke the *truncate()* method once per atom, for
+the atoms it owns.
+
+When invoked for the Ith atom, the value of the *arg* internal-style
+variable, defined by the *python* command, is set to the x-coord of
+the Ith atom.  The call via python-style variable *foo* to the Python
+*truncate()* function passes the value of the *arg* variable as the
+function's first (and only) argument.  Likewise, the return value of
+the Python function is stored by the python-style variable *foo* and
+used in the *xtrunc* atom-style variable formula for the Ith atom.
+
+The resulting per-atom vector for *xtrunc* will thus contain the
+truncated x-coord of every atom in the system.  The dump command
+includes the truncated xyz coords for each atom in its output.
+
+See the :doc:`python <python>` command for more details on options the
+*python* command can specify as well as examples of more complex Python
+functions which can be wrapped in this manner.  In particular, the
+Python function can take a variety of arguments, some generated by the
+*python* command, and others by the arguments of the Python function
+wrapper.
+
+----------
+
 Atom Values and Vectors
 -----------------------